diff --git a/docs/changelog/highlights.mdx b/docs/changelog/highlights.mdx index 7739e1c09..64f5e52cb 100644 --- a/docs/changelog/highlights.mdx +++ b/docs/changelog/highlights.mdx @@ -46,9 +46,9 @@ Ground-up rewrite of the memory pipeline with 20+ point benchmark improvements: - **~3-4x 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 +- **Graph memory (built-in)**: entities extracted, embedded, and linked across memories, with no external graph store required -Breaking changes: Graph memory removed from OSS, `search()` defaults changed, deprecated params removed. See [migration guide](/migration/oss-v2-to-v3). +Breaking changes: external graph stores removed from OSS (replaced by built-in graph memory), `search()` defaults changed, deprecated params removed. See [migration guide](/migration/oss-v2-to-v3). diff --git a/docs/changelog/platform.mdx b/docs/changelog/platform.mdx index 6547f3124..af3d73fc5 100644 --- a/docs/changelog/platform.mdx +++ b/docs/changelog/platform.mdx @@ -25,7 +25,7 @@ mode: "wide" **Improvements:** -- **UI:** Removed Graph Memory tab, page, and all references from dashboard, sidebar, project settings, playground, and billing +- **UI:** Removed the legacy external-graph-store visualization tab, page, and its references from dashboard, sidebar, project settings, playground, and billing diff --git a/docs/changelog/sdk.mdx b/docs/changelog/sdk.mdx index b8382ed05..3f40318c3 100644 --- a/docs/changelog/sdk.mdx +++ b/docs/changelog/sdk.mdx @@ -114,8 +114,8 @@ mode: "wide" - **`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)) +- **External Graph Store 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, about 4,000 lines. The external graph store integration is no longer part of the OSS SDK; graph drivers (neo4j, memgraph, kuzu, etc.) can be uninstalled. Graph memory now runs natively as built-in entity linking. 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 now runs automatically and no longer needs a flag. 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)) @@ -1066,7 +1066,7 @@ See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to- - **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)) +- **External Graph Store Removed (OSS):** `graph_memory.ts` (675 lines), `graphs/tools.ts` (267 lines), `graphs/utils.ts` (116 lines), `graphs/configs.ts` (30 lines) deleted. The external graph store integration is no longer part of the OSS SDK; graph memory now runs natively as built-in entity linking ([#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 diff --git a/docs/core-concepts/memory-evaluation.mdx b/docs/core-concepts/memory-evaluation.mdx index d03e8f21f..aae537c48 100644 --- a/docs/core-concepts/memory-evaluation.mdx +++ b/docs/core-concepts/memory-evaluation.mdx @@ -17,7 +17,7 @@ Some benchmarks today — particularly smaller ones like LoCoMo and LongMemEval ## Architecture Overview -Mem0's memory system operates across two phases — **extraction** (writing) and **retrieval** (reading) — with an entity linking layer connecting them. +Mem0's memory system operates across two phases, **extraction** (writing) and **retrieval** (reading), with a graph memory layer (entity linking) connecting them. ### Memory Extraction (Distillation) @@ -27,14 +27,14 @@ When new conversations arrive, the extraction pipeline processes them through fi 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 +5. **Graph Memory (Entity Linking)**: Identify entities (proper nouns, quoted text, compound noun phrases) and link them across memories into a graph 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 | +| **Graph / Entity Store** | Entities + embeddings + linked memory IDs | Graph connections across memories + entity-based retrieval boost | | **SQL Database** | History log (ADD events) + rolling message window | Audit trail + extraction dedup context | @@ -76,7 +76,7 @@ The combined score outperformed every individual signal across every category te *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). +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 graph memory / entity linking (connecting facts across memories). ### LongMemEval diff --git a/docs/docs.json b/docs/docs.json index a75dd1ebe..01bd5e6e9 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -71,6 +71,7 @@ "pages": [ "platform/features/v2-memory-filters", "platform/features/entity-scoped-memory", + "platform/features/graph-memory", "platform/features/async-client", "platform/features/multimodal-support", "platform/features/custom-categories", @@ -647,10 +648,6 @@ "source": "/open-source/features/custom-fact-extraction-prompt", "destination": "/open-source/features/custom-instructions" }, - { - "source": "/platform/features/graph-memory", - "destination": "/migration/oss-v2-to-v3" - }, { "source": "/cookbooks/essentials/choosing-memory-architecture-vector-vs-graph", "destination": "/migration/oss-v2-to-v3" @@ -1025,7 +1022,7 @@ }, { "source": "/features/graph-memory", - "destination": "/migration/oss-v2-to-v3" + "destination": "/platform/features/graph-memory" }, { "source": "/features/:slug", diff --git a/docs/llms.txt b/docs/llms.txt index ccca47734..6456364d5 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -197,6 +197,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f - [Platform Features Overview](https://docs.mem0.ai/platform/features/platform-overview) [Platform]: Use when surveying what managed offers beyond CRUD. - [V2 Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters) [Platform]: Use when compound filters (AND/OR on metadata, entity, time) are needed at search. - [Entity-Scoped Memory](https://docs.mem0.ai/platform/features/entity-scoped-memory) [Platform]: Use when partitioning memories by user, agent, app, or run. +- [Graph Memory](https://docs.mem0.ai/platform/features/graph-memory) [Platform]: Use when connecting facts across memories through shared entities for entity-centric or multi-hop questions. - [Async Client](https://docs.mem0.ai/platform/features/async-client) [Platform]: Use when the app issues many concurrent Mem0 calls and needs non-blocking I/O. - [Multimodal Support](https://docs.mem0.ai/platform/features/multimodal-support) [Platform]: Use when storing images or PDFs as memory input. - [Custom Categories](https://docs.mem0.ai/platform/features/custom-categories) [Platform]: Use when the default categories do not match the domain. diff --git a/docs/migration/oss-v2-to-v3.mdx b/docs/migration/oss-v2-to-v3.mdx index 7c883b5bd..9d40fd937 100644 --- a/docs/migration/oss-v2-to-v3.mdx +++ b/docs/migration/oss-v2-to-v3.mdx @@ -328,27 +328,27 @@ The new algorithm automatically creates a parallel entity store collection named 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. -## Graph Memory → Entity Linking +## Graph Memory: Now Built-In -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. +External graph **store** support has been removed from the open-source SDK and replaced by **built-in graph memory** (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) +- All external graph store 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. +Mem0 now builds the graph itself. It 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. Memories that share an entity are linked, and at search time entities from the query are matched against this collection to boost connected 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. +- Uninstall external graph drivers (neo4j, memgraph, etc.) if you were using them only for Mem0 +- No data migration is required. Built-in graph memory activates automatically on the next `add()` call. -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. +The old `relations` field on search results (populated by the external graph store) is no longer returned. Entity connections are now applied through retrieval ranking rather than exposed as a separate, directly traversable structure. If your application read or traversed the `relations` array, you will need to redesign that part against the new API. ## How the New Algorithm Works diff --git a/docs/migration/platform-v2-to-v3.mdx b/docs/migration/platform-v2-to-v3.mdx index fa021aac2..36261bc2f 100644 --- a/docs/migration/platform-v2-to-v3.mdx +++ b/docs/migration/platform-v2-to-v3.mdx @@ -1,6 +1,6 @@ --- 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." +description: "Guide for Mem0 Platform users to adopt the new memory algorithm with single-pass extraction, built-in graph memory, and multi-signal retrieval." icon: "arrow-right" iconType: "solid" --- @@ -18,8 +18,7 @@ The new Mem0 memory algorithm is a ground-up redesign of how memories are extrac | **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 | +| **Graph memory** | External graph store (Neo4j, etc.) + manual setup | Built-in and automatic; entities extracted and linked across memories natively, no external store | | **Retrieval** | Semantic (vector) only | Hybrid retrieval combining multiple signals | ## What This Means for Your Application @@ -249,19 +248,18 @@ await client.search("query", { For the full list of parameter changes across all SDKs, see the [OSS migration guide](/migration/oss-v2-to-v3#removed-parameters-reference). -## Graph Memory → Entity Linking +## Graph Memory Is Now Built-In -Graph memory has been replaced by **built-in entity linking**. The changes: +Graph memory no longer requires an external graph database. It is now **native to the platform** and automatic. 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 external graph store to configure.** Previously, graph memory required a separate Neo4j (or similar) deployment. Mem0 now builds the graph itself from your memories, so there is nothing to provision and no connection strings to manage. +- **Always on, no flag.** The `enable_graph` project setting is no longer needed; graph memory activates automatically. (The API parameter is now ignored if sent.) +- **Connections power retrieval directly.** 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 the graph 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. +**No migration work is required.** Graph memory activates automatically for all projects on the new algorithm. Existing memories are not re-processed, but any new memories you add are added to the graph going forward. See [Graph Memory](/platform/features/graph-memory) for how the built-in graph works. -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. +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 connections are now applied through retrieval ranking rather than returned as a separate `relations` array. ## Migration Checklist diff --git a/docs/platform/features/entity-scoped-memory.mdx b/docs/platform/features/entity-scoped-memory.mdx index d325623d2..1e85b1108 100644 --- a/docs/platform/features/entity-scoped-memory.mdx +++ b/docs/platform/features/entity-scoped-memory.mdx @@ -5,6 +5,10 @@ description: Scope conversations by user, agent, app, and session so memories la Mem0's Platform API lets you separate memories for different users, agents, and apps. By tagging each write and query with the right identifiers, you can prevent data from mixing between them, maintain clear audit trails, and control data retention. + +**Entity IDs vs. graph entities.** This page covers the `user_id` / `agent_id` / `app_id` / `run_id` identifiers used to *scope* memories. These are different from the **graph entities** (the people, places, and concepts surfaced in [Graph Memory](/platform/features/graph-memory)). + + Want the long-form tutorial? The Partition Memories by Entity cookbook walks through multi-agent storage, debugging, and cleanup step by step. diff --git a/docs/platform/features/graph-memory.mdx b/docs/platform/features/graph-memory.mdx new file mode 100644 index 000000000..1cb48dd59 --- /dev/null +++ b/docs/platform/features/graph-memory.mdx @@ -0,0 +1,93 @@ +--- +title: "Graph Memory" +description: "Mem0 Platform builds a native graph of the entities in your memories, connecting people, places, and concepts across memories with no external graph database to provision." +icon: "circle-nodes" +iconType: "solid" +--- + +Mem0 Platform automatically organizes your memories into a **graph**: the **graph entities** mentioned across your memories (the people, places, organizations, and concepts they refer to) become nodes, and memories that share an entity are connected. This is how Mem0 reasons across separate facts, for example linking everything it knows about a person, a company, or a project, without you defining any schema. + +Graph Memory is **built in**. There is no Neo4j, Memgraph, or other graph store to deploy, no connection strings to manage, and nothing to enable. It runs natively inside the platform and is always on. + + + **Graph Memory matters when…** + - You ask entity-centric questions like "what do we know about Alice?" and expect facts pulled from many different conversations + - Your app needs multi-hop recall, connecting a fact in one memory to a related fact in another + - You previously used an external graph store and want the same cross-memory connections with zero infrastructure + + + + **Graph entities vs. entity IDs.** The entities in your graph (people, places, and concepts extracted from memory text) are different from the *entity IDs* (`user_id`, `agent_id`, `app_id`, `run_id`) used to scope memories. Those are covered in [Entity-Scoped Memory](/platform/features/entity-scoped-memory). + + + + Graph Memory is the native successor to Mem0's earlier graph store integration. Earlier versions connected an external graph database (Neo4j and others) and exposed a `relations` field. Mem0 now builds the graph itself from your memories. See [What changed from the external graph store](#what-changed-from-the-external-graph-store) below. + + +## How it works + +Graph Memory is built and used across the two phases of the memory pipeline: **extraction** (when you add memories) and **retrieval** (when you search). + +### 1. Entities become nodes + +Every time you add a memory, Mem0 extracts the **entities** it contains: the proper nouns, names, and key phrases that identify a specific person, place, organization, product, or concept (for example *Alice*, *San Francisco*, *Acme Corp*, *the Q1 roadmap*). Each distinct entity is stored once and embedded, so entities that refer to the same thing can be matched even when they are phrased differently. + +### 2. Shared entities become connections + +When the same entity appears in more than one memory, those memories are **linked** through that entity. Over time this forms a graph: a web of entities, each connecting all the memories that mention it. The connections are derived directly from your data. There is no relationship schema to define and nothing to label by hand. + +### 3. The graph powers retrieval + +At search time, Mem0 extracts the entities from your query and matches them against the graph. Memories connected to those entities receive a ranking boost, which is combined with semantic (vector) and keyword (BM25) scores into the single `score` returned on each result. + +This is what lets Mem0 answer entity-centric and multi-hop questions: a query about *Alice* surfaces facts about Alice that live in completely different memories, because the graph connects them. The connecting-facts-across-memories behavior contributes to Mem0's gains on multi-hop and temporal benchmarks. See [Memory Evaluation](/core-concepts/memory-evaluation). + + +Graph Memory affects **ranking**, not the response shape. Search results come back in the normal format with a combined `score`; there is no separate graph payload to parse. + + +## What's in the graph + +| Element | What it is | +| --- | --- | +| **Graph entity** (node) | A distinct person, place, organization, product, or concept extracted from your memories (e.g. *Alice*, *Acme Corp*). Distinct from the user/agent/app/run *entity IDs* used to scope memories. | +| **Memory node** | An individual memory (fact) stored for a user, agent, or session. | +| **Connection** | A link between an entity and every memory that mentions it. Two entities are related when they co-occur in one or more memories. | + +Graph Memory captures **which entities your memories are about and how they connect through shared context**. It does not assign typed, labeled relationships between entities (it won't, for example, record a "manages" edge from one person to another); connections are inferred from co-occurrence rather than declared. This is what makes it schema-free and zero-configuration. + +## Availability + +Graph Memory is **automatic and included on all plans**. It activates on the new memory algorithm with no flag, no configuration, and no external dependencies. You don't need to do anything to benefit from it. + +```python +from mem0 import MemoryClient + +client = MemoryClient(api_key="your-api-key") + +# Entities are extracted and linked into the graph automatically on add +client.add( + messages=[ + {"role": "user", "content": "I work at Acme Corp with Alice on the Q1 roadmap"} + ], + user_id="jordan", +) + +# Entity matches from the query are used to connect and boost related memories +results = client.search( + query="who does jordan work with?", + filters={"user_id": "jordan"}, +) +``` + +## What changed from the external graph store + +Earlier versions of Mem0 offered graph memory by connecting an **external graph database** (Neo4j, Memgraph, Kuzu, Apache AGE, or Neptune) through an `enable_graph` flag and a `graph_store` configuration block. That integration has been replaced by **native, built-in Graph Memory**: + +- **No external graph store.** The graph is built inside Mem0 from your memories. There is nothing to provision or connect. +- **Always on, all plans.** The `enable_graph` flag is no longer needed; Graph Memory is automatic. (If you still send the parameter, it is ignored.) +- **Connections power retrieval directly.** Entity connections are folded into the combined `score` on each result. The standalone `relations` field that the external graph store returned is no longer populated. If your application read that field, see the migration guide below. + + + Full details on the move to the new algorithm, including the `relations` field change. +