• [2026-09-05] 🎉 v0.4.0: Attributed Memory (Source Ledger):

  • Per-document rollback: add(items, source_id=...) records raw pre-merge results; remove_source() rolls back exactly (re-merging surviving sources), upsert_source() replaces a document in one step
  • Opt-in ledger: track_sources=True; ~1.5-2x storage overhead, bounded (only the current version per source is kept)
  • suspended_index(): batch mutations without dropping the vector index
  • Embedder fingerprint: indexes record the embedder signature and refuse vectors from a different embedding space

• [2026-09-04] 🎉 v0.3.0: Incremental Index Maintenance & Semantic Editing:

  • sync_index(): Patch the FAISS index in place — delete/re-embed only the affected vectors instead of dropping the whole index (up to 200× fewer embedding calls on small edits)
  • remove_many() / upsert(): Batch removal and replace-by-key semantics that preserve the index
  • edit(): LLM-assisted single-item semantic editing — remove one wrong fact while keeping the rest, with key-invariance validation, dry-run, and in-place vector refresh
  • index_built: Property alias for has_index()

• [2026-01-28] 🎉 v0.2.0: Lookups Feature Released:

  • Multi-dimensional Indexing: Create O(1) secondary indices for fast queries by custom keys (name, location, time, etc.)
  • Auto-maintained: Indices automatically update when items merge or are removed
  • Memory Efficient: Stores only references (primary keys), not data copies
  • Example: Build a time-series database where primary key includes timestamp, but query by character name using Lookups!
  • Learn more → | 中文

• [2026-01-21] v0.1.5 Released:

  • 🎯 Production Safety: Added max_workers parameter to control LLM batch processing concurrency
  • ⚡ Rate Limit Protection: Prevents hitting API rate limits from providers like OpenAI, preventing account throttling
  • 🔧 Fine-Grained Control: Customize concurrency per merge strategy (default: 5 workers)
  • Learn more →

• [2026-01-19] v0.1.4 Released:

  • API Improvement: Renamed merge_strategy parameter to strategy_or_merger for better clarity and flexibility
  • Enhancement: Added **kwargs support to directly pass merger-specific parameters (like rule and dynamic_rule for CUSTOM_RULE) through OMem without pre-configuration
  • Benefit: Cleaner API and more intuitive usage patterns for advanced merging scenarios
  • Learn more →

• [2026-01-19] v0.1.3 Released:

  • New Feature: Added MergeStrategy.LLM.CUSTOM_RULE strategy for user-defined merge logic. Inject static rules and dynamic context (via functions) directly into the LLM merger!
  • Breaking Change: Renamed legacy strategies for clarity:
    • KEEP_OLD → KEEP_EXISTING
    • KEEP_NEW → KEEP_INCOMING
    • FIELD_MERGE → MERGE_FIELD
  • Learn more about Custom Rules

Problem: If your primary key includes timestamp (for time-series), how do you query by character name?
Solution: Use Lookups for O(1) exact-match queries on any field!

# Create lookups for different dimensions
memory.create_lookup("by_character", lambda x: x.char_name)
memory.create_lookup("by_location", lambda x: x.location)

# Query - automatic sync with merges
character_events = memory.get_by_lookup("by_character", "Alice")
location_events = memory.get_by_lookup("by_location", "Kitchen")

Key Features:

• ✨ Auto-maintained: Lookups update when items merge or are removed
• ✨ Memory efficient: Stores only references, not data copies
• ✨ Consistent: Merge operations automatically sync lookups

Full Documentation → | 中文文档 →

An AI agent that doesn't just store errors—it synthesizes debugging wisdom over time using LLM.BALANCED strategy.

from ontomem import OMem, MergeStrategy
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

class BugFixExperience(BaseModel):
    error_signature: str
    solutions: list[str]
    prevention_tips: str

memory = OMem(
    memory_schema=BugFixExperience,
    key_extractor=lambda x: x.error_signature,
    llm_client=ChatOpenAI(model="gpt-4o"),
    embedder=OpenAIEmbeddings(),
    strategy_or_merger=MergeStrategy.LLM.BALANCED
)

# Day 1: Pip install
memory.add(BugFixExperience(
    error_signature="ModuleNotFoundError: pandas",
    solutions=["pip install pandas"],
    prevention_tips="Check requirements.txt"
))

# Day 2: Docker container (Different solution!)
memory.add(BugFixExperience(
    error_signature="ModuleNotFoundError: pandas",
    solutions=["apt-get install python3-pandas"],  # Added to list!
    prevention_tips="Use system packages in containers"  # LLM merges both tips
))

# Result: Single record with merged solutions + synthesized advice
guidance = memory.get("ModuleNotFoundError: pandas")
print(guidance.prevention_tips)
# >>> "In standard environments, check requirements.txt. 
#      In containerized environments, prefer system packages..."

Turn a stream of fragmented events into a single "Daily Summary" record using Composite Keys.

from ontomem import OMem, MergeStrategy

class DailyTrace(BaseModel):
    user: str
    date: str
    actions: list[str]  # Accumulates all day
    summary: str        # LLM synthesizes entire day

