chore(release): promote Python SDK to 2.0.0 and TS SDK to 3.0.0 (#4860 )

docs: new algorithm migration guides + memory evaluation (#4811 )
Co-authored-by: kartik-mem0 <kartik.labhshetwar@mem0.ai> Co-authored-by: Saket Aryan <saketaryan2002@gmail.com>
2026-04-16 17:13:50 +05:30 · 2026-04-16 17:13:13 +05:30 · 2026-04-16 16:23:50 +05:30 · 2026-04-16 12:17:13 +05:30 · 2026-04-16 05:28:49 +05:30 · 2026-04-16 04:09:51 +05:30
82 changed files with 2575 additions and 2151 deletions
@@ -41,16 +41,30 @@
 <p align="center">
  <a href="https://mem0.ai/research"><strong>📄 Building Production-Ready AI Agents with Scalable Long-Term Memory →</strong></a>
 </p>
-<p align="center">
-  <strong>⚡ +26% Accuracy vs. OpenAI Memory • 🚀 91% Faster • 💰 90% Fewer Tokens</strong>
-</p>

-> **🎉 mem0ai v1.0.0 is now available!** This major release includes API modernization, improved vector store support, and enhanced GCP integration. [See migration guide →](MIGRATION_GUIDE_v1.0.md)
+## New Memory Algorithm (April 2026)

-##  🔥 Research Highlights
- **+26% Accuracy** over OpenAI Memory on the LOCOMO benchmark
- **91% Faster Responses** than full-context, ensuring low-latency at scale
- **90% Lower Token Usage** than full-context, cutting costs without compromise
+| Benchmark | Old | New  | Tokens  | Latency p50  |
+| --- | --- | --- | --- | --- |
+| **LoCoMo** | 71.4 | **91.6** | 7.0K  | 0.88s  |
+| **LongMemEval** | 67.8 | **93.4** | 6.8K  | 1.09s  |
+| **BEAM (1M)** | — | **64.1** | 6.7K  | 1.00s  |
+| **BEAM (10M)** | — | **48.6** | 6.9K  | 1.05s  |
+
+All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops).
+
+**What changed:**
+- **Single-pass ADD-only extraction** -- one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten.
+- **Agent-generated facts are first-class** -- when an agent confirms an action, that information is now stored with equal weight.
+- **Entity linking** -- entities are extracted, embedded, and linked across memories for retrieval boosting.
+- **Multi-signal retrieval** -- semantic, BM25 keyword, and entity matching scored in parallel and fused.
+
+See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgrade instructions. The [evaluation framework](https://github.com/mem0ai/memory-benchmarks) is open-sourced so anyone can reproduce the numbers.
+
+## Research Highlights
+- **91.6 on LoCoMo** -- +20 points over the previous algorithm
+- **93.4 on LongMemEval** -- +26 points, with +53.6 on assistant memory recall
+- **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
 - [Read the full paper](https://mem0.ai/research)

 # Introduction
@@ -116,7 +130,7 @@ See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full comm

 ### Basic Usage

-Mem0 requires an LLM to function, with `gpt-4.1-nano-2025-04-14` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).

 Mem0 uses `text-embedding-3-small` from OpenAI as the default embedding model. For best results with hybrid search (semantic + keyword + entity boosting), we recommend using at least [Qwen 600M](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) or a comparable embedding model. See [Supported Embeddings](https://docs.mem0.ai/components/embedders/overview) for configuration details.

@@ -131,13 +145,13 @@ memory = Memory()

 def chat_with_memories(message: str, user_id: str = "default_user") -> str:
    # Retrieve relevant memories
-    relevant_memories = memory.search(query=message, user_id=user_id, limit=3)
+    relevant_memories = memory.search(query=message, filters={"user_id": user_id}, top_k=3)
    memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"])

    # Generate Assistant response
    system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}"
    messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}]
-    response = openai_client.chat.completions.create(model="gpt-4.1-nano-2025-04-14", messages=messages)
+    response = openai_client.chat.completions.create(model="gpt-5-mini", messages=messages)
    assistant_response = response.choices[0].message.content

    # Create new memories from the conversation
@@ -4,6 +4,26 @@ description: "Major product launches, headline features, and milestones for Mem0
 mode: "wide"
 ---

+<Update label="2026-04-14" description="Mem0 SDK v2.0.0 / v3.0.0">
+
+**New Memory Algorithm — State-of-the-Art Accuracy at 90% Lower Cost**
+
+Ground-up rewrite of the memory pipeline with 20+ point benchmark improvements:
+
+- **LoCoMo:** 71.4 → **91.6** (+20) — multi-turn conversation recall
+- **LongMemEval:** 67.8 → **93.4** (+26) — long-term memory across sessions
+- **BEAM (1M tokens):** **64.1** — production-scale memory evaluation
+- **Agent memories are first-class** — Previous algorithm: 46% on assistant recall. New: **100%**
+- **Temporal reasoning works** — "Where did I live before SF?" Previous: 51%. New: **93%**
+- **90% fewer tokens** — Under 7K tokens per retrieval vs 25K+ for full-context approaches
+- **ADD-only extraction** — Memories accumulate; nothing is overwritten or deleted
+- **Hybrid retrieval** — Semantic + BM25 keyword + entity boost, scored in parallel
+- **Entity linking** — Entities extracted, embedded, and linked across memories
+
+Breaking changes: Graph memory removed from OSS, `search()` defaults changed, deprecated params removed. See [migration guide](/migration/oss-v2-to-v3).
+
+</Update>
+
 <Update label="2026-04-06" description="Mem0 Skill Graph">

 **Mem0 Skill Graph — In-Context Documentation for AI Agents**
@@ -31,7 +51,7 @@ A full-featured command-line interface for Mem0, available in both Python and No

 </Update>

-<Update label="2026-04-04" description="OpenClaw v1.0.4">
+<Update label="2026-04-06" description="OpenClaw v1.0.4">

 **OpenClaw Plugin — Production-Ready**

@@ -7,7 +7,57 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">

