chore: merge origin/main into mintlify/af82bda4 and resolve conflicts

docs/platform/cli.mdx

@@ -1,6 +1,7 @@
 ---
-title: CLI
-description: "Use the mem0 CLI to add, search, list, update, and delete memories directly from your terminal, with npm and Python packages for humans and agents."
+title: "CLI for Terminal Memory Management"
+sidebarTitle: "CLI"
+description: "Manage memories from your terminal, for both humans and AI agents."
 icon: "terminal"
 iconType: "solid"
 ---
@@ -143,6 +144,7 @@ Search memories using natural language.
 ```bash
 mem0 search "dietary restrictions" --user-id alice
 mem0 search "preferred tools" --user-id alice --output json --top-k 5
+mem0 search "invoices" --user-id alice --filter '{"AND": [{"categories": {"in": ["work"]}}]}'
 ```
 
 | Flag | Description |
@@ -155,7 +157,7 @@ mem0 search "preferred tools" --user-id alice --output json --top-k 5
 | `--threshold` | Minimum similarity score (default: 0.3) |
 | `--rerank` | Enable reranking |
 | `--keyword` | Use keyword search instead of semantic |
-| `--filter` | Advanced filter expression (JSON) |
+| `--filter` | Advanced filter as JSON: `{"AND": [...]}` or `{"OR": [...]}`, e.g. `{"AND": [{"categories": {"in": ["work"]}}]}` |
 | `--fields` | Return only the named fields |
 | `--show-expired` | Include expired memories |
 | `--reference-date` | Reference date for relative queries (`YYYY-MM-DD` or Unix timestamp) |
@@ -471,7 +473,7 @@ These two flags belong to `mem0` itself, so they go **before** the command name:
 |------|-------------|
 | `--json` | Enable agent mode: structured JSON envelope output, no colors or spinners |
 | `--agent` | Alias for `--json` |
-| `--version` | Print the CLI version and exit |
+| `--version` | Print the CLI version and exit. `mem0 version` does the same thing as a regular subcommand |
 
 <Warning>
 On `init` only, `--agent` means something different. `mem0 init --agent` creates an Agent Mode account (see [Sign up as an agent](/platform/agent-signup)); it does not switch the output to JSON. To get JSON from `init`, put the flag first: `mem0 --json init`.

docs/platform/features/advanced-retrieval.mdx

