Open Source: Migrating to the New Memory Algorithm

Overview

The new Mem0 release redesigns both extraction and retrieval, and cleans up the SDK surface across Python and TypeScript:

• Extraction: Single-pass ADD-only (one LLM call, no UPDATE/DELETE)
• Retrieval: Multi-signal hybrid search (semantic + BM25 keyword + entity matching)
• Entity matching: Automatic entity extraction feeds a third scoring signal in hybrid search, boosting memories that share entities with the query
• Graph memory moved to Platform: The external graph store integration is removed from OSS; graph memory is now a built-in, always-on Mem0 Platform feature
• SDK cleanup: Deprecated parameters removed, naming conventions standardized
• API surface aligned with Platform: Entity IDs now follow the same convention across OSS and Platform: top-level kwargs for add() / delete_all(), inside filters for search() / get_all()

These changes produce a +20 point improvement on LoCoMo (71.4 → 91.6) and +26 point improvement on LongMemEval (67.8 → 93.4), while cutting extraction latency roughly in half.

Breaking Changes

Python Open Source

TypeScript Open Source

Python Client SDK

TypeScript Client SDK

Step-by-Step Migration

1. Update Installation

# For hybrid search + entity extraction (recommended)
pip install --upgrade "mem0ai[nlp]"
python -m spacy download en_core_web_sm

# Qdrant users: also install fastembed to enable BM25 keyword search
pip install fastembed
```

<Info>
**Supported Python versions for `[nlp]` extras: 3.10 – 3.12.** spaCy and its `blis` / `thinc` dependencies do not yet ship prebuilt wheels for Python 3.13, so installs on 3.13 will fail at build time. Use Python 3.12 (or older) for the `[nlp]` extras until upstream support lands. The base `mem0ai` package works on all supported Python versions; only the NLP extras are constrained.
</Info>

pip install fastembed

2. Update Configuration

# After
config = {
    "custom_instructions": "Focus on user preferences",  # [OK] New name
    # custom_update_memory_prompt removed: use custom_instructions
    # enable_graph and graph_store removed: graph memory is now a Mem0 Platform feature
}
```

// After
const config = {
  customInstructions: "Focus on user preferences",  // [OK] New name
  // enableGraph and graphStore removed: graph memory is now a Mem0 Platform feature
};
```

3. Update Search Calls

# After: entity IDs go inside `filters` (matches Platform API)
results = m.search(
    "what meetings did I attend?",
    filters={"user_id": "alice"},   # [REMOVED top-level kwarg, use filters]
    top_k=20,           # New default is 20 (was 100)
    threshold=0.1,      # New default (pass 0.0 to disable)
    rerank=False         # New default (pass True to restore)
)
for r in results:
    print(r["score"])
```

<Warning>
Passing `user_id`, `agent_id`, or `run_id` as a top-level kwarg to `search()` or `get_all()` now raises `ValueError`. They must be inside the `filters` dict. The change aligns the OSS SDK with the Platform API contract.
</Warning>

// After: entity IDs go inside `filters` (matches Platform API)
const results = await m.search("what meetings did I attend?", {
  filters: { userId: "alice" },   // [REMOVED top-level option, use filters]
  topK: 20                        // [OK] Renamed from 'limit'
});
```

# Before
client = MemoryClient(api_key="...", org_id="org-1", project_id="proj-1")
results = client.search("query", user_id="alice", top_k=20, enable_graph=True)

# After
client = MemoryClient(api_key="...")  # org_id, project_id removed
results = client.search(
    "query",
    options=SearchMemoryOptions(
        filters={"user_id": "alice"},
        top_k=20
    )
)
```

// After
const client = new MemoryClient({ apiKey: "..." });
const results = await client.search("query", {
  filters: { userId: "alice" },
  topK: 20
});
```

4. Update Add Calls

# After: only ADD events
result = m.add("I love hiking and my dog's name is Max", user_id="alice")
for item in result["results"]:
    print("New memory:", item["memory"])  # Only ADD events
```

# Before
client.add(messages, user_id="alice", async_mode=True, output_format="v1.1")

# After: async_mode and output_format removed (async by default, v1.1 always)
client.add(
    messages,
    options=AddMemoryOptions(user_id="alice")
)
# Or using **kwargs
client.add(messages, user_id="alice")
```

// After
await client.add(messages, {
  userId: "alice"         // [OK] camelCase
});
```

5. Update Vector Store Dependencies

If you're using Qdrant or Upstash, update your client libraries:

# Qdrant users
pip install "qdrant-client>=1.12.0"

# Upstash users
pip install "upstash-vector>=0.6.0"

6. Entity Matching Store Setup

The new algorithm automatically creates a parallel collection named {your_collection}_entities to power entity matching, the third signal in hybrid search. No manual setup is required: it's created on first use. This is separate from and unrelated to graph memory, which is a Mem0 Platform feature.

Graph Memory: Platform Only

Graph memory is removed from the open-source SDK. It is not being replaced by an OSS equivalent: graph memory is a Mem0 Platform feature, built in and always on, with no external graph database required. See Graph Memory for what it does on Platform.

What was removed from OSS:

• enable_graph / enableGraph config flag
• graph_store / graphStore configuration block
• All external graph store drivers (Neo4j, Memgraph, Kuzu, Apache AGE, Neptune) and their code paths (~4000 lines)

Migration:

