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 linking: Automatic entity extraction and cross-memory linking
• 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 store support has been removed
}
```

// After
const config = {
  customInstructions: "Focus on user preferences",  // [OK] New name
  // enableGraph and graphStore removed — graph store support has been removed
};
```

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 Store Setup

The new algorithm automatically creates a parallel entity store collection named {your_collection}_entities. No manual setup is required — it's created on first use.

Graph Memory → Entity Linking

Graph store support has been removed from the open-source SDK. It is replaced by built-in entity linking, which runs natively with no external dependencies.

What was removed:

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

What replaces it:

Entity linking extracts entities (proper nouns, quoted text, compound noun phrases) from every memory during the add pipeline and stores them in a parallel collection ({collection}_entities) inside your existing vector store. At search time, entities from the query are matched against this collection and used to boost relevant memories. The boost is folded into the combined score on each result.

Migration:

• Remove enable_graph / enableGraph from your config
• Remove the graph_store / graphStore block — it is no longer read
• Uninstall graph drivers (neo4j, memgraph, etc.) if you were using them only for Mem0
• No data migration is required. Entity linking activates automatically on the next add() call.

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 + linking

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 graph 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, expiration_date, 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, expiration_date / expirationDate, 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 store support removed entirely)

TypeScript OSS — Removed/renamed parameters

Config: customPrompt → renamed to customInstructions

Config: enableGraph + graphStore → removed (graph store support removed entirely)

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 store collection creation fails

The entity 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