@@ -99,16 +99,23 @@ results = client.search(
 
 ### Recommended Configurations
 
+`rerank` is the only lever here that changes result *order*. `filters`, `top_k`, and `threshold` change *which* memories come back, not how they're ordered. The two functions below send the same query and filters; the only difference is the `rerank` flag.
+
 <CodeGroup>
 ```python Python
-# Basic search - good for exploration
+# Fast path - use for exploratory search, or anywhere the user scans a list
+# of results instead of trusting result #1 (dashboards, "show me everything
+# about X" style queries). No reranking overhead.
 def quick_search(query, user_id):
     return client.search(
         query=query,
         filters={"user_id": user_id},
     )
 
-# Reranked search - good when result order matters
+# Precision path - use when only the top result reaches the user, e.g. an
+# agent that injects a single fact into a prompt. Reranking (see above)
+# re-scores every match and moves the closest one to position 1, at the
+# cost of ~150-200ms added latency.
 def standard_search(query, user_id):
     return client.search(
         query=query,
@@ -118,14 +125,19 @@ def standard_search(query, user_id):
 ```
 
 ```javascript JavaScript
-// Basic search - good for exploration
+// Fast path - use for exploratory search, or anywhere the user scans a list
+// of results instead of trusting result #1 (dashboards, "show me everything
+// about X" style queries). No reranking overhead.
 function quickSearch(query, userId) {
     return client.search(query, {
         filters: { user_id: userId },
     });
 }
 
-// Reranked search - good when result order matters
+// Precision path - use when only the top result reaches the user, e.g. an
+// agent that injects a single fact into a prompt. Reranking (see above)
+// re-scores every match and moves the closest one to position 1, at the
+// cost of ~150-200ms added latency.
 function standardSearch(query, userId) {
     return client.search(query, {
         filters: { user_id: userId },
@@ -135,6 +147,8 @@ function standardSearch(query, userId) {
 ```
 </CodeGroup>
 
+**What changes in the response:** both calls return the same fields on each memory (see the [Search Memories API reference](/api-reference/memory/search-memories) for the full response shape). The only difference is the *order* of the `results` array, the same effect shown in the [Reranking example above](#reranking): `quick_search` returns results ranked by raw similarity, `standard_search` returns the reranked order.
+
 ## Best Practices
 
 ### Do

docs/platform/features/custom-categories.mdx

@@ -75,7 +75,7 @@ print(response)
 ```
 </CodeGroup>
 
-This "Updated custom categories" message is specific to a PATCH-style partial update, which is what `client.project.update()` sends. Calling the raw API with a full PUT instead returns a generic `{"message": "Project updated successfully."}`, regardless of which fields changed.
+Treat the `message` string as informational. The project endpoint accepts `PATCH` only, and its documented response is the generic `{"message": "Project updated successfully"}`. Confirm an update by reading the field back, as in the next step, rather than by matching on the message.
 
 ### 2. Confirm the active catalog
 

docs/platform/features/custom-instructions.mdx

@@ -1,6 +1,7 @@
 ---
-title: Custom Instructions
-description: 'Guide Mem0 Platform memory extraction with natural language project-level instructions that decide what conversation details to store or ignore.'
+title: "Platform Custom Instructions"
+sidebarTitle: "Custom Instructions"
+description: 'Control how Mem0 extracts and stores memories using natural language guidelines'
 ---
 
 ## What are Custom Instructions?
@@ -95,6 +96,100 @@ Exclude:
 - [Irrelevant information]
 ```
 
+## Agent Custom Instructions
+
+`custom_instructions` applies to every memory your project extracts, no matter whose it is. But what is worth remembering about an agent is rarely what is worth remembering about a user: an agent's useful memories are things like which tools fail, which retry strategies work, and how a given environment behaves, not personal preferences.
+
+`agent_custom_instructions` is an optional second set of extraction rules that applies only to agent-scoped memories.
+
+Available from Python SDK `v2.0.17` and TypeScript SDK `v3.1.5`. Upgrade first if you are on an earlier release.
+
+Set it on the project alongside `custom_instructions`:
+
+<CodeGroup>
+```python Python
+client.project.update(
+    custom_instructions="Extract the user's preferences, goals, and constraints.",
+    agent_custom_instructions=(
+        "Extract operational lessons for the agent:\n"
+        "- Tools that failed and the error returned\n"
+        "- Retry or fallback strategies that worked\n"
+        "- Environment quirks worth recalling on the next run\n\n"
+        "Exclude: user preferences, personal details."
+    ),
+)
+```
+
+```javascript JavaScript
+await client.updateProject({
+  customInstructions: "Extract the user's preferences, goals, and constraints.",
+  agentCustomInstructions: `Extract operational lessons for the agent:
+- Tools that failed and the error returned
+- Retry or fallback strategies that worked
+- Environment quirks worth recalling on the next run
+
+Exclude: user preferences, personal details.`,
+});
+```
+</CodeGroup>
+
+### Which instructions apply
+
+Which set governs an `add()` call depends on the entity IDs you pass with it:
+
+| The add call passes | Instructions applied |
+|---------------------|----------------------|
+| `user_id` only | `custom_instructions` |
+| `agent_id` only | `agent_custom_instructions` |
+| `user_id` **and** `agent_id` | `agent_custom_instructions` govern the memories attributed to the assistant; `custom_instructions` govern the rest |
+
+`agent_custom_instructions` is unset by default. While it is unset, `custom_instructions` applies to every memory, so projects that don't set it behave exactly as they did before.
+
+### Overriding for a single call
+
+Both fields are also accepted per request, overriding the project setting for that `add()` only:
+
+<CodeGroup>
+```python Python
+client.add(
+    messages,
+    filters={"agent_id": "support-agent"},
+    agent_custom_instructions="Only remember which tools errored and why.",
+)
+```
+
+```javascript JavaScript
+await client.add(messages, {
+  agentId: "support-agent",
+  agentCustomInstructions: "Only remember which tools errored and why.",
+});
+```
+</CodeGroup>
+
+### Reading and clearing
+
+<CodeGroup>
+```python Python
+# Read the current value
+response = client.project.get(fields=["agent_custom_instructions"])
+print(response["agent_custom_instructions"])
+
+# Clear it; agent memories fall back to custom_instructions
+client.project.update(agent_custom_instructions="")
+```
+
+```javascript JavaScript
+// Read the current value
+const response = await client.getProject({
+  fields: ["agentCustomInstructions"],
+});
+console.log(response.agentCustomInstructions);
+
+// Clear it; agent memories fall back to customInstructions
+await client.updateProject({ agentCustomInstructions: "" });
+```
+</CodeGroup>
+
 ## Real-World Examples
 
 <Tabs>

docs/platform/features/dream.mdx

@@ -1,6 +1,6 @@
 ---
 title: Dream
-description: "Dream keeps Mem0 user memory sharp by distilling recurring patterns, retiring outdated facts, and merging duplicates in the background."
+description: "Dream keeps a user's memory clean over time by distilling recurring patterns, retiring outdated facts, and merging duplicates in the background."
 ---
 
 # Dream

docs/platform/features/memory-decay.mdx

@@ -64,7 +64,7 @@ client.project.update(decay=True)
 ```
 
 ```javascript JavaScript
-await client.project.update({ decay: true });
+await client.updateProject({ decay: true });
 ```
 
 ```bash cURL
@@ -75,32 +75,32 @@ curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PR
 ```
 
 ```json Response
-{ "message": "Updated decay" }
+{ "message": "Project updated successfully" }
 ```
 </CodeGroup>
 
 ### 2. Confirm the state
 
-`decay` is returned on every project read; there is currently no way to narrow the response to just this field, so read the full project object and pick out `decay`.
+`decay` is returned on every project read. To fetch only this field, use `?fields=decay`.
 
 <CodeGroup>
 ```python Python
-response = client.project.get()
+response = client.project.get(fields=["decay"])
 print(response["decay"])
 ```
 
 ```javascript JavaScript
-const response = await client.project.get();
+const response = await client.getProject({ fields: ["decay"] });
 console.log(response.decay);
 ```
 
 ```bash cURL
-curl "https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/" \
+curl "https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/?fields=decay" \
   -H "Authorization: Token $MEM0_API_KEY"
 ```
 
 ```json Response
-{ "decay": true, "...": "full project object" }
+{ "decay": true }
 ```
 </CodeGroup>
 
@@ -114,7 +114,7 @@ client.project.update(decay=False)
 ```
 
 ```javascript JavaScript
-await client.project.update({ decay: false });
+await client.updateProject({ decay: false });
 ```
 
 ```bash cURL

docs/platform/features/multimodal-support.mdx

@@ -1,6 +1,7 @@
 ---
-title: Multimodal Support
-description: Add images, PDFs, and other documents alongside text on the Mem0 Platform so agents can extract and recall insights from mixed visual content.
+title: "Platform Multimodal Support"
+sidebarTitle: "Multimodal Support"
+description: Integrate images and documents into your interactions with Mem0
 ---
 
 Mem0 extends its capabilities beyond text by supporting multimodal data, including images and documents. With this feature, users can seamlessly integrate visual and document content into their interactions, allowing Mem0 to extract relevant information from various media types and enrich the memory system.
@@ -76,18 +77,8 @@ await client.add(messages, { userId: "alice" })
 
 ```json Output
 {
-  "results": [
-    {
-      "memory": "Name is Alice",
-      "event": "ADD",
-      "id": "7ae113a3-3cb5-46e9-b6f7-486c36391847"
-    },
-    {
-      "memory": "Likes large pizza with toppings including cherry tomatoes, black olives, green spinach, yellow bell peppers, diced ham, and sliced mushrooms",
-      "event": "ADD",
-      "id": "56545065-7dee-4acf-8bf2-a5b2535aabb3"
-    }
-  ]
+  "event_id": "evt-uuid",
+  "status": "PENDING"
 }
 ```
 </CodeGroup>

docs/platform/features/timestamp.mdx

@@ -82,11 +82,11 @@ client.add(messages, { userId: "user1", timestamp: unixTimestamp })
 ```
 
 ```bash cURL
-curl -X POST "https://api.mem0.ai/v1/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'm travelling to SF"}],
+         "messages": [{"role": "user", "content": "Travelling to SF"}],
          "user_id": "user1",
          "timestamp": 1721577600
      }'
@@ -94,13 +94,8 @@ curl -X POST "https://api.mem0.ai/v1/memories/" \
 
 ```json Output
 {
-    "results": [
-        {
-            "id": "a1b2c3d4-e5f6-4g7h-8i9j-k0l1m2n3o4p5",
-            "data": {"memory": "Travelling to SF"},
-            "event": "ADD"
-        }
-    ]
+    "event_id": "evt-uuid",
+    "status": "PENDING"
 }
 ```
 

docs/platform/features/v2-memory-filters.mdx

@@ -29,6 +29,46 @@ Filters use a nested JSON structure with logical operators at the root:
 }
 ```
 
+A single bare condition needs no wrapper:
+
+```python
+# Works: one condition, no wrapper needed
+filters = {"user_id": "user_123"}
+```
+
+Sibling top-level keys in a flat object are accepted too: the API implicitly ANDs them, so the flat form and the explicit `AND` form are equivalent:
+
+```python
+# Works: sibling keys are implicitly ANDed
+filters = {
+    "user_id": "user_123",
+    "categories": {"in": ["finance"]}
+}
+
+# Equivalent, explicit form
+filters = {
+    "AND": [
+        {"user_id": "user_123"},
+        {"categories": {"in": ["finance"]}}
+    ]
+}
+```
+
+Reach for an explicit `AND`, `OR`, or `NOT` wrapper when you need `OR` or `NOT` semantics, or when you need to nest conditions. What the API does reject is an unrecognized top-level key:
+
+```python
+# Rejected: unknown top-level key
+filters = {"user_id": "user_123", "bogus_key": "z"}
+# 400: Top-level key must be a logical operator or an allowed field:
+# ['AND', 'OR', 'NOT', 'user_id', 'agent_id', 'app_id', 'run_id',
+#  'created_at', 'updated_at', 'timestamp', 'expiration_date', 'text',
+#  'categories', 'metadata', 'keywords_search', 'memory_ids', 'keywords']
+```
+
+<Callout type="info" icon="cloud" color="#00A8FF">
+Both the hosted Platform API and the self-hosted OSS SDK implicitly AND sibling top-level keys, so the flat and explicit `AND` forms behave the same way on either. The real differences: Platform validates each top-level key against a fixed allow-list and returns a 400 for anything else, and Platform has no `nin` operator. See [Enhanced Metadata Filtering](/open-source/features/metadata-filtering) for the OSS grammar.
+</Callout>
+
 ## Available fields and operators
 
 ### Entity fields
@@ -42,14 +82,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"}}` |
 
@@ -66,6 +107,14 @@ The `*` wildcard matches any non-null value. Records with null values for that f
 Use operator keywords exactly as shown (`eq`, `ne`, `gte`, etc.). SQL-style symbols such as `>=` or `!=` are rejected by the Platform API.
 </Callout>
 
+<Callout type="warning" icon="exclamation-triangle" color="#E74C3C">
+There is no `nin` ("not in") operator on Platform. It is an OSS-only operator; see [Enhanced Metadata Filtering](/open-source/features/metadata-filtering). To exclude a set of values on Platform, wrap an `in` clause in `NOT`:
+
+```python
+{"NOT": {"categories": {"in": ["spam", "test"]}}}
+```
+</Callout>
+
 ## Common filter patterns
 
 Use these ready-made filters to target typical retrieval scenarios without rebuilding logic from scratch.
@@ -328,7 +377,7 @@ Level up foundational patterns with compound filters that coordinate entity scop
 ## Best practices
 
 <Callout type="tip" icon="lightbulb" color="#26A17B">
-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.
 </Callout>
 
 <Callout type="tip" icon="lightbulb" color="#26A17B">
@@ -392,7 +441,7 @@ A filter object with both an `AND` key and a sibling `OR` key at the same level
 
 <AccordionGroup>
   <Accordion title="Do I need AND/OR/NOT?">
-    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.
   </Accordion>
 
   <Accordion title="What does * match?">
@@ -421,8 +470,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"]}}
             ]}
         ]
     }