memory = OMem(
    memory_schema=DailyTrace,
    key_extractor=lambda x: f"{x.user}_{x.date}",  # <-- THE MAGIC KEY
    llm_client=ChatOpenAI(model="gpt-4o"),
    embedder=OpenAIEmbeddings(),
    strategy_or_merger=MergeStrategy.LLM.BALANCED
)

# 9:00 AM event
memory.add(DailyTrace(user="Alice", date="2024-01-01", actions=["Login"]))

# 5:00 PM event (Same day → Merges into SAME record)
memory.add(DailyTrace(user="Alice", date="2024-01-01", actions=["Logout"]))

# Next day (New date → NEW record)
memory.add(DailyTrace(user="Alice", date="2024-01-02", actions=["Login"]))

# Results:
# - alice_2024-01-01: actions=["Login", "Logout"], summary="Active trading day..."
# - alice_2024-01-02: actions=["Login"], summary="Brief session..."

# Semantic search across time
results = memory.search("When was Alice frustrated?", top_k=1)

For a complete working example, see examples/06_temporal_memory_consolidation.py

Inject your own merge logic with static rules and dynamic context:

from datetime import datetime

# Define a dynamic rule function (evaluated at merge time)
def get_time_context():
    hour = datetime.now().hour
    if hour >= 9 and hour <= 17:
        return "Business hours: Prefer stable, verified data"
    else:
        return "After-hours: Prioritize recent updates"

# Use CUSTOM_RULE with static rule + dynamic context
memory = OMem(
    memory_schema=BugFixExperience,
    key_extractor=lambda x: x.error_signature,
    llm_client=ChatOpenAI(model="gpt-4o"),
    embedder=OpenAIEmbeddings(),
    strategy_or_merger=MergeStrategy.LLM.CUSTOM_RULE,
    rule="""
    Merge debugging experiences intelligently:
    - Combine all unique solutions into a list
    - Synthesize prevention tips, incorporating domain context
    - Keep the most recent solution as primary recommendation
    """,
    dynamic_rule=get_time_context  # Evaluated at merge time!
)

# Example use: Errors evolve over time
memory.add(BugFixExperience(
    error_signature="ModuleNotFoundError: pandas",
    solutions=["pip install pandas"],
    prevention_tips="Check requirements.txt first"
))

memory.add(BugFixExperience(
    error_signature="ModuleNotFoundError: pandas",
    solutions=["Use conda-forge mirror"],
    prevention_tips="In restricted networks, try conda"
))

# Result: LLM merges both, considering time context from dynamic_rule
result = memory.get("ModuleNotFoundError: pandas")
print(result.prevention_tips)
# >>> "Check requirements.txt first. For restricted networks, use conda-forge mirror..."

When to use CUSTOM_RULE:

• Complex domain-specific merging logic
• Time/context-aware decisions (e.g., "prefer old data at 2 AM, new data during day")
• Environment-specific rules (e.g., "production mode: conservative, staging: aggressive")
• Multi-factor decision making that LLM strategies don't cover

When using LLM-based merge strategies (LLM.BALANCED, LLM.PREFER_INCOMING, LLM.PREFER_EXISTING, LLM.CUSTOM_RULE), OntoMem makes batch API calls to your LLM provider. By default, these can run concurrently, which may hit rate limits or API throttling.

The max_workers Parameter

Control the maximum number of concurrent LLM requests using the max_workers parameter:

memory = OMem(
    memory_schema=UserProfile,
    key_extractor=lambda x: x.uid,
    llm_client=ChatOpenAI(model="gpt-4o"),
    embedder=OpenAIEmbeddings(),
    strategy_or_merger=MergeStrategy.LLM.BALANCED,
    max_workers=3  # Limit to 3 concurrent requests
)

Configuration Guidelines

Tuning Tips

1. Start Conservative: Begin with max_workers=2 to ensure stability
2. Monitor Performance: Check merge times and error rates
3. Gradually Increase: If stable, try max_workers=5, then higher
4. Check Provider Limits: Verify your OpenAI tier's rate limits (requests per minute)
5. Observe Errors: If you see RateLimitError, reduce max_workers

Example: Production Setup

import os

# Read from environment
max_workers = int(os.getenv("ONTOMEM_MAX_WORKERS", 3))

memory = OMem(
    memory_schema=UserProfile,
    key_extractor=lambda x: x.uid,
    llm_client=ChatOpenAI(model="gpt-4o"),
    embedder=OpenAIEmbeddings(),
    strategy_or_merger=MergeStrategy.LLM.BALANCED,
    max_workers=max_workers  # Easy to adjust without code changes
)

Note: The max_workers parameter only affects LLM-based merge strategies. Classic strategies (MERGE_FIELD, KEEP_INCOMING, KEEP_EXISTING) do not use LLM and are not affected.

To set up the development environment with all testing and documentation tools:

uv sync --group dev

Core Requirements:

• Python 3.11+
• LangChain (for LLM integration)
• Pydantic (for schema definition)
• FAISS (for vector search)