Merge remote-tracking branch 'origin/main' into HEAD

docs/platform/cli.mdx

@@ -143,6 +143,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 +156,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 +472,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/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