diff --git a/docs/core-concepts/memory-types.mdx b/docs/core-concepts/memory-types.mdx
index 7a0277435..a2a18e077 100644
--- a/docs/core-concepts/memory-types.mdx
+++ b/docs/core-concepts/memory-types.mdx
@@ -1,68 +1,69 @@
---
title: Memory Types
-description: "See how Mem0 layers conversation, session, and user memories to keep agents contextual."
+description: "What memory_type actually does in Mem0: procedural memory is implemented, semantic and episodic are not."
icon: "tag"
iconType: "solid"
---
-# How Mem0 Organizes Memory
+# Memory Types
-Mem0 separates memory into layers so agents remember the right detail at the right time. Think of it like a notebook: a sticky note for the current task, a daily journal for the session, and an archive for everything a user has shared.
+Mem0's Python SDK exposes a `memory_type` parameter on `add()`. The underlying `MemoryType` enum defines three values, but only one of them is wired up. This page states plainly which is which so you don't build against a type that doesn't exist yet.
-## Key terms
+## Status
-- **Conversation memory**: In-flight messages inside a single turn (what was just said).
-- **Session memory**: Short-lived facts that apply for the current task or channel.
-- **User memory**: Long-lived knowledge tied to a person, account, or workspace.
-- **Organizational memory**: Shared context available to multiple agents or teams.
+| Type | Enum value | Status | Notes |
+| --- | --- | --- | --- |
+| Procedural memory | `procedural_memory` | **Implemented** | Python OSS only (`Memory`/`AsyncMemory`). Pass `memory_type="procedural_memory"` and `agent_id` to `add()`. Not available on the Platform `MemoryClient`, and not available in the TypeScript SDK (OSS or Platform). |
+| Semantic memory | `semantic_memory` | **Not implemented** | Defined in the `MemoryType` enum but never read anywhere else in the codebase. Passing it to `add()` raises a validation error. There is no evidence in this repo of a roadmap date for this. |
+| Episodic memory | `episodic_memory` | **Not implemented** | Same as above: defined, never wired into the extraction pipeline, rejected by validation, no documented roadmap. |
-```mermaid
-graph LR
- A[Conversation turn] --> B[Session memory]
- B --> C[User memory]
- C --> D[Org memory]
- C --> E[Mem0 retrieval layer]
-```
+
+ Only `procedural_memory` is a real, working value. Calling `memory.add(messages, memory_type="semantic_memory")` (or `episodic_memory`) is rejected and tells you to pass `procedural_memory` instead. Sync `Memory.add()` raises `Mem0ValidationError`; `AsyncMemory.add()` raises a plain `ValueError`.
+
-## Short-term vs long-term memory
+## Procedural memory
-Short-term memory keeps the current conversation coherent. It includes:
-
-- **Conversation history**: recent turns in order so the agent remembers what was just said.
-- **Working memory**: temporary state such as tool outputs or intermediate calculations.
-- **Attention context**: the immediate focus of the assistant, similar to what a person holds in mind mid-sentence.
-
-Long-term memory preserves knowledge across sessions. It captures:
-
-- **Factual memory**: user preferences, account details, and domain facts.
-- **Episodic memory**: summaries of past interactions or completed tasks.
-- **Semantic memory**: relationships between concepts so agents can reason about them later.
-
-Mem0 maps these classic categories onto its layered storage so you can decide what should fade quickly versus what should last for months.
-
-## How does it work?
-
-Mem0 stores each layer separately and merges them when you query:
-
-1. **Capture**: Messages enter the conversation layer while the turn is active.
-2. **Promote**: Relevant details persist to session or user memory based on your `user_id`, `run_id`, and metadata.
-3. **Retrieve**: The search pipeline pulls from all layers, ranking user memories first, then session notes, then raw history.
+Procedural memory stores step-by-step task knowledge (how an agent performs a workflow) rather than facts about a user. It requires `agent_id`:
```python
-import os
-
from mem0 import Memory
memory = Memory()
-# Sticky note: conversation memory
memory.add(
- ["I'm Alex and I prefer boutique hotels."],
+ [
+ {"role": "user", "content": "Book a flight from SFO to NYC"},
+ {"role": "assistant", "content": "1. Search flights. 2. Filter by price. 3. Confirm booking."},
+ ],
+ agent_id="travel-agent",
+ memory_type="procedural_memory",
+)
+```
+
+Omit `memory_type` entirely and Mem0 stores the messages as an ordinary memory: there is no semantic/episodic pathway for it to fall into. Any other explicit value is rejected by validation rather than quietly falling back to an ordinary memory.
+
+## How every other memory is scoped
+
+Outside of the `procedural_memory` special case, Mem0 does not sort memories into named types. Every memory is scoped by the identifiers you pass in, and the same identifiers are used to retrieve it later:
+
+- **`user_id`**: ties a memory to a specific person or account.
+- **`agent_id`**: ties a memory to a specific agent or assistant persona.
+- **`run_id`**: ties a memory to a specific session, task, or conversation thread.
+- **`app_id`** (Platform only): ties a memory to a specific application or tenant, in addition to the three above. See Entity-Scoped Memory.
+
+At least one identifier is required on `add()`. Passing more than one narrows the scope further (for example, `user_id` + `run_id` together).
+
+```python
+from mem0 import Memory
+
+memory = Memory()
+
+memory.add(
+ "I'm Alex and I prefer boutique hotels.",
user_id="alex",
run_id="trip-planning-2025",
)
-# Later in the session, pull long-term + session context
results = memory.search(
"Any hotel preferences?",
filters={"user_id": "alex", "run_id": "trip-planning-2025"},
@@ -70,52 +71,48 @@ results = memory.search(
```
- Use `run_id` when you want short-term context to expire automatically; rely on `user_id` for lasting personalization.
+ Use `run_id` when you want a set of memories to stay tied to one session or task; use `user_id` alone for anything that should persist across every session for that person.
-## When should you use each layer?
+## How memories are extracted and updated
-- **Conversation memory**: Tool calls or chain-of-thought that only matter within the current turn.
-- **Session memory**: Multi-step tasks (onboarding flows, debugging sessions) that should reset once complete.
-- **User memory**: Personal preferences, account state, or compliance details that must persist across interactions.
-- **Organizational memory**: Shared FAQs, product catalogs, or policies that every agent should recall.
+When `infer=True` (the default) on `add()`, Mem0 runs a single pipeline rather than routing through separate type-specific paths:
-## How it compares
+1. **Context gathering**: pulls the most recent messages already stored for the same `user_id`/`agent_id`/`run_id` scope.
+2. **Existing memory retrieval**: embeds the new messages and runs a vector search against memories already in that same scope, to find candidates that might need to change.
+3. **Extraction**: a single LLM call compares the new messages against the retrieved candidates and decides, per fact, whether to `ADD`, `UPDATE`, `DELETE`, or leave a memory alone.
-| Layer | Lifetime | Short or long term | Best for | Trade-offs |
-| --- | --- | --- | --- | --- |
-| Conversation | Single response | Short-term | Tool execution detail | Lost after the turn finishes |
-| Session | Minutes to hours | Short-term | Multi-step flows | Clear it manually when done |
-| User | Weeks to forever | Long-term | Personalization | Requires consent/governance |
-| Org | Configured globally | Long-term | Shared knowledge | Needs owner to keep current |
+Alongside this, both OSS and Platform extract named entities (people, places, organizations) from memory text and use shared entities between memories to boost related results at search time. On Platform, that entity graph is also queryable directly; see Graph Memory. In OSS, entities only affect ranking, there is no separate graph to query.
- Avoid storing secrets or unredacted PII in user or org memories: Mem0 is retrievable by design. Encrypt or hash sensitive values first.
+ Avoid storing secrets or unredacted PII in memories: they are retrievable by design. Encrypt or hash sensitive values before calling `add()`.
## Put it into practice
-- Use the Add Memory guide to persist user preferences.
-- Follow Advanced Memory Operations to tune metadata and retrieval.
-
-## See it live
-
-- AI Tutor with Mem0 shows session vs user memories in action.
-- Support Inbox with Mem0 demonstrates shared org memory.
-
-{/* DEBUG: verify CTA targets */}
-
+
+
diff --git a/docs/llms.txt b/docs/llms.txt
index 8546335f6..eee7abe5a 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -185,7 +185,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or a Platform call st
## Core Concepts
- [How Mem0 Works](https://docs.mem0.ai/core-concepts/how-it-works) [Both]: Use when explaining the end-to-end pipeline: extraction (ADD-only distillation), storage across vector/entity/history stores, and multi-signal retrieval.
-- [Memory Types](https://docs.mem0.ai/core-concepts/memory-types) [Both]: Use when explaining working, factual, episodic, and semantic memory distinctions.
+- [Memory Types](https://docs.mem0.ai/core-concepts/memory-types) [Both]: Use when checking which `memory_type` values actually work: `procedural_memory` is implemented, `semantic_memory` and `episodic_memory` are defined in the enum but rejected by validation.
- [Memory Operations - Add](https://docs.mem0.ai/core-concepts/memory-operations/add) [Both]: Use when explaining how `add()` extracts facts, resolves conflicts, and writes to both stores.
- [Memory Operations - Search](https://docs.mem0.ai/core-concepts/memory-operations/search) [Both]: Use when explaining how queries are processed and ranked.
- [Memory Operations - Update](https://docs.mem0.ai/core-concepts/memory-operations/update) [Both]: Use when memories need to be edited in place or reconciled against new info.
diff --git a/docs/platform/features/v2-memory-filters.mdx b/docs/platform/features/v2-memory-filters.mdx
index 034fc0f76..3d5e08d07 100644
--- a/docs/platform/features/v2-memory-filters.mdx
+++ b/docs/platform/features/v2-memory-filters.mdx
@@ -42,14 +42,15 @@ Filters use a nested JSON structure with logical operators at the root:
### Time fields
| Field | Operators | Example |
|-------|-----------|---------|
-| `created_at` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"created_at": {"gte": "2024-01-01"}}` |
-| `updated_at` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"updated_at": {"lt": "2024-12-31"}}` |
-| `timestamp` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` | `{"timestamp": {"gt": "2024-01-01"}}` |
+| `created_at` | `gt`, `gte`, `lt`, `lte`, `ne`, `in`. Explicit `eq` is rejected, pass a bare value instead | `{"created_at": {"gte": "2024-01-01"}}` |
+| `updated_at` | `gt`, `gte`, `lt`, `lte`, `ne`, `in`. Explicit `eq` is rejected, pass a bare value instead | `{"updated_at": {"lt": "2024-12-31"}}` |
+| `timestamp` | `gt`, `gte`, `lt`, `lte`, `ne`, `in`. Explicit `eq` is rejected, pass a bare value instead | `{"timestamp": {"gt": "2024-01-01"}}` |
+| `expiration_date` | `gt`, `gte`, `lt`, `lte`, `ne`, `in`. Explicit `eq` is rejected, pass a bare value instead | `{"expiration_date": {"lte": "2026-12-31"}}` |
### Content fields
| Field | Operators | Example |
|-------|-----------|---------|
-| `categories` | `eq`, `ne`, `in` (matches any category in the list), `contains` (case-insensitive) | `{"categories": {"in": ["finance"]}}` |
+| `categories` | `in` (takes a list, matches any category in it), `contains` (case-insensitive). `eq` and `ne` are rejected | `{"categories": {"in": ["finance"]}}` |
| `metadata` | `eq`, `ne`, `contains` | `{"metadata": {"key": "value"}}` |
| `keywords` | `contains` (case-sensitive), `icontains` (case-insensitive) | `{"keywords": {"icontains": "invoice"}}` |
@@ -328,7 +329,7 @@ Level up foundational patterns with compound filters that coordinate entity scop
## Best practices
-The root does not have to be `AND`, `OR`, or `NOT`. A bare filter like `{"user_id": "alice"}` works on its own; wrap conditions in a logical operator only when you need to combine more than one.
+The root does not have to be `AND`, `OR`, or `NOT`. A bare filter like `{"user_id": "alice"}` works on its own, and several top-level keys in one flat filter are implicitly ANDed. Wrap conditions in a logical operator when you need OR/NOT semantics or nested grouping.
@@ -392,7 +393,7 @@ A filter object with both an `AND` key and a sibling `OR` key at the same level
- No. A bare filter like `{"user_id": "u1"}` works on its own. Add `AND`, `OR`, or `NOT` only when you need to combine more than one condition.
+ No. A bare filter like `{"user_id": "u1"}` works on its own, and several top-level keys in one flat filter like `{"user_id": "u1", "agent_id": "a1"}` are implicitly ANDed. Reach for `AND`, `OR`, or `NOT` when you need OR/NOT semantics or nested grouping, not merely to combine conditions.
@@ -421,8 +422,8 @@ A filter object with both an `AND` key and a sibling `OR` key at the same level
"AND": [
{"user_id": "user_123"},
{"OR": [
- {"categories": "finance"},
- {"categories": "health"}
+ {"categories": {"in": ["finance"]}},
+ {"categories": {"in": ["health"]}}
]}
]
}
diff --git a/docs/platform/platform-vs-oss.mdx b/docs/platform/platform-vs-oss.mdx
index 609497c6a..92bcc27b4 100644
--- a/docs/platform/platform-vs-oss.mdx
+++ b/docs/platform/platform-vs-oss.mdx
@@ -6,7 +6,7 @@ icon: "code-compare"
## Which Mem0 is right for you?
-Mem0 offers two powerful ways to add memory to your AI applications. Choose based on your priorities:
+Mem0 offers two ways to add memory to your AI applications. Both run the same core extraction and retrieval logic; the Platform adds hosting, a small set of v3-only capabilities, and management surfaces that OSS does not have.
**Managed, hassle-free**
- Get started in 5 minutes with our hosted solution. Perfect for fast iteration and production apps.
+ Get started in 5 minutes with our hosted solution. No vector store, LLM, or embedder to configure.
-
+
| Feature | Platform | Open Source |
|---------|----------|-------------|
- | **Time to first memory** | 5 minutes | 15-30 minutes |
- | **Infrastructure needed** | None | Vector DB + Python/Node env |
- | **API key setup** | One environment variable | Configure LLM + embedder + vector DB |
- | **Maintenance** | Fully managed by Mem0 | Self-managed |
+ | **Vector store, LLM, embedder** | Run and tuned by Mem0 | You provision, configure, and pay for each |
+ | **Scaling & availability** | Managed | Your responsibility |
+ | **Web dashboard** | `app.mem0.ai` | Not included |
+ | **Time to first memory** | Minutes (API key only) | Depends on your vector DB / LLM setup |
-
+
| Feature | Platform | Open Source |
|---------|----------|-------------|
- | **User & agent memories** | ✅ | ✅ |
- | **Smart deduplication** | ✅ | ✅ |
- | **Semantic search** | ✅ | ✅ |
- | **Memory updates** | ✅ | ✅ |
- | **Multi-language SDKs** | Python, JavaScript | Python, JavaScript |
+ | **Scoping identifiers** | `user_id`, `agent_id`, `run_id`, plus `app_id` for app/tenant separation | `user_id`, `agent_id`, `run_id` only, no `app_id` |
+ | **Organizations & projects** | Multi-org, multi-project, with member roles ([API reference](/api-reference/organization/get-org)) | No org/project concept; a single local config |
+ | **Project-wide event feed** | `GET /v1/events/` lists recent add/search/delete events per org and project, usable for dashboards, alerting, or audit trails | Only per-memory `history(memory_id)`, no project-wide event log |
+
+ See [Entity-Scoped Memory](/platform/features/entity-scoped-memory) for the full `app_id` model.
-
+
| Feature | Platform | Open Source |
|---------|----------|-------------|
- | **Multimodal support** | ✅ | ✅ |
- | **Custom categories** | ✅ | Limited |
- | **Advanced retrieval** | ✅ | ✅ |
- | **Temporal reasoning** | ✅ (v3) | ❌ |
- | **Memory decay** | ✅ (v3) | ❌ |
- | **Graph memory** | ✅ Built-in | ✅ External graph store |
- | **Memory filters v2** | ✅ | ⚠️ (via metadata) |
- | **Webhooks** | ✅ | ❌ |
- | **Memory export** | ✅ | ❌ |
+ | **Graph Memory** | Native, always-on graph over extracted entities; connections feed directly into the ranking `score` ([details](/platform/features/graph-memory)) | Removed. OSS previously connected external graph stores (Neo4j, Memgraph, Kuzu, Apache AGE); that integration was dropped when the v3 pipeline landed. OSS still extracts entities and uses them to boost ranking, but there is no queryable graph and no `relations` field |
+ | **Memory Decay** | Opt-in per project; reinforces recently-used memories and gently dampens stale ones at search time ([details](/platform/features/memory-decay)) | Not supported. Passing `decay` raises `"The decay parameter is not supported by the OSS Memory SDK."` |
+ | **Temporal Reasoning** | Boosts memories whose event dates match the time expressed in a query (`timestamp` / `reference_date`) ([details](/platform/features/temporal-reasoning)) | Not supported. Both parameters raise a "not supported by the OSS Memory SDK" error |
+ | **Dream (background consolidation)** | Continuously synthesizes patterns, supersedes outdated facts, and merges duplicates per user ([details](/platform/features/dream)) | Not available |
-
+
| Feature | Platform | Open Source |
|---------|----------|-------------|
- | **Hosting** | Managed by Mem0 | Self-hosted |
- | **Auto-scaling** | ✅ | Manual |
- | **High availability** | ✅ Built-in | DIY setup |
- | **Vector DB choice** | Managed | 20+ stores: Qdrant, Pinecone, Chroma, Weaviate, Milvus, pgvector |
- | **LLM choice** | Managed (optimized) | 15+ providers: OpenAI, Anthropic, Gemini, Groq, Ollama, Together |
- | **Data residency** | US (expandable) | Your choice |
+ | **Custom categories** | Set per project or per `add` call ([details](/platform/features/custom-categories)) | Not supported. `Memory.add()` has no `custom_categories` parameter, and OSS project updates are rejected outright |
+ | **Webhooks** | Project-scoped HTTP callbacks on memory and ingest events ([details](/platform/features/webhooks)) | Not available |
+ | **Memory Export** | Schema-driven structured export jobs over filtered memories ([details](/platform/features/memory-export)) | Not available |
+ | **Batch operations** | `batch_update` and `batch_delete` apply up to 1000 memories per call | Not available. Loop over the single-memory `update`/`delete` calls |
+ | **Feedback** | `feedback(memory_id, ...)` records `POSITIVE`, `NEGATIVE`, or `VERY_NEGATIVE` signals against a retrieved memory ([details](/platform/features/feedback-mechanism)) | Not available |
+ | **Summaries** | `get_summary(filters)` returns a generated summary over the matching memories | Not available |
+ | **Filterable fields** | Top-level filter keys come from a fixed allowlist: `user_id`, `agent_id`, `app_id`, `run_id`, `created_at`, `updated_at`, `timestamp`, `expiration_date`, `categories`, `metadata`, `keywords`, `memory_ids`, plus the `AND`/`OR`/`NOT` operators and a few endpoint-specific extras. Any other key is rejected with a `400` ([details](/platform/features/v2-memory-filters)) | Any metadata key is filterable directly, with no allowlist |
+ | **Comparison operators** | Depends on the field: `metadata` accepts `eq`, `ne`, `contains`; `categories` accepts `contains`, `in`; the date fields accept the range operators | The filter layer accepts the full set on any key: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `icontains`. What actually runs depends on the vector store you configured, so confirm operator coverage for yours ([details](/open-source/features/metadata-filtering)) |
-
- | Aspect | Platform | Open Source |
- |--------|----------|-------------|
- | **License** | Usage-based pricing | Apache 2.0 (free) |
- | **Infrastructure costs** | Included in pricing | You pay for VectorDB + LLM + hosting |
- | **Support** | Included | Community + GitHub |
- | **Best for** | Fast iteration, production apps | Cost-sensitive, custom requirements |
-
-
-
- | Feature | Platform | Open Source |
+
+ | Channel | Platform | Open Source |
|---------|----------|-------------|
- | **REST API** | ✅ | ✅ (self-hosted server) |
- | **Python SDK** | ✅ | ✅ |
- | **JavaScript SDK** | ✅ | ✅ |
- | **Framework integrations** | LangChain, CrewAI, LlamaIndex, and 20+ more | Same |
- | **Dashboard** | ✅ Web-based | ❌ |
- | **Analytics** | ✅ Built-in | DIY |
+ | **Community & maintainers** | Discord, GitHub Discussions, direct calls with the founders | Same: Discord, GitHub Discussions, direct calls with the founders |
+
+ Support channels are currently the same for both. If you need something contractual (a support SLA, for example), ask before assuming it exists: it is not documented as a Platform benefit today.
+User Profiles are not listed above. The feature is still being finalized internally, so this page does not present it as an available Platform benefit.
+
---
## Decision Guide
**Choose Platform if you want:**
-- Fast time to market: get your AI app with memory live in hours, not weeks.
-- Production-ready hosting: auto-scaling, high availability, and managed infrastructure.
-- Built-in analytics: track memory usage, query patterns, and user engagement through the dashboard.
-- Advanced features: webhooks, memory export, custom categories, and priority support.
+- Zero infrastructure: no vector store, LLM, or embedder to provision or tune.
+- The v3-only ranking features: Graph Memory, Memory Decay, Temporal Reasoning, and Dream.
+- App-level and org/project-level scoping, plus webhooks, memory export, and custom categories.
**Choose Open Source if you need:**
-- Full data control: host everything on your infrastructure with complete data residency.
-- Custom configuration: choose your own vector DB, LLM provider, embedder, and deployment strategy.
-- Extensibility: modify the codebase, add custom features, and contribute back to the community.
-- Cost optimization: use local LLMs (Ollama), self-hosted vector DBs, and optimize for your use case.
+- Full data control: host everything on your own infrastructure.
+- Custom configuration: your own vector DB, LLM provider, and embedder ([25 vector stores](/components/vectordbs/overview), [18 LLM providers](/components/llms/overview), [11 embedders](/components/embedders/overview) at the time of writing).
+- Extensibility: modify the codebase, add custom providers, and contribute back.
+- Cost optimization: local LLMs (Ollama), self-hosted vector DBs, no usage-based billing.
---