• Remove enable_graph / enableGraph from your config
• Remove the graph_store / graphStore block: it is no longer read
• Uninstall external graph drivers (neo4j, memgraph, etc.) if you were using them only for Mem0
• If you need graph memory, use Mem0 Platform instead of self-hosted OSS

How the New Algorithm Works

Extraction: Single-Pass ADD-Only

Input conversation
    → Retrieve top-10 related existing memories (for deduplication context)
    → Single LLM call: extract all distinct new facts
    → Batch embed extracted memories
    → Hash-based deduplication (MD5, prevents exact duplicates)
    → Batch insert into vector store
    → Entity extraction (for entity matching)

The previous algorithm used two LLM calls: one to extract candidate facts, one to decide ADD/UPDATE/DELETE actions against existing memories. The new algorithm collapses this into a single call that only adds. The model spends its capacity on understanding the input rather than diffing against existing state.

Retrieval: Multi-Signal Hybrid Search

Query
    → Preprocess (lemmatize keywords, extract entities)
    → Parallel scoring:
        1. Semantic search (vector similarity)
        2. BM25 keyword search (normalized term matching)
        3. Entity matching (entity overlap boost)
    → Score fusion → Top-K selection

Scoring: The three signals are normalized and fused into a single combined score per result. The fusion adapts based on which signals are available at runtime (semantic-only, semantic + BM25, or all three when spaCy + the entity store are active).

BM25 is a boost signal, not a recall expander. Only semantic search results are candidates: BM25 and entity scores boost ranking but don't add new candidates.

Vector Store Compatibility

All 15 supported vector stores have been enhanced with two new capabilities:

Qdrant-specific changes:

• Now uses sparse vectors (BM25) alongside dense vectors in the same collection
• Requires fastembed library for BM25 encoding (lazy-loaded, gracefully degrades)
• Install: pip install fastembed

All other vector stores:

• Enhanced with keyword_search() methods using their native full-text capabilities
• No additional dependencies required

Graceful Degradation

The new features degrade gracefully when optional dependencies are missing:

You always get semantic search. Hybrid search features layer on top when available.

Removed Parameters Reference

These parameters have been removed across all SDKs. Remove them from your code:

Python Client SDK: Removed parameters

Constructor: org_id, project_id

All methods: api_version, output_format, async_mode, org_name, project_name, org_id, project_id

add(): enable_graph, immutable, filter_memories, batch_size, force_add_only, includes, excludes, keyword_search

search(): enable_graph

get_all(): enable_graph

project.update(): enable_graph

TypeScript Client SDK: Removed parameters

Constructor: organizationId, projectId, organizationName, projectName

All methods: OutputFormat enum, API_VERSION enum

add(): enable_graph / enableGraph, async_mode / asyncMode, output_format / outputFormat, immutable, filter_memories / filterMemories, batch_size / batchSize, force_add_only / forceAddOnly, includes, excludes, keyword_search / keywordSearch

search(): enable_graph / enableGraph

get_all(): enable_graph / enableGraph

Python OSS: Removed/renamed parameters

Config: custom_fact_extraction_prompt → renamed to custom_instructions

Config: custom_update_memory_prompt → deprecated, use custom_instructions

Config: enable_graph + graph_store → removed (graph memory is now a Mem0 Platform feature)

TypeScript OSS: Removed/renamed parameters

Config: customPrompt → renamed to customInstructions

Config: enableGraph + graphStore → removed (graph memory is now a Mem0 Platform feature)

search(): limit → renamed to topK

Common Issues

TypeScript: limit is not a valid parameter

The limit parameter has been renamed to topK in the TypeScript OSS:

// Before
const results = await m.search("query", { userId: "alice", limit: 20 });

// After
const results = await m.search("query", { filters: { userId: "alice" }, topK: 20 });

TypeScript Client: snake_case params no longer work

All TypeScript Client SDK parameters now use camelCase. The SDK handles conversion to/from the API automatically:

// Before
await client.search("query", { user_id: "alice", top_k: 20 });

// After
await client.search("query", { filters: { userId: "alice" }, topK: 20 });

ValueError: Top-level entity parameters not supported in search() / get_all()

search() and get_all() now require entity IDs inside filters. Top-level kwargs raise ValueError. This aligns the OSS SDK with the Platform API.

# Before
results = m.search("query", user_id="alice", top_k=20)

# After
results = m.search("query", filters={"user_id": "alice"}, top_k=20)

add() and delete_all() continue to accept entity IDs as top-level kwargs.

Search returns fewer results than before

The default threshold changed from None to 0.1. Low-relevance results that were previously included are now filtered out. To restore the old behavior:

results = m.search("query", filters={"user_id": "alice"}, threshold=0.0)

spaCy model not found

If you see errors about missing spaCy models, download the required model:

python -m spacy download en_core_web_sm

If spaCy is not installed at all, install the NLP extras:

pip install "mem0ai[nlp]"

Entity matching store collection creation fails

The entity matching store tries to create a {collection_name}_entities collection automatically. If your vector database has restricted permissions, pre-create this collection with the same embedding dimensions as your main collection.

Score values are different from before

The top-level score still ranges [0, 1], but it is computed differently in v3. Relative ranking between results stays comparable, but absolute numbers shift: retune any hard thresholds in your app against representative queries.

If you need the raw cosine similarity for a specific use case, run an unboosted vector query directly against your vector store via vector_store.search(...).

Need Help?

• Join our Discord community for real-time support
• Open an issue on GitHub
• Check the evaluation docs to benchmark the new algorithm on your data