-<Update label="2026-04-04" description="v1.0.11">
+<Update label="2026-04-14" description="v2.0.0">
+
+**Major Release** — Python SDK with V3 memory pipeline, ADD-only extraction, and cleaned-up API surface.
+
+**New Features:**
+- **Single-Pass Extraction:** Replaced 2-LLM-call pipeline with additive extraction using `ADDITIVE_EXTRACTION_PROMPT`. Memories accumulate via `linked_memory_ids` — no more UPDATE/DELETE events ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Hybrid Search:** Combined semantic + BM25 keyword matching + entity boost with additive scoring. Native `keyword_search()` added to 15 vector store adapters (Qdrant, Elasticsearch, OpenSearch, Azure AI Search, Weaviate, Redis, PGVector, Pinecone, Databricks, MongoDB, Milvus, Baidu, Upstash, Azure MySQL, Vertex AI) ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Entity Extraction & Linking:** spaCy-based entity extraction with second vector collection (`{collection}_entities`) for cross-memory relationship retrieval. Optional dependency: `pip install mem0ai[nlp]` ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Batch Operations:** Batch embedding, batch persist, and batch entity linking (8-phase pipeline) for both sync `Memory` and async `AsyncMemory` at full parity ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Message Persistence:** SQLite-based rolling window (10 messages per session scope) for LLM context ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Valkey Cluster Mode:** Added `cluster_mode` parameter for Valkey Cluster Mode Enabled (CME) deployments ([#4759](https://github.com/mem0ai/mem0/pull/4759))
+- **V3 API Endpoints:** `MemoryClient.add()` now posts to `/v3/memories/add/`; `MemoryClient.get_all()` posts to `/v3/memories/` and returns a paginated envelope `{"count": int, "next": str | None, "previous": str | None, "results": [...]}` ([#4856](https://github.com/mem0ai/mem0/pull/4856))
+- **Default model:** `gpt-5-mini` is now the default across `OpenAILLM`, `OpenAIStructuredLLM`, `AzureOpenAILLM`, `AzureOpenAIStructuredLLM`, and `LiteLLM` fallback ([#4829](https://github.com/mem0ai/mem0/pull/4829))
+
+**Breaking Changes:**
+- **`add()` returns ADD-only events** — No more `"UPDATE"` or `"DELETE"` events. Memories accumulate; nothing is overwritten ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`search()` default `threshold` is now `0.1`** — Pass `threshold=0.0` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`search()` `score` is now a combined multi-signal score** — The top-level `score` fuses semantic similarity, BM25 keyword match, and entity boost into one value. Absolute numbers shift versus the old raw cosine score; retune any hard thresholds against representative queries. Per-signal scores are not exposed on the response ([#4805](https://github.com/mem0ai/mem0/pull/4805), [#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **`search()` default `rerank` is now `False`** — Pass `rerank=True` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`top_k` default changed 100 → 20** in `Memory.get_all()` and `Memory.search()` (sync + async). Pass `top_k=100` explicitly to restore the old behavior ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Entity ID validation:** `user_id` / `agent_id` / `run_id` are trimmed; empty-string and whitespace-only values now raise `ValueError` ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Search params validation:** `threshold` must be a number in `[0, 1]`; `top_k` must be a non-negative integer — invalid inputs raise `ValueError` ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`messages` in `Memory.add()` rejects invalid types:** Passing `None` or non-`(str | dict | list)` values raises `Mem0ValidationError` (`error_code="VALIDATION_003"`) ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`qdrant-client>=1.12.0` required** — Upgrade from `>=1.9.1` ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`org_id` and `project_id` removed** — Removed from `MemoryClient` constructor and all method signatures ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Graph Memory Removed (OSS):** `mem0/memory/graph_memory.py`, `memgraph_memory.py`, `kuzu_memory.py`, `apache_age_memory.py`, and `mem0/graphs/` (Neo4j / Memgraph / Kuzu / Apache AGE / Neptune drivers) deleted — ~4,000 lines. Graph memory is no longer supported in the OSS SDK; graph drivers (neo4j, memgraph, kuzu, etc.) can be uninstalled. Use the Platform API for graph features. Remove `enable_graph` and `graph_store` from your config ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **`enable_graph` removed from Client SDK** — Graph memory is now a project-level setting on the Platform. Remove `enable_graph` from `MemoryClient.add()` / `search()` / `get_all()` / `update_project()` calls ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+- **`custom_fact_extraction_prompt` renamed to `custom_instructions`** — Update config and memory module references ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Typed option classes** — Added Pydantic v2 typed classes: `AddMemoryOptions`, `SearchMemoryOptions`, `GetAllMemoryOptions`, `DeleteAllMemoryOptions`, `UpdateMemoryOptions`, `ProjectUpdateOptions` ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+
+**Security:**
+- **FAISS:** Prevent arbitrary code execution via pickle deserialization in `FAISS` vector store ([#4833](https://github.com/mem0ai/mem0/pull/4833))
+
+**Bug Fixes:**
+- **V3 migration crashes:** Fixed crashes in the v3 migration path; entity linking on OSS is now functional across Qdrant and Milvus backends ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **Qdrant entity store:** Entity store now shares the existing Qdrant client when using embedded mode (`path=...`), eliminating RocksDB lock contention between the main and entity collections ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **Reranker:** Fixed incorrect use of SentenceTransformer for cross-encoder reranker models — switched to CrossEncoder API for proper scoring ([#4806](https://github.com/mem0ai/mem0/pull/4806))
+- **S3 Vectors:** Handle `vector=None` in `update()` to prevent boto3 validation error when `event=NONE` ([#4594](https://github.com/mem0ai/mem0/pull/4594))
+- **LLMs:** Made OpenAI `store` parameter opt-in to prevent leaking to non-OpenAI backends like Google Gemini ([#4757](https://github.com/mem0ai/mem0/pull/4757))
+- **LLMs:** Forward `response_format` to Azure OpenAI API to prevent JSON parsing failures ([#4689](https://github.com/mem0ai/mem0/pull/4689))
+- **Core:** Guard `temp_uuid_mapping` lookups against LLM-hallucinated IDs with safe `.get()` and warnings ([#4674](https://github.com/mem0ai/mem0/pull/4674))
+- **Client:** Prevent `MemoryClient.feedback()` telemetry TypeError by merging feedback data into single payload ([#4795](https://github.com/mem0ai/mem0/pull/4795))
+
+**Improvements:**
+- **Telemetry:** Sample OSS hot-path events at 10% via PostHog `before_send` hook to reduce event volume ([#4771](https://github.com/mem0ai/mem0/pull/4771))
+
+See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to-v2) and [Platform migration guide](https://docs.mem0.ai/migration/platform-v2-to-v3) for upgrade instructions.
+
+</Update>
+
+<Update label="2026-04-06" description="v1.0.11">

 **New Features & Updates:**
 - **SDK:** Added `multilingual` parameter to project update ([#4314](https://github.com/mem0ai/mem0/pull/4314))
@@ -843,7 +893,59 @@ mode: "wide"
 </Tab>

 <Tab title="TypeScript">
-<Update label="2026-04-04" description="v2.4.6">
+<Update label="2026-04-14" description="v3.0.0">
+
+**Major Release** — TypeScript SDK with V3 memory pipeline, camelCase parameters, and cleaned-up API surface.
+
+**V3 Memory Pipeline (OSS):**
+- **Single-Pass Extraction:** Additive extraction pipeline aligned with Python SDK — memories accumulate, no UPDATE/DELETE events ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Entity Extraction & Linking:** New `entity_extraction.ts` module (720+ lines) with cross-memory relationship retrieval ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Message Persistence:** SQLite-based message history via new `SQLiteManager.ts` with rolling window for LLM context ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Batch Embeddings:** `embedBatch()` support in OpenAI and Azure embedding providers ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **Scoring & Lemmatization:** New `scoring.ts` and `lemmatization.ts` utilities for hybrid search ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **New Prompts:** `prompts/index.ts` (592+ lines) with additive extraction prompt aligned with Python SDK ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **V3 API Endpoints:** `MemoryClient.add()` now posts to `/v3/memories/add/`; `MemoryClient.getAll()` posts to `/v3/memories/` with paginated envelope `{ count, next, previous, results }` ([#4856](https://github.com/mem0ai/mem0/pull/4856))
+- **Default model:** `gpt-5-mini` is now the default in `OpenAI`, `OpenAIStructured`, and `Azure` LLM providers ([#4829](https://github.com/mem0ai/mem0/pull/4829))
+
+**Breaking Changes:**
+- **Graph Memory Removed (OSS):** `graph_memory.ts` (675 lines), `graphs/tools.ts` (267 lines), `graphs/utils.ts` (116 lines), `graphs/configs.ts` (30 lines) deleted. Graph memory is no longer supported in the OSS SDK — use Platform API for graph features ([#4805](https://github.com/mem0ai/mem0/pull/4805))
+- **camelCase Parameters (Client SDK):** All user-facing parameters converted from snake_case to camelCase. Mapping is transparent at API boundary via `camelToSnakeKeys()` / `snakeToCamelKeys()` ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+  ```typescript
+  // Before
+  client.add(messages, { user_id: "alice", top_k: 5 });
+  // After
+  client.add(messages, { userId: "alice", topK: 5 });
+  ```
+- **Per-Method Option Types:** Replaced monolithic `MemoryOptions` with typed interfaces: `AddMemoryOptions`, `SearchMemoryOptions`, `GetAllMemoryOptions`, `DeleteAllMemoryOptions` ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **Removed Deprecated Parameters:** `org_id`, `project_id`, `api_version`, `output_format`, `async_mode`, `enable_graph`, `limit` removed from client method signatures. `ClientOptions` reduced to `{ apiKey, host }` only ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`limit` renamed to `topK` (OSS):** Update all search calls ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`topK` default changed 100 → 20** in `Memory.getAll()` and `Memory.search()`. Pass `topK: 100` explicitly to restore the old behavior ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Entity ID validation:** `userId` / `agentId` / `runId` are trimmed; empty-string and whitespace-only values now throw ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **Search params validation:** `threshold` must be in `[0, 1]`; `topK` must be a non-negative integer — invalid inputs throw ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`messages` in `Memory.add()` is required:** Passing `undefined` or `null` now throws ([#4843](https://github.com/mem0ai/mem0/pull/4843))
+- **`customPrompt` renamed to `customInstructions` (OSS):** Update memory and vector store configurations ([#4740](https://github.com/mem0ai/mem0/pull/4740))
+- **`enableGraph` removed (OSS):** Config option removed — graph memory no longer available in OSS ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+
+**New Features:**
+- **LLMs:** Added DeepSeek LLM provider with OpenAI-compatible integration using custom baseURL to `api.deepseek.com` ([#4613](https://github.com/mem0ai/mem0/pull/4613))
+- **Entity store isolation:** `MemoryVectorStore` now uses a dedicated `_entities.db` file, preventing entity/memory store collisions ([#4829](https://github.com/mem0ai/mem0/pull/4829), [#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Payload backward compatibility:** Legacy camelCase payload keys normalized to snake_case on read ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+
+**Bug Fixes:**
+- **V3 migration:** Fixed crashes in the OSS migration path; entity linking works end-to-end ([#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **PGVector init race:** `PGVector.initialize()` now memoises the in-flight init promise ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Redis module detection:** Handles both node-redis v4+ and legacy `moduleList` response shapes ([#4841](https://github.com/mem0ai/mem0/pull/4841))
+- **Config:** Fixed `ConfigManager.mergeConfig()` to only include `graphStore` when explicitly provided by user, preventing default Neo4j connection attempts ([#4776](https://github.com/mem0ai/mem0/pull/4776))
+- **LLMs:** Config manager now falls back to `userConf.url` for `baseURL` — prevents custom LLM providers (Ollama, LMStudio) from silently connecting to OpenAI ([#4761](https://github.com/mem0ai/mem0/pull/4761))
+
+**Improvements:**
+- **Telemetry:** Sample OSS hot-path events at 10% to reduce PostHog event volume ([#4771](https://github.com/mem0ai/mem0/pull/4771))
+
+See the [TypeScript SDK migration guide](https://docs.mem0.ai/migration/ts-v2-to-v3) for upgrade instructions.
+
+</Update>
+
+<Update label="2026-04-06" description="v2.4.6">

 **New Features & Updates:**
 - **Client:** Added `multilingual` parameter to project update types ([#4314](https://github.com/mem0ai/mem0/pull/4314))
@@ -21,7 +21,7 @@ os.environ["OPENAI_API_KEY"] = "your-api-key"

 # Initialize a LangChain model directly
 openai_model = ChatOpenAI(
-    model="gpt-4.1-nano-2025-04-14",
+    model="gpt-5-mini",
    temperature=0.2,
    max_tokens=2000
 )
@@ -16,7 +16,7 @@ config = {
    "llm": {
        "provider": "litellm",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.2,
            "max_tokens": 2000,
        }
@@ -20,7 +20,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.2,
            "max_tokens": 2000,
        }
@@ -86,7 +86,7 @@ config = {
    "llm": {
        "provider": "openai_structured",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.0,
        }
    }
@@ -91,7 +91,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14"
+            "model": "gpt-5-mini"
        }
    },
    "reranker": {
@@ -189,7 +189,7 @@ for i, prompt in enumerate(prompts):
    config["reranker"]["config"]["scoring_prompt"] = prompt
    memory = Memory.from_config(config)

-    results = memory.search("test query", user_id="test_user")
+    results = memory.search("test query", filters={"user_id": "test_user"})
    print(f"Prompt {i+1} results: {results}")
 ```

@@ -35,7 +35,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14"
+            "model": "gpt-5-mini"
        }
    },
    "reranker": {
@@ -95,7 +95,7 @@ messages = [
 memory.add(messages, user_id="bob")

 # Search with reranking
-results = memory.search("What is the user's profession?", user_id="bob")
+results = memory.search("What is the user's profession?", filters={"user_id": "bob"})

 for result in results['results']:
    print(f"Memory: {result['memory']}")
@@ -175,7 +175,7 @@ queries = [

 results = []
 for query in queries:
-    result = m.search(query, user_id="alice", rerank=True)
+    result = m.search(query, filters={"user_id": "alice"}, rerank=True)
    results.append(result)
 ```

@@ -111,7 +111,7 @@ messages = [
 memory.add(messages, user_id="david")

 # Search with LLM reranking
-results = memory.search("What programming topics is the user studying?", user_id="david")
+results = memory.search("What programming topics is the user studying?", filters={"user_id": "david"})

 for result in results['results']:
    print(f"Memory: {result['memory']}")
@@ -283,12 +283,12 @@ for result in results["results"]:
 def safe_llm_rerank_search(query, user_id, max_retries=3):
    for attempt in range(max_retries):
        try:
-            return m.search(query, user_id=user_id, rerank=True)
+            return m.search(query, filters={"user_id": user_id}, rerank=True)
        except Exception as e:
            print(f"Attempt {attempt + 1} failed: {e}")
            if attempt == max_retries - 1:
                # Fall back to vector search
-                return m.search(query, user_id=user_id, rerank=False)
+                return m.search(query, filters={"user_id": user_id}, rerank=False)

 # Use the safe function
 results = safe_llm_rerank_search("What are my preferences?", "alice")
@@ -376,19 +376,19 @@ class RobustLLMReranker:
        # Try primary LLM reranker
        for attempt in range(max_retries):
            try:
-                return self.primary.search(query, user_id=user_id, rerank=True)
+                return self.primary.search(query, filters={"user_id": user_id}, rerank=True)
            except Exception as e:
                print(f"Primary reranker attempt {attempt + 1} failed: {e}")

        # Try fallback reranker
        if self.fallback:
            try:
-                return self.fallback.search(query, user_id=user_id, rerank=True)
+                return self.fallback.search(query, filters={"user_id": user_id}, rerank=True)
            except Exception as e:
                print(f"Fallback reranker failed: {e}")

        # Final fallback: vector search only
-        return self.primary.search(query, user_id=user_id, rerank=False)
+        return self.primary.search(query, filters={"user_id": user_id}, rerank=False)

 # Usage
 primary_config = {
@@ -101,7 +101,7 @@ messages = [
 memory.add(messages, user_id="charlie")

 # Search with local reranking
-results = memory.search("What books does the user like?", user_id="charlie")
+results = memory.search("What books does the user like?", filters={"user_id": "charlie"})

 for result in results['results']:
    print(f"Memory: {result['memory']}")
@@ -86,7 +86,7 @@ messages = [
 memory.add(messages, user_id="alice")

 # Search with reranking
-results = memory.search("What Italian food does the user like?", user_id="alice")
+results = memory.search("What Italian food does the user like?", filters={"user_id": "alice"})

 for result in results['results']:
    print(f"Memory: {result['memory']}")
@@ -153,7 +153,7 @@ def measure_reranker_performance(config, queries, user_id):
    latencies = []
    for query in queries:
        start_time = time.time()
-        results = memory.search(query, user_id=user_id)
+        results = memory.search(query, filters={"user_id": user_id})
        latency = time.time() - start_time
        latencies.append(latency)

@@ -191,7 +191,7 @@ class CachedReranker:

    @lru_cache(maxsize=1000)
    def search_cached(self, query_hash, user_id):
-        return self.memory.search(query, user_id=user_id)
+        return self.memory.search(query, filters={"user_id": user_id})

    def search(self, query, user_id):
        query_hash = hashlib.md5(f"{query}_{user_id}".encode()).hexdigest()
@@ -72,7 +72,7 @@ m.add(messages, user_id="alice", metadata={"category": "movies"})
 ### Search Memories

 ```python
-results = m.search("What kind of movies does Alice like?", user_id="alice")
+results = m.search("What kind of movies does Alice like?", filters={"user_id": "alice"})
 ```

 ### Features
@@ -36,7 +36,7 @@ messages = [
 m.add(messages, user_id="alice", metadata={"category": "movies"})

 # Search memories
-results = m.search(query="sci-fi recommendations", user_id="alice")
+results = m.search(query="sci-fi recommendations", filters={"user_id": "alice"})
 ```

 ### Config
@@ -60,7 +60,7 @@ class PersonalAITutor:
        """
        # Start a streaming response request to the AI
        response = self.client.responses.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
            instructions="You are a personal AI Tutor.",
            input=question,
            stream=True
@@ -81,7 +81,7 @@ class PersonalAITutor:
        :param user_id: Optional user ID to filter memories.
        :return: List of memories.
        """
-        return self.memory.get_all(user_id=user_id)
+        return self.memory.get_all(filters={"user_id": user_id})

 # Instantiate the PersonalAITutor
 ai_tutor = PersonalAITutor()
@@ -57,7 +57,7 @@ m = Memory.from_config(config)
 m.add("I'm visiting Paris", user_id="john")

 # Retrieve memories
-memories = m.get_all(user_id="john")
+memories = m.get_all(filters={"user_id": "john"})
 ```

 ## Key Points
@@ -47,7 +47,7 @@ ${memoriesStr}`;
  ];
  
  const response = await openaiClient.chat.completions.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
    messages: messages
  });
  
@@ -36,7 +36,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.1,
            "max_tokens": 2000,
        }
@@ -77,7 +77,7 @@ class PersonalTravelAssistant:

        # Generate response using Responses API
        response = self.client.responses.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
            input=prompt
        )

@@ -89,11 +89,11 @@ class PersonalTravelAssistant:
        return answer

    def get_memories(self, user_id):
-        memories = self.memory.get_all(user_id=user_id)
+        memories = self.memory.get_all(filters={"user_id": user_id})
        return [m['memory'] for m in memories['results']]

    def search_memories(self, query, user_id):
-        memories = self.memory.search(query, user_id=user_id)
+        memories = self.memory.search(query, filters={"user_id": user_id})
        return [m['memory'] for m in memories['results']]

 # Usage example
@@ -143,7 +143,7 @@ class PersonalTravelAssistant:

        # Generate response using gpt-4.1-nano
        response = self.client.chat.completions.create(
-            model="gpt-4.1-nano-2025-04-14"2025-04-14",
+            model="gpt-5-mini",
            messages=self.messages
        )
        answer = response.choices[0].message.content
@@ -126,10 +126,9 @@ async def search_memories(
    print(f"Finding memories related to: {query}")
    results = await mem0_client.search(
        query,
-        user_id=USER_ID,
-        limit=5,
+        filters={"user_id": USER_ID},
+        top_k=5,
        threshold=0.7,  # Higher threshold for more relevant results
-
    )

    # Format and return the results
@@ -161,7 +160,7 @@ def create_memory_voice_agent():
            Use the search_memories tool when you need context from past conversations or user asks you to recall something.
            """,
        ),
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
        tools=[save_memories, search_memories],
    )
    
@@ -342,10 +341,9 @@ async def search_memories(
    print(f"Finding memories related to: {query}")
    results = await mem0_client.search(
        query,
-        user_id=USER_ID,
-        limit=5,
+        filters={"user_id": USER_ID},
+        top_k=5,
        threshold=0.7,  # Higher threshold for more relevant results
-
    )

    # Format and return the results
@@ -368,7 +366,7 @@ def create_memory_voice_agent():
            Use the search_memories tool when you need context from past conversations or user asks you to recall something.
            """,
        ),
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
        tools=[save_memories, search_memories],
    )
    
@@ -62,7 +62,7 @@ mem0_client = MemoryClient(api_key="your-mem0-key")

 def chat(user_input, user_id):
    # Retrieve relevant memories
-    memories = mem0_client.search(user_input, user_id=user_id, limit=5)
+    memories = mem0_client.search(user_input, filters={"user_id": user_id}, top_k=5)
    context = "\\n".join(m["memory"] for m in memories["results"])

    # Call LLM with memory context
@@ -123,7 +123,7 @@ ollama_chat = OpenAI(base_url=f"{OLLAMA_URL}/v1", api_key="ollama")

 def chat(user_input, user_id):
    # Retrieve relevant memories
-    memories = memory.search(user_input, user_id=user_id, limit=5)
+    memories = memory.search(user_input, filters={"user_id": user_id}, top_k=5)
    context = "\n".join(m["memory"] for m in memories["results"])

    # Call LLM with memory context (Ollama via OpenAI-compatible API)
@@ -319,7 +319,7 @@ print([m["memory"] for m in memories["results"]])
  </Tab>
  <Tab title="Open Source">
 ```python
-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 print([m["memory"] for m in memories["results"]])
 # Output: ["Max wants to run marathon under 4 hours", "hey", "lol ok", "cool thanks", "gtg bye"]
 ```
@@ -397,7 +397,7 @@ print([m["memory"] for m in memories["results"]])
 chat("hey how's it going", user_id="max")
 chat("I prefer trail running over roads", user_id="max")

-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 print([m["memory"] for m in memories["results"]])
 # Output: ["Max wants to run marathon under 4 hours", "Max prefers trail running over roads"]
 ```
@@ -446,7 +446,7 @@ Retrieve agent style alongside user memories:
  <Tab title="Platform">
 ```python
 # Get coach personality
-agent_memories = mem0_client.search("coaching style", agent_id="ray_coach")
+agent_memories = mem0_client.search("coaching style", filters={"agent_id": "ray_coach"})
 # Output: ["Max wants direct, data-driven feedback. Skip motivational language."]

 # Store conversations with agent_id
@@ -459,7 +459,7 @@ mem0_client.add([
  <Tab title="Open Source">
 ```python
 # Get coach personality
-agent_memories = memory.search("coaching style", agent_id="ray_coach")
+agent_memories = memory.search("coaching style", filters={"agent_id": "ray_coach"})
 # Output: ["Max wants direct, data-driven feedback. Skip motivational language."]

 # Store conversations with agent_id
@@ -706,13 +706,13 @@ memory.add(
 <Tabs>
  <Tab title="Platform">
 ```python
-memories = mem0_client.search("training plan", user_id="max", limit=5)
+memories = mem0_client.search("training plan", filters={"user_id": "max"}, top_k=5)
 # Gets: marathon goal, trail preference, ankle injury (if still valid)
 ```
  </Tab>
  <Tab title="Open Source">
 ```python
-memories = memory.search("training plan", user_id="max", limit=5)
+memories = memory.search("training plan", filters={"user_id": "max"}, top_k=5)
 # Gets: marathon goal, trail preference, ankle injury (if still valid / not pruned)
 ```
  </Tab>
@@ -806,7 +806,7 @@ mem0_client.update(goal_memory["id"], "Max wants to run sub-3:45 marathon")
  <Tab title="Open Source">
 ```python
 # Find the old memory
-memories = memory.get_all(user_id="max")
+memories = memory.get_all(filters={"user_id": "max"})
 goal_memory = [m for m in memories["results"] if "sub-4" in m["memory"]][0]

 # Update it
@@ -83,7 +83,7 @@ class MultiAgentLearningSystem:

    def __init__(self, student_id: str):
        self.student_id = student_id
-        self.llm = OpenAI(model="gpt-4.1-nano-2025-04-14", temperature=0.2)
+        self.llm = OpenAI(model="gpt-5-mini", temperature=0.2)

        # Memory context for this student
        self.memory_context = {"user_id": student_id, "app": "learning_assistant"}
@@ -22,7 +22,7 @@ import os
 from llama_index.llms.openai import OpenAI

 os.environ["OPENAI_API_KEY"] = "<your-openai-api-key>"
-llm = OpenAI(model="gpt-4.1-nano-2025-04-14")
+llm = OpenAI(model="gpt-5-mini")
 ```

 Initialize the Mem0 client. You can find your API key <a href="https://app.mem0.ai/dashboard/api-keys" rel="nofollow">here</a>. Read about Mem0 [Open Source](https://docs.mem0.ai/open-source/overview).
@@ -1,766 +0,0 @@
---
-title: MiroFish Swarm Memory
-description: "Build a multi-agent swarm simulation with graph-powered memory using Mem0 and MiroFish patterns."
---
-
-<Snippet file="blank-notif.mdx" />
-
-Build a multi-agent swarm simulation with graph-powered memory using Mem0 OSS and [MiroFish](https://github.com/666ghj/MiroFish) patterns. MiroFish is a graph-centric system — it extracts entities and relationships from documents, builds a knowledge graph, and queries it throughout its pipeline. Mem0's Graph Memory is a natural replacement for its Zep Cloud integration.
-
-<Note>
-  This cookbook demonstrates the **core memory patterns** using a simplified simulation. MiroFish's actual architecture uses a factory pattern (`memory_factory.py`) with abstract providers, batch buffering with retries in `ZepGraphMemoryUpdater`, and IPC-based agent interviews. This cookbook focuses on the Mem0 API integration points — wrap these calls in your own retry/batch logic for production use.
-</Note>
-
-## Overview
-
-This cookbook implements a **Housing Policy Prediction Simulation** following MiroFish's five-stage workflow:
-
-1. **Graph Building** — Ingest seed documents, extract entities and relationships
-2. **Environment Setup** — Query the knowledge graph to enrich agent profiles
-3. **Simulation** — Track agent interactions with per-agent memory isolation
-4. **Report Generation** — Semantic search + graph traversal for analysis
-5. **Deep Interaction** — Query post-simulation memory and relationships (MiroFish also supports live agent interviews via IPC — not covered here)
-
-Three agents debate a housing policy reform:
- **Mayor Chen** — Policy advocate pushing for zoning reform
- **Wang (Homeowner)** — Opposition leader organizing resistance
- **Professor Li** — Academic providing data-driven analysis
-
-## Prerequisites
-
-```bash
-pip install "mem0ai[graph]"
-```
-
-You need a graph backend. Choose one:
-
-| Backend | Setup | Best for |
-|---|---|---|
-| **Neo4j Aura** (free tier) | [Sign up](https://neo4j.com/product/auradb/), get Bolt URI | Production, closest to Zep |
-| **Neo4j Docker** | `docker run -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5` | Local development |
-| **Kuzu** (embedded) | No setup needed — runs in-process | Quick testing, zero dependencies |
-
-```bash
-export OPENAI_API_KEY="sk-..."
-
-# Option A: Neo4j Docker (local development)
-docker run -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:5
-export NEO4J_URL="neo4j://localhost:7687"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="password"
-
-# Option B: Neo4j Aura (production — free tier available)
-export NEO4J_URL="neo4j+s://<your-instance>.databases.neo4j.io"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="your-aura-password"
-
-# Option C: Kuzu (zero setup — auto-detected when NEO4J_URL is not set)
-# No exports needed
-```
-
-## Complete Implementation
-
-```python
-"""
-MiroFish Swarm Prediction Simulation with Mem0 Graph Memory
-
-MiroFish uses Zep Cloud as its knowledge graph backend. This implementation
-replaces Zep with Mem0 OSS Graph Memory, which provides:
- Automatic entity extraction from text
- Relationship mining (source → relationship → destination triples)
- Combined vector + graph search returning memories AND relations
- Per-agent isolation via run_id
- Self-hosted with no node caps
-
-Follows MiroFish's 5-stage pipeline:
-1. Graph Building    - Ingest seed documents, extract entities
-2. Environment Setup - Query graph to enrich agent profiles
-3. Simulation        - Track agent actions with per-agent isolation
-4. Report Generation - Semantic + graph search for analysis
-5. Deep Interaction  - Query post-simulation knowledge graph
-
-Run:
-    export OPENAI_API_KEY="sk-..."
-    export NEO4J_URL="neo4j://localhost:7687"
-    export NEO4J_USERNAME="neo4j"
-    export NEO4J_PASSWORD="password"
-    python mirofish_swarm_memory.py
-"""
-
-import os
-import time
-from mem0 import Memory
-
-
-# ======================================================================
-# MiroFish Agent Action Types (matches OASIS simulation output)
-# ======================================================================
-
-# Twitter actions
-TWITTER_ACTIONS = [
-    "CREATE_POST", "LIKE_POST", "REPOST", "FOLLOW",
-    "DO_NOTHING", "QUOTE_POST",
-]
-
-# Reddit actions (superset — includes moderation + discovery)
-REDDIT_ACTIONS = [
-    "LIKE_POST", "DISLIKE_POST", "CREATE_POST", "CREATE_COMMENT",
-    "LIKE_COMMENT", "DISLIKE_COMMENT", "SEARCH_POSTS", "SEARCH_USER",
-    "TREND", "REFRESH", "DO_NOTHING", "FOLLOW", "MUTE",
-]
-
-# Combined (DO_NOTHING is skipped during memory storage)
-MIROFISH_ACTIONS = list(set(TWITTER_ACTIONS + REDDIT_ACTIONS) - {"DO_NOTHING"})
-
-
-# ======================================================================
-# Graph Memory Configuration
-# ======================================================================
-
-def build_config():
-    """Build Mem0 config with Graph Memory.
-
-    Uses Neo4j if credentials are set, otherwise falls back to Kuzu (embedded).
-    """
-    neo4j_url = os.environ.get("NEO4J_URL")
-
-    # Shared config for LLM, embedder, and vector store
-    base = {
-        "llm": {
-            "provider": "openai",
-            "config": {"model": "gpt-4o-mini", "temperature": 0.1}
-        },
-        "embedder": {
-            "provider": "openai",
-            "config": {"model": "text-embedding-3-small", "embedding_dims": 1536}
-        },
-        "vector_store": {
-            "provider": "qdrant",
-            "config": {
-                "collection_name": "mirofish",
-                "embedding_model_dims": 1536,
-            }
-        },
-    }
-
-    custom_prompt = (
-        "Extract all people, organizations, policies, locations, "
-        "and their relationships. Capture support/opposition stances, "
-        "affiliations, and quantitative claims."
-    )
-
-    if neo4j_url:
-        base["graph_store"] = {
-            "provider": "neo4j",
-            "config": {
-                "url": neo4j_url,
-                "username": os.environ.get("NEO4J_USERNAME", "neo4j"),
-                "password": os.environ.get("NEO4J_PASSWORD", "password"),
-            },
-            "custom_prompt": custom_prompt,
-        }
-    else:
-        # Fallback: Kuzu embedded (no external services needed)
-        print("  NEO4J_URL not set — using Kuzu (embedded) graph store")
-        base["graph_store"] = {
-            "provider": "kuzu",
-            "config": {"db": "/tmp/mirofish_graph.kuzu"},
-            "custom_prompt": custom_prompt,
-        }
-
-    return base
-
-
-# ======================================================================
-# Simulation Engine
-# ======================================================================
-
-class MiroFishSimulation:
-    """
-    Multi-agent simulation with graph-powered memory.
-
-    Uses Mem0 Graph Memory to replace MiroFish's Zep Cloud integration:
-    - Entities and relationships are extracted automatically from text
-    - search() returns both semantic memories AND graph relations
-    - Per-agent isolation via run_id
-    - Project isolation via user_id
-    """
-
-    def __init__(self, project_id: str, config: dict):
-        self.project_id = project_id
-        self.memory = Memory.from_config(config)
-        self.stats = {
-            "documents_ingested": 0,
-            "activities_recorded": 0,
-            "rounds_completed": 0,
-        }
-
-    # ------------------------------------------------------------------
-    # Stage 1: Graph Building — Seed Document Ingestion
-    # ------------------------------------------------------------------
-
-    def ingest_documents(self, documents: list[str]):
-        """Ingest seed documents and extract entities + relationships.
-
-        MiroFish equivalent: GraphBuilderService.build_graph()
-        Zep equivalent: graph.add_batch() with episode polling
-
-        With Mem0 Graph Memory, each document is processed by the LLM
-        to extract entities (people, orgs, policies) and relationships
-        (supports, opposes, filed). These become nodes and edges in the
-        graph store, alongside vector embeddings for semantic search.
-        """
-        print("  Ingesting documents and building knowledge graph...")
-        for i, doc in enumerate(documents):
-            result = self.memory.add(
-                [{"role": "user", "content": doc}],
-                user_id=self.project_id,
-                metadata={"stage": "graph_building", "source": "seed_document", "chunk_index": i}
-            )
-            # Graph Memory returns extracted relations
-            relations = result.get("relations", {})
-            added = relations.get("added_entities", [])
-            if added:
-                print(f"    Doc {i}: extracted {len(added)} entities/relations")
-
-        self.stats["documents_ingested"] = len(documents)
-        print(f"  Ingested {len(documents)} documents")
-
-    # ------------------------------------------------------------------
-    # Stage 2: Environment Setup — Agent Profile Enrichment
-    # ------------------------------------------------------------------
-
-    def enrich_agent_profile(self, agent_name: str, persona_query: str) -> dict:
-        """Search memory + graph for context relevant to an agent's persona.
-
-        MiroFish equivalent: OasisProfileGenerator using graph.search()
-
-        Returns both semantic memories and graph relations that can be
-        injected into the agent's system prompt.
-        """
-        results = self.memory.search(
-            persona_query,
-            user_id=self.project_id,
-            limit=10
-        )
-        facts = [r["memory"] for r in results.get("results", [])]
-        relations = results.get("relations", [])
-
-        print(f"  {agent_name}: {len(facts)} facts, {len(relations)} relations")
-        return {"facts": facts, "relations": relations}
-
-    # ------------------------------------------------------------------
-    # Stage 3: Simulation — Agent Activity Tracking
-    # ------------------------------------------------------------------
-
-    def record_action(self, agent_id: str, agent_name: str,
-                      action_type: str, content: str,
-                      platform: str, round_num: int):
-        """Record a single agent action as a memory with graph extraction.
-
-        MiroFish equivalent: ZepGraphMemoryUpdater.add_activity()
-        Zep equivalent: graph.add(type="text", data=episode_text)
-
-        Agent memories use run_id to group by agent (no assistant
-        memories involved). Graph Memory extracts entities/relationships
-        from the action content automatically.
-        """
-        formatted = f"{agent_name} [{action_type}]: {content}"
-
-        self.memory.add(
-            [{"role": "user", "content": formatted}],
-            run_id=agent_id,
-            metadata={
-                "action_type": action_type,
-                "platform": platform,
-                "round": round_num,
-                "agent_name": agent_name,
-            }
-        )
-        self.stats["activities_recorded"] += 1
-
-    def run_round(self, round_num: int, activities: list[tuple]):
-        """Execute one simulation round."""
-        print(f"  Round {round_num}: {len(activities)} actions")
-        for agent_id, agent_name, action_type, content, platform in activities:
-            self.record_action(agent_id, agent_name, action_type, content, platform, round_num)
-        self.stats["rounds_completed"] = max(self.stats["rounds_completed"], round_num)
-
-    def recall_agent_memory(self, agent_id: str, query: str) -> dict:
-        """Agent recalls its own memories mid-simulation.
-
-        Searches by run_id to match the scope used during add().
-        """
-        results = self.memory.search(
-            query,
-            run_id=agent_id,
-            limit=5
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    # ------------------------------------------------------------------
-    # Stage 4: Report Generation — Semantic + Graph Retrieval
-    # ------------------------------------------------------------------
-
-    def quick_search(self, query: str, limit: int = 10) -> dict:
-        """Semantic search + graph relations across all agents.
-
-        MiroFish equivalent: ZepToolsService.quick_search()
-        Returns both vector-matched memories and related graph triples.
-        """
-        results = self.memory.search(
-            query,
-            user_id=self.project_id,
-            limit=limit
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    def panorama_search(self) -> dict:
-        """Retrieve all memories + all graph relations.
-
-        MiroFish equivalent: ZepToolsService.panorama_search()
-        Returns the complete knowledge state for report generation.
-        """
-        results = self.memory.get_all(user_id=self.project_id)
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    def agent_search(self, agent_id: str, query: str, limit: int = 10) -> dict:
-        """Search within a single agent's memory space."""
-        results = self.memory.search(
-            query,
-            run_id=agent_id,
-            limit=limit
-        )
-        return {
-            "memories": [r["memory"] for r in results.get("results", [])],
-            "relations": results.get("relations", []),
-        }
-
-    # ------------------------------------------------------------------
-    # Cleanup
-    # ------------------------------------------------------------------
-
-    def cleanup(self):
-        """Delete all memories and graph data for this simulation."""
-        self.memory.delete_all(user_id=self.project_id)
-        print(f"  Cleaned up all memories for {self.project_id}")
-
-
-# ======================================================================
-# Run the full 5-stage pipeline
-# ======================================================================
-
-def main():
-    project_id = f"mirofish_housing_{int(time.time())}"
-    config = build_config()
-    sim = MiroFishSimulation(project_id=project_id, config=config)
-
-    # ==================================================================
-    # STAGE 1: Graph Building — Ingest seed documents
-    # ==================================================================
-    print("=" * 60)
-    print("STAGE 1: Graph Building")
-    print("=" * 60)
-
-    sim.ingest_documents([
-        "The city council proposed a new zoning reform allowing higher "
-        "density housing in suburban areas. Mayor Chen expressed strong "
-        "support, citing a 40% housing shortage affecting young professionals. "
-        "The reform would allow buildings up to 8 stories in previously "
-        "restricted 3-story zones.",
-
-        "Local homeowners association president Wang opposes the reform, "
-        "arguing it will decrease property values by 15-20%. The association "
-        "represents 5,000 homeowners in the affected districts. Wang has "
-        "organized three community meetings and collected 2,000 signatures.",
-
-        "Professor Li from Beijing University published research showing "
-        "similar reforms in Shenzhen led to 15% price drops in existing "
-        "homes but created 30% more affordable housing units within 3 years. "
-        "The study covered 12 districts and 50,000 housing units.",
-    ])
-
-    # ==================================================================
-    # STAGE 2: Environment Setup — Enrich agent profiles
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 2: Environment Setup")
-    print("=" * 60)
-
-    mayor_context = sim.enrich_agent_profile(
-        "Mayor Chen",
-        "Mayor Chen housing reform zoning policy"
-    )
-    wang_context = sim.enrich_agent_profile(
-        "Wang",
-        "Wang homeowner opposition property values petition"
-    )
-    li_context = sim.enrich_agent_profile(
-        "Professor Li",
-        "Professor Li research housing data Shenzhen"
-    )
-
-    print("\n  Example profile context for Mayor Chen:")
-    for fact in mayor_context["facts"][:3]:
-        print(f"    Fact: {fact}")
-    for rel in mayor_context["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 3: Simulation — Run agent interactions
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 3: Simulation")
-    print("=" * 60)
-
-    # Round 1: Opening statements
-    sim.run_round(1, [
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "This reform will create 10,000 new housing units by 2028. "
-         "Young families deserve affordable homes. #HousingForAll",
-         "twitter"),
-
-        ("wang_homeowner", "Wang", "CREATE_POST",
-         "Our property values will plummet! The council ignores the "
-         "voices of 5,000 homeowners. #StopTheReform",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_POST",
-         "New analysis: Shenzhen zoning data shows net positive outcomes "
-         "after 3 years. Short-term pain, long-term gain for housing equity.",
-         "twitter"),
-    ])
-
-    # Round 2: Debate and interaction
-    sim.run_round(2, [
-        ("wang_homeowner", "Wang", "CREATE_COMMENT",
-         "Replied to Professor Li: 'Shenzhen is a tier-1 city with "
-         "completely different dynamics. Your comparison is misleading.'",
-         "twitter"),
-
-        ("mayor_chen", "Mayor Chen", "LIKE_POST",
-         "Liked Professor Li's post about Shenzhen housing data.",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_COMMENT",
-         "Replied to Wang: 'The methodology controls for city tier "
-         "and population density. I invite you to review the full dataset.'",
-         "twitter"),
-
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "Data from @ProfLi confirms what we've been saying: zoning "
-         "reform works. Let's move forward with evidence, not fear.",
-         "twitter"),
-    ])
-
-    # Round 3: Escalation and platform expansion
-    sim.run_round(3, [
-        ("wang_homeowner", "Wang", "CREATE_POST",
-         "Filing formal petition with 3,000 signatures against the "
-         "zoning reform. Council meeting next Tuesday. All homeowners "
-         "must attend!",
-         "reddit"),
-
-        ("mayor_chen", "Mayor Chen", "CREATE_POST",
-         "Announcing public town hall on zoning reform this Saturday. "
-         "All voices welcome. Data-driven decisions benefit everyone.",
-         "twitter"),
-
-        ("prof_li", "Professor Li", "CREATE_POST",
-         "Published full dataset and methodology on my university page. "
-         "Transparency is essential for informed public debate.",
-         "twitter"),
-
-        ("wang_homeowner", "Wang", "FOLLOW",
-         "Followed @MayorChen to monitor policy updates.",
-         "twitter"),
-    ])
-
-    # Mid-simulation: agent recalls own memory + graph
-    print("\n  Mid-simulation recall for Mayor Chen:")
-    mayor_recall = sim.recall_agent_memory(
-        "mayor_chen",
-        "What positions have I taken on housing reform?"
-    )
-    for mem in mayor_recall["memories"]:
-        print(f"    Memory: {mem}")
-    for rel in mayor_recall["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 4: Report Generation — Retrieve memories + graph for analysis
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 4: Report Generation")
-    print("=" * 60)
-
-    # Quick search: targeted query
-    print("\n  Quick Search: 'opposition to housing reform'")
-    opposition = sim.quick_search("opposition to housing reform", limit=5)
-    for mem in opposition["memories"]:
-        print(f"    Memory: {mem}")
-    for rel in opposition["relations"][:3]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # Agent-specific search
-    print("\n  Agent Search: Wang's activities")
-    wang_activities = sim.agent_search("wang_homeowner", "all actions and statements")
-    for mem in wang_activities["memories"]:
-        print(f"    Memory: {mem}")
-
-    # Panorama: full overview
-    print("\n  Panorama Search: all memories + relations")
-    panorama = sim.panorama_search()
-    print(f"    Total memories: {len(panorama['memories'])}")
-    print(f"    Total relations: {len(panorama['relations'])}")
-    for mem in panorama["memories"][:5]:
-        print(f"    Memory: {mem}")
-    if len(panorama["memories"]) > 5:
-        print(f"    ... and {len(panorama['memories']) - 5} more")
-    for rel in panorama["relations"][:5]:
-        src = rel.get("source", "?")
-        edge = rel.get("relationship", "?")
-        dst = rel.get("destination", rel.get("target", "?"))
-        print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # STAGE 5: Deep Interaction — Post-simulation queries
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("STAGE 5: Deep Interaction")
-    print("=" * 60)
-
-    queries = [
-        "How did the debate evolve across the three rounds?",
-        "What evidence was cited by each side?",
-        "Who supports and who opposes the reform?",
-    ]
-
-    for query in queries:
-        print(f"\n  Query: '{query}'")
-        results = sim.quick_search(query, limit=3)
-        for mem in results["memories"][:2]:
-            print(f"    Memory: {mem}")
-        for rel in results["relations"][:2]:
-            src = rel.get("source", rel.get("source_node", "?"))
-            edge = rel.get("relationship", rel.get("relation", "?"))
-            dst = rel.get("destination", rel.get("destination_node", "?"))
-            print(f"    Relation: {src} --[{edge}]--> {dst}")
-
-    # ==================================================================
-    # Summary
-    # ==================================================================
-    print("\n" + "=" * 60)
-    print("SIMULATION COMPLETE")
-    print("=" * 60)
-    print(f"  Project ID:        {project_id}")
-    print(f"  Documents ingested: {sim.stats['documents_ingested']}")
-    print(f"  Activities tracked: {sim.stats['activities_recorded']}")
-    print(f"  Rounds completed:  {sim.stats['rounds_completed']}")
-    print(f"  Total memories:    {len(panorama['memories'])}")
-    print(f"  Total relations:   {len(panorama['relations'])}")
-
-    # Cleanup (uncomment to delete all memories + graph data)
-    # sim.cleanup()
-
-
-if __name__ == "__main__":
-    print("MiroFish Swarm Prediction Simulation powered by Mem0 Graph Memory\n")
-    main()
-```
-
-## How It Works
-
-### Graph Memory: The Right Fit for MiroFish
-
-MiroFish's entire pipeline revolves around a **knowledge graph** — it extracts entities from documents, builds relationships, and queries the graph throughout simulation and reporting. Mem0's Graph Memory provides the same capabilities:
-
-| MiroFish needs | Zep Cloud | Mem0 Graph Memory |
-|---|---|---|
-| **Entity extraction** | Built-in via Zep API | Automatic via LLM extraction |
-| **Relationship mining** | Graph edges | `(source) --[relationship]--> (destination)` triples |
-| **Semantic + keyword search** | Semantic + BM25 | Vector similarity + graph relation retrieval |
-| **Graph traversal** | Node/edge queries | `relations` array in search results |
-| **Per-agent isolation** | Single shared graph in MiroFish | Native `run_id` scoping |
-| **Self-hosting** | No (cloud only) | Yes — Neo4j, Memgraph, Kuzu, Neptune |
-| **Node/memory limits** | Capped on free tier | Unlimited (self-hosted) |
-
-### How search() Returns Both Memories and Relations
-
-When Graph Memory is enabled, every `search()` call returns two arrays:
-
-```python
-results = memory.search("housing reform", user_id="my_sim")
-
-# Vector-matched memories (ordered by similarity)
-results["results"]   # [{"memory": "...", "score": 0.85, ...}, ...]
-
-# Graph relations connected to query entities
-results["relations"] # [{"source": "mayor_chen", "relationship": "supports", "destination": "zoning_reform"}, ...]
-```
-
-This is what makes Mem0 Graph Memory a natural replacement for Zep — you get semantic search AND structured graph data in a single call.
-
-### Per-Agent Memory Isolation
-
-`user_id` scopes the simulation project. `run_id` tags individual agent actions at storage time (we use `run_id` instead of `agent_id` since no assistant memories are involved). Searches use `user_id` for project-wide retrieval:
-
-```python
-# Store project-level memories (seed documents)
-memory.add(
-    [{"role": "user", "content": "Mayor Chen supports the zoning reform."}],
-    user_id="my_sim"
-)
-
-# Store agent-specific memories (simulation actions)
-memory.add(
-    [{"role": "user", "content": "Mayor Chen [CREATE_POST]: Reform works!"}],
-    run_id="mayor_chen"
-)
-
-# Search project-level memories (seed docs)
-memory.search("housing reform", user_id="my_sim")
-
-# Search agent-specific memories (actions stored with run_id)
-memory.search("housing reform", run_id="mayor_chen")
-
-# Get all project-level memories + graph relations
-memory.get_all(user_id="my_sim")
-```
-
-<Note>
-  Use `user_id` for project-level data (seed documents) and `run_id` for agent actions — both for `add()` and `search()`. Always match the scope: if you `add()` with `run_id`, `search()` with `run_id`. Use the message list format `[{"role": "user", "content": "..."}]` for all `add()` calls — it works on both OSS and Cloud.
-</Note>
-
-### Stage Mapping
-
-| MiroFish Stage | What Happens | Mem0 Graph Memory Call |
-|---|---|---|
-| **1. Graph Building** | Ingest docs, extract entities | `memory.add(doc, user_id=project)` — entities/relations extracted automatically |
-| **2. Environment Setup** | Enrich agent personas from graph | `memory.search(query, user_id=project)` — returns facts + relations |
-| **3. Simulation** | Track per-agent actions | `memory.add(messages, run_id=agent)` |
-| **3. Simulation** | Mid-round recall | `memory.search(query, run_id=agent)` |
-| **4. Report Generation** | Targeted analysis | `memory.search(query, user_id=project)` — memories + graph |
-| **4. Report Generation** | Full overview | `memory.get_all(user_id=project)` — all memories + all relations |
-| **5. Deep Interaction** | Follow-up queries | `memory.search(query, user_id=project)` |
-
-### Zep-to-Mem0 Migration Reference
-
-For developers replacing MiroFish's Zep integration. Note that Mem0 Graph Memory covers the core graph operations but some Zep features have no direct equivalent — see caveats below.
-
-| MiroFish Service | Zep Call | Mem0 Graph Memory Equivalent | Caveat |
-|---|---|---|---|
-| GraphBuilderService | `client.graph.create()` | Implicit on first `memory.add()` | |
-| GraphBuilderService | `client.graph.set_ontology()` | `custom_prompt` in graph_store config | Freeform text, not a typed schema like Zep's `EntityModel`/`EdgeModel` |
-| GraphBuilderService | `client.graph.add_batch(episodes)` | `memory.add()` per chunk | No batch API — call per chunk |
-| GraphBuilderService | `client.graph.episode.get(uuid)` | Not needed (add is synchronous in OSS) | |
-| GraphBuilderService | `client.graph.delete(id)` | `memory.delete_all(user_id=...)` | |
-| ZepEntityReader | `client.graph.node.get_by_graph_id()` | `memory.get_all(user_id=...)` → `relations` | |
-| ZepEntityReader | `client.graph.node.get(uuid)` | `memory.search(entity_name, user_id=...)` | Semantic search, not exact ID lookup |
-| ZepEntityReader | `client.graph.node.get_entity_edges()` | `memory.search(entity_name, user_id=...)` → `relations` | Returns all matching relations, not edges for a specific node |
-| ZepGraphMemoryUpdater | `client.graph.add(type="text")` | `memory.add(messages, run_id=...)` | No batch buffering or retry — implement in your wrapper |
-| ZepToolsService | `search_graph(query, scope)` | `memory.search(query, user_id=...)` → memories + relations | |
-| ZepToolsService | `get_entities()` | `memory.get_all(user_id=...)` → `relations` | |
-| ZepToolsService | Panorama (all nodes + edges) | `memory.get_all(user_id=...)` | No temporal fact separation (active vs historical) |
-| ZepToolsService | InsightForge (multi-query decomposition) | Not available | Implement LLM-driven sub-query decomposition in your own ReportAgent |
-| OasisProfileGenerator | `client.graph.search()` | `memory.search(query, user_id=...)` | |
-
-<Note>
-  **What Mem0 Graph Memory does not cover**: Zep's typed ontology schemas (`EntityModel`, `EdgeModel`), temporal fact lifecycle (`valid_at`/`invalid_at`/`expired_at`), single-node-by-ID lookup, and InsightForge's multi-query decomposition. For InsightForge-like functionality, implement sub-query logic in your own ReportAgent using `memory.search()` as the retrieval primitive.
-</Note>
-
-### Custom Extraction Prompts
-
-Guide what entities and relationships Mem0 extracts — analogous to (but less structured than) Zep's `set_ontology()`:
-
-```python
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {"url": "...", "username": "...", "password": "..."},
-        "custom_prompt": (
-            "Extract all people, organizations, policies, locations, "
-            "and their relationships. Capture support/opposition stances, "
-            "affiliations, and quantitative claims."
-        ),
-    }
-}
-```
-
-### Action Types
-
-MiroFish's OASIS engine produces these agent action types. Format them as natural language when storing. Skip `DO_NOTHING` actions (no memory value). `TREND` and `REFRESH` are Reddit-only discovery actions — store if you want to track browsing behavior.
-
-| Action Type | Platform | Example Memory Content |
-|---|---|---|
-| `CREATE_POST` | Both | `"Mayor Chen [CREATE_POST]: This reform will create 10,000 units"` |
-| `CREATE_COMMENT` | Reddit | `"Wang [CREATE_COMMENT]: Replied to Prof Li: 'Your data is misleading'"` |
-| `LIKE_POST` | Both | `"Mayor Chen [LIKE_POST]: Liked Prof Li's post about Shenzhen data"` |
-| `REPOST` | Twitter | `"Prof Li [REPOST]: Reposted Mayor Chen's town hall announcement"` |
-| `FOLLOW` | Both | `"Wang [FOLLOW]: Followed @MayorChen"` |
-| `QUOTE_POST` | Twitter | `"Mayor Chen [QUOTE_POST]: 'Data confirms reform works' quoting Prof Li"` |
-| `DISLIKE_POST` | Reddit | `"Wang [DISLIKE_POST]: Downvoted Mayor Chen's reform post"` |
-| `TREND` | Reddit | `"Prof Li [TREND]: Browsed trending topics"` |
-| `DO_NOTHING` | Both | Skip — no memory value |
-
-## Running the Example
-
-```bash
-# Option A: Neo4j (production)
-export OPENAI_API_KEY="sk-..."
-export NEO4J_URL="neo4j://localhost:7687"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="password"
-python mirofish_swarm_memory.py
-
-# Option B: Kuzu (zero dependencies, just need OpenAI key)
-export OPENAI_API_KEY="sk-..."
-python mirofish_swarm_memory.py  # auto-detects missing NEO4J_URL, uses Kuzu
-```
-
-<Note>
-Exact output varies as Mem0 automatically extracts and deduplicates entities. The specific relations and memory counts depend on LLM extraction quality.
-</Note>
-
-## Best Practices
-
-1. **Unique `user_id` per simulation** — Use timestamps or UUIDs (e.g., `mirofish_housing_1742198400`) to prevent memory collisions between runs
-2. **Always set `run_id` for agent actions** — Per-agent isolation prevents memory cross-contamination between agents
-3. **Use `custom_prompt`** — Guide entity extraction to capture domain-specific relationships (people, policies, stances)
-4. **Format actions as natural language** — `"Mayor Chen [CREATE_POST]: content"` extracts better entities than raw JSON
-5. **Query relations for reports** — The `relations` array in search results gives structured `(source, relationship, destination)` triples for building analytical reports
-6. **Cleanup old simulations** — Call `delete_all(user_id=...)` when a simulation run is no longer needed
-
-## Resources
-
- [MiroFish GitHub](https://github.com/666ghj/MiroFish) — Source code and setup guide
- [MiroFish Documentation](https://deepwiki.com/666ghj/MiroFish) — Full framework docs
- [Mem0 Graph Memory](/open-source/features/graph-memory) — Graph Memory documentation
- [Mem0 Documentation](https://docs.mem0.ai/introduction) — Full API reference
-
-<CardGroup cols={2}>
-  <Card title="Graph Memory" icon="network-wired" href="/open-source/features/graph-memory">
-    Full Graph Memory documentation with provider setup.
-  </Card>
-  <Card title="MiroFish GitHub" icon="fish" href="https://github.com/666ghj/MiroFish">
-    MiroFish source code and setup guide.
-  </Card>
-</CardGroup>
@@ -112,7 +112,7 @@ async def search_memory(
        query: The search query.
    """
    user_id = context.context.user_id or "default_user"
-    memories = await client.search(query, user_id=user_id)
+    memories = await client.search(query, filters={"user_id": user_id})
    results = '\n'.join([result["memory"] for result in memories["results"]])
    return str(results)
 ```
@@ -1,17 +1,17 @@
 ---
 title: Bedrock with Persistent Memory
-description: "Pair Mem0 with AWS Bedrock, OpenSearch, and Neptune for a managed stack."
+description: "Pair Mem0 with AWS Bedrock and OpenSearch for a managed stack."
 ---


-This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock**, **OpenSearch Service (AOSS)**, and **AWS Neptune Analytics** for persistent memory capabilities in Python.
+This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock** and **OpenSearch Service (AOSS)** for persistent memory capabilities in Python.

 ## Installation

 Install the required dependencies to include the Amazon data stack, including **boto3**, **opensearch-py**, and **langchain-aws**:

 ```bash
-pip install "mem0ai[graph,extras]"
+pip install "mem0ai[extras]"
 ```

 ## Environment Setup
@@ -38,7 +38,6 @@ This sets up Mem0 with:
 - [AWS Bedrock for LLM](https://docs.mem0.ai/components/llms/models/aws_bedrock)
 - [AWS Bedrock for embeddings](https://docs.mem0.ai/components/embedders/models/aws_bedrock#aws-bedrock)
 - [OpenSearch as the vector store](https://docs.mem0.ai/components/vectordbs/dbs/opensearch)
- [Graph Memory guide](https://docs.mem0.ai/open-source/features/graph-memory)

 ```python
 import boto3
@@ -79,12 +78,6 @@ config = {
            "embedding_model_dims": 1024,
        }
    },
-    "graph_store": {
-        "provider": "neptune",
-        "config": {
-            "endpoint": f"neptune-graph://my-graph-identifier",
-        },
-    },
 }

 # Initialize the memory system
@@ -93,8 +86,6 @@ m = Memory.from_config(config)

 ## Usage

-Reference [Notebook example](https://github.com/mem0ai/mem0/blob/main/examples/graph-db-demo/neptune-example.ipynb)
-
 ### Add a memory

 ```python
@@ -112,13 +103,13 @@ result = m.add(messages, user_id="alice", metadata={"category": "movie_recommend
 ### Search a memory

 ```python
-relevant_memories = m.search(query, user_id="alice")
+relevant_memories = m.search(query, filters={"user_id": "alice"})
 ```

 ### Get all memories

 ```python
-all_memories = m.get_all(user_id="alice")
+all_memories = m.get_all(filters={"user_id": "alice"})
 ```

 ### Get a specific memory
@@ -129,15 +120,12 @@ memory = m.get(memory_id)

 ## Conclusion

-With Mem0 and AWS services like Bedrock, OpenSearch, and Neptune Analytics, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.
+With Mem0 and AWS services like Bedrock and OpenSearch, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.

 ---

 <CardGroup cols={2}>
-  <Card title="Neptune Analytics with Mem0" icon="database" href="/cookbooks/integrations/neptune-analytics">
-    Explore graph-based memory storage with AWS Neptune Analytics.
-  </Card>
-  <Card title="Graph Memory Features" icon="sitemap" href="/open-source/features/graph-memory">
-    Learn how to leverage knowledge graphs for entity relationships.
+  <Card title="Memory Evaluation" icon="chart-line" href="/core-concepts/memory-evaluation">
+    Understand how Mem0's memory system is benchmarked and evaluated.
  </Card>
 </CardGroup>
@@ -1,133 +0,0 @@
---
-title: Graph Memory on Neptune
-description: "Combine Mem0 graph memory with AWS Neptune Analytics and Bedrock."
---
-
-
-This example demonstrates how to configure and use the `mem0ai` SDK with **AWS Bedrock** and **AWS Neptune Analytics** for persistent memory capabilities in Python.
-
-## Installation
-
-Install the required dependencies to include the Amazon data stack, including **boto3** and **langchain-aws**:
-
-```bash
-pip install "mem0ai[graph,extras]"
-```
-
-## Environment Setup
-
-Set your AWS environment variables:
-
-```python
-import os
-
-# Set these in your environment or notebook
-os.environ['AWS_REGION'] = 'us-west-2'
-os.environ['AWS_ACCESS_KEY_ID'] = 'AK00000000000000000'
-os.environ['AWS_SECRET_ACCESS_KEY'] = 'AS00000000000000000'
-
-# Confirm they are set
-print(os.environ['AWS_REGION'])
-print(os.environ['AWS_ACCESS_KEY_ID'])
-print(os.environ['AWS_SECRET_ACCESS_KEY'])
-```
-
-## Configuration and Usage
-
-This sets up Mem0 with:
- [AWS Bedrock for LLM](https://docs.mem0.ai/components/llms/models/aws_bedrock)
- [AWS Bedrock for embeddings](https://docs.mem0.ai/components/embedders/models/aws_bedrock#aws-bedrock)
- [Neptune Analytics as the vector store](https://docs.mem0.ai/components/vectordbs/dbs/neptune_analytics)
- [Graph Memory guide](https://docs.mem0.ai/open-source/features/graph-memory).
-
-```python
-import boto3
-from mem0.memory.main import Memory
-
-region = 'us-west-2'
-neptune_analytics_endpoint = 'neptune-graph://my-graph-identifier'
-
-config = {
-    "embedder": {
-        "provider": "aws_bedrock",
-        "config": {
-            "model": "amazon.titan-embed-text-v2:0"
-        }
-    },
-    "llm": {
-        "provider": "aws_bedrock",
-        "config": {
-            "model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
-            "temperature": 0.1,
-            "max_tokens": 2000
-        }
-    },
-    "vector_store": {
-        "provider": "neptune",
-        "config": {
-            "collection_name": "mem0",
-            "endpoint": neptune_analytics_endpoint,
-        },
-    },
-    "graph_store": {
-        "provider": "neptune",
-        "config": {
-            "endpoint": neptune_analytics_endpoint,
-        },
-    },
-}
-
-# Initialize the memory system
-m = Memory.from_config(config)
-```
-
-## Usage
-
-Reference [Notebook example](https://github.com/mem0ai/mem0/blob/main/examples/graph-db-demo/neptune-example.ipynb)
-
-#### Add a memory:
-
-```python
-messages = [
-    {"role": "user", "content": "I'm planning to watch a movie tonight. Any recommendations?"},
-    {"role": "assistant", "content": "How about a thriller movies? They can be quite engaging."},
-    {"role": "user", "content": "I'm not a big fan of thriller movies but I love sci-fi movies."},
-    {"role": "assistant", "content": "Got it! I'll avoid thriller recommendations and suggest sci-fi movies in the future."}
-]
-
-# Store inferred memories (default behavior)
-result = m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"})
-```
-
-#### Search a memory:
-```python
-relevant_memories = m.search(query, user_id="alice")
-```
-
-#### Get all memories:
-```python
-all_memories = m.get_all(user_id="alice")
-```
-
-#### Get a specific memory:
-```python
-memory = m.get(memory_id)
-```
-
-
---
-
-## Conclusion
-
-With Mem0 and AWS services like Bedrock and Neptune Analytics, you can build intelligent AI companions that remember, adapt, and personalize their responses over time. This makes them ideal for long-term assistants, tutors, or support bots with persistent memory and natural conversation abilities.
-
---
-
-<CardGroup cols={2}>
-  <Card title="AWS Bedrock with Mem0" icon="aws" href="/cookbooks/integrations/aws-bedrock">
-    Combine Neptune Analytics with AWS Bedrock for complete AWS stack.
-  </Card>
-  <Card title="Graph Memory Architecture" icon="sitemap" href="/cookbooks/essentials/choosing-memory-architecture-vector-vs-graph">
-    Understand when to use graph vs vector memory for your use case.
-  </Card>
-</CardGroup>
@@ -121,7 +121,7 @@ const carRecommendationTool = zodResponsesFunction({

 // Use the tool in your OpenAI request
 const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
    tools: [{ type: "web_search_preview" }, carRecommendationTool],
    input: `${getMemoryString(relevantMemories)}\n${userInput}`,
 });
@@ -133,7 +133,7 @@ Combine memory with web search for up-to-date recommendations:

 ```javascript
 const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
    tools: [{ type: "web_search_preview" }, carRecommendationTool],
    input: `${getMemoryString(relevantMemories)}\n${userInput}`,
 });
@@ -204,7 +204,7 @@ async function main(memory = false) {
  }

  const response = await openAIClient.responses.create({
-    model: "gpt-4.1-nano-2025-04-14",
+    model: "gpt-5-mini",
    tools: [{ type: "web_search_preview" }, tool],
    input: `${getMemoryString(relevantMemories)}\n${input}`,
  });
@@ -202,7 +202,7 @@ Preferences:
    ]

    response = openai.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
        messages=messages
    )
    clean_response = response.choices[0].message.content.strip()
@@ -79,7 +79,7 @@ class CustomerSupportAIAgent:
        :param user_id: Optional user ID to filter memories.
        :return: List of memories.
        """
-        return self.memory.get_all(user_id=user_id)
+        return self.memory.get_all(filters={"user_id": user_id})

 # Instantiate the CustomerSupportAIAgent
 support_agent = CustomerSupportAIAgent()
@@ -45,7 +45,7 @@ class CollaborativeAgent:

    def brainstorm(self, prompt):
        # Get recent messages for context
-        memories = self.mem.search(prompt, run_id=self.run_id, limit=5)["results"]
+        memories = self.mem.search(prompt, filters={"run_id": self.run_id}, top_k=5)["results"]
        context = "\n".join(f"- {m['memory']} (by {m.get('actor_id', 'Unknown')})" for m in memories)
        client = OpenAI()
        messages = [
@@ -53,14 +53,14 @@ class CollaborativeAgent:
            {"role": "user", "content": f"Prompt: {prompt}\nContext:\n{context}"}
        ]
        reply = client.chat.completions.create(
-            model="gpt-4.1-nano-2025-04-14",
+            model="gpt-5-mini",
            messages=messages
        ).choices[0].message.content.strip()
        self.add_message("assistant", "assistant", reply)
        return reply

    def get_all_messages(self):
-        return self.mem.get_all(run_id=self.run_id)["results"]
+        return self.mem.get_all(filters={"run_id": self.run_id})["results"]

    def print_sorted_by_time(self):
        messages = self.get_all_messages()
@@ -0,0 +1,354 @@
+---
+title: "Memory Evaluation"
+description: "Understand how Mem0's memory system is evaluated, benchmark results, and how to run evaluations on your own data."
+icon: "chart-bar"
+iconType: "solid"
+---
+
+## Why Memory Evaluation Matters
+
+Most AI agent memory systems retrieve information by maximizing context window size. That works on benchmarks but not in production, where every token adds cost. **Token efficiency** — achieving high accuracy with less context per query — is what separates benchmark performance from production viability.
+
+The new Mem0 algorithm achieves competitive accuracy on LoCoMo, LongMemEval, and BEAM while averaging **under 7,000 tokens per retrieval call**. Full-context approaches on the same benchmarks routinely consume 25,000+ tokens per query.
+
+Evaluating a memory system at scale comes down to three parameters: **accuracy** (what the benchmarks measure), **cost** (context tokens per query), and **performance** (latency). Optimizing one is easy. Balancing all three at scale is the actual problem.
+
+Some benchmarks today — particularly smaller ones like LoCoMo and LongMemEval — can be materially improved by aggressive retrieval strategies, larger context windows, or frontier models. That does not necessarily mean the underlying memory system has gotten better. We evaluate under constraints that reflect how memory systems actually run in production: limited context windows and practical token budgets.
+
+## Architecture Overview
+
+Mem0's memory system operates across two phases — **extraction** (writing) and **retrieval** (reading) — with an entity linking layer connecting them.
+
+### Memory Extraction (Distillation)
+
+When new conversations arrive, the extraction pipeline processes them through five stages:
+
+1. **Store New Memories** — Conversation enters the pipeline asynchronously (after the agent responds)
+2. **Context Lookup** — Find related existing memories to avoid duplicates
+3. **Distill Memories** — Single-pass LLM extraction produces ADD-only facts from input + context
+4. **Deduplicate + Embed** — Hash-based deduplication, then vectorize new memories
+5. **Entity Linking** — Identify entities (proper nouns, quoted text, compound noun phrases) and link them across memories
+
+Memories are distributed across three storage layers, each tuned for a specific retrieval pattern:
+
+| Store | Contents | Purpose |
+|---|---|---|
+| **Vector Database** | Memory text, embeddings, metadata (timestamps, hash, categories, attributed_to) | Primary fact storage + semantic retrieval |
+| **Entity Store** | Entities + embeddings + linked memory IDs | Entity-based retrieval boost |
+| **SQL Database** | History log (ADD events) + rolling message window | Audit trail + extraction dedup context |
+
+<Info>
+The key architectural decision is **ADD-only extraction**. New facts are stored alongside old ones — nothing is overwritten or deleted. When information changes, both the old and new facts survive. This preserves temporal context and eliminates information loss from premature consolidation.
+</Info>
+
+### Multi-Signal Retrieval
+
+When a query arrives, the retrieval pipeline scores candidates across three signals in parallel:
+
+1. **Semantic Search** — Vector similarity scoring against memory embeddings
+2. **Keyword Search** — Normalized term matching via BM25 with verb-form lemmatization
+3. **Entity Search** — Entity graph matching boosts memories linked to query entities
+
+Results are fused via rank scoring into a final top-K set. Different query types lean on different signals:
+
+| Query Type | Primary Signal | Example |
+|---|---|---|
+| Conceptual | Semantic | "What does the user think about remote work?" |
+| Factual/exact | BM25 keyword | "What meetings did I attend last week?" |
+| Entity-centric | Entity matching | "What do we know about Alice?" |
+| Temporal | Semantic + keyword | "When did the user first mention the project?" |
+
+The combined score outperformed every individual signal across every category tested.
+
+## Benchmarks
+
+### LoCoMo
+
+[LoCoMo](https://github.com/snap-stanford/locomo) tests single-hop, multi-hop, open-domain, and temporal memory recall across conversational sessions.
+
+| Category | Old Algorithm | New Algorithm | Delta |
+|---|---|---|---|
+| **Overall** | **71.4** | **91.6** | **+20.2** |
+| Single-hop | 76.6 | 92.3 | +15.7 |
+| Multi-hop | 70.2 | 93.3 | +23.1 |
+| Open-domain | 57.3 | 76.0 | +18.7 |
+| Temporal | 63.2 | 92.8 | +29.6 |
+
+*Mean tokens: 6,956*
+
+The two largest gains are **temporal queries (+29.6)** and **multi-hop reasoning (+23.1)**. Both categories directly test the ADD-only architecture (preserving temporal context) and entity linking (connecting facts across memories).
+
+### LongMemEval
+
+[LongMemEval](https://github.com/xiaowu0162/LongMemEval) evaluates memory across single-session and multi-session contexts, including knowledge updates and temporal reasoning.
+
+| Category | Old Algorithm | New Algorithm | Delta |
+|---|---|---|---|
+| **Overall** | **67.8** | **93.4** | **+25.6** |
+| Single-session (user) | 94.3 | 97.1 | +2.8 |
+| Single-session (assistant) | 46.4 | 100.0 | +53.6 |
+| Single-session (preference) | 76.7 | 96.7 | +20.0 |
+| Knowledge update | 79.5 | 96.2 | +16.7 |
+| Temporal reasoning | 51.1 | 93.2 | +42.1 |
+| Multi-session | 70.7 | 86.5 | +15.8 |
+
+*Mean tokens: 6,787*
+
+The biggest gain is **single-session assistant (+53.6)** — the previous algorithm had a blind spot for agent-generated facts. The new algorithm treats them as first-class memories.
+
+The **+42.1 on temporal reasoning** reflects the ADD-only architecture preserving chronological context that the previous UPDATE/DELETE model would destroy.
+
+### BEAM
+
+[BEAM](https://github.com/mem0ai/memory-benchmarks) evaluates memory systems at 1M and 10M token scales across ten task categories. It is the only public benchmark that operates at context volumes production AI agents actually encounter.
+
+| Category | 1M | 10M |
+|---|---|---|
+| **Overall** | **64.1** | **48.6** |
+| preference_following | 88.3 | 90.4 |
+| instruction_following | 85.2 | 82.5 |
+| information_extraction | 70.0 | 56.3 |
+| knowledge_update | 65.0 | 75.0 |
+| multi_session_reasoning | 65.2 | 26.1 |
+| summarization | 63.5 | 46.9 |
+| temporal_reasoning | 61.8 | 16.3 |
+| event_ordering | 53.6 | 20.2 |
+| abstention | 52.5 | 40.0 |
+| contradiction_resolution | 35.7 | 32.5 |
+
+*Mean tokens (1M): 6,719. Mean tokens (10M): 6,914.*
+
+<Info>
+**BEAM is the most relevant benchmark here.** It operates at 1M and 10M token scales and cannot be solved by simply expanding the context window. The results at 10M reflect where memory systems actually stand at production context volumes. The system holds up well on preference following, instruction following, and knowledge updates at both scales. Weaker categories at 10M (temporal reasoning, event ordering, multi-session reasoning) are open problems across the field — they require higher-order representations of how events relate to each other across time, which is a primary focus of our ongoing research.
+</Info>
+
+### Performance Summary
+
+All results use a single-pass retrieval setup: one retrieval call, one answer, no agentic loops.
+
+| Benchmark | Old Algorithm | New Algorithm | Average tokens / query |
+|---|---|---|---|
+| **LoCoMo** | 71.4 | **91.6** | 6,956 |
+| **LongMemEval** | 67.8 | **93.4** | 6,787 |
+| **BEAM (1M)** | — | **64.1** | 6,719 |
+| **BEAM (10M)** | — | **48.6** | 6,914 |
+
+<Info>
+Scores reflect Mem0's managed platform, which includes proprietary optimizations not available in the open-source SDK. Open-source users should expect directionally similar gains but not identical numbers.
+</Info>
+
+All benchmarks run on the same production-representative model stack. Scores carry a ±1 point confidence interval due to judge inconsistency.
+
+## Running Evaluations
+
+The full evaluation framework is [open-sourced](https://github.com/mem0ai/memory-benchmarks) so anyone can reproduce the numbers independently. It supports both Mem0 Cloud and self-hosted OSS backends.
+
+### Setup
+
+<Tabs>
+  <Tab title="Mem0 Cloud">
+    ```bash
+    git clone https://github.com/mem0ai/memory-benchmarks.git
+    cd memory-benchmarks
+    pip install -r requirements.txt
+
+    # Set your API keys
+    export MEM0_API_KEY=m0-your-key
+    export OPENAI_API_KEY=sk-your-key
+    ```
+  </Tab>
+  <Tab title="Mem0 OSS (Docker)">
+    ```bash
+    git clone https://github.com/mem0ai/memory-benchmarks.git
+    cd memory-benchmarks
+    pip install -r requirements.txt
+
+    # Copy and configure environment
+    cp .env.example .env
+    # Edit .env to add OPENAI_API_KEY
+
+    # Start local Mem0 server + Qdrant
+    docker compose up -d
+    # Mem0 server: http://localhost:8888
+    # Qdrant:      http://localhost:6333
+    ```
+  </Tab>
+</Tabs>
+
+### Running a Benchmark
+
+Each benchmark is a Python module with its own runner ([source code](https://github.com/mem0ai/memory-benchmarks/tree/main/benchmarks)). All share common CLI options:
+
+| Option | Default | Description |
+|---|---|---|
+| `--project-name` | (required) | Run identifier for tracking results |
+| `--backend` | `oss` | `oss` (self-hosted) or `cloud` (Mem0 Platform) |
+| `--mem0-api-key` | — | Mem0 API key (required for `cloud` backend) |
+| `--mem0-host` | `http://localhost:8888` | Mem0 server URL (for `oss` backend) |
+| `--top-k` | `200` | Number of memories to retrieve per query |
+| `--top-k-cutoffs` | `10,20,50,200` | Evaluate accuracy at multiple retrieval depths (BEAM default: `100`) |
+| `--answerer-model` | *(varies)* | LLM for generating answers from retrieved memories |
+| `--judge-model` | *(varies)* | LLM for judging answer correctness |
+| `--provider` | `openai` | LLM provider: `openai`, `anthropic`, `azure` |
+| `--judge-provider` | (same as `--provider`) | Override provider for the judge model |
+| `--max-workers` | `10` | Parallel workers for evaluation |
+| `--predict-only` | — | Stop after search, skip answer + judge phases |
+| `--evaluate-only` | — | Skip ingest + search, evaluate existing results |
+| `--resume` | — | Resume from checkpoint (BEAM and LongMemEval; on by default for LongMemEval) |
+
+<CodeGroup>
+```bash LoCoMo
+# ~300 questions across 10 conversations (fastest benchmark)
+python -m benchmarks.locomo.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --top-k 200
+
+# Self-hosted
+python -m benchmarks.locomo.run \
+  --project-name my-eval \
+  --top-k 200
+```
+
+```bash LongMemEval
+# 500 questions across 6 categories
+python -m benchmarks.longmemeval.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --all-questions \
+  --top-k 200
+
+# Self-hosted
+python -m benchmarks.longmemeval.run \
+  --project-name my-eval \
+  --all-questions \
+  --top-k 200
+```
+
+```bash BEAM
+# 1M token scale (100 conversations)
+python -m benchmarks.beam.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --chat-sizes 1M \
+  --conversations 0-99 \
+  --top-k 200
+
+# 10M token scale
+python -m benchmarks.beam.run \
+  --project-name my-eval \
+  --backend cloud \
+  --mem0-api-key $MEM0_API_KEY \
+  --chat-sizes 10M \
+  --conversations 0-99 \
+  --top-k 200
+```
+</CodeGroup>
+
+### Custom Model Configuration
+
+To run evaluations with custom models (Azure OpenAI, Ollama, etc.), copy one of the provided configs:
+
+```bash
+# Available configs: openai.yaml, azure-openai.yaml, ollama.yaml
+cp configs/azure-openai.yaml mem0-config.yaml
+# Edit mem0-config.yaml with your model details
+
+# Uncomment the volume mount in docker-compose.yml, then restart:
+docker compose down && docker compose up -d
+```
+
+### Viewing Results
+
+Results are saved to `results/[benchmark]/` and can be explored through the built-in web UI:
+
+```bash
+npm install
+npm run dev -- -p 3001
+# Open http://localhost:3001
+```
+
+The UI lets you browse per-question results, inspect retrieval details, and compare multiple runs.
+
+### Result Format
+
+Each evaluated question produces a structured result:
+
+```json
+{
+  "id": "locomo_q_001",
+  "group": "temporal",
+  "question": "When did the user first mention moving?",
+  "ground_truth": "During the March 3rd conversation",
+  "retrieval": {
+    "search_query": "when did user mention moving",
+    "search_results": ["..."],
+    "search_latency_ms": 123.4,
+    "total_results": 42
+  },
+  "generation": {
+    "generated_answer": "The user first mentioned moving on March 3rd",
+    "model": "<answerer-model>",
+    "prompt_tokens": 500,
+    "completion_tokens": 100
+  },
+  "judgment": {
+    "judgment": "CORRECT",
+    "score": 0.85,
+    "reason": "Answer correctly identifies the date",
+    "model": "<judge-model>"
+  },
+  "cutoff_results": {
+    "top_10": { "score": 0.75, "judgment": "CORRECT" },
+    "top_50": { "score": 0.85, "judgment": "CORRECT" },
+    "top_200": { "score": 0.90, "judgment": "CORRECT" }
+  }
+}
+```
+
+## Interpreting Results
+
+When evaluating memory systems, keep these considerations in mind:
+
+- **Saturating a small benchmark is not the same as building a memory system that works at scale.** Small benchmarks can be brute-forced with aggressive retrieval and frontier models.
+- **Token efficiency matters as much as accuracy.** A system that scores 95% using 25K tokens per query isn't comparable to one scoring 90% using 7K tokens. Report mean tokens per query alongside scores.
+- **Compare at equal constraints.** Always compare systems using the same retrieval budget, the same model, and the same latency budget. A frontier model at maximum recall is not comparable to a smaller production-grade model at production-realistic retrieval depth.
+- **Watch for score ceiling effects.** Categories like "single-session user" are already near-saturated (97%+). Improvements in these categories are less meaningful than gains in harder categories like temporal reasoning or multi-session.
+- **BEAM at 10M is the real test.** Any system can look good at small scale. The 10M-token BEAM benchmark reveals whether the retrieval system actually scales.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="What judge model is used for evaluation?">
+    The judge model is configurable via `--judge-model` and `--judge-provider` flags. See the [evaluation repository](https://github.com/mem0ai/memory-benchmarks) for the current defaults. Scores carry a ±1 point confidence interval due to judge inconsistency.
+  </Accordion>
+  <Accordion title="Can I evaluate with a different extraction model?">
+    Yes. For self-hosted, configure the extraction model in your `mem0-config.yaml` (see the `configs/` directory of the evaluation repo for provider-specific examples). For Mem0 Cloud, extraction uses the platform's default. Using a frontier model will likely produce higher scores but at higher cost and latency.
+  </Accordion>
+  <Accordion title="Why are BEAM scores lower than LoCoMo/LongMemEval?">
+    BEAM operates at 1M and 10M token scales — orders of magnitude larger than LoCoMo or LongMemEval. At these scales, similar content appears multiple times across the window, and the memory system must surface the exact correct memory over many close matches. The scores reflect the genuine difficulty of the task, not a regression in the algorithm.
+  </Accordion>
+  <Accordion title="How do I contribute a new benchmark?">
+    Open a pull request to the [memory-benchmarks repository](https://github.com/mem0ai/memory-benchmarks) with your benchmark implementation. See the repository README for the expected interface and format.
+  </Accordion>
+</AccordionGroup>
+
+## Resources
+
+<CardGroup cols={2}>
+  <Card title="Evaluation Repository" icon="github" href="https://github.com/mem0ai/memory-benchmarks">
+    Open-source evaluation framework for reproducing all benchmark results
+  </Card>
+  <Card title="Research" icon="flask" href="https://mem0.ai/research">
+    Published research papers and technical reports
+  </Card>
+  <Card title="Blog Post" icon="newspaper" href="https://mem0.ai/blog/new-algorithm">
+    Detailed writeup of the new algorithm design and results
+  </Card>
+  <Card title="Platform Migration" icon="arrow-right" href="/migration/platform-v2-to-v3">
+    Guide for migrating your Platform integration
+  </Card>
+</CardGroup>
@@ -56,7 +56,7 @@ Search converts your natural language question into a vector embedding, then fin
 client.search("What are Alice's hobbies?", filters={"user_id": "alice"})

 # OSS
-m.search("What are Alice's hobbies?", user_id="alice")
+m.search("What are Alice's hobbies?", filters={"user_id": "alice"})
 ```

 <Tip>
@@ -74,7 +74,7 @@ m.search("What are Alice's hobbies?", user_id="alice")

 | Capability | Mem0 Platform | Mem0 OSS |
 | --- | --- | --- |
-| **user_id usage** | In `filters={"user_id": "alice"}` for search/get_all | As parameter `user_id="alice"` for all operations |
+| **Entity IDs on search / get_all** | Inside `filters={"user_id": "alice"}` | Inside `filters={"user_id": "alice"}` (aligned with Platform in v3 — top-level kwargs raise `ValueError`) |
 | **Filter syntax** | Logical operators (`AND`, `OR`, comparisons) with field-level access | Basic field filters, extend via Python hooks |
 | **Reranking** | Toggle `rerank=True` with managed reranker catalog | Requires configuring local or third-party rerankers |
 | **Thresholds** | Request-level configuration (`threshold`, `top_k`) | Controlled via SDK parameters |
@@ -125,14 +125,13 @@ from mem0 import Memory

 m = Memory()

-# Simple search
-related_memories = m.search("Should I drink coffee or tea?", user_id="alice")
+# Simple search — entity IDs go in `filters`
+related_memories = m.search("Should I drink coffee or tea?", filters={"user_id": "alice"})

-# Search with filters
+# Search with additional metadata filters (combine entity + metadata in the same dict)
 memories = m.search(
    "food preferences",
-    user_id="alice",
-    filters={"categories": {"contains": "diet"}}
+    filters={"user_id": "alice", "categories": {"contains": "diet"}},
 )
 ```

@@ -141,13 +140,14 @@ import { Memory } from 'mem0ai/oss';

 const memory = new Memory();

-// Simple search
-const relatedMemories = memory.search("Should I drink coffee or tea?", { userId: "alice" });
+// Simple search — entity IDs go inside `filters`
+const relatedMemories = memory.search("Should I drink coffee or tea?", {
+    filters: { userId: "alice" },
+});

-// Search with filters (if supported)
+// Combine entity + metadata filters in the same filters object
 const memories = memory.search("food preferences", {
-    userId: "alice",
-    filters: { categories: { contains: "diet" } }
+    filters: { userId: "alice", categories: { contains: "diet" } },
 });
 ```
 </CodeGroup>
@@ -176,8 +176,12 @@ client.search("query", filters={

 *OSS:*
 ```python
-# Get memories from a specific agent session
-m.search("query", user_id="alice", agent_id="chatbot", run_id="session-123")
+# Get memories from a specific agent session — entity IDs combined in filters
+m.search("query", filters={
+    "user_id": "alice",
+    "agent_id": "chatbot",
+    "run_id": "session-123",
+})
 ```

 **Filter by Date Range:**
@@ -55,7 +55,8 @@
                      "core-concepts/memory-operations/add",
                      "core-concepts/memory-operations/search",
                      "core-concepts/memory-operations/update",
-                      "core-concepts/memory-operations/delete"
+                      "core-concepts/memory-operations/delete",
+                      "core-concepts/memory-evaluation"
                    ]
                  },
                  {
@@ -78,7 +79,6 @@
                        "group": "Advanced Features",
                        "icon": "bolt",
                        "pages": [
-                          "platform/features/graph-threshold",
                          "platform/features/advanced-retrieval",
                          "platform/advanced-memory-operations",
                          "platform/features/criteria-retrieval",
@@ -118,6 +118,7 @@
                    "group": "Migration Guide",
                    "icon": "arrow-right",
                    "pages": [
+                      "migration/platform-v2-to-v3",
                      "migration/oss-to-platform",
                      "migration/api-changes"
                    ]
@@ -162,13 +163,11 @@
                    "icon": "server",
                    "pages": [
                      "open-source/features/overview",
-                      "open-source/features/graph-memory",
                      "open-source/features/metadata-filtering",
                      "open-source/features/reranker-search",
                      "open-source/features/async-memory",
                      "open-source/features/multimodal-support",
                      "open-source/features/custom-instructions",
-                      "open-source/features/custom-update-memory-prompt",
                      "open-source/features/rest-api",
                      "open-source/features/openai_compatibility"
                    ]
@@ -295,6 +294,13 @@
                      }
                    ]
                  },
+                  {
+                    "group": "Migration",
+                    "icon": "arrow-right",
+                    "pages": [
+                      "migration/oss-v2-to-v3"
+                    ]
+                  },
                  {
                    "group": "Community & Support",
                    "icon": "users",
@@ -361,7 +367,6 @@
                      "cookbooks/integrations/mastra-agent",
                      "cookbooks/integrations/healthcare-google-adk",
                      "cookbooks/integrations/aws-bedrock",
-                      "cookbooks/integrations/neptune-analytics",
                      "cookbooks/integrations/tavily-search"
                    ]
                  },
@@ -373,8 +378,7 @@
                      "cookbooks/frameworks/llamaindex-multiagent",
                      "cookbooks/frameworks/multimodal-retrieval",
                      "cookbooks/frameworks/eliza-os-character",
-                      "cookbooks/frameworks/gemini-3-with-mem0-mcp",
-                      "cookbooks/frameworks/mirofish-swarm-memory"
+                      "cookbooks/frameworks/gemini-3-with-mem0-mcp"
                    ]
                  }
                ]
@@ -633,7 +637,7 @@
    },
    {
      "source": "/platform/features/graph-memory",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/changelog",
@@ -733,11 +737,23 @@
    },
    {
      "source": "/examples/aws_neptune_analytics_hybrid_store",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/examples/aws_neptune_analytics_hybrid_st",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
+    },
+    {
+      "source": "/cookbooks/integrations/neptune-analytics",
+      "destination": "/migration/oss-v2-to-v3"
+    },
+    {
+      "source": "/platform/features/graph-threshold",
+      "destination": "/migration/platform-v2-to-v3"
+    },
+    {
+      "source": "/open-source/features/custom-update-memory-prompt",
+      "destination": "/open-source/features/custom-instructions"
    },
    {
      "source": "/examples/personalized-search-tavily-mem0",
@@ -809,11 +825,11 @@
    },
    {
      "source": "/open-source/graph_memory/overview",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/open-source/graph_memory/features",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/v0x/examples/ai_companion_js",
@@ -909,7 +925,7 @@
    },
    {
      "source": "/v0x/examples/aws_neptune_analytics_hybrid_store",
-      "destination": "/cookbooks/integrations/neptune-analytics"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/features/memory-export",
@@ -993,7 +1009,7 @@
    },
    {
      "source": "/features/graph-memory",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/features/:slug",
@@ -1101,7 +1117,7 @@
    },
    {
      "source": "/open-source/graph-memory",
-      "destination": "/open-source/features/graph-memory"
+      "destination": "/migration/oss-v2-to-v3"
    },
    {
      "source": "/cookbooks/customer-support-agent",
@@ -50,7 +50,7 @@ local_config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.1,
            "max_tokens": 2000,
        },
@@ -103,7 +103,7 @@ def demonstrate_sync_memory(local_config, sample_messages, sample_preferences, u
        ]

        for query in search_queries:
-            results = memory.search(query, user_id=user_id)
+            results = memory.search(query, filters={"user_id": user_id})
        
            if results and "results" in results:
                for j, result in enumerate(results['results']): 
@@ -111,7 +111,7 @@ def demonstrate_sync_memory(local_config, sample_messages, sample_preferences, u
            else:
                print("No results found")

-        all_memories = memory.get_all(user_id=user_id)
+        all_memories = memory.get_all(filters={"user_id": user_id})
        if all_memories and "results" in all_memories:
            print(f"Total memories: {len(all_memories['results'])}")

@@ -37,7 +37,7 @@ from agno.tools.mem0 import Mem0Tools

 agent = Agent(
    name="Memory Agent",
-    model=OpenAIChat(id="gpt-4.1-nano-2025-04-14"),
+    model=OpenAIChat(id="gpt-5-mini"),
    tools=[Mem0Tools()],
    description="An assistant that remembers and personalizes using Mem0 memory."
 )
@@ -126,7 +126,7 @@ def chat_user(

    if user_input:
        # Search for relevant memories
-        memories = client.search(user_input, user_id=user_id)
+        memories = client.search(user_input, filters={"user_id": user_id})
        memory_context = "\n".join(f"- {m['memory']}" for m in memories['results'])

        # Construct the prompt
@@ -72,7 +72,7 @@ Create a function to get context-aware responses based on user's question and pr

 ```python
 def get_context_aware_response(question):
-    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    relevant_memories = memory_client.search(question, filters={"user_id": USER_ID})
    context = "\n".join([m["memory"] for m in relevant_memories.get('results', [])])

    prompt = f"""Answer the user question considering the previous interactions:
@@ -104,7 +104,7 @@ manager = ConversableAgent(
 )

 def escalate_to_manager(question):
-    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    relevant_memories = memory_client.search(question, filters={"user_id": USER_ID})
    context = "\n".join([m["memory"] for m in relevant_memories.get('results', [])])

    prompt = f"""
@@ -107,10 +107,10 @@ messages = [
 m.add(messages, user_id="alice", metadata={"category": "movie_recommendations"})

 # Search for memory
-relevant = m.search("What kind of movies does Alice like?", user_id="alice")
+relevant = m.search("What kind of movies does Alice like?", filters={"user_id": "alice"})

 # Retrieve all user memories
-all_memories = m.get_all(user_id="alice")
+all_memories = m.get_all(filters={"user_id": "alice"})
 ```

 ## Key Features
@@ -125,8 +125,5 @@ all_memories = m.get_all(user_id="alice")
  <Card title="AWS Bedrock Cookbook" icon="aws" href="/cookbooks/integrations/aws-bedrock">
    Complete guide to using Bedrock with Mem0
  </Card>
-  <Card title="Neptune Analytics Cookbook" icon="database" href="/cookbooks/integrations/neptune-analytics">
-    Build graph memory with AWS Neptune
-  </Card>
 </CardGroup>

@@ -56,7 +56,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.0,
            "api_key": keywordsai_api_key,
            "openai_base_url": base_url,
@@ -40,7 +40,7 @@ load_dotenv()
 # os.environ["MEM0_API_KEY"] = "your-mem0-api-key"

 # Initialize LangChain and Mem0
-llm = ChatOpenAI(model="gpt-4.1-nano-2025-04-14")
+llm = ChatOpenAI(model="gpt-5-mini")
 mem0 = MemoryClient()
 ```

@@ -66,7 +66,7 @@ Create functions to handle context retrieval, response generation, and addition
 def retrieve_context(query: str, user_id: str) -> List[Dict]:
    """Retrieve relevant context from Mem0"""
    try:
-        memories = mem0.search(query, user_id=user_id)
+        memories = mem0.search(query, filters={"user_id": user_id})
        memory_list = memories['results']
        
        serialized_memories = ' '.join([mem["memory"] for mem in memory_list])
@@ -68,7 +68,7 @@ def chatbot(state: State):

    try:
        # Retrieve relevant memories
-        memories = mem0.search(messages[-1].content, user_id=user_id)
+        memories = mem0.search(messages[-1].content, filters={"user_id": user_id})
        
        # Handle dict response format
        memory_list = memories['results']
@@ -148,7 +148,7 @@ async def entrypoint(ctx: JobContext):

    session = AgentSession(
        stt=deepgram.STT(),
-        llm=openai.LLM(model="gpt-4.1-nano-2025-04-14"),
+        llm=openai.LLM(model="gpt-5-mini"),
        tts=openai.TTS(voice="ash",),
        turn_detection=EnglishModel(),
        vad=silero.VAD.load(),
@@ -83,7 +83,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.2,
            "max_tokens": 2000,
        },
@@ -116,7 +116,7 @@ from dotenv import load_dotenv
 load_dotenv()

 # os.environ["OPENAI_API_KEY"] = "<your-openai-api-key>"
-llm = OpenAI(model="gpt-4.1-nano-2025-04-14")
+llm = OpenAI(model="gpt-5-mini")
 ```

 ### SimpleChatEngine
@@ -45,7 +45,7 @@ mem0 = MemoryClient()
@function_tool
 def search_memory(query: str, user_id: str) -> str:
    """Search through past conversations and memories"""
-    memories = mem0.search(query, user_id=user_id, top_k=3)
+    memories = mem0.search(query, filters={"user_id": user_id}, top_k=3)
    if memories and memories.get('results'):
        return "\n".join([f"- {mem['memory']}" for mem in memories['results']])
    return "No relevant memories found."
@@ -64,7 +64,7 @@ agent = Agent(
    Use the save_memory tool to store important information about the user.
    Always personalize your responses based on available memory.""",
    tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )

 def chat_with_agent(user_input: str, user_id: str) -> str:
@@ -115,7 +115,7 @@ travel_agent = Agent(
    understand the user's travel preferences and history before making recommendations.
    After providing your response, use store_conversation to save important details.""",
    tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )

 health_agent = Agent(
@@ -124,7 +124,7 @@ health_agent = Agent(
    understand the user's health goals and dietary preferences.
    After providing advice, use store_conversation to save relevant information.""",
    tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )

 # Triage agent with handoffs
@@ -135,7 +135,7 @@ triage_agent = Agent(
    For health-related questions (fitness, diet, wellness, exercise), hand off to the Health Advisor.
    For general questions, handle them directly using available tools.""",
    handoffs=[travel_agent, health_agent],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )

 def chat_with_handoffs(user_input: str, user_id: str) -> str:
@@ -147,7 +147,6 @@ openclaw mem0 stats
 | `apiKey` | `string` | — | **Required.** Mem0 API key (supports `${MEM0_API_KEY}`) |
 | `orgId` | `string` | — | Organization ID |
 | `projectId` | `string` | — | Project ID |
-| `enableGraph` | `boolean` | `false` | Entity graph for relationships |
 | `customInstructions` | `string` | *(built-in)* | Extraction rules — what to store, how to format |
 | `customCategories` | `object` | *(12 defaults)* | Category name → description map for tagging |

@@ -78,7 +78,7 @@ npm install @mem0/vercel-ai-provider

     > `getMemories` will return raw memories in the form of an array of objects, while `retrieveMemories` will return a response in string format with a system prompt ingested with the retrieved memories.

-     > `getMemories` is an object with two keys: `results` and `relations` if `enable_graph` is enabled. Otherwise, it will return an array of objects.
+     > `getMemories` returns an array of memory objects.

 ### 1. Basic Text Generation with Memory Context

@@ -270,24 +270,6 @@ main();

 > **Note**: File support is available with providers that support multimodal capabilities like Google's Gemini models. The example shows how to process PDF files, but you can also work with images, text files, and other supported formats.

-## Graph Memory
-
-Mem0 AI SDK now supports Graph Memory. You can enable it by setting `enable_graph` to `true` in the `mem0Config` object.
-
-```typescript
-const mem0 = createMem0({
-  mem0Config: { enable_graph: true },
-});
-```
-
-You can also pass `enable_graph` in the standalone functions. This includes `getMemories`, `retrieveMemories`, and `addMemories`.
-
-```typescript
-const memories = await getMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx", enable_graph: true });
-```
-
-The `getMemories` function will return an object with two keys: `results` and `relations`, if `enable_graph` is set to `true`. Otherwise, it will return an array of objects.
-
 ## Supported LLM Providers

 | Provider | Configuration Value |
@@ -45,7 +45,6 @@ Key differentiators:
 - [Custom Categories](https://docs.mem0.ai/platform/features/custom-categories): Define domain-specific categories to improve memory organization

 ### Advanced Features
- [Graph Memory](https://docs.mem0.ai/platform/features/graph-memory): Build and query relationships between entities for contextually relevant retrieval
 - [Graph Threshold](https://docs.mem0.ai/platform/features/graph-threshold): Configure graph relationship sensitivity and strength
 - [Advanced Retrieval](https://docs.mem0.ai/platform/features/advanced-retrieval): Enhanced search with keyword search, reranking, and filtering capabilities
 - [Criteria-Based Retrieval](https://docs.mem0.ai/platform/features/criteria-retrieval): Targeted memory retrieval using custom criteria
@@ -81,7 +80,6 @@ Key differentiators:

 ### Open Source Features
 - [Features Overview](https://docs.mem0.ai/open-source/features/overview): Overview of all open-source features
- [Graph Memory](https://docs.mem0.ai/open-source/features/graph-memory): Build and query entity relationships using graph stores like Neo4j
 - [Metadata Filtering](https://docs.mem0.ai/open-source/features/metadata-filtering): Advanced filtering using custom metadata fields
 - [Reranker Search](https://docs.mem0.ai/open-source/features/reranker-search): Enhanced search results with reranking models
 - [Async Memory](https://docs.mem0.ai/open-source/features/async-memory): Asynchronous memory operations for better performance
@@ -246,7 +244,6 @@ Key differentiators:
 - [Multimodal Retrieval](https://docs.mem0.ai/cookbooks/frameworks/multimodal-retrieval): Memory systems handling text, images, and documents
 - [Eliza OS Character](https://docs.mem0.ai/cookbooks/frameworks/eliza-os-character): Character-based AI with persistent personality
 - [Gemini with Mem0 MCP](https://docs.mem0.ai/cookbooks/frameworks/gemini-3-with-mem0-mcp): Google Gemini integration using MCP server
- [Mirofish Swarm Memory](https://docs.mem0.ai/cookbooks/frameworks/mirofish-swarm-memory): Swarm-based multi-agent memory patterns

 ## API Reference

@@ -0,0 +1,538 @@
+---
+title: "Open Source: Migrating to the New Memory Algorithm"
+description: "Guide for self-hosted Mem0 users to upgrade to the new memory algorithm with ADD-only extraction, hybrid search, and entity linking."
+icon: "arrow-right"
+iconType: "solid"
+---
+
+<Warning>
+**Breaking changes ahead.** This release includes renamed parameters, removed parameters, changed defaults, and a fundamentally different extraction model. Read this guide before upgrading.
+</Warning>
+
+## 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
+
+| Change | Old | New | Migration |
+|---|---|---|---|
+| `search()` / `get_all()` entity IDs | Top-level kwargs (`user_id="..."`) | Inside `filters` dict | `m.search("q", filters={"user_id": "..."})` — top-level kwargs now raise `ValueError` |
+| `top_k` default | `100` | `20` | Pass `top_k=100` explicitly to restore |
+| `threshold` default | `None` (no filtering) | `0.1` (filters low-relevance) | Pass `threshold=0.0` for old behavior |
+| `threshold` validation | Any float | Must be in `[0, 1]` | Out-of-range values now raise `ValueError` |
+| `rerank` default | `True` | `False` | Pass `rerank=True` to restore |
+| Entity ID validation | Accepted any string | Trimmed; empty / whitespace-only rejected (`ValueError`) | Pass a non-empty identifier without internal spaces |
+| `messages` in `add()` | Could be `None` | Must be `str` / `dict` / `list[dict]` — other types raise `Mem0ValidationError` (code `VALIDATION_003`) | Always pass a string, dict, or list of messages |
+| `add()` events | Returns `ADD`, `UPDATE`, `DELETE` | Returns `ADD` only | Update code expecting UPDATE/DELETE |
+| Custom extraction prompt | `custom_fact_extraction_prompt` | `custom_instructions` | Rename in config |
+| Custom update prompt | `custom_update_memory_prompt` | Deprecated | Use `custom_instructions` instead |
+| Graph memory | `enable_graph` + `graph_store` in config | Removed | Graph store support has been removed entirely |
+| Qdrant client | `>=1.9.1` | `>=1.12.0` | Update dependency |
+| Upstash client | `>=0.1.0` | `>=0.6.0` | Update dependency |
+
+### TypeScript Open Source
+
+| Change | Old | New | Migration |
+|---|---|---|---|
+| Search parameter | `search(query, { limit: 10 })` | `search(query, { topK: 10 })` | Rename `limit` → `topK` |
+| `topK` default | `100` | `20` | Pass `topK: 100` explicitly to restore |
+| `search()` / `getAll()` entity IDs | Top-level options (`userId: "..."`) | Inside `filters` object | `m.search("q", { filters: { userId: "..." } })` |
+| `threshold` validation | Any number | Must be in `[0, 1]` | Out-of-range values now throw |
+| Entity ID validation | Any string | Trimmed; empty / whitespace-only rejected | Pass non-empty identifiers without internal spaces |
+| `messages` in `add()` | Could be `null` / `undefined` | Required — throws on null/undefined | Always pass a string or array |
+| Payload key for lemmatized text | `text_lemmatized` (snake_case) | `textLemmatized` (camelCase) | TS-only internal field. If you share a vector store collection between Python and TS SDKs, lemma-based BM25 will not resolve across languages — keep collections language-scoped. |
+| Custom prompt | `customPrompt` | `customInstructions` | Rename in config |
+| Graph memory | `enableGraph` + `graphStore` in config | Removed | Graph store support has been removed entirely |
+| Default graph config | Neo4j default config applied | No default graph config | Graph store config is no longer used |
+
+### Python Client SDK
+
+| Change | Old | New | Migration |
+|---|---|---|---|
+| Constructor | `MemoryClient(api_key, org_id, project_id)` | `MemoryClient(api_key)` | Remove `org_id`, `project_id` from constructor |
+| Method options | `client.add(messages, **kwargs)` | `client.add(messages, options=AddMemoryOptions(...))` | Use typed option classes (or `**kwargs` still works) |
+| Removed params | `api_version`, `output_format`, `async_mode`, `filter_memories`, `expiration_date`, `keyword_search`, `force_add_only`, `batch_size`, `immutable`, `includes`, `excludes`, `enable_graph`, `org_name`, `project_name` | — | Remove from all calls |
+
+### TypeScript Client SDK
+
+| Change | Old | New | Migration |
+|---|---|---|---|
+| Constructor | `new MemoryClient({ apiKey, organizationId, projectId })` | `new MemoryClient({ apiKey })` | Remove `organizationId`, `projectId`, `organizationName`, `projectName` |
+| All params | snake_case: `user_id`, `agent_id`, `top_k` | camelCase: `userId`, `agentId`, `topK` | Rename all params to camelCase |
+| Removed params | `api_version`, `output_format`, `async_mode`, `enable_graph`, `org_id`, `project_id`, `org_name`, `project_name`, `filter_memories`, `batch_size`, `force_add_only`, `immutable`, `expiration_date`, `includes`, `excludes`, `keyword_search` | — | Remove from all calls |
+| Output format enum | `OutputFormat.V1`, `OutputFormat.V1_1` | Removed | v1.1 is now always used |
+| API version enum | `API_VERSION.V1`, `API_VERSION.V2` | Removed | Handled internally |
+
+## Step-by-Step Migration
+
+### 1. Update Installation
+
+<Tabs>
+  <Tab title="Python">
+    ```bash
+    # Basic upgrade
+    pip install --upgrade mem0ai
+
+    # 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>
+  </Tab>
+  <Tab title="TypeScript">
+    ```bash
+    npm install mem0ai@latest
+    ```
+  </Tab>
+</Tabs>
+
+<Info>
+The Python `[nlp]` extra installs [spaCy](https://spacy.io/) for entity extraction and keyword lemmatization. Without it, Mem0 still works but falls back to semantic-only search (no entity linking, no BM25 lemmatization).
+</Info>
+
+<Warning>
+**Qdrant users — install `fastembed` to enable BM25 keyword search.** The Qdrant backend uses [fastembed](https://github.com/qdrant/fastembed) to encode sparse (BM25) vectors alongside dense vectors in the same collection. Without it, BM25 is silently disabled and search falls back to semantic-only — you'll see a log warning `"fastembed not installed — BM25 keyword search disabled"` on the first search call. Other vector stores use their native full-text capabilities and don't need `fastembed`.
+
+```bash
+pip install fastembed
+```
+</Warning>
+
+### 2. Update Configuration
+
+<Tabs>
+  <Tab title="Python OSS">
+    ```python
+    # Before
+    config = {
+        "custom_fact_extraction_prompt": "Focus on user preferences",  # [REMOVED] Renamed
+        "custom_update_memory_prompt": "Be concise when updating",      # [REMOVED] Deprecated
+        "graph_store": {
+            "provider": "neo4j",
+            "config": { "url": "...", "username": "...", "password": "..." }
+        },
+        "enable_graph": True,  # [REMOVED] Removed
+    }
+
+    # 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
+    }
+    ```
+  </Tab>
+  <Tab title="TypeScript OSS">
+    ```typescript
+    // Before
+    const config = {
+      customPrompt: "Focus on user preferences",  // [REMOVED] Renamed
+      enableGraph: true,                            // [REMOVED] Removed
+      graphStore: {
+        provider: "neo4j",
+        config: { url: "...", username: "...", password: "..." }
+      }
+    };
+
+    // After
+    const config = {
+      customInstructions: "Focus on user preferences",  // [OK] New name
+      // enableGraph and graphStore removed — graph store support has been removed
+    };
+    ```
+  </Tab>
+</Tabs>
+
+### 3. Update Search Calls
+
+<Tabs>
+  <Tab title="Python OSS">
+    ```python
+    # Before — entity IDs as top-level kwargs
+    results = m.search(
+        "what meetings did I attend?",
+        user_id="alice",
+        top_k=20
+    )
+    for r in results:
+        print(r["score"])  # Was raw cosine similarity
+
+    # 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>
+  </Tab>
+  <Tab title="TypeScript OSS">
+    ```typescript
+    // Before — entity IDs as top-level options
+    const results = await m.search("what meetings did I attend?", {
+      userId: "alice",
+      limit: 20          // [REMOVED] Renamed to 'topK' for consistency
+    });
+
+    // 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'
+    });
+    ```
+  </Tab>
+  <Tab title="Python Client SDK">
+    ```python
+    from mem0 import MemoryClient
+    from mem0.client.types import SearchMemoryOptions
+
+    # 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
+        )
+    )
+    ```
+  </Tab>
+  <Tab title="TypeScript Client SDK">
+    ```typescript
+    // Before
+    const client = new MemoryClient({
+      apiKey: "...",
+      organizationId: "org-1",  // [REMOVED] Removed
+      projectId: "proj-1"       // [REMOVED] Removed
+    });
+    const results = await client.search("query", {
+      user_id: "alice",         // [REMOVED] snake_case
+      top_k: 20,                // [REMOVED] snake_case
+      enable_graph: true        // [REMOVED] Removed
+    });
+
+    // After
+    const client = new MemoryClient({ apiKey: "..." });
+    const results = await client.search("query", {
+      filters: { userId: "alice" },
+      topK: 20
+    });
+    ```
+  </Tab>
+</Tabs>
+
+### 4. Update Add Calls
+
+<Tabs>
+  <Tab title="Python OSS">
+    ```python
+    # Before — could return ADD, UPDATE, DELETE events
+    result = m.add("I love hiking and my dog's name is Max", user_id="alice")
+    for item in result["results"]:
+        if item["event"] == "ADD":
+            print("New memory:", item["memory"])
+        elif item["event"] == "UPDATE":
+            print("Updated:", item["memory"])     # [REMOVED] No longer returned
+        elif item["event"] == "DELETE":
+            print("Deleted:", item["memory"])      # [REMOVED] No longer returned
+
+    # 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
+    ```
+  </Tab>
+  <Tab title="Python Client SDK">
+    ```python
+    from mem0.client.types import AddMemoryOptions
+
+    # 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")
+    ```
+  </Tab>
+  <Tab title="TypeScript Client SDK">
+    ```typescript
+    // Before
+    await client.add(messages, {
+      user_id: "alice",       // [REMOVED] snake_case
+      async_mode: true,       // [REMOVED] Removed
+      output_format: "v1.1",  // [REMOVED] Removed
+      enable_graph: true      // [REMOVED] Removed
+    });
+
+    // After
+    await client.add(messages, {
+      userId: "alice"         // [OK] camelCase
+    });
+    ```
+  </Tab>
+</Tabs>
+
+<Tip>
+The ADD-only model means memories accumulate over time. When information changes, the new fact is stored alongside the old one. Retrieval handles ranking — the most relevant, current information surfaces first.
+</Tip>
+
+### 5. Update Vector Store Dependencies
+
+If you're using Qdrant or Upstash, update your client libraries:
+
+```bash
+# 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.
+
+<Warning>
+Make sure your vector store user/credentials have permission to create new collections. If you're using a managed vector database with restricted permissions, pre-create the `{collection_name}_entities` collection with the same embedding dimensions as your main collection.
+</Warning>
+
+## 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.
+
+<Warning>
+Graph relationships exposed via the old `relations` field on search results are no longer populated. Entity relationships are consumed indirectly through retrieval ranking, not exposed as a queryable graph structure. If your application depended on traversing graph relationships directly, you will need to redesign that part against the new API.
+</Warning>
+
+## 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:
+
+| Capability | Purpose | Fallback if Unsupported |
+|---|---|---|
+| `keyword_search()` | BM25/full-text keyword matching | Falls back to semantic-only search |
+| `search_batch()` | Batch search for entity matching | Falls back to sequential search |
+
+**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:
+
+| Missing Dependency | Impact | Search Still Works? |
+|---|---|---|
+| spaCy (`mem0ai[nlp]`) | No entity extraction, no BM25 lemmatization | Yes (semantic-only) |
+| `fastembed` (Qdrant) | No BM25 keyword search | Yes (semantic + entity) |
+| Entity store unavailable | No entity boosting | Yes (semantic + BM25) |
+
+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:
+
+```typescript
+// 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:
+
+```typescript
+// 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.
+
+```python
+# 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:
+
+```python
+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:
+
+```bash
+python -m spacy download en_core_web_sm
+```
+
+If spaCy is not installed at all, install the NLP extras:
+
+```bash
+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](https://mem0.ai/discord) for real-time support
+- Open an issue on [GitHub](https://github.com/mem0ai/mem0/issues)
+- Check the [evaluation docs](/core-concepts/memory-evaluation) to benchmark the new algorithm on your data
@@ -0,0 +1,328 @@
+---
+title: "Platform: Migrating to the New Memory Algorithm"
+description: "Guide for Mem0 Platform users to adopt the new memory algorithm with single-pass extraction, entity linking, and multi-signal retrieval."
+icon: "arrow-right"
+iconType: "solid"
+---
+
+<Info>
+**No action required for most users.** The new algorithm is rolling out automatically to all Mem0 Platform projects. This guide covers what changed, what to expect, and how to take full advantage of the new capabilities.
+</Info>
+
+## Overview
+
+The new Mem0 memory algorithm is a ground-up redesign of how memories are extracted, stored, and retrieved. It scores **91.6 on LoCoMo** and **93.4 on LongMemEval** — a +20 and +26 point improvement over the previous algorithm — while cutting extraction latency roughly in half.
+
+| What Changed | Before | After |
+|---|---|---|
+| **Extraction** | Two LLM passes (extract + merge) | Single-pass ADD-only (one LLM call) |
+| **Memory mutations** | ADD, UPDATE, DELETE | ADD only — nothing is overwritten or deleted |
+| **Agent-generated facts** | Often ignored | First-class, stored with equal weight |
+| **Entity linking** | Not available | Entities extracted and linked across memories |
+| **Graph memory** | Separate graph store + dashboard visualization | Replaced by built-in entity linking, no graph visuals on platform dashboard |
+| **Retrieval** | Semantic (vector) only | Hybrid retrieval combining multiple signals |
+
+## What This Means for Your Application
+
+### Memories accumulate instead of being overwritten
+
+The previous algorithm could UPDATE or DELETE existing memories during extraction. The new algorithm only adds new facts. When information changes (e.g., a user moves from New York to San Francisco), both facts are preserved with temporal context. This means:
+
+- **More memories over time** — your memory count will grow rather than plateau
+- **Better temporal reasoning** — the system can distinguish "used to live in New York" from "now lives in San Francisco"
+- **No information loss** — facts that seemed contradictory but were actually complementary are preserved
+
+<Tip>
+If your application previously relied on UPDATE/DELETE behavior to keep memory counts low, the new algorithm handles this at retrieval time instead. Multi-signal retrieval ranks the most relevant, current information higher without destroying historical context.
+</Tip>
+
+### Agent-generated facts are now captured
+
+Previously, when an agent said something like "I've booked your flight for March 3rd," the system would often ignore it and only store what the user explicitly stated. The new algorithm treats agent-generated facts as first-class memories. If your application involves agents that confirm actions, provide recommendations, or share information, you'll see significantly better recall on those interactions.
+
+### Retrieval is hybrid now
+
+Search now uses hybrid retrieval, which improves ranking quality — especially for queries involving exact keywords, proper nouns, or entities that appear across multiple memories. The response shape is unchanged:
+
+```json
+{
+  "results": [
+    {
+      "id": "mem-uuid",
+      "memory": "User moved to San Francisco in January 2026",
+      "score": 0.82,
+      "metadata": {},
+      "categories": ["location"]
+    }
+  ]
+}
+```
+
+The top-level `score` remains a `[0, 1]` value. Relative ranking between results stays comparable to v2, but absolute numbers shift since the scoring method changed — retune any hard thresholds in your app against representative queries.
+
+## API Changes
+
+### New V3 Endpoints
+
+The new algorithm is available through the V3 API. The endpoints split into per-operation paths:
+
+| Operation | SDK method | Endpoint |
+|---|---|---|
+| Add memories | `client.add()` | `POST /v3/memories/add/` |
+| Search memories | `client.search()` | `POST /v3/memories/search/` |
+| Get all memories (paginated) | `client.get_all()` | `POST /v3/memories/` |
+
+<Info>
+`get_all` / list now returns a paginated envelope: `{"count": int, "next": str | null, "previous": str | null, "results": [...]}`. Pass `page` and `page_size` as query params to paginate; defaults return the first page.
+</Info>
+
+<CodeGroup>
+```python Python
+from mem0 import MemoryClient
+
+client = MemoryClient(api_key="your-api-key")
+
+# Add memories (same interface, improved extraction)
+result = client.add(
+    messages=[
+        {"role": "user", "content": "I just moved to San Francisco from New York"},
+        {"role": "assistant", "content": "That's exciting! I'll update your location preferences."}
+    ],
+    user_id="alice"
+)
+
+# Search with multi-signal retrieval
+results = client.search(
+    query="where does the user live?",
+    filters={"user_id": "alice"}
+)
+
+# List memories (paginated)
+page = client.get_all(filters={"user_id": "alice"}, page=1, page_size=50)
+# page == {"count": 123, "next": "...", "previous": None, "results": [...]}
+```
+
+```bash cURL
+# Add memories
+curl -X POST https://api.mem0.ai/v3/memories/add/ \
+  -H "Authorization: Token your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "I just moved to San Francisco from New York"},
+      {"role": "assistant", "content": "That'\''s exciting! I'\''ll update your location preferences."}
+    ],
+    "user_id": "alice"
+  }'
+
+# Search memories
+curl -X POST https://api.mem0.ai/v3/memories/search/ \
+  -H "Authorization: Token your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "where does the user live?",
+    "filters": {"user_id": "alice"}
+  }'
+
+# List memories (paginated)
+curl -X POST 'https://api.mem0.ai/v3/memories/?page=1&page_size=50' \
+  -H "Authorization: Token your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"filters": {"user_id": "alice"}}'
+```
+</CodeGroup>
+
+### Search Parameter Changes
+
+| Parameter | V1/V2 | V3 | Notes |
+|---|---|---|---|
+| `top_k` | Supported | Supported (1-1000, default 10) | No change |
+| `threshold` | Default: none | Default: `0.1` | Pass `0.0` to disable |
+| `rerank` | Default: `true` | Default: `false` | Pass `true` to enable (adds latency) |
+| Entity IDs in `search` / `get_all` | Top-level | Inside `filters` dict | Top-level raises 400 |
+
+### Response Format
+
+**Add response** — asynchronous, returns an `event_id` for polling:
+
+```json
+{
+  "message": "Memory processing has been queued for background execution",
+  "status": "PENDING",
+  "event_id": "evt-uuid"
+}
+```
+
+Poll status via `GET /v1/event/{event_id}/` — status will be `SUCCEEDED` or `FAILED`.
+
+**Search response** — combined multi-signal score per result:
+
+```json
+{
+  "results": [
+    {
+      "id": "mem-uuid",
+      "memory": "User moved to San Francisco from New York in January 2026",
+      "score": 0.82,
+      "metadata": {},
+      "categories": ["location"],
+      "created_at": "2026-01-15T10:30:00Z",
+      "updated_at": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+**List response** — paginated envelope (new in V3):
+
+```json
+{
+  "count": 123,
+  "next": "https://api.mem0.ai/v3/memories/?page=2&page_size=50",
+  "previous": null,
+  "results": [
+    {
+      "id": "mem-uuid",
+      "memory": "...",
+      "metadata": {},
+      "categories": [],
+      "created_at": "2026-01-15T10:30:00Z",
+      "updated_at": "2026-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+## SDK Breaking Changes
+
+Alongside the algorithm update, the Python and TypeScript client SDKs have been cleaned up. These changes affect how you initialize and call the client.
+
+### Python Client SDK
+
+```python
+from mem0 import MemoryClient
+
+# Before
+client = MemoryClient(
+    api_key="...",
+    org_id="org-1",       # [REMOVED] Removed
+    project_id="proj-1"   # [REMOVED] Removed
+)
+client.add(messages, user_id="alice", async_mode=True, output_format="v1.1")
+
+# After
+client = MemoryClient(api_key="...")
+client.add(messages, user_id="alice")
+# async_mode and output_format removed (async by default, v1.1 always)
+```
+
+**Removed parameters:** `org_id`, `project_id`, `api_version`, `output_format`, `async_mode`, `enable_graph`, `immutable`, `expiration_date`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`, `org_name`, `project_name`
+
+### TypeScript Client SDK
+
+All parameters now use **camelCase** (the SDK handles conversion to/from the API automatically):
+
+```typescript
+// Before
+const client = new MemoryClient({
+  apiKey: "...",
+  organizationId: "org-1",  // [REMOVED] Removed
+  projectId: "proj-1"       // [REMOVED] Removed
+});
+await client.search("query", {
+  user_id: "alice",          // [REMOVED] snake_case
+  top_k: 20,                 // [REMOVED] snake_case
+  enable_graph: true          // [REMOVED] Removed
+});
+
+// After
+const client = new MemoryClient({ apiKey: "..." });
+await client.search("query", {
+  filters: { userId: "alice" },  // [OK] inside filters
+  topK: 20                       // [OK] camelCase
+});
+```
+
+**Removed:** `OutputFormat` enum, `API_VERSION` enum, `organizationId`, `projectId`, `organizationName`, `projectName`, `enableGraph`, `asyncMode`, `outputFormat`, `immutable`, `expirationDate`, `filterMemories`, `batchSize`, `forceAddOnly`, `includes`, `excludes`, `keywordSearch`
+
+<Info>
+For the full list of parameter changes across all SDKs, see the [OSS migration guide](/migration/oss-v2-to-v3#removed-parameters-reference).
+</Info>
+
+## Graph Memory → Entity Linking
+
+Graph memory has been replaced by **built-in entity linking**. The changes:
+
+- **Graph visualizations removed from the platform dashboard.** The graph view in your project dashboard is no longer available.
+- **`enable_graph` project setting removed.** The toggle is gone from the dashboard; the API parameter is ignored.
+- **No external graph store to configure.** Previously graph memory required a separate Neo4j (or similar) deployment. Entity linking runs natively inside the platform — nothing to provision, no connection strings to manage.
+- **Entity linking is the native replacement.** Entities (proper nouns, quoted text, compound noun phrases) are automatically extracted from every memory and linked across memories belonging to the same user. At search time, entities from the query are matched against this index and used to boost ranking. The boost is folded into the combined `score` returned on each result.
+
+**No migration work is required.** Entity linking activates automatically for all projects on the new algorithm. Existing memories are not re-processed, but any new memories you add will be indexed for entity-based retrieval going forward.
+
+<Note>
+If your application previously read graph relations from the API response (`relations` field on search results), note that this field is no longer populated. Entity relationships are now consumed indirectly through retrieval ranking, not exposed as a separate graph structure.
+</Note>
+
+## Migration Checklist
+
+<Steps>
+  <Step title="Review your search thresholds">
+    The default `threshold` is now `0.1` (previously no threshold). If your application was relying on unfiltered results, explicitly pass `threshold=0.0` in your search calls to preserve the old behavior. In most cases, the new default is better — it filters out low-relevance noise.
+  </Step>
+  <Step title="Review reranking usage">
+    Reranking is now `false` by default. If your application depended on reranked results, add `rerank=True` to your search calls. Note that reranking adds latency (~200-400ms) but can improve ordering quality for complex queries.
+  </Step>
+  <Step title="Update score handling (optional)">
+    The top-level `score` field continues to work as before. It is now a combined multi-signal score (semantic + keyword + entity) rather than pure cosine similarity, so the absolute numbers will differ. Relative ranking remains comparable — if you have threshold-based filtering in your app, retune on a representative query set.
+  </Step>
+  <Step title="Adjust memory count expectations">
+    With ADD-only extraction, memory counts will grow over time rather than being consolidated. This is by design — retrieval handles relevance ranking. If you have hard limits on memory count, consider using the memory expiration feature or periodic cleanup.
+  </Step>
+  <Step title="Test with representative queries">
+    The biggest improvements are in temporal reasoning (+29.6 on LoCoMo), multi-hop queries (+23.1), and assistant memory recall (+53.6 on LongMemEval). Test queries in these categories to see the improvement.
+  </Step>
+</Steps>
+
+## Backward Compatibility
+
+- **V1 and V2 endpoints continue to work.** There is no requirement to migrate to V3 endpoints immediately.
+- **Existing memories are preserved.** The new algorithm does not modify or re-process previously stored memories.
+- **Search response shape is unchanged.** The top-level `score` and `results[]` array are the same; existing code that reads `score` continues to work. What changed is the scoring method behind the number (multi-signal fusion instead of pure cosine), so the absolute values shift even when ranking stays comparable.
+- **List response shape changed.** `get_all` now returns a paginated envelope (`{count, next, previous, results}`) instead of a bare `{results: [...]}`. Update code that reads `response["results"]` to continue working, or switch to the client SDKs which handle both shapes.
+
+## Performance Improvements
+
+| Metric | Previous Algorithm | New Algorithm |
+|---|---|---|
+| **LoCoMo Overall** | 71.4 | **91.6** (+20.2) |
+| **LongMemEval Overall** | 67.8 | **93.4** (+25.6) |
+| **Extraction latency (p50)** | ~2.0s | **~1.0s** |
+| **Mean tokens per query** | — | 6.8-7.0K (top200) |
+
+All benchmarks were run on a production-representative stack — deliberately avoiding frontier models to keep numbers representative of real production workloads.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Do I need to re-process my existing memories?">
+    No. Existing memories remain as-is. New memories added after the rollout will use the new extraction algorithm. Both old and new memories are searchable through the same retrieval pipeline.
+  </Accordion>
+  <Accordion title="Will my memory count increase faster now?">
+    Yes. The ADD-only approach means memories accumulate rather than being consolidated. This is intentional — the retrieval system handles ranking and relevance. If you need to manage memory volume, use the expiration date feature or the delete API.
+  </Accordion>
+  <Accordion title="Can I opt out of the new algorithm?">
+    The new algorithm is the default for all platform users. If you have a specific need to use the previous extraction behavior, contact support.
+  </Accordion>
+  <Accordion title="How does entity linking affect my existing integrations?">
+    Entity linking is automatic and transparent. It improves retrieval quality without requiring any changes to your integration. Entities are extracted from both new memories and search queries, and matched automatically.
+  </Accordion>
+</AccordionGroup>
+
+## Need Help?
+
+If you run into issues during migration or have questions about the new algorithm:
+
+- Join our [Discord community](https://mem0.ai/discord) for real-time support
+- Email us at [support@mem0.ai](mailto:support@mem0.ai)
+- Check the [API reference](/api-reference) for detailed endpoint documentation
@@ -130,7 +130,7 @@ memory = Memory.from_config_file("config.yaml")
 </Tabs>

 <Info icon="check">
-  Run `memory.add(["Remember my favorite cafe in Tokyo."], user_id="alex")` and then `memory.search("favorite cafe", user_id="alex")`. You should see the Qdrant collection populate and the reranker mark the memory as a top hit.
+  Run `memory.add(["Remember my favorite cafe in Tokyo."], user_id="alex")` and then `memory.search("favorite cafe", filters={"user_id": "alex"})`. You should see the Qdrant collection populate and the reranker mark the memory as a top hit.
 </Info>

 ## Tune component settings
@@ -90,7 +90,7 @@ async def get_memory():

 async def safe_memory_usage():
    async with get_memory() as memory:
-        return await memory.search("test query", user_id="alice")
+        return await memory.search("test query", filters={"user_id": "alice"})
 ```

 <Tip>
@@ -145,7 +145,7 @@ async def robust_memory_search():
    memory = AsyncMemory()

    async def search_operation():
-        return await memory.search("test query", user_id="alice")
+        return await memory.search("test query", filters={"user_id": "alice"})

    return await with_timeout_and_retry(search_operation)
 ```
@@ -173,11 +173,11 @@ result = await memory.add(
 # Search memories
 results = await memory.search(
    query="Where am I travelling?",
-    user_id="alice"
+    filters={"user_id": "alice"}
 )

 # List memories
-all_memories = await memory.get_all(user_id="alice")
+all_memories = await memory.get_all(filters={"user_id": "alice"})

 # Get a specific memory
 specific_memory = await memory.get(memory_id="memory-id-here")
@@ -213,13 +213,11 @@ await memory.add(
    run_id="consultation-001"
 )

-all_user_memories = await memory.get_all(user_id="alice")
-agent_memories = await memory.get_all(user_id="alice", agent_id="diet-assistant")
-session_memories = await memory.get_all(user_id="alice", run_id="consultation-001")
+all_user_memories = await memory.get_all(filters={"user_id": "alice"})
+agent_memories = await memory.get_all(filters={"user_id": "alice", "agent_id": "diet-assistant"})
+session_memories = await memory.get_all(filters={"user_id": "alice", "run_id": "consultation-001"})
 specific_memories = await memory.get_all(
-    user_id="alice",
-    agent_id="diet-assistant",
-    run_id="consultation-001"
+    filters={"user_id": "alice", "agent_id": "diet-assistant", "run_id": "consultation-001"}
 )

 history = await memory.history(memory_id="memory-id-here")
@@ -240,7 +238,7 @@ async_openai_client = AsyncOpenAI()
 async_memory = AsyncMemory()

 async def chat_with_memories(message: str, user_id: str = "default_user") -> str:
-    search_result = await async_memory.search(query=message, user_id=user_id, top_k=3)
+    search_result = await async_memory.search(query=message, filters={"user_id": user_id}, top_k=3)
    relevant_memories = search_result["results"]
    memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories)

@@ -255,7 +253,7 @@ async def chat_with_memories(message: str, user_id: str = "default_user") -> str
    ]

    response = await async_openai_client.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
        messages=messages
    )

@@ -280,7 +278,7 @@ async def handle_initialization_errors():
    try:
        config = MemoryConfig(
            vector_store={"provider": "chroma", "config": {"path": "./chroma_db"}},
-            llm={"provider": "openai", "config": {"model": "gpt-4.1-nano-2025-04-14"}}
+            llm={"provider": "openai", "config": {"model": "gpt-5-mini"}}
        )
        AsyncMemory(config=config)
        print("AsyncMemory initialized successfully")
@@ -297,7 +295,7 @@ async def handle_memory_operation_errors():
        print(f"Invalid memory ID: {err}")

    try:
-        await memory.search(query="", user_id="alice")
+        await memory.search(query="", filters={"user_id": "alice"})
    except ValueError as err:
        print(f"Invalid search query: {err}")
 ```
@@ -326,7 +324,7 @@ async def add_memory(messages: list, user_id: str):
@app.get("/memories/search")
 async def search_memories(query: str, user_id: str, limit: int = 10):
    try:
-        result = await memory.search(query=query, user_id=user_id, top_k=limit)
+        result = await memory.search(query=query, filters={"user_id": user_id}, top_k=limit)
        return {"status": "success", "data": result}
    except Exception as exc:
        raise HTTPException(status_code=500, detail=str(exc))
@@ -109,7 +109,7 @@ config = {
    "llm": {
        "provider": "openai",
        "config": {
-            "model": "gpt-4.1-nano-2025-04-14",
+            "model": "gpt-5-mini",
            "temperature": 0.2,
            "max_tokens": 2000,
        }
@@ -1,306 +0,0 @@
---
-title: Custom Update Memory Prompt
-description: Decide how Mem0 adds, updates, or deletes memories using your own rules.
-icon: "arrows-rotate"
---
-
-The custom update memory prompt tells Mem0 how to handle changes when new facts arrive. Craft the prompt so the LLM can compare incoming facts with existing memories and choose the right action.
-
-<Info>
-  **You’ll use this when…**
-  - Stored memories need to stay consistent as users change preferences or correct past statements.
-  - Your product has clear rules for when to add, update, delete, or leave a memory untouched.
-  - You want traceable decisions (ADD, UPDATE, DELETE, NONE) for auditing or compliance.
-</Info>
-
-<Warning>
-  Prompts that mix instructions or omit examples can lead to wrong actions like deleting valid memories. Keep the language simple and test each action path.
-</Warning>
-
---
-
-## Feature anatomy
-
- **Action verbs:** The prompt teaches the model to return `ADD`, `UPDATE`, `DELETE`, or `NONE` for every memory entry.
- **ID retention:** Updates reuse the original memory ID so downstream systems maintain history.
- **Old vs. new text:** Updates include `old_memory` so you can track what changed.
- **Decision table:** Your prompt should explain when to use each action and show concrete examples.
-
-<AccordionGroup>
-  <Accordion title="Decision guide">
-    | Action | When to choose it | Output details |
-    | --- | --- | --- |
-    | `ADD` | Fact is new and not stored yet | Generate a new ID and set `event: "ADD"`. |
-    | `UPDATE` | Fact replaces older info about the same topic | Keep the original ID, include `old_memory`. |
-    | `DELETE` | Fact contradicts the stored memory or you explicitly remove it | Keep ID, set `event: "DELETE"`. |
-    | `NONE` | Fact matches existing memory or is irrelevant | Keep ID with `event: "NONE"`. |
-  </Accordion>
-</AccordionGroup>
-
---
-
-## Configure it
-
-### Author the prompt
-
-<CodeGroup>
-```python Python
-UPDATE_MEMORY_PROMPT = """You are a smart memory manager which controls the memory of a system.
-You can perform four operations: (1) add into the memory, (2) update the memory, (3) delete from the memory, and (4) no change.
-
-Based on the above four operations, the memory will change.
-
-Compare newly retrieved facts with the existing memory. For each new fact, decide whether to:
- ADD: Add it to the memory as a new element
- UPDATE: Update an existing memory element
- DELETE: Delete an existing memory element
- NONE: Make no change (if the fact is already present or irrelevant)
-
-There are specific guidelines to select which operation to perform:
-
-1. **Add**: If the retrieved facts contain new information not present in the memory, then you have to add it by generating a new ID in the id field.
- **Example**:
-    - Old Memory:
-        [
-            {
-                "id" : "0",
-                "text" : "User is a software engineer"
-            }
-        ]
-    - Retrieved facts: ["Name is John"]
-    - New Memory:
-        {
-            "memory" : [
-                {
-                    "id" : "0",
-                    "text" : "User is a software engineer",
-                    "event" : "NONE"
-                },
-                {
-                    "id" : "1",
-                    "text" : "Name is John",
-                    "event" : "ADD"
-                }
-            ]
-
-        }
-
-2. **Update**: If the retrieved facts contain information that is already present in the memory but the information is totally different, then you have to update it. 
-If the retrieved fact contains information that conveys the same thing as the elements present in the memory, then you have to keep the fact which has the most information. 
-Example (a) -- if the memory contains "User likes to play cricket" and the retrieved fact is "Loves to play cricket with friends", then update the memory with the retrieved facts.
-Example (b) -- if the memory contains "Likes cheese pizza" and the retrieved fact is "Loves cheese pizza", then you do not need to update it because they convey the same information.
-If the direction is to update the memory, then you have to update it.
-Please keep in mind while updating you have to keep the same ID.
-Please note to return the IDs in the output from the input IDs only and do not generate any new ID.
- **Example**:
-    - Old Memory:
-        [
-            {
-                "id" : "0",
-                "text" : "I really like cheese pizza"
-            },
-            {
-                "id" : "1",
-                "text" : "User is a software engineer"
-            },
-            {
-                "id" : "2",
-                "text" : "User likes to play cricket"
-            }
-        ]
-    - Retrieved facts: ["Loves chicken pizza", "Loves to play cricket with friends"]
-    - New Memory:
-        {
-        "memory" : [
-                {
-                    "id" : "0",
-                    "text" : "Loves cheese and chicken pizza",
-                    "event" : "UPDATE",
-                    "old_memory" : "I really like cheese pizza"
-                },
-                {
-                    "id" : "1",
-                    "text" : "User is a software engineer",
-                    "event" : "NONE"
-                },
-                {
-                    "id" : "2",
-                    "text" : "Loves to play cricket with friends",
-                    "event" : "UPDATE",
-                    "old_memory" : "User likes to play cricket"
-                }
-            ]
-        }
-
-
-3. **Delete**: If the retrieved facts contain information that contradicts the information present in the memory, then you have to delete it. Or if the direction is to delete the memory, then you have to delete it.
-Please note to return the IDs in the output from the input IDs only and do not generate any new ID.
- **Example**:
-    - Old Memory:
-        [
-            {
-                "id" : "0",
-                "text" : "Name is John"
-            },
-            {
-                "id" : "1",
-                "text" : "Loves cheese pizza"
-            }
-        ]
-    - Retrieved facts: ["Dislikes cheese pizza"]
-    - New Memory:
-        {
-        "memory" : [
-                {
-                    "id" : "0",
-                    "text" : "Name is John",
-                    "event" : "NONE"
-                },
-                {
-                    "id" : "1",
-                    "text" : "Loves cheese pizza",
-                    "event" : "DELETE"
-                }
-        ]
-        }
-
-4. **No Change**: If the retrieved facts contain information that is already present in the memory, then you do not need to make any changes.
- **Example**:
-    - Old Memory:
-        [
-            {
-                "id" : "0",
-                "text" : "Name is John"
-            },
-            {
-                "id" : "1",
-                "text" : "Loves cheese pizza"
-            }
-        ]
-    - Retrieved facts: ["Name is John"]
-    - New Memory:
-        {
-        "memory" : [
-                {
-                    "id" : "0",
-                    "text" : "Name is John",
-                    "event" : "NONE"
-                },
-                {
-                    "id" : "1",
-                    "text" : "Loves cheese pizza",
-                    "event" : "NONE"
-                }
-            ]
-        }
-"""
-```
-</CodeGroup>
-
-### Define the expected output format
-
-<CodeGroup>
-```json Add
-{
-  "memory": [
-    {
-      "id": "0",
-      "text": "This information is new",
-      "event": "ADD"
-    }
-  ]
-}
-```
-
-```json Update
-{
-  "memory": [
-    {
-      "id": "0",
-      "text": "This information replaces the old information",
-      "event": "UPDATE",
-      "old_memory": "Old information"
-    }
-  ]
-}
-```
-
-```json Delete
-{
-  "memory": [
-    {
-      "id": "0",
-      "text": "This information will be deleted",
-      "event": "DELETE"
-    }
-  ]
-}
-```
-
-```json No Change
-{
-  "memory": [
-    {
-      "id": "0",
-      "text": "No changes for this information",
-      "event": "NONE"
-    }
-  ]
-}
-```
-</CodeGroup>
-
-<Info icon="check">
-  Consistent JSON structure makes it easy to parse decisions downstream or log them for auditing.
-</Info>
-
---
-
-## See it in action
-
- Run reconciliation jobs that compare retrieved facts to existing memories.  
- Feed both sources into the custom prompt, then apply the returned actions (add new entries, update text, delete outdated facts).
- Log each decision so product teams can review why a change happened.
-
-<Note>
-  The prompt works alongside `custom_instructions`—fact extraction identifies candidate facts, and the update prompt decides how to merge them into long-term storage.
-</Note>
-
---
-
-## Verify the feature is working
-
- Test all four actions with targeted examples, including edge cases where facts differ only slightly.
- Confirm update responses keep the original IDs and include `old_memory`.
- Ensure delete actions only trigger when contradictions appear or when you explicitly request removal.
-
---
-
-## Best practices
-
-1. **Keep instructions brief:** Remove redundant wording so the LLM focuses on the decision logic.
-2. **Document your schema:** Share the prompt and examples with your team so everyone knows how memories evolve.
-3. **Track prompt versions:** When rules change, bump a version number and archive the prior prompt.
-4. **Review outputs regularly:** Skim audit logs weekly to spot drift or repeated mistakes.
-5. **Pair with monitoring:** Visualize counts of each action to detect spikes in deletes or updates.
-
---
-
-## Compare prompts
-
-| Feature | `custom_update_memory_prompt` | `custom_instructions` |
-| --- | --- | --- |
-| Primary job | Decide memory actions (ADD/UPDATE/DELETE/NONE) | Pull facts from user and assistant messages |
-| Inputs | Retrieved facts + existing memory entries | Raw conversation turns |
-| Output | Structured memory array with events | Array of extracted facts |
-
---
-
-<CardGroup cols={2}>
-  <Card title="Design Fact Extraction" icon="sparkles" href="/open-source/features/custom-instructions">
-    Coordinate both prompts so fact extraction feeds clean inputs into the update flow.
-  </Card>
-  <Card title="Build Email Automations" icon="inbox" href="/cookbooks/operations/email-automation">
-    See how update prompts keep customer profiles current in a working automation.
-  </Card>
-</CardGroup>
@@ -1,421 +0,0 @@
---
-title: Graph Memory
-description: "Layer relationships onto Mem0 search so agents remember who did what, when, and with whom."
-icon: "network-wired"
---
-
-Graph Memory extends Mem0 by persisting nodes and edges alongside embeddings, so recalls stitch together people, places, and events instead of just keywords.
-
-<Info icon="sparkles">
-**You’ll use this when…**
- Conversation history mixes multiple actors and objects that vectors alone blur together
- Compliance or auditing demands a graph of who said what and when
- Agent teams need shared context without duplicating every memory in each run
-</Info>
-
-## How Graph Memory Maps Context
-
-Mem0 extracts entities and relationships from every memory write, stores embeddings in your vector database, and mirrors relationships in a graph backend. On retrieval, vector search narrows candidates while the graph returns related context alongside the results.
-
-```mermaid
-graph LR
-    A[Conversation] --> B(Extraction LLM)
-    B --> C[Vector Store]
-    B --> D[Graph Store]
-    E[Query] --> C
-    C --> F[Candidate Memories]
-    F --> D
-    D --> G[Contextual Recall]
-```
-
-## How It Works
-
-<Steps>
-<Step title="Extract people, places, and facts">
-Mem0’s extraction LLM identifies entities, relationships, and timestamps from the conversation payload you send to `memory.add`.
-</Step>
-<Step title="Store vectors and edges together">
-Embeddings land in your configured vector database while nodes and edges flow into a graph backend (Neo4j, Memgraph, Neptune, Kuzu, or Apache AGE).
-</Step>
-<Step title="Expose graph context at search time">
-`memory.search` performs vector similarity (optionally reranked by your configured reranker) and returns the results list. Graph Memory runs in parallel and adds related entities in the `relations` array—it does not reorder the vector hits automatically.
-</Step>
-</Steps>
-
-## Quickstart (Neo4j Aura)
-
-<Info icon="clock">
-**Time to implement:** ~10 minutes · **Prerequisites:** Python 3.10+, Node.js 18+, Neo4j Aura DB (free tier)
-</Info>
-
-Provision a free [Neo4j Aura](https://neo4j.com/product/auradb/) instance, copy the Bolt URI, username, and password, then follow the language tab that matches your stack.
-
-<Tabs>
-  <Tab title="Python">
-<Steps>
-<Step title="Install Mem0 with graph extras">
-```bash
-pip install "mem0ai[graph]"
-```
-</Step>
-<Step title="Export Neo4j credentials">
-```bash
-export NEO4J_URL="neo4j+s://<your-instance>.databases.neo4j.io"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="your-password"
-```
-</Step>
-<Step title="Add and recall a relationship">
-```python
-import os
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {
-            "url": os.environ["NEO4J_URL"],
-            "username": os.environ["NEO4J_USERNAME"],
-            "password": os.environ["NEO4J_PASSWORD"],
-            "database": "neo4j",
-        }
-    }
-}
-
-memory = Memory.from_config(config)
-
-conversation = [
-    {"role": "user", "content": "Alice met Bob at GraphConf 2025 in San Francisco."},
-    {"role": "assistant", "content": "Great! Logging that connection."},
-]
-
-memory.add(conversation, user_id="demo-user")
-
-results = memory.search(
-    "Who did Alice meet at GraphConf?",
-    user_id="demo-user",
-    top_k=3,
-    rerank=True,
-)
-
-for hit in results["results"]:
-    print(hit["memory"])
-```
-</Step>
-</Steps>
-  </Tab>
-  <Tab title="TypeScript">
-<Steps>
-<Step title="Install the OSS SDK">
-```bash
-npm install mem0ai
-```
-</Step>
-<Step title="Load Neo4j credentials">
-```bash
-export NEO4J_URL="neo4j+s://<your-instance>.databases.neo4j.io"
-export NEO4J_USERNAME="neo4j"
-export NEO4J_PASSWORD="your-password"
-```
-</Step>
-<Step title="Enable graph memory and query it">
-```typescript
-import { Memory } from "mem0ai/oss";
-
-const config = {
-  graphStore: {
-    provider: "neo4j",
-    config: {
-      url: process.env.NEO4J_URL!,
-      username: process.env.NEO4J_USERNAME!,
-      password: process.env.NEO4J_PASSWORD!,
-      database: "neo4j",
-    },
-  },
-};
-
-const memory = new Memory(config);
-
-const conversation = [
-  { role: "user", content: "Alice met Bob at GraphConf 2025 in San Francisco." },
-  { role: "assistant", content: "Great! Logging that connection." },
-];
-
-await memory.add(conversation, { userId: "demo-user" });
-
-const results = await memory.search(
-  "Who did Alice meet at GraphConf?",
-  { userId: "demo-user", topK: 3, rerank: true }
-);
-
-results.results.forEach((hit) => {
-  console.log(hit.memory);
-});
-```
-</Step>
-</Steps>
-  </Tab>
-</Tabs>
-
-<Info icon="check">
-Expect to see **Alice met Bob at GraphConf 2025** in the output. In Neo4j Browser run `MATCH (p:Person)-[r]->(q:Person) RETURN p,r,q LIMIT 5;` to confirm the edge exists.
-</Info>
-
-<Note>
-Graph Memory enriches responses by adding related entities in the `relations` key. The ordering of `results` always comes from vector search (plus any reranker you configure); graph edges do not reorder those hits automatically.
-</Note>
-
-## Operate Graph Memory Day-to-Day
-
-<AccordionGroup>
-  <Accordion title="Refine extraction prompts">
-    Guide which relationships become nodes and edges.
-
-<CodeGroup>
-```python Python
-import os
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {
-            "url": os.environ["NEO4J_URL"],
-            "username": os.environ["NEO4J_USERNAME"],
-            "password": os.environ["NEO4J_PASSWORD"],
-        },
-        "custom_prompt": "Please only capture people, organisations, and project links.",
-    }
-}
-
-memory = Memory.from_config(config_dict=config)
-```
-
-```typescript TypeScript
-import { Memory } from "mem0ai/oss";
-
-const config = {
-  graphStore: {
-    provider: "neo4j",
-    config: {
-      url: process.env.NEO4J_URL!,
-      username: process.env.NEO4J_USERNAME!,
-      password: process.env.NEO4J_PASSWORD!,
-    },
-    customInstructions: "Please only capture people, organisations, and project links.",
-  }
-};
-
-const memory = new Memory(config);
-```
-</CodeGroup>
-  </Accordion>
-  <Accordion title="Raise the confidence threshold">
-    Keep noisy edges out of the graph by demanding higher extraction confidence.
-
-```python
-config["graph_store"]["config"]["threshold"] = 0.75
-```
-  </Accordion>
-  <Accordion title="Organize multi-agent graphs">
-    Separate or share context across agents and sessions with `user_id`, `agent_id`, and `run_id`.
-
-<CodeGroup>
-```typescript TypeScript
-memory.add("I prefer Italian cuisine", { userId: "bob", agentId: "food-assistant" });
-memory.add("I'm allergic to peanuts", { userId: "bob", agentId: "health-assistant" });
-memory.add("I live in Seattle", { userId: "bob" });
-
-const food = await memory.search("What food do I like?", { userId: "bob", agentId: "food-assistant" });
-const allergies = await memory.search("What are my allergies?", { userId: "bob", agentId: "health-assistant" });
-const location = await memory.search("Where do I live?", { userId: "bob" });
-```
-</CodeGroup>
-  </Accordion>
-</AccordionGroup>
-
-<Note>
-Monitor graph growth, especially on free tiers, by periodically cleaning dormant nodes: `MATCH (n) WHERE n.lastSeen < date() - duration('P90D') DETACH DELETE n`.
-</Note>
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="Neo4j connection refused">
-    Confirm Bolt connectivity is enabled, credentials match Aura, and your IP is allow-listed. Retry after confirming the URI format is `neo4j+s://...`.
-  </Accordion>
-  <Accordion title="Neptune Analytics rejects requests">
-    Ensure the graph identifier matches the vector dimension used by your embedder and that the IAM role allows `neptune-graph:*DataViaQuery` actions.
-  </Accordion>
-</AccordionGroup>
-
-## Decision Points
-
- Select the graph store that fits your deployment (managed Aura vs. self-hosted Neo4j vs. AWS Neptune vs. local Kuzu vs. Apache AGE on PostgreSQL).
- Decide whether to include a graph store in your config; routine conversations may stay vector-only to save latency.
- Set a policy for pruning stale relationships so your graph stays fast and affordable.
-
-## Provider setup
-
-Choose your backend and expand the matching panel for configuration details and links.
-
-<AccordionGroup>
-  <Accordion title="Neo4j Aura or self-hosted">
-    Install the APOC plugin for self-hosted deployments, then configure Mem0:
-
-```typescript
-import { Memory } from "mem0ai/oss";
-
-const config = {
-    graphStore: {
-        provider: "neo4j",
-        config: {
-            url: "neo4j+s://<HOST>",
-            username: "neo4j",
-            password: "<PASSWORD>",
-        }
-    }
-};
-
-const memory = new Memory(config);
-```
-
-Additional docs: [Neo4j Aura Quickstart](https://neo4j.com/docs/aura/), [APOC installation](https://neo4j.com/docs/apoc/current/installation/).
-  </Accordion>
-  <Accordion title="Memgraph (Docker)">
-    Run Memgraph Mage locally with schema introspection enabled:
-
-```bash
-docker run -p 7687:7687 memgraph/memgraph-mage:latest --schema-info-enabled=True
-```
-
-Then point Mem0 at the instance:
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "memgraph",
-        "config": {
-            "url": "bolt://localhost:7687",
-            "username": "memgraph",
-            "password": "your-password",
-        },
-    },
-}
-
-m = Memory.from_config(config_dict=config)
-```
-
-Learn more: [Memgraph Docs](https://memgraph.com/docs).
-  </Accordion>
-  <Accordion title="Amazon Neptune Analytics">
-    Match vector dimensions between Neptune and your embedder, enable public connectivity (if needed), and grant IAM permissions:
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neptune",
-        "config": {
-            "endpoint": "neptune-graph://<GRAPH_ID>",
-        },
-    },
-}
-
-m = Memory.from_config(config_dict=config)
-```
-
-Reference: [Neptune Analytics Guide](https://docs.aws.amazon.com/neptune/latest/analytics/).
-  </Accordion>
-  <Accordion title="Amazon Neptune DB (with external vectors)">
-    Create a Neptune cluster, enable the public endpoint if you operate outside the VPC, and point Mem0 at the host:
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neptunedb",
-        "config": {
-            "collection_name": "<VECTOR_COLLECTION_NAME>",
-            "endpoint": "neptune-graph://<HOST_ENDPOINT>",
-        },
-    },
-}
-
-m = Memory.from_config(config_dict=config)
-```
-
-Reference: [Accessing Data in Neptune DB](https://docs.aws.amazon.com/neptune/latest/userguide/).
-  </Accordion>
-  <Accordion title="Kuzu (embedded)">
-    Kuzu runs in-process, so supply a path (or `:memory:`) for the database file:
-
-```python
-config = {
-    "graph_store": {
-        "provider": "kuzu",
-        "config": {
-            "db": "/tmp/mem0-example.kuzu"
-        }
-    }
-}
-```
-
-Kuzu will clear its state when using `:memory:` once the process exits. See the [Kuzu documentation](https://kuzudb.com/docs/) for advanced settings.
-  </Accordion>
-  <Accordion title="Apache AGE (PostgreSQL extension)">
-    [Apache AGE](https://age.apache.org/) adds graph database capabilities to PostgreSQL, letting you run Cypher queries alongside SQL on the same server. Start AGE via Docker, then configure Mem0:
-
-```bash
-docker run --name age-postgres \
-  -e POSTGRES_DB=mem0_db \
-  -e POSTGRES_USER=mem0_user \
-  -e POSTGRES_PASSWORD=mem0_pass \
-  -p 5432:5432 \
-  -d apache/age
-```
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "apache_age",
-        "config": {
-            "host": "localhost",
-            "port": 5432,
-            "database": "mem0_db",
-            "username": "mem0_user",
-            "password": "mem0_pass",
-            "graph_name": "mem0_graph",
-        },
-    },
-}
-
-m = Memory.from_config(config_dict=config)
-```
-
-Apache AGE does not have a built-in vector index, so similarity search is computed client-side. This works well for moderate graph sizes; for very large graphs consider pairing AGE with pgvector for the vector store.
-
-Reference: [Apache AGE documentation](https://age.apache.org/age-manual/master/index.html).
-  </Accordion>
-</AccordionGroup>
-
-<CardGroup cols={2}>
-  <Card
-    title="Enhanced Metadata Filtering"
-    description="Blend field-level filters with graph context to zero in on the right memories."
-    icon="funnel"
-    href="/open-source/features/metadata-filtering"
-  />
-  <Card
-    title="Reranker-Enhanced Search"
-    description="Layer rerankers on top of vectors and graphs for the cleanest results."
-    icon="sparkles"
-    href="/open-source/features/reranker-search"
-  />
-</CardGroup>
@@ -41,7 +41,7 @@ messages = [

 chat_completion = client.chat.completions.create(
    messages=messages,
-    model="gpt-4.1-nano-2025-04-14",
+    model="gpt-5-mini",
    user_id="alice"
 )
 ```
@@ -69,7 +69,7 @@ client = Mem0(config=config)

 chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "What's the capital of France?"}],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )
 ```

@@ -85,14 +85,14 @@ client = Mem0(api_key="m0-xxx")
 # Store preferences
 client.chat.completions.create(
    messages=[{"role": "user", "content": "I love Indian food but I'm allergic to cheese."}],
-    model="gpt-4.1-nano-2025-04-14",
+    model="gpt-5-mini",
    user_id="alice"
 )

 # Later conversation reuses the memory
 response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Suggest dinner options in San Francisco."}],
-    model="gpt-4.1-nano-2025-04-14",
+    model="gpt-5-mini",
    user_id="alice"
 )

@@ -15,9 +15,6 @@ Mem0 Open Source ships with capabilities that adapt memory behavior for producti
 ## Choose your path

 <CardGroup cols={3}>
-  <Card title="Graph Memory" icon="network-wired" href="/open-source/features/graph-memory">
-    Store entity relationships for multi-hop recall.
-  </Card>
  <Card title="Advanced Metadata Filtering" icon="filter" href="/open-source/features/metadata-filtering">
    Query with logical operators and nested conditions.
  </Card>
@@ -35,10 +32,7 @@ Mem0 Open Source ships with capabilities that adapt memory behavior for producti
  </Card>
 </CardGroup>

-<CardGroup cols={3}>
-  <Card title="Custom Memory Updates" icon="arrows-rotate" href="/open-source/features/custom-update-memory-prompt">
-    Control memory refinement with custom instructions.
-  </Card>
+<CardGroup cols={2}>
  <Card title="REST API" icon="code" href="/open-source/features/rest-api">
    HTTP endpoints for language-agnostic integrations.
  </Card>
@@ -222,7 +222,7 @@ config = {
 def smart_search(query, user_id, use_rerank=None):
    if use_rerank is None:
        use_rerank = len(query.split()) > 3
-    return m.search(query, user_id=user_id, rerank=use_rerank)
+    return m.search(query, filters={"user_id": user_id}, rerank=use_rerank)
 ```

 <Tip>
@@ -233,10 +233,10 @@ def smart_search(query, user_id, use_rerank=None):

 ```python
 try:
-    results = m.search("test query", user_id="alice", rerank=True)
+    results = m.search("test query", filters={"user_id": "alice"}, rerank=True)
 except Exception as exc:
    print(f"Reranking failed: {exc}")
-    results = m.search("test query", user_id="alice", rerank=False)
+    results = m.search("test query", filters={"user_id": "alice"}, rerank=False)
 ```

 <Warning>
@@ -247,7 +247,7 @@ except Exception as exc:

 ```python
 # Before: basic vector search
-results = m.search("query", user_id="alice")
+results = m.search("query", filters={"user_id": "alice"})

 # After: same API with reranking enabled via config
 config = {
@@ -260,7 +260,7 @@ config = {
 }

 m = Memory.from_config(config)
-results = m.search("query", user_id="alice")
+results = m.search("query", filters={"user_id": "alice"})
 ```

 ---
@@ -43,7 +43,7 @@ await memory.add(messages, { userId: "alice", metadata: { category: "movie_recom

 <Step title="Search memories">
 ```ts
-const results = await memory.search("What do you know about me?", { userId: "alice" });
+const results = await memory.search("What do you know about me?", { filters: { userId: "alice" } });
 console.log(results);
 ```

@@ -67,7 +67,7 @@ console.log(results);
 </Steps>

 <Note>
-By default the Node SDK uses local-friendly settings (OpenAI `gpt-4.1-nano-2025-04-14`, `text-embedding-3-small`, in-memory vector store, and SQLite history). Swap components by passing a config as shown below.
+By default the Node SDK uses local-friendly settings (OpenAI `gpt-5-mini`, `text-embedding-3-small`, in-memory vector store, and SQLite history). Swap components by passing a config as shown below.
 </Note>

 ## Configure for production
@@ -106,7 +106,7 @@ const memory = new Memory({

 <CodeGroup>
 ```ts Get all memories
-const allMemories = await memory.getAll({ userId: "alice" });
+const allMemories = await memory.getAll({ filters: { userId: "alice" } });
 console.log(allMemories);
 ```

@@ -116,7 +116,7 @@ console.log(singleMemory);
 ```

 ```ts Search memories
-const result = await memory.search("What do you know about me?", { userId: "alice" });
+const result = await memory.search("What do you know about me?", { filters: { userId: "alice" } });
 console.log(result);
 ```

@@ -37,12 +37,12 @@ Mem0 Open Source delivers the same adaptive memory engine as the platform, but p
  <Card title="Configure Components" icon="sliders" href="/open-source/configuration">
    LLM, embedder, vector store, reranker setup.
  </Card>
-  <Card title="Graph Memory Capability" icon="network-wired" href="/open-source/features/graph-memory">
-    Relationship-aware recall with Neo4j, Memgraph.
-  </Card>
  <Card title="Tune Retrieval & Rerankers" icon="sparkles" href="/open-source/features/reranker-search">
    Hybrid retrieval and reranker controls.
  </Card>
+  <Card title="Memory Evaluation" icon="chart-line" href="/core-concepts/memory-evaluation">
+    Benchmarks and how Mem0 is tested.
+  </Card>
 </CardGroup>

 <CardGroup cols={2}>
@@ -75,7 +75,7 @@ Mem0 Open Source delivers the same adaptive memory engine as the platform, but p

 <Note>
  Mem0 OSS works out of the box with sensible defaults:
-  - LLM: OpenAI `gpt-4.1-nano-2025-04-14` (via `OPENAI_API_KEY`)
+  - LLM: OpenAI `gpt-5-mini` (via `OPENAI_API_KEY`)
  - Embeddings: OpenAI `text-embedding-3-small`
  - Vector store: Local Qdrant instance storing data at `/tmp/qdrant`
  - History store: SQLite database at `~/.mem0/history.db`
@@ -52,7 +52,7 @@ m.add(messages, user_id="alex")

 <Step title="Search memories">
 ```python
-results = m.search("What do you know about me?", user_id="alex")
+results = m.search("What do you know about me?", filters={"user_id": "alex"})
 print(results)
 ```

@@ -79,7 +79,7 @@ print(results)

 <Note>
 By default `Memory()` wires up:
- OpenAI `gpt-4.1-nano-2025-04-14` for fact extraction and updates
+- OpenAI `gpt-5-mini` for fact extraction and updates
 - OpenAI `text-embedding-3-small` embeddings (1536 dimensions)
 - Qdrant vector store with on-disk data at `/tmp/qdrant`
 - SQLite history at `~/.mem0/history.db`
@@ -1048,8 +1048,8 @@
 											},
 											"expiration_date": {
 												"type": "string",
-												"format": "date-time",
-												"description": "The date and time when the memory will expire. Format: YYYY-MM-DD.",
+												"format": "date",
+												"description": "The date when the memory will expire. Format: YYYY-MM-DD.",
 												"title": "Expiration date",
 												"nullable": true,
 												"default": null
@@ -1096,7 +1096,7 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Retrieve memories for a specific user\nuser_memories = client.get_all(user_id=\"<user_id>\")\n\nprint(user_memories)"
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Retrieve memories for a specific user\nuser_memories = client.get_all(filters={\"user_id\": \"<user_id>\"})\n\nprint(user_memories)"
 					},
 					{
 						"lang": "JavaScript",
@@ -1232,8 +1232,8 @@
 				"tags": [
 					"memories"
 				],
-				"description": "Delete memories by filter. At least one filter is required \u2014 previously omitting all filters silently deleted everything; now it returns a validation error.",
-				"operationId": "memories_delete",
+				"description": "Delete memories by filter. At least one filter is required — previously omitting all filters silently deleted everything; now it returns a validation error.",
+				"operationId": "memories_delete_all",
 				"parameters": [
 					{
 						"name": "user_id",
@@ -1315,15 +1315,15 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Delete all memories for a specific user\nclient.delete_all(user_id=\"<user_id>\")\n\n# Delete all memories for every user in the project (wildcard)\nclient.delete_all(user_id=\"*\")\n\n# Full project wipe \u2014 all four filters must be explicitly set to \"*\"\nclient.delete_all(user_id=\"*\", agent_id=\"*\", app_id=\"*\", run_id=\"*\")\n\n# NOTE: Calling delete_all() with no filters raises a validation error.\n# At least one filter is required to prevent accidental data loss."
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\n# Delete all memories for a specific user\nclient.delete_all(user_id=\"<user_id>\")\n\n# Delete all memories for every user in the project (wildcard)\nclient.delete_all(user_id=\"*\")\n\n# Full project wipe — all four filters must be explicitly set to \"*\"\nclient.delete_all(user_id=\"*\", agent_id=\"*\", app_id=\"*\", run_id=\"*\")\n\n# NOTE: Calling delete_all() with no filters raises a validation error.\n# At least one filter is required to prevent accidental data loss."
 					},
 					{
 						"lang": "JavaScript",
-						"source": "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Delete all memories for a specific user\nclient.deleteAll({ user_id: \"<user_id>\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));\n\n// Delete all memories for every user in the project (wildcard)\nclient.deleteAll({ user_id: \"*\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));\n\n// Full project wipe \u2014 all four filters must be explicitly set to \"*\"\nclient.deleteAll({ user_id: \"*\", agent_id: \"*\", app_id: \"*\", run_id: \"*\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));"
+						"source": "// To use the JavaScript SDK, install the package:\n// npm i mem0ai\n\nimport MemoryClient from 'mem0ai';\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\n// Delete all memories for a specific user\nclient.deleteAll({ user_id: \"<user_id>\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));\n\n// Delete all memories for every user in the project (wildcard)\nclient.deleteAll({ user_id: \"*\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));\n\n// Full project wipe — all four filters must be explicitly set to \"*\"\nclient.deleteAll({ user_id: \"*\", agent_id: \"*\", app_id: \"*\", run_id: \"*\" })\n  .then(result => console.log(result))\n  .catch(error => console.error(error));"
 					},
 					{
 						"lang": "cURL",
-						"source": "# Delete memories for a specific user\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=<user_id>' \\\n  --header 'Authorization: Token <api-key>'\n\n# Delete memories for all users (wildcard)\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=*' \\\n  --header 'Authorization: Token <api-key>'\n\n# Full project wipe \u2014 all four filters must be set to *\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=*&agent_id=*&app_id=*&run_id=*' \\\n  --header 'Authorization: Token <api-key>'"
+						"source": "# Delete memories for a specific user\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=<user_id>' \\\n  --header 'Authorization: Token <api-key>'\n\n# Delete memories for all users (wildcard)\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=*' \\\n  --header 'Authorization: Token <api-key>'\n\n# Full project wipe — all four filters must be set to *\ncurl --request DELETE \\\n  --url 'https://api.mem0.ai/v1/memories/?user_id=*&agent_id=*&app_id=*&run_id=*' \\\n  --header 'Authorization: Token <api-key>'"
 					},
 					{
 						"lang": "Go",
@@ -1393,8 +1393,8 @@
 											},
 											"expiration_date": {
 												"type": "string",
-												"format": "date-time",
-												"description": "The date and time when the memory will expire. Format: YYYY-MM-DD.",
+												"format": "date",
+												"description": "The date when the memory will expire. Format: YYYY-MM-DD.",
 												"title": "Expiration date",
 												"nullable": true,
 												"default": null
@@ -1540,8 +1540,8 @@
 											},
 											"expiration_date": {
 												"type": "string",
-												"format": "date-time",
-												"description": "The date and time when the memory will expire. Format: YYYY-MM-DD.",
+												"format": "date",
+												"description": "The date when the memory will expire. Format: YYYY-MM-DD.",
 												"title": "Expiration date",
 												"nullable": true,
 												"default": null
@@ -1589,7 +1589,7 @@
 				"x-code-samples": [
 					{
 						"lang": "Python",
-						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\nquery = \"Your search query here\"\n\nresults = client.search(query, user_id=\"<user_id>\")\nprint(results)"
+						"source": "# To use the Python SDK, install the package:\n# pip install mem0ai\n\nfrom mem0 import MemoryClient\nclient = MemoryClient(api_key=\"your_api_key\")\n\nquery = \"Your search query here\"\n\nresults = client.search(query, filters={\"user_id\": \"<user_id>\"})\nprint(results)"
 					},
 					{
 						"lang": "JavaScript",
@@ -1675,8 +1675,8 @@
 											},
 											"expiration_date": {
 												"type": "string",
-												"format": "date-time",
-												"description": "The date and time when the memory will expire. Format: YYYY-MM-DD.",
+												"format": "date",
+												"description": "The date when the memory will expire. Format: YYYY-MM-DD.",
 												"title": "Expiration date",
 												"nullable": true,
 												"default": null
@@ -1734,12 +1734,510 @@
 				"x-codegen-request-body-name": "data"
 			}
 		},
+		"/v3/memories/": {
+			"post": {
+				"tags": [
+					"memories"
+				],
+				"summary": "Get all memories (V3, paginated)",
+				"description": "List memories scoped by filters, paginated. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. `filters` supports the same operator set as V2 search (`AND`, `OR`, `NOT`, `in`, `gte`, `lte`, etc.). Response is a paginated envelope; pass `page` and `page_size` as query parameters to step through results.",
+				"operationId": "memories_list_v3",
+				"parameters": [
+					{
+						"in": "query",
+						"name": "page",
+						"schema": {
+							"type": "integer",
+							"minimum": 1,
+							"default": 1
+						},
+						"description": "1-indexed page number."
+					},
+					{
+						"in": "query",
+						"name": "page_size",
+						"schema": {
+							"type": "integer",
+							"minimum": 1,
+							"maximum": 200,
+							"default": 100
+						},
+						"description": "Results per page."
+					}
+				],
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"filters"
+								],
+								"properties": {
+									"filters": {
+										"type": "object",
+										"description": "Entity and metadata filters. Must include at least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`).",
+										"additionalProperties": true
+									}
+								}
+							},
+							"example": {
+								"filters": {
+									"user_id": "alice"
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Paginated envelope of memories.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"properties": {
+										"count": {
+											"type": "integer",
+											"description": "Total number of memories matching the filters."
+										},
+										"next": {
+											"type": "string",
+											"format": "uri",
+											"nullable": true,
+											"description": "URL for the next page, or `null` if this is the last page."
+										},
+										"previous": {
+											"type": "string",
+											"format": "uri",
+											"nullable": true,
+											"description": "URL for the previous page, or `null` if this is the first page."
+										},
+										"results": {
+											"type": "array",
+											"items": {
+												"type": "object",
+												"properties": {
+													"id": {
+														"type": "string",
+														"format": "uuid",
+														"description": "Unique memory identifier."
+													},
+													"memory": {
+														"type": "string",
+														"description": "The extracted memory fact."
+													},
+													"score": {
+														"type": "number",
+														"format": "float",
+														"minimum": 0,
+														"maximum": 1,
+														"description": "Combined multi-signal relevance score in [0, 1] (search responses only)."
+													},
+													"metadata": {
+														"type": "object",
+														"additionalProperties": true,
+														"description": "User-supplied metadata attached to the memory."
+													},
+													"categories": {
+														"type": "array",
+														"items": {
+															"type": "string"
+														}
+													},
+													"created_at": {
+														"type": "string",
+														"format": "date-time"
+													},
+													"updated_at": {
+														"type": "string",
+														"format": "date-time"
+													}
+												},
+												"required": [
+													"id",
+													"memory",
+													"created_at"
+												]
+											}
+										}
+									},
+									"required": [
+										"count",
+										"next",
+										"previous",
+										"results"
+									]
+								},
+								"example": {
+									"count": 123,
+									"next": "https://api.mem0.ai/v3/memories/?page=2&page_size=100",
+									"previous": null,
+									"results": [
+										{
+											"id": "mem-uuid",
+											"memory": "User moved to San Francisco from New York in January 2026",
+											"metadata": {},
+											"categories": [
+												"location"
+											],
+											"created_at": "2026-01-15T10:30:00Z",
+											"updated_at": "2026-01-15T10:30:00Z"
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Validation error — e.g. empty `filters` or no positively-scoped entity ID."
+					},
+					"401": {
+						"description": "Unauthorized — missing or invalid API key."
+					}
+				},
+				"security": [
+					{
+						"tokenAuth": []
+					}
+				],
+				"x-codeSamples": [
+					{
+						"lang": "cURL",
+						"source": "curl -X POST 'https://api.mem0.ai/v3/memories/?page=1&page_size=50' \\\n  -H \"Authorization: Token <api-key>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"filters\": {\"user_id\": \"alice\"}}'"
+					},
+					{
+						"lang": "Python",
+						"source": "from mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your-api-key\")\n\npage = client.get_all(filters={\"user_id\": \"alice\"}, page=1, page_size=50)\n# page == {\"count\": 123, \"next\": \"...\", \"previous\": None, \"results\": [...]}\nprint(page[\"count\"], len(page[\"results\"]))"
+					},
+					{
+						"lang": "JavaScript",
+						"source": "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst page = await client.getAll({\n  filters: { userId: \"alice\" },\n  page: 1,\n  pageSize: 50,\n});\nconsole.log(page.count, page.results.length);"
+					}
+				]
+			}
+		},
+		"/v3/memories/add/": {
+			"post": {
+				"tags": [
+					"memories"
+				],
+				"summary": "Add memories (V3)",
+				"description": "Extract and store memories from a conversation using the V3 additive pipeline. Entity IDs (`user_id` / `agent_id` / `run_id`) are accepted at the top level. At least one entity ID is required so the memory is scoped to a session.",
+				"operationId": "memories_add_v3",
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"messages"
+								],
+								"properties": {
+									"messages": {
+										"type": "array",
+										"description": "Conversation messages to extract memories from.",
+										"items": {
+											"type": "object",
+											"properties": {
+												"role": {
+													"type": "string",
+													"enum": [
+														"user",
+														"assistant",
+														"system"
+													]
+												},
+												"content": {
+													"type": "string"
+												}
+											},
+											"required": [
+												"role",
+												"content"
+											]
+										}
+									},
+									"user_id": {
+										"type": "string",
+										"description": "Scope memories to this user."
+									},
+									"agent_id": {
+										"type": "string",
+										"description": "Scope memories to this agent."
+									},
+									"run_id": {
+										"type": "string",
+										"description": "Scope memories to this session / run."
+									},
+									"metadata": {
+										"type": "object",
+										"additionalProperties": true,
+										"description": "User-supplied metadata to attach to each extracted memory."
+									},
+									"custom_instructions": {
+										"type": "string",
+										"description": "Project-level instructions that guide extraction for this call."
+									},
+									"infer": {
+										"type": "boolean",
+										"default": true,
+										"description": "When `false`, stores each message verbatim without running the extraction LLM."
+									}
+								}
+							},
+							"example": {
+								"messages": [
+									{
+										"role": "user",
+										"content": "I just moved to San Francisco from New York."
+									},
+									{
+										"role": "assistant",
+										"content": "Got it — I'll update your location."
+									}
+								],
+								"user_id": "alice"
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Memory addition queued; returns an event identifier clients can poll via `GET /v1/event/{event_id}/`.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"properties": {
+										"message": {
+											"type": "string"
+										},
+										"status": {
+											"type": "string",
+											"enum": [
+												"PENDING",
+												"SUCCEEDED",
+												"FAILED"
+											]
+										},
+										"event_id": {
+											"type": "string",
+											"format": "uuid"
+										}
+									}
+								},
+								"example": {
+									"message": "Memory processing has been queued for background execution",
+									"status": "PENDING",
+									"event_id": "2c4d1f44-4f7b-4b2f-9f6e-7b5b4f5a1234"
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Validation error — e.g. missing `messages` or no entity ID supplied."
+					},
+					"401": {
+						"description": "Unauthorized — missing or invalid API key."
+					}
+				},
+				"security": [
+					{
+						"tokenAuth": []
+					}
+				],
+				"x-codeSamples": [
+					{
+						"lang": "cURL",
+						"source": "curl -X POST https://api.mem0.ai/v3/memories/add/ \\\n  -H \"Authorization: Token <api-key>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"messages\": [\n      {\"role\": \"user\", \"content\": \"I just moved to San Francisco from New York.\"},\n      {\"role\": \"assistant\", \"content\": \"Got it — I\\u0027ll update your location.\"}\n    ],\n    \"user_id\": \"alice\"\n  }'"
+					},
+					{
+						"lang": "Python",
+						"source": "from mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your-api-key\")\n\nresult = client.add(\n    messages=[\n        {\"role\": \"user\", \"content\": \"I just moved to San Francisco from New York.\"},\n        {\"role\": \"assistant\", \"content\": \"Got it — I'll update your location.\"}\n    ],\n    user_id=\"alice\",\n)\nprint(result)"
+					},
+					{
+						"lang": "JavaScript",
+						"source": "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst result = await client.add(\n  [\n    { role: \"user\", content: \"I just moved to San Francisco from New York.\" },\n    { role: \"assistant\", content: \"Got it — I'll update your location.\" },\n  ],\n  { userId: \"alice\" }\n);\nconsole.log(result);"
+					}
+				]
+			}
+		},
+		"/v3/memories/search/": {
+			"post": {
+				"tags": [
+					"memories"
+				],
+				"summary": "Search memories (V3)",
+				"description": "Relevance-ranked search across stored memories. V3 uses hybrid retrieval — the returned `score` is a combined `[0, 1]` value; per-signal component scores are not exposed on the response. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. At least one entity ID is required.",
+				"operationId": "memories_search_v3",
+				"requestBody": {
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"type": "object",
+								"required": [
+									"query",
+									"filters"
+								],
+								"properties": {
+									"query": {
+										"type": "string",
+										"minLength": 1,
+										"description": "Natural-language search query."
+									},
+									"filters": {
+										"type": "object",
+										"description": "Entity and metadata filters. Must include at least one entity ID (`user_id`, `agent_id`, `app_id`, or `run_id`). Supports `AND`, `OR`, `NOT`, and comparison operators (`in`, `gte`, `lte`, `gt`, `lt`, `contains`, `icontains`, `ne`).",
+										"additionalProperties": true
+									},
+									"top_k": {
+										"type": "integer",
+										"minimum": 1,
+										"maximum": 1000,
+										"default": 10,
+										"description": "Number of results to return."
+									},
+									"threshold": {
+										"type": "number",
+										"minimum": 0.0,
+										"maximum": 1.0,
+										"default": 0.1,
+										"description": "Minimum semantic relevance score. Pass `0.0` to disable filtering."
+									},
+									"rerank": {
+										"type": "boolean",
+										"default": false,
+										"description": "Apply the managed reranker for better ordering (adds latency)."
+									}
+								}
+							},
+							"example": {
+								"query": "where does the user live?",
+								"filters": {
+									"user_id": "alice"
+								},
+								"top_k": 10
+							}
+						}
+					}
+				},
+				"responses": {
+					"200": {
+						"description": "Ranked search results.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"type": "object",
+									"properties": {
+										"results": {
+											"type": "array",
+											"items": {
+												"type": "object",
+												"properties": {
+													"id": {
+														"type": "string",
+														"format": "uuid",
+														"description": "Unique memory identifier."
+													},
+													"memory": {
+														"type": "string",
+														"description": "The extracted memory fact."
+													},
+													"score": {
+														"type": "number",
+														"format": "float",
+														"minimum": 0,
+														"maximum": 1,
+														"description": "Combined multi-signal relevance score in [0, 1] (search responses only)."
+													},
+													"metadata": {
+														"type": "object",
+														"additionalProperties": true,
+														"description": "User-supplied metadata attached to the memory."
+													},
+													"categories": {
+														"type": "array",
+														"items": {
+															"type": "string"
+														}
+													},
+													"created_at": {
+														"type": "string",
+														"format": "date-time"
+													},
+													"updated_at": {
+														"type": "string",
+														"format": "date-time"
+													}
+												},
+												"required": [
+													"id",
+													"memory",
+													"created_at"
+												]
+											}
+										}
+									},
+									"required": [
+										"results"
+									]
+								},
+								"example": {
+									"results": [
+										{
+											"id": "mem-uuid",
+											"memory": "User moved to San Francisco from New York in January 2026",
+											"score": 0.82,
+											"metadata": {},
+											"categories": [
+												"location"
+											],
+											"created_at": "2026-01-15T10:30:00Z",
+											"updated_at": "2026-01-15T10:30:00Z"
+										}
+									]
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "Validation error — e.g. empty `query`, missing `filters`, or no positively-scoped entity ID."
+					},
+					"401": {
+						"description": "Unauthorized — missing or invalid API key."
+					}
+				},
+				"security": [
+					{
+						"tokenAuth": []
+					}
+				],
+				"x-codeSamples": [
+					{
+						"lang": "cURL",
+						"source": "curl -X POST https://api.mem0.ai/v3/memories/search/ \\\n  -H \"Authorization: Token <api-key>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"where does the user live?\",\n    \"filters\": {\"user_id\": \"alice\"},\n    \"top_k\": 10\n  }'"
+					},
+					{
+						"lang": "Python",
+						"source": "from mem0 import MemoryClient\n\nclient = MemoryClient(api_key=\"your-api-key\")\n\nresults = client.search(\n    \"where does the user live?\",\n    filters={\"user_id\": \"alice\"},\n    top_k=10,\n)\nfor r in results[\"results\"]:\n    print(r[\"memory\"], r[\"score\"])"
+					},
+					{
+						"lang": "JavaScript",
+						"source": "import MemoryClient from \"mem0ai\";\n\nconst client = new MemoryClient({ apiKey: \"your-api-key\" });\n\nconst results = await client.search(\"where does the user live?\", {\n  filters: { userId: \"alice\" },\n  topK: 10,\n});\nfor (const r of results.results) {\n  console.log(r.memory, r.score);\n}"
+					}
+				]
+			}
+		},
 		"/v1/memories/{entity_type}/{entity_id}/": {
 			"get": {
 				"tags": [
 					"memories"
 				],
-				"operationId": "memories_read",
+				"operationId": "memories_entity_read",
 				"responses": {
 					"200": {
 						"description": "Successfully retrieved memories.",
@@ -5176,9 +5674,10 @@
 						"nullable": true
 					},
 					"expiration_date": {
-						"description": "The date and time when the memory will expire. Format: YYYY-MM-DD",
+						"description": "The date when the memory will expire. Format: YYYY-MM-DD",
 						"title": "Expiration date",
 						"type": "string",
+						"format": "date",
 						"nullable": true
 					},
 					"org_id": {
@@ -5742,4 +6241,4 @@
 		}
 	},
 	"x-original-swagger-version": "2.0"
-}
+}
@@ -62,11 +62,11 @@ Search for memories based on a query asynchronously.
 <CodeGroup>

 ```python Python
-await client.search("What is Alice's favorite sport?", user_id="alice")
+await client.search("What is Alice's favorite sport?", filters={"user_id": "alice"})
 ```

 ```javascript JavaScript
-await client.search("What is Alice's favorite sport?", { userId: "alice" });
+await client.search("What is Alice's favorite sport?", { filters: { userId: "alice" } });
 ```

 </CodeGroup>
@@ -42,7 +42,7 @@ You can retrieve memories using the `search` method.
 <CodeGroup>

 ```python Python
-client.search("What is Alice's favorite sport?", user_id="alice")
+client.search("What is Alice's favorite sport?", filters={"user_id": "alice"})
 ```

 ```json Output
@@ -1,210 +0,0 @@
---
-title: Configurable Graph Threshold
-description: "Configure the graph store threshold parameter to control how strictly nodes are matched during data ingestion."
---
-
-## Overview
-
-The graph store threshold parameter controls how strictly nodes are matched during graph data ingestion based on embedding similarity. This feature allows you to customize the matching behavior to prevent false matches or enable entity merging based on your specific use case.
-
-## Configuration
-
-Add the `threshold` parameter to your graph store configuration:
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neo4j",  # or memgraph, neptune, kuzu
-        "config": {
-            "url": "bolt://localhost:7687",
-            "username": "neo4j",
-            "password": "password"
-        },
-        "threshold": 0.7  # Default value, range: 0.0 to 1.0
-    }
-}
-
-memory = Memory.from_config(config)
-```
-
-## Parameters
-
-| Parameter | Type | Default | Range | Description |
-|-----------|------|---------|-------|-------------|
-| `threshold` | float | 0.7 | 0.0 - 1.0 | Minimum embedding similarity score required to match existing nodes during graph ingestion |
-
-## Use Cases
-
-### Strict Matching (UUIDs, IDs)
-
-Use higher thresholds (0.95-0.99) when working with identifiers that should remain distinct:
-
-```python
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {...},
-        "threshold": 0.95  # Strict matching
-    }
-}
-```
-
-**Example:** Prevents UUID collisions like `MXxBUE18QVBQTElDQVRJT058MjM3MTM4NjI5` being matched with `MXxBUE18QVBQTElDQVRJT058MjA2OTYxMzM`
-
-### Permissive Matching (Natural Language)
-
-Use lower thresholds (0.6-0.7) when entity variations should be merged:
-
-```python
-config = {
-    "graph_store": {
-        "threshold": 0.6  # Permissive matching
-    }
-}
-```
-
-**Example:** Merges similar entities like "Bob" and "Robert" as the same person.
-
-## Threshold Guidelines
-
-| Use Case | Recommended Threshold | Behavior |
-|----------|----------------------|----------|
-| UUIDs, IDs, Keys | 0.95 - 0.99 | Prevent false matches between similar identifiers |
-| Structured Data | 0.85 - 0.9 | Balanced precision and recall |
-| General Purpose | 0.7 - 0.8 | Default recommendation |
-| Natural Language | 0.6 - 0.7 | Allow entity variations to merge |
-
-## Examples
-
-### Example 1: Preventing Data Loss with UUIDs
-
-```python
-from mem0 import Memory
-
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {
-            "url": "bolt://localhost:7687",
-            "username": "neo4j",
-            "password": "password"
-        },
-        "threshold": 0.98  # Very strict for UUIDs
-    }
-}
-
-memory = Memory.from_config(config)
-
-# These UUIDs create separate nodes instead of being incorrectly merged
-memory.add(
-    [{"role": "user", "content": "MXxBUE18QVBQTElDQVRJT058MjM3MTM4NjI5 relates to Project A"}],
-    user_id="user1"
-)
-
-memory.add(
-    [{"role": "user", "content": "MXxBUE18QVBQTElDQVRJT058MjA2OTYxMzM relates to Project B"}],
-    user_id="user1"
-)
-```
-
-### Example 2: Merging Entity Variations
-
-```python
-config = {
-    "graph_store": {
-        "provider": "neo4j",
-        "config": {...},
-        "threshold": 0.6  # More permissive
-    }
-}
-
-memory = Memory.from_config(config)
-
-# These will be merged as the same entity
-memory.add([{"role": "user", "content": "Bob works at Google"}], user_id="user1")
-memory.add([{"role": "user", "content": "Robert works at Google"}], user_id="user1")
-```
-
-### Example 3: Different Thresholds for Different Clients
-
-```python
-# Client 1: Strict matching for transactional data
-memory_strict = Memory.from_config({
-    "graph_store": {"threshold": 0.95}
-})
-
-# Client 2: Permissive matching for conversational data
-memory_permissive = Memory.from_config({
-    "graph_store": {"threshold": 0.6}
-})
-```
-
-## Supported Graph Providers
-
-The threshold parameter works with all graph store providers:
-
- ✅ Neo4j
- ✅ Memgraph
- ✅ Kuzu
- ✅ Neptune (both Analytics and DB)
-
-## How It Works
-
-When adding a relation to the graph:
-
-1. **Embedding Generation**: The system generates embeddings for source and destination entities
-2. **Node Search**: Searches for existing nodes with similar embeddings
-3. **Threshold Comparison**: Compares similarity scores against the configured threshold
-4. **Decision**:
-   - If similarity ≥ threshold: Uses the existing node
-   - If similarity < threshold: Creates a new node
-
-```python
-# Pseudocode
-if node_similarity >= threshold:
-    use_existing_node()
-else:
-    create_new_node()
-```
-
-## Troubleshooting
-
-### Issue: Duplicate nodes being created
-
-**Symptom**: Expected nodes to merge but they're created separately
-
-**Solution**: Lower the threshold
-```python
-config = {"graph_store": {"threshold": 0.6}}
-```
-
-### Issue: Unrelated entities being merged
-
-**Symptom**: Different entities incorrectly matched as the same node
-
-**Solution**: Raise the threshold
-```python
-config = {"graph_store": {"threshold": 0.95}}
-```
-
-### Issue: Validation error
-
-**Symptom**: `ValidationError: threshold must be between 0.0 and 1.0`
-
-**Solution**: Ensure threshold is in valid range
-```python
-config = {"graph_store": {"threshold": 0.7}}  # Valid: 0.0 ≤ x ≤ 1.0
-```
-
-## Backward Compatibility
-
- **Default Value**: 0.7 (maintains existing behavior)
- **Optional Parameter**: Existing code works without any changes
- **No Breaking Changes**: Graceful fallback if not specified
-
-## Related
-
- [Graph Memory](/open-source/features/graph-memory)
- [Issue #3590](https://github.com/mem0ai/mem0/issues/3590)
@@ -20,9 +20,6 @@ Mem0 Platform features help managed deployments scale from basic filtering to gr
  <Card title="Go Real-Time with Async" icon="bolt" href="/platform/features/async-client">
    Non-blocking add/search requests for agents.
  </Card>
-  <Card title="Unlock Graph Memory" icon="circle-nodes" href="/open-source/features/graph-memory">
-    Relationship-aware recall across entities.
-  </Card>
  <Card
    title="Boost Retrieval Quality"
    icon="sparkles"
@@ -72,7 +72,7 @@ await client.add(messages, { userId: "user123" });
 ````

 ```bash cURL
-curl -X POST https://api.mem0.ai/v1/memories/add \
+curl -X POST https://api.mem0.ai/v3/memories/add/ \
  -H "Authorization: Token $MEM0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
@@ -104,7 +104,7 @@ console.log(results);
 ````

 ```bash cURL
-curl -X POST https://api.mem0.ai/v1/memories/search \
+curl -X POST https://api.mem0.ai/v3/memories/search/ \
  -H "Authorization: Token $MEM0_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
@@ -88,19 +88,19 @@ Sub-50ms retrieval. Dual storage: vector embeddings + graph databases.
  from mem0 import MemoryClient
  client = MemoryClient(api_key="m0-xxx")
  client.add("I prefer dark mode and use VS Code.", user_id="user1")
-  results = client.search("What editor do they use?", user_id="user1")
+  results = client.search("What editor do they use?", filters={"user_id": "user1"})

 **Quick Usage (JavaScript Platform):**
  import MemoryClient from 'mem0ai';
  const client = new MemoryClient({ apiKey: 'm0-xxx' });
-  await client.add([{ role: "user", content: "I prefer dark mode." }], { user_id: "user1" });
-  const results = await client.search("What editor?", { user_id: "user1" });
+  await client.add([{ role: "user", content: "I prefer dark mode." }], { userId: "user1" });
+  const results = await client.search("What editor?", { filters: { userId: "user1" } });

 **Quick Usage (Python Open Source):**
  from mem0 import Memory
  m = Memory()
  m.add("I prefer dark mode and use VS Code.", user_id="user1")
-  results = m.search("What editor do they use?", user_id="user1")
+  results = m.search("What editor do they use?", filters={"user_id": "user1"})

 Help me integrate Mem0 into my project. Start by asking what I'm building,
 what language/framework I'm using, and whether I want managed or self-hosted.
@@ -1,6 +1,6 @@
 {
  "name": "mem0ai",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0",
  "description": "The Memory Layer For Your AI Apps",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
@@ -1,6 +1,7 @@
 import axios from "axios";
 import {
  AllUsers,
+  PaginatedMemories,
  ProjectOptions,
  Memory,
  MemoryHistory,
@@ -221,7 +222,7 @@ export default class MemoryClient {
    this._captureEvent("add", [payloadKeys]);

    const response = await this._fetchWithErrorHandling(
-      `${this.host}/v3/memories/`,
+      `${this.host}/v3/memories/add/`,
      {
        method: "POST",
        headers: this.headers,
@@ -284,7 +285,7 @@ export default class MemoryClient {
    );
  }

-  async getAll(options?: GetAllMemoryOptions): Promise<Array<Memory>> {
+  async getAll(options?: GetAllMemoryOptions): Promise<PaginatedMemories> {
    // Reject top-level entity params - must use filters instead
    rejectTopLevelEntityParams(options as Record<string, any>, "getAll");

@@ -293,12 +294,11 @@ export default class MemoryClient {
    this._captureEvent("get_all", [payloadKeys]);
    const { page, pageSize, filters, ...rest } = options ?? {};
    const body: Record<string, any> = {
-      output_format: "v1.1",
      ...camelToSnakeKeys(rest),
      ...(filters && { filters }),
    };

-    let url = `${this.host}/v2/memories/`;
+    let url = `${this.host}/v3/memories/`;
    if (page && pageSize) {
      url += `?page=${page}&page_size=${pageSize}`;
    }
@@ -142,6 +142,13 @@ export interface AllUsers {
  previous: any;
 }

+export interface PaginatedMemories {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: Array<Memory>;
+}
+
 export interface ProjectResponse {
  customInstructions?: string;
  customCategories?: string[];
@@ -124,13 +124,16 @@ describeIntegration("MemoryClient Integration — CRUD", () => {
        filters: { user_id: TEST_USER_ID },
      });

-      // v1.1 output_format returns { results: [...] }
+      // Paginated shape: { count, next, previous, results: [...] }
+      expect(response).toHaveProperty("count");
+      expect(response).toHaveProperty("next");
+      expect(response).toHaveProperty("previous");
      expect(response).toHaveProperty("results");
-      const memories = (response as any).results;
-      expect(Array.isArray(memories)).toBe(true);
-      expect(memories.length).toBeGreaterThanOrEqual(memoryIds.length);
+      expect(typeof response.count).toBe("number");
+      expect(Array.isArray(response.results)).toBe(true);
+      expect(response.results.length).toBeGreaterThanOrEqual(memoryIds.length);

-      for (const mem of memories) {
+      for (const mem of response.results) {
        expect(typeof mem.id).toBe("string");
        expect(typeof mem.memory).toBe("string");
      }
@@ -143,9 +146,12 @@ describeIntegration("MemoryClient Integration — CRUD", () => {
        pageSize: 1,
      });

-      // Paginated response is an object with results array
      expect(page1).toBeDefined();
-      expect(page1).toHaveProperty("results");
+      expect(page1).toHaveProperty("count");
+      expect(page1).toHaveProperty("next");
+      expect(page1).toHaveProperty("previous");
+      expect(Array.isArray(page1.results)).toBe(true);
+      expect(page1.results.length).toBeLessThanOrEqual(1);
    });
  });

@@ -206,11 +212,10 @@ describeIntegration("MemoryClient Integration — CRUD", () => {
        filters: { user_id: `nonexistent-user-${randomUUID()}` },
      });

-      // v1.1 output_format returns { results: [...] }
      expect(response).toHaveProperty("results");
-      const memories = (response as any).results;
-      expect(Array.isArray(memories)).toBe(true);
-      expect(memories.length).toBe(0);
+      expect(Array.isArray(response.results)).toBe(true);
+      expect(response.results.length).toBe(0);
+      expect(response.count).toBe(0);
    });

    test("deleteAll for non-existent user does not throw", async () => {
@@ -70,10 +70,7 @@ export async function waitForMemories(
    const response = await withRetry(() =>
      client.getAll({ filters: { user_id: userId } }),
    );
-    // v1.1 output_format returns { results: [...] }
-    const memories = Array.isArray(response)
-      ? response
-      : ((response as any)?.results ?? []);
+    const memories = response.results ?? [];
    if (memories.length >= minCount) {
      return memories;
    }
@@ -21,33 +21,33 @@ installConsoleSuppression();
 // ─── add() ───────────────────────────────────────────────

 describe("MemoryClient - add()", () => {
-  test("sends POST to /v3/memories/", async () => {
+  test("sends POST to /v3/memories/add/", async () => {
    const extra = new Map<string, { status: number; body: unknown }>();
-    extra.set("/v3/memories/", { status: 200, body: [createMockMemory()] });
+    extra.set("/v3/memories/add/", { status: 200, body: [createMockMemory()] });
    const mock = setupMockFetch(extra);

    const client = new MemoryClient({ apiKey: TEST_API_KEY });
    await client.add([{ role: "user", content: "Hello" }], { userId: "u1" });

-    expect(findFetchCall(mock, "/v3/memories/", "POST")).toBeDefined();
+    expect(findFetchCall(mock, "/v3/memories/add/", "POST")).toBeDefined();
  });

  test("includes messages in request body", async () => {
    const messages = [{ role: "user" as const, content: "Hello, I am Alex" }];
    const extra = new Map<string, { status: number; body: unknown }>();
-    extra.set("/v3/memories/", { status: 200, body: [createMockMemory()] });
+    extra.set("/v3/memories/add/", { status: 200, body: [createMockMemory()] });
    const mock = setupMockFetch(extra);

    const client = new MemoryClient({ apiKey: TEST_API_KEY });
    await client.add(messages, { userId: "u1" });

-    const call = findFetchCall(mock, "/v3/memories/", "POST");
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
    expect(getFetchBody(call!).messages).toEqual(messages);
  });

  test("includes user_id in request body", async () => {
    const extra = new Map<string, { status: number; body: unknown }>();
-    extra.set("/v3/memories/", { status: 200, body: [createMockMemory()] });
+    extra.set("/v3/memories/add/", { status: 200, body: [createMockMemory()] });
    const mock = setupMockFetch(extra);

    const client = new MemoryClient({ apiKey: TEST_API_KEY });
@@ -55,19 +55,19 @@ describe("MemoryClient - add()", () => {
      user_id: "user_1",
    });

-    const call = findFetchCall(mock, "/v3/memories/", "POST");
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
    expect(getFetchBody(call!).user_id).toBe("user_1");
  });

  test("sends empty messages array without crashing", async () => {
    const extra = new Map<string, { status: number; body: unknown }>();
-    extra.set("/v3/memories/", { status: 200, body: [] });
+    extra.set("/v3/memories/add/", { status: 200, body: [] });
    const mock = setupMockFetch(extra);

    const client = new MemoryClient({ apiKey: TEST_API_KEY });
    await client.add([], { userId: "u1" });

-    const call = findFetchCall(mock, "/v3/memories/", "POST");
+    const call = findFetchCall(mock, "/v3/memories/add/", "POST");
    expect(getFetchBody(call!).messages).toEqual([]);
  });
 });
@@ -254,7 +254,7 @@ describe("MemoryClient - getAll() entity param rejection", () => {

  test("accepts filters with user_id", async () => {
    const extra = new Map<string, { status: number; body: unknown }>();
-    extra.set("/v2/memories/", {
+    extra.set("/v3/memories/", {
      status: 200,
      body: { results: [] },
    });
@@ -262,6 +262,6 @@ describe("MemoryClient - getAll() entity param rejection", () => {

    const client = new MemoryClient({ apiKey: TEST_API_KEY });
    await client.getAll({ filters: { user_id: "u1" } });
-    expect(findFetchCall(mock, "/v2/memories/", "POST")).toBeDefined();
+    expect(findFetchCall(mock, "/v3/memories/", "POST")).toBeDefined();
  });
 });
@@ -262,6 +262,181 @@ export class Memory {
    return this._entityStore;
  }

+  /**
+   * Normalize a filters object for entity-store scoping: keeps only
+   * user_id/agent_id/run_id keys whose values are defined.
+   */
+  private _sessionFiltersFromPayload(
+    payload: Record<string, any>,
+  ): Record<string, any> {
+    const filters: Record<string, any> = {};
+    if (payload.user_id) filters.user_id = payload.user_id;
+    if (payload.agent_id) filters.agent_id = payload.agent_id;
+    if (payload.run_id) filters.run_id = payload.run_id;
+    return filters;
+  }
+
+  /**
+   * Remove `memoryId` from every entity record scoped to `filters`.
+   * If an entity's `linkedMemoryIds` becomes empty after removal, the
+   * entity record itself is deleted. Errors on individual entities are
+   * swallowed so one bad record does not break the whole operation.
+   *
+   * No-op if the entity store has not been initialized yet.
+   */
+  private async _removeMemoryFromEntityStore(
+    memoryId: string,
+    filters: Record<string, any>,
+  ): Promise<void> {
+    let entityStore: VectorStore;
+    try {
+      entityStore = await this.getEntityStore();
+    } catch (e) {
+      console.debug(`Entity store unavailable during cleanup: ${e}`);
+      return;
+    }
+
+    let rows: Array<{ id: string; payload: Record<string, any> }> = [];
+    try {
+      const listed = await entityStore.list(filters, 10000);
+      rows = (
+        Array.isArray(listed) && Array.isArray(listed[0])
+          ? listed[0]
+          : (listed as any)
+      ) as Array<{ id: string; payload: Record<string, any> }>;
+    } catch (e) {
+      console.debug(`Entity store list failed during cleanup: ${e}`);
+      return;
+    }
+
+    for (const row of rows) {
+      try {
+        const payload = row.payload || {};
+        const linked: string[] = Array.isArray(payload.linkedMemoryIds)
+          ? payload.linkedMemoryIds
+          : [];
+        if (!linked.includes(memoryId)) continue;
+
+        const remaining = linked.filter((id) => id !== memoryId);
+        if (remaining.length === 0) {
+          try {
+            await entityStore.delete(row.id);
+          } catch (e) {
+            console.debug(`Entity delete failed for id=${row.id}: ${e}`);
+          }
+        } else {
+          const newPayload = { ...payload, linkedMemoryIds: remaining };
+          // entityStore.update requires a vector — re-embed entity text.
+          const entityText =
+            typeof payload.data === "string" ? payload.data : "";
+          if (!entityText) {
+            // Can't re-embed without text; skip gracefully.
+            console.debug(
+              `Entity id=${row.id} missing 'data'; skipping update during cleanup`,
+            );
+            continue;
+          }
+          let vec: number[];
+          try {
+            vec = await this.embedder.embed(entityText);
+          } catch (e) {
+            console.debug(`Entity re-embed failed for '${entityText}': ${e}`);
+            continue;
+          }
+          try {
+            await entityStore.update(row.id, vec, newPayload);
+          } catch (e) {
+            console.debug(`Entity update failed for id=${row.id}: ${e}`);
+          }
+        }
+      } catch (e) {
+        console.debug(`Entity cleanup error for id=${row?.id}: ${e}`);
+      }
+    }
+  }
+
+  /**
+   * Extract entities from `text` and link them to `memoryId` in the
+   * entity store, scoped to `filters` (user_id / agent_id / run_id).
+   *
+   * Simpler single-memory variant of Phase 7 in add(): no cross-memory
+   * dedup, but still does per-entity "search for existing, update if
+   * match >= 0.95 else insert new". Non-fatal errors are swallowed.
+   */
+  private async _linkEntitiesForMemory(
+    memoryId: string,
+    text: string,
+    filters: Record<string, any>,
+  ): Promise<void> {
+    try {
+      const entities = extractEntities(text);
+      if (entities.length === 0) return;
+
+      const entityStore = await this.getEntityStore();
+
+      for (const entity of entities) {
+        try {
+          let entityVec: number[];
+          try {
+            entityVec = await this.embedder.embed(entity.text);
+          } catch (e) {
+            console.debug(`Entity embed failed for '${entity.text}': ${e}`);
+            continue;
+          }
+
+          let matches: Array<{
+            id: string;
+            score?: number;
+            payload: Record<string, any>;
+          }> = [];
+          try {
+            matches = await entityStore.search(entityVec, 1, filters);
+          } catch {}
+
+          if (matches.length > 0 && (matches[0].score ?? 0) >= 0.95) {
+            const match = matches[0];
+            const payload = match.payload || {};
+            const linked = new Set<string>(
+              Array.isArray(payload.linkedMemoryIds)
+                ? payload.linkedMemoryIds
+                : [],
+            );
+            linked.add(memoryId);
+            payload.linkedMemoryIds = Array.from(linked).sort();
+            try {
+              await entityStore.update(match.id, entityVec, payload);
+            } catch (e) {
+              console.debug(`Entity update failed for '${entity.text}': ${e}`);
+            }
+          } else {
+            const entityPayload: Record<string, any> = {
+              data: entity.text,
+              entityType: entity.type,
+              linkedMemoryIds: [memoryId],
+            };
+            if (filters.user_id) entityPayload.user_id = filters.user_id;
+            if (filters.agent_id) entityPayload.agent_id = filters.agent_id;
+            if (filters.run_id) entityPayload.run_id = filters.run_id;
+
+            try {
+              await entityStore.insert(
+                [entityVec],
+                [uuidv4()],
+                [entityPayload],
+              );
+            } catch (e) {
+              console.debug(`Entity insert failed for '${entity.text}': ${e}`);
+            }
+          }
+        } catch (e) {
+          console.debug(`Entity link error for '${entity.text}': ${e}`);
+        }
+      }
+    } catch (e) {
+      console.warn(`Entity linking failed during update: ${e}`);
+    }
+  }
+
  private buildSessionScope(filters: SearchFilters): string {
    const parts: string[] = [];
    for (const key of ["agent_id", "run_id", "user_id"].sort()) {
@@ -863,17 +1038,23 @@ export class Memory {
    // Validate search parameters (before applying defaults)
    validateSearchParams(config.threshold, config.topK);

-    // Validate and trim entity IDs in filters
-    const normalizedFilters = config.filters
-      ? {
-          ...config.filters,
-          user_id: validateAndTrimEntityId(config.filters.user_id, "user_id"),
-          agent_id: validateAndTrimEntityId(
-            config.filters.agent_id,
-            "agent_id",
-          ),
-          run_id: validateAndTrimEntityId(config.filters.run_id, "run_id"),
-        }
+    // Validate and trim entity IDs in filters. Only include keys whose
+    // validated value is defined — otherwise downstream vector stores
+    // receive `agent_id: undefined` / `run_id: undefined` and fail
+    // (Qdrant rejects the malformed match, pgvector binds NULL, Redis
+    // emits a literal "undefined" string in TAG filters).
+    const normalizedFilters: Record<string, any> = config.filters
+      ? Object.fromEntries(
+          Object.entries({
+            ...config.filters,
+            user_id: validateAndTrimEntityId(config.filters.user_id, "user_id"),
+            agent_id: validateAndTrimEntityId(
+              config.filters.agent_id,
+              "agent_id",
+            ),
+            run_id: validateAndTrimEntityId(config.filters.run_id, "run_id"),
+          }).filter(([, v]) => v !== undefined),
+        )
      : {};

    await this._ensureInitialized();
@@ -1194,13 +1375,17 @@ export class Memory {

    const { topK = 20 } = config;

-    // Validate and trim entity IDs in filters
-    const filters = {
-      ...(config.filters || {}),
-      user_id: validateAndTrimEntityId(config.filters?.user_id, "user_id"),
-      agent_id: validateAndTrimEntityId(config.filters?.agent_id, "agent_id"),
-      run_id: validateAndTrimEntityId(config.filters?.run_id, "run_id"),
-    };
+    // Validate and trim entity IDs in filters. Drop keys that resolve to
+    // undefined so downstream vector stores don't receive
+    // `agent_id: undefined` / `run_id: undefined` and fail.
+    const filters: Record<string, any> = Object.fromEntries(
+      Object.entries({
+        ...(config.filters || {}),
+        user_id: validateAndTrimEntityId(config.filters?.user_id, "user_id"),
+        agent_id: validateAndTrimEntityId(config.filters?.agent_id, "agent_id"),
+        run_id: validateAndTrimEntityId(config.filters?.run_id, "run_id"),
+      }).filter(([, v]) => v !== undefined),
+    );

    await this._captureEvent("get_all", {
      topK,
@@ -1260,6 +1445,7 @@ export class Memory {
      ...metadata,
      data,
      hash: createHash("md5").update(data).digest("hex"),
+      textLemmatized: lemmatizeForBm25(data),
      createdAt: new Date().toISOString(),
    };

@@ -1317,6 +1503,16 @@ export class Memory {
      newMetadata.updatedAt,
    );

+    // Entity-store cleanup: strip this memory's id from old-text entities,
+    // then re-extract entities from the new text and link them back.
+    try {
+      const sessionFilters = this._sessionFiltersFromPayload(newMetadata);
+      await this._removeMemoryFromEntityStore(memoryId, sessionFilters);
+      await this._linkEntitiesForMemory(memoryId, data, sessionFilters);
+    } catch (e) {
+      console.warn(`Entity store cleanup/link failed during update: ${e}`);
+    }
+
    return memoryId;
  }

@@ -1327,6 +1523,9 @@ export class Memory {
    }

    const prevValue = existingMemory.payload.data;
+    const sessionFilters = this._sessionFiltersFromPayload(
+      existingMemory.payload || {},
+    );
    await this.vectorStore.delete(memoryId);
    await this.db.addHistory(
      memoryId,
@@ -1338,6 +1537,14 @@ export class Memory {
      1,
    );

+    // Entity-store cleanup: strip this memory's id from any entity records
+    // that linked to it. Non-fatal — log and continue on error.
+    try {
+      await this._removeMemoryFromEntityStore(memoryId, sessionFilters);
+    } catch (e) {
+      console.warn(`Entity store cleanup failed during delete: ${e}`);
+    }
+
    return memoryId;
  }

@@ -660,6 +660,9 @@ export function extractEntities(text: string): ExtractedEntity[] {
    txt = txt.replace(/\s*:+$/, "");
    // Strip leading numbered list markers
    txt = txt.replace(/^\d+\s*\.\s*/, "");
+    // Strip trailing sentence punctuation (".", ",", ";", "!", "?") — otherwise
+    // "Paris." and "Paris" produce different embeddings and break entity dedup.
+    txt = txt.replace(/[.,;!?]+$/, "").trim();

    if (!txt || txt.length <= 2 || hasArtifacts(txt)) {
      continue;
@@ -9,6 +9,19 @@ import type {
 import { VectorStore } from "./base";
 import { SearchFilters, VectorStoreConfig, VectorStoreResult } from "../types";

+/**
+ * Escape RediSearch TAG filter special characters. Any punctuation in the
+ * value (including `-`, which appears in every UUID) must be backslash-
+ * escaped, otherwise RediSearch either parses it as an operator (`-` is
+ * minus, `|` is OR) or rejects the whole expression as a syntax error.
+ */
+function escapeRedisTagValue(value: unknown): string {
+  return String(value).replace(
+    /([,.<>{}\[\]"':;!@#$%^&*()\-+=~|/\\\s])/g,
+    "\\$1",
+  );
+}
+
 interface RedisConfig extends VectorStoreConfig {
  redisUrl: string;
  collectionName: string;
@@ -377,8 +390,8 @@ export class RedisDB implements VectorStore {
    const snakeFilters = filters ? toSnakeCase(filters) : undefined;
    const filterExpr = snakeFilters
      ? Object.entries(snakeFilters)
-          .filter(([_, value]) => value !== null)
-          .map(([key, value]) => `@${key}:{${value}}`)
+          .filter(([_, value]) => value !== null && value !== undefined)
+          .map(([key, value]) => `@${key}:{${escapeRedisTagValue(value)}}`)
          .join(" ")
      : "*";

@@ -615,8 +628,8 @@ export class RedisDB implements VectorStore {
    const snakeFilters = filters ? toSnakeCase(filters) : undefined;
    const filterExpr = snakeFilters
      ? Object.entries(snakeFilters)
-          .filter(([_, value]) => value !== null)
-          .map(([key, value]) => `@${key}:{${value}}`)
+          .filter(([_, value]) => value !== null && value !== undefined)
+          .map(([key, value]) => `@${key}:{${escapeRedisTagValue(value)}}`)
          .join(" ")
      : "*";

@@ -167,7 +167,7 @@ class MemoryClient:

        kwargs = self._prepare_params(kwargs)
        payload = self._prepare_payload(messages, kwargs)
-        response = self.client.post("/v3/memories/", json=payload)
+        response = self.client.post("/v3/memories/add/", json=payload)
        response.raise_for_status()
        if "metadata" in kwargs:
            del kwargs["metadata"]
@@ -207,7 +207,7 @@ class MemoryClient:
            **kwargs: Optional parameters for filtering (filters, page, page_size).

        Returns:
-            A dictionary containing memories in v1.1 format: {"results": [...]}
+            A paginated dict: {"count": int, "next": str | None, "previous": str | None, "results": [...]}

        Raises:
            ValidationError: If the input data is invalid.
@@ -233,9 +233,9 @@ class MemoryClient:
                "page": params.pop("page"),
                "page_size": params.pop("page_size"),
            }
-            response = self.client.post("/v2/memories/", json=params, params=query_params)
+            response = self.client.post("/v3/memories/", json=params, params=query_params)
        else:
-            response = self.client.post("/v2/memories/", json=params)
+            response = self.client.post("/v3/memories/", json=params)
        response.raise_for_status()
        if "metadata" in kwargs:
            del kwargs["metadata"]
@@ -247,12 +247,7 @@ class MemoryClient:
                "sync_type": "sync",
            },
        )
-        result = response.json()
-
-        # Ensure v1.1 format (wrap raw list if needed)
-        if isinstance(result, list):
-            return {"results": result}
-        return result
+        return response.json()

    @api_error_handler
    def search(self, query: str, options: Optional[SearchMemoryOptions] = None, **kwargs) -> Dict[str, Any]:
@@ -1095,7 +1090,7 @@ class AsyncMemoryClient:

        kwargs = self._prepare_params(kwargs)
        payload = self._prepare_payload(messages, kwargs)
-        response = await self.async_client.post("/v3/memories/", json=payload)
+        response = await self.async_client.post("/v3/memories/add/", json=payload)
        response.raise_for_status()
        if "metadata" in kwargs:
            del kwargs["metadata"]
@@ -1119,7 +1114,7 @@ class AsyncMemoryClient:
            **kwargs: Optional parameters for filtering (filters, page, page_size).

        Returns:
-            A dictionary containing memories in v1.1 format: {"results": [...]}
+            A paginated dict: {"count": int, "next": str | None, "previous": str | None, "results": [...]}

        Raises:
            ValidationError: If the input data is invalid.
@@ -1145,9 +1140,9 @@ class AsyncMemoryClient:
                "page": params.pop("page"),
                "page_size": params.pop("page_size"),
            }
-            response = await self.async_client.post("/v2/memories/", json=params, params=query_params)
+            response = await self.async_client.post("/v3/memories/", json=params, params=query_params)
        else:
-            response = await self.async_client.post("/v2/memories/", json=params)
+            response = await self.async_client.post("/v3/memories/", json=params)
        response.raise_for_status()
        if "metadata" in kwargs:
            del kwargs["metadata"]
@@ -1159,12 +1154,7 @@ class AsyncMemoryClient:
                "sync_type": "async",
            },
        )
-        result = response.json()
-
-        # Ensure v1.1 format (wrap raw list if needed)
-        if isinstance(result, list):
-            return {"results": result}
-        return result
+        return response.json()

    @api_error_handler
    async def search(self, query: str, options: Optional[SearchMemoryOptions] = None, **kwargs) -> Dict[str, Any]:
@@ -453,6 +453,84 @@ class Memory(MemoryBase):
        except Exception as e:
            logger.warning(f"Entity upsert failed for '{entity_text}': {e}")

+    def _remove_memory_from_entity_store(self, memory_id, filters):
+        """Strip `memory_id` from every entity record scoped to `filters`.
+
+        For each entity whose `linked_memory_ids` contains `memory_id`:
+          - remove the id; if the list becomes empty, delete the entity record.
+          - otherwise re-embed the entity text and update the payload
+            (the vector store's update() requires a vector).
+
+        No-op if the entity store has never been initialized in this process.
+        Errors on individual entities are swallowed at debug level; outer
+        failures are swallowed at warning level so the primary delete/update
+        path is never broken by entity cleanup.
+        """
+        if self._entity_store is None:
+            return
+        search_filters = {k: v for k, v in filters.items() if k in ("user_id", "agent_id", "run_id") and v}
+        try:
+            listed = self.entity_store.list(filters=search_filters, top_k=10000)
+            rows = listed[0] if isinstance(listed, (list, tuple)) and listed and isinstance(listed[0], list) else listed
+            for row in rows or []:
+                try:
+                    payload = getattr(row, "payload", None) or {}
+                    linked = payload.get("linked_memory_ids", [])
+                    if not isinstance(linked, list) or memory_id not in linked:
+                        continue
+                    remaining = [mid for mid in linked if mid != memory_id]
+                    if not remaining:
+                        try:
+                            self.entity_store.delete(vector_id=row.id)
+                        except Exception as e:
+                            logger.debug(f"Entity delete failed for id={row.id}: {e}")
+                    else:
+                        entity_text = payload.get("data")
+                        if not isinstance(entity_text, str) or not entity_text:
+                            logger.debug(f"Entity id={row.id} missing 'data'; skipping update during cleanup")
+                            continue
+                        try:
+                            vec = self.embedding_model.embed(entity_text, "update")
+                        except Exception as e:
+                            logger.debug(f"Entity re-embed failed for '{entity_text}': {e}")
+                            continue
+                        new_payload = {**payload, "linked_memory_ids": remaining}
+                        try:
+                            self.entity_store.update(
+                                vector_id=row.id,
+                                vector=vec,
+                                payload=new_payload,
+                            )
+                        except Exception as e:
+                            logger.debug(f"Entity update failed for id={row.id}: {e}")
+                except Exception as e:
+                    logger.debug(f"Entity cleanup error: {e}")
+        except Exception as e:
+            logger.warning(f"Entity store cleanup failed for memory_id={memory_id}: {e}")
+
+    def _link_entities_for_memory(self, memory_id, text, filters):
+        """Extract entities from `text` and link them to `memory_id` in the
+        entity store, scoped to `filters`. Simpler single-memory variant of
+        Phase 7 in add(): per-entity search-then-update-or-insert via the
+        existing `_upsert_entity` helper. Non-fatal on any failure.
+        """
+        try:
+            entities = extract_entities(text)
+            if not entities:
+                return
+            seen = set()
+            for entity_type, entity_text in entities:
+                key = entity_text.strip().lower()
+                if not key or key in seen:
+                    continue
+                seen.add(key)
+                try:
+                    self._upsert_entity(entity_text, entity_type, memory_id, filters)
+                except Exception as e:
+                    logger.debug(f"Entity link failed for '{entity_text}': {e}")
+        except Exception as e:
+            logger.warning(f"Entity linking failed for memory_id={memory_id}: {e}")
+
    @classmethod
    def from_config(cls, config_dict: Dict[str, Any]):
        try:
@@ -1624,6 +1702,13 @@ class Memory(MemoryBase):
            actor_id=new_metadata.get("actor_id"),
            role=new_metadata.get("role"),
        )
+
+        # Entity-store cleanup: strip this memory's id from old-text entities,
+        # then re-extract entities from the new text and link them back.
+        session_filters = {k: new_metadata[k] for k in ("user_id", "agent_id", "run_id") if new_metadata.get(k)}
+        self._remove_memory_from_entity_store(memory_id, session_filters)
+        self._link_entities_for_memory(memory_id, data, session_filters)
+
        return memory_id

    def _delete_memory(self, memory_id, existing_memory=None):
@@ -1635,6 +1720,8 @@ class Memory(MemoryBase):
        prev_value = existing_memory.payload.get("data", "")
        created_at = _normalize_iso_timestamp_to_utc(existing_memory.payload.get("created_at"))
        updated_at = datetime.now(timezone.utc).isoformat()
+        payload = existing_memory.payload or {}
+        session_filters = {k: payload[k] for k in ("user_id", "agent_id", "run_id") if payload.get(k)}
        self.vector_store.delete(vector_id=memory_id)
        self.db.add_history(
            memory_id,
@@ -1647,6 +1734,11 @@ class Memory(MemoryBase):
            role=existing_memory.payload.get("role"),
            is_deleted=1,
        )
+
+        # Entity-store cleanup: strip this memory's id from any entity records
+        # that linked to it. Non-fatal — the helper swallows errors.
+        self._remove_memory_from_entity_store(memory_id, session_filters)
+
        return memory_id

    def reset(self):
@@ -1753,6 +1845,114 @@ class AsyncMemory(MemoryBase):
            )
        return self._entity_store

+    async def _upsert_entity_async(self, entity_text, entity_type, memory_id, filters):
+        """Async variant of `_upsert_entity` — per-entity search-then-update-or-insert."""
+        try:
+            entity_embedding = await asyncio.to_thread(self.embedding_model.embed, entity_text, "add")
+            search_filters = {k: v for k, v in filters.items() if k in ("user_id", "agent_id", "run_id") and v}
+
+            existing = await asyncio.to_thread(
+                self.entity_store.search,
+                query=entity_text,
+                vectors=entity_embedding,
+                top_k=1,
+                filters=search_filters,
+            )
+
+            if existing and existing[0].score >= 0.95:
+                match = existing[0]
+                payload = match.payload or {}
+                linked_ids = payload.get("linked_memory_ids", [])
+                if memory_id not in linked_ids:
+                    linked_ids.append(memory_id)
+                    payload["linked_memory_ids"] = linked_ids
+                    await asyncio.to_thread(
+                        self.entity_store.update,
+                        vector_id=match.id,
+                        vector=None,
+                        payload=payload,
+                    )
+            else:
+                entity_id = str(uuid.uuid4())
+                entity_payload = {
+                    "data": entity_text,
+                    "entity_type": entity_type,
+                    "linked_memory_ids": [memory_id],
+                    **{k: v for k, v in search_filters.items()},
+                }
+                await asyncio.to_thread(
+                    self.entity_store.insert,
+                    vectors=[entity_embedding],
+                    ids=[entity_id],
+                    payloads=[entity_payload],
+                )
+        except Exception as e:
+            logger.warning(f"Entity upsert failed for '{entity_text}' (async): {e}")
+
+    async def _remove_memory_from_entity_store(self, memory_id, filters):
+        """Async variant of `Memory._remove_memory_from_entity_store`."""
+        if self._entity_store is None:
+            return
+        search_filters = {k: v for k, v in filters.items() if k in ("user_id", "agent_id", "run_id") and v}
+        try:
+            listed = await asyncio.to_thread(self.entity_store.list, filters=search_filters, top_k=10000)
+            rows = listed[0] if isinstance(listed, (list, tuple)) and listed and isinstance(listed[0], list) else listed
+            for row in rows or []:
+                try:
+                    payload = getattr(row, "payload", None) or {}
+                    linked = payload.get("linked_memory_ids", [])
+                    if not isinstance(linked, list) or memory_id not in linked:
+                        continue
+                    remaining = [mid for mid in linked if mid != memory_id]
+                    if not remaining:
+                        try:
+                            await asyncio.to_thread(self.entity_store.delete, vector_id=row.id)
+                        except Exception as e:
+                            logger.debug(f"Entity delete failed for id={row.id} (async): {e}")
+                    else:
+                        entity_text = payload.get("data")
+                        if not isinstance(entity_text, str) or not entity_text:
+                            logger.debug(f"Entity id={row.id} missing 'data'; skipping update during cleanup (async)")
+                            continue
+                        try:
+                            vec = await asyncio.to_thread(self.embedding_model.embed, entity_text, "update")
+                        except Exception as e:
+                            logger.debug(f"Entity re-embed failed for '{entity_text}' (async): {e}")
+                            continue
+                        new_payload = {**payload, "linked_memory_ids": remaining}
+                        try:
+                            await asyncio.to_thread(
+                                self.entity_store.update,
+                                vector_id=row.id,
+                                vector=vec,
+                                payload=new_payload,
+                            )
+                        except Exception as e:
+                            logger.debug(f"Entity update failed for id={row.id} (async): {e}")
+                except Exception as e:
+                    logger.debug(f"Entity cleanup error (async): {e}")
+        except Exception as e:
+            logger.warning(f"Entity store cleanup failed for memory_id={memory_id} (async): {e}")
+
+    async def _link_entities_for_memory(self, memory_id, text, filters):
+        """Async variant of `Memory._link_entities_for_memory`."""
+        try:
+            entities = await asyncio.to_thread(extract_entities, text)
+            if not entities:
+                return
+            seen = set()
+            for entity_type, entity_text in entities:
+                key = entity_text.strip().lower()
+                if not key or key in seen:
+                    continue
+                seen.add(key)
+                try:
+                    await self._upsert_entity_async(entity_text, entity_type, memory_id, filters)
+                except Exception as e:
+                    logger.debug(f"Entity link failed for '{entity_text}' (async): {e}")
+        except Exception as e:
+            logger.warning(f"Entity linking failed for memory_id={memory_id} (async): {e}")
+
    @classmethod
    def from_config(cls, config_dict: Dict[str, Any]):
        try:
@@ -2926,6 +3126,13 @@ class AsyncMemory(MemoryBase):
            actor_id=new_metadata.get("actor_id"),
            role=new_metadata.get("role"),
        )
+
+        # Entity-store cleanup: strip this memory's id from old-text entities,
+        # then re-extract entities from the new text and link them back.
+        session_filters = {k: new_metadata[k] for k in ("user_id", "agent_id", "run_id") if new_metadata.get(k)}
+        await self._remove_memory_from_entity_store(memory_id, session_filters)
+        await self._link_entities_for_memory(memory_id, data, session_filters)
+
        return memory_id

    async def _delete_memory(self, memory_id, existing_memory=None):
@@ -2937,6 +3144,8 @@ class AsyncMemory(MemoryBase):
        prev_value = existing_memory.payload.get("data", "")
        created_at = _normalize_iso_timestamp_to_utc(existing_memory.payload.get("created_at"))
        updated_at = datetime.now(timezone.utc).isoformat()
+        payload = existing_memory.payload or {}
+        session_filters = {k: payload[k] for k in ("user_id", "agent_id", "run_id") if payload.get(k)}

        await asyncio.to_thread(self.vector_store.delete, vector_id=memory_id)
        await asyncio.to_thread(
@@ -2952,6 +3161,10 @@ class AsyncMemory(MemoryBase):
            is_deleted=1,
        )

+        # Entity-store cleanup: strip this memory's id from any entity records
+        # that linked to it. Non-fatal — the helper swallows errors.
+        await self._remove_memory_from_entity_store(memory_id, session_filters)
+
        return memory_id

    async def reset(self):
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "mem0ai"
-version = "2.0.0b1"
+version = "2.0.0"
 description = "Long-term memory for AI Agents"
 authors = [
    { name = "Mem0", email = "support@mem0.ai" }
Author	SHA1	Message	Date
Saket Aryan	fb224083e4	chore(release): promote Python SDK to 2.0.0 and TS SDK to 3.0.0 (#4860 )	2026-04-16 17:13:50 +05:30
Chaithanya Kumar	30469aec17	docs: new algorithm migration guides + memory evaluation (#4811 ) Co-authored-by: kartik-mem0 <kartik.labhshetwar@mem0.ai> Co-authored-by: Saket Aryan <saketaryan2002@gmail.com>	2026-04-16 17:13:13 +05:30
Saket Aryan	50db9e428d	chore(release): bump SDK versions to next beta (#4859 )	2026-04-16 16:23:50 +05:30
soumil-rathi	fb87349664	fix(oss): v3 entity cleanup, filter fixes, and QA hardening (TS + Python) (#4858 ) Co-authored-by: Soumil Rathi <soumilrathi@gmail.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-16 12:17:13 +05:30
Saket Aryan	8827553576	fix: adopt new v3 memory endpoints in Python + TS clients (#4856 )	2026-04-16 05:28:49 +05:30
Kabir Kohli	c8e20a9bb5	fix(docs): resolve duplicate operationIds and expiration_date type in openapi spec (#4854 )	2026-04-16 04:09:51 +05:30