docs/platform/mem0-mcp.mdx

@@ -7,8 +7,8 @@ estimatedTime: "~2 minutes"
 
 <Info>
   **Prerequisites**
-  - Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Sign up here</a>)
-  - API key (<a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Get one from dashboard</a>)
+  - Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-mem0-mcp">Sign up here</a>)
+  - API key (<a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp">Get one from dashboard</a>)
   - Node.js 18+ (for npx)
   - An MCP-compatible client (Claude, Claude Code, Codex, Cursor, Windsurf, VS Code, OpenCode)
 </Info>
@@ -28,11 +28,15 @@ npx mcp-add \
   --name mem0-mcp \
   --type http \
   --url "https://mcp.mem0.ai/mcp" \
-  --clients "claude,claude code,cursor,windsurf,vscode,opencode"
+  --clients "claude code,cursor,windsurf,vscode,opencode"
 ```
 
 `mcp-add` is a helper that writes the Mem0 server into each client's own MCP config file, so you do not have to edit them by hand. Name only the clients you actually use. If you would rather see the change yourself, every client's manual config is under [Client-specific setup](#client-specific-setup).
 
+<Note>
+  Claude Desktop is not in the list above: it rejects the `mcp-add` command. Add it through Settings instead, see [Claude Desktop](#client-specific-setup) below.
+</Note>
+
 Restart each client afterwards so it picks up the new server.
 
 ## Signing in
@@ -49,7 +53,7 @@ The server is authenticated, so connecting is not enough on its own. There are t
   <Tab title="Use your API key">
     For clients without browser sign-in, or for headless environments like CI, send your API key as a bearer token instead. Where you put it depends on the client; see [Client-specific setup](#client-specific-setup) for the exact syntax.
 
-    Get a key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a>, and keep it out of any file you commit.
+    Get a key from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp">Mem0 dashboard</a>, and keep it out of any file you commit.
   </Tab>
 </Tabs>
 
@@ -81,25 +85,14 @@ You can also configure individual clients:
 
 <AccordionGroup>
   <Accordion title="Claude Desktop">
-    ```bash
-    npx mcp-add \
-      --name mem0-mcp \
-      --type http \
-      --url "https://mcp.mem0.ai/mcp" \
-      --clients "claude"
-    ```
+    Claude Desktop does not support the `mcp-add` command, it rejects the server as "not a valid MCP server." Add the Mem0 server through the Settings UI instead:
 
-    Or manually add to your Claude Desktop configuration (`claude_desktop_config.json`):
-    ```json
-    {
-      "mcpServers": {
-        "mem0-mcp": {
-          "type": "http",
-          "url": "https://mcp.mem0.ai/mcp"
-        }
-      }
-    }
-    ```
+    1. Open Claude Desktop and go to **Settings > Connectors**.
+    2. Click **Add custom connector**.
+    3. Enter a name (for example `mem0-mcp`) and the URL `https://mcp.mem0.ai/mcp`.
+    4. Save, then restart Claude Desktop.
+
+    The first time you use a Mem0 tool, Claude Desktop opens a browser window to sign in, see [Signing in](#signing-in).
   </Accordion>
 
   <Accordion title="Claude Code">
@@ -213,7 +206,7 @@ Two things to look for while you do it:
 - Your client should show the Mem0 tools among its available tools. Most clients list them in a tools or MCP panel.
 - The first tool call should trigger the browser sign-in described above, unless you configured an API key.
 
-To confirm from outside the client, open the <a href="https://app.mem0.ai/dashboard?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a>: anything the agent saved appears there.
+To confirm from outside the client, open the <a href="https://app.mem0.ai/dashboard?utm_source=oss&utm_medium=platform-mem0-mcp">Mem0 dashboard</a>: anything the agent saved appears there.
 
 ---
 
@@ -225,7 +218,7 @@ To confirm from outside the client, open the <a href="https://app.mem0.ai/dashbo
 | "Connection refused" or "failed to connect" | The client cannot reach the server | Check your internet connection, then confirm the URL is exactly `https://mcp.mem0.ai/mcp` |
 | The agent has no Mem0 tools | The config was written but the client has not reloaded it | Restart the client. If the tools are still missing, check that `mcp-add` wrote to the config file your client actually reads |
 | `npx: command not found` | Node.js is not installed | Install it from [nodejs.org](https://nodejs.org) |
-| "Invalid API key" | The key is wrong, revoked, or from a different account | Get a new one from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Mem0 dashboard</a> |
+| "Invalid API key" | The key is wrong, revoked, or from a different account | Get a new one from the <a href="https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp">Mem0 dashboard</a> |
 
 ---
 

docs/platform/overview.mdx

@@ -1,6 +1,7 @@
 ---
-title: "Overview"
-description: "Mem0 Platform is the fully managed memory layer for AI agents and chat apps, adding personalized long-term context in minutes with no infrastructure."
+title: "Platform Overview"
+sidebarTitle: "Overview"
+description: "Managed memory layer for AI agents, production-ready in minutes"
 icon: "cloud"
 ---
 

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.
 
 <CardGroup cols={2}>
   <Card
@@ -16,7 +16,7 @@ Mem0 offers two powerful ways to add memory to your AI applications. Choose base
   >
     **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.
   </Card>
 
   <Card
@@ -32,89 +32,85 @@ Mem0 offers two powerful ways to add memory to your AI applications. Choose base
 
 ---
 
-## Feature Comparison
+## What's the same
+
+The core memory loop is identical on both: `add`, `search`, `get`, `get_all`, `update`, `delete`, `delete_all`, and per-memory `history` all exist on the self-hosted `Memory`/`AsyncMemory` classes and on the hosted `MemoryClient`/`AsyncMemoryClient`. Both support:
+
+- **Entity scoping** by `user_id`, `agent_id`, and `run_id`
+- **Filter grouping**: both accept `AND`/`OR`/`NOT` wrappers, both implicitly AND a flat multi-key filter like `{"user_id": "alice", "agent_id": "a1"}`, and both accept `*` as a wildcard value. Which fields you may filter on, and which operators each field accepts, differ (see below)
+- **Entity-aware ranking**: both extract entities from memory text and use shared entities to boost related results at search time
+- **Multimodal input**, **memory expiration** (`expiration_date`), **reranking**, **procedural memory** (Python), and **custom extraction instructions** (`custom_instructions`)
+- Python and JavaScript SDKs, plus a REST API (self-hosted via `server/`, or hosted)
+
+## What's actually different
 
 <AccordionGroup>
-  <Accordion title="Setup & Getting Started" icon="rocket">
+  <Accordion title="Hosting & infrastructure" icon="server">
     | 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 |
   </Accordion>
 
-  <Accordion title="Core Memory Features" icon="brain">
+  <Accordion title="Entity scoping & workspace structure" icon="layer-group">
     | 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.
   </Accordion>
 
-  <Accordion title="Advanced Capabilities" icon="sparkles">
+  <Accordion title="Search-time ranking (v3-only)" icon="sparkles">
     | 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 |
   </Accordion>
 
-  <Accordion title="Infrastructure & Scaling" icon="server">
+  <Accordion title="Configuration & data operations" icon="sliders">
     | 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)) |
   </Accordion>
 
-  <Accordion title="Pricing & Cost" icon="dollar-sign">
-    | 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 |
-  </Accordion>
-
-  <Accordion title="Development & Integration" icon="code">
-    | Feature | Platform | Open Source |
+  <Accordion title="Support" icon="life-ring">
+    | 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.
   </Accordion>
 </AccordionGroup>
 
+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.
 
 ---
 

docs/platform/quickstart.mdx

@@ -13,8 +13,8 @@ In about five minutes you will get an API key, store your first memory, and sear
 
 ## Prerequisites
 
-- Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-quickstart" rel="nofollow">Sign up here</a>)
-- API key (<a href="https://app.mem0.ai/dashboard/settings?tab=api-keys&subtab=configuration" rel="nofollow">Get one from dashboard</a>)
+- Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-quickstart">Sign up here</a>)
+- API key (<a href="https://app.mem0.ai/dashboard/settings?tab=api-keys&subtab=configuration">Get one from dashboard</a>)
 - Python 3.10+, Node.js 18+, or cURL. The CLI needs either Node.js 18+ or Python 3.10+.
 
 ## Store your first memory