chore(release): bump SDK, CLI, and plugin versions (#6800)

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./integrations/mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
-      "version": "0.2.13"
+      "version": "0.2.14"
     }
   ]
 }

.cursor-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./integrations/mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
-      "version": "0.2.13"
+      "version": "0.2.14"
     }
   ]
 }

.github/workflows/ci-gate.yml

@@ -38,6 +38,7 @@ jobs:
       cli_python: ${{ steps.filter.outputs.cli_python }}
       cli_node: ${{ steps.filter.outputs.cli_node }}
       openclaw: ${{ steps.filter.outputs.openclaw }}
+      mem0_plugin: ${{ steps.filter.outputs.mem0_plugin }}
       opencode_plugin: ${{ steps.filter.outputs.opencode_plugin }}
       pi_agent_plugin: ${{ steps.filter.outputs.pi_agent_plugin }}
       n8n_nodes_mem0: ${{ steps.filter.outputs.n8n_nodes_mem0 }}
@@ -73,6 +74,11 @@ jobs:
               - 'integrations/openclaw/**'
               - '.github/workflows/openclaw-checks.yml'
               - '.github/workflows/ci-gate.yml'
+            mem0_plugin:
+              - 'integrations/mem0-plugin/**'
+              - '!integrations/mem0-plugin/.opencode-plugin/**'
+              - '.github/workflows/mem0-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
             opencode_plugin:
               - 'integrations/mem0-plugin/.opencode-plugin/**'
               - '.github/workflows/opencode-plugin-checks.yml'
@@ -131,6 +137,13 @@ jobs:
     uses: ./.github/workflows/openclaw-checks.yml
     secrets: inherit
 
+  mem0-plugin:
+    name: Mem0 Plugin
+    needs: changes
+    if: needs.changes.outputs.mem0_plugin == 'true'
+    uses: ./.github/workflows/mem0-plugin-checks.yml
+    secrets: inherit
+
   opencode-plugin:
     name: OpenCode Plugin
     needs: changes
@@ -173,6 +186,7 @@ jobs:
       - cli-python
       - cli-node
       - openclaw
+      - mem0-plugin
       - opencode-plugin
       - pi-agent-plugin
       - n8n-nodes-mem0

.github/workflows/mem0-plugin-checks.yml

@@ -0,0 +1,58 @@
+name: Mem0 Plugin Checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+#
+# Covers the Python plugin (scripts/ + tests/). The nested .opencode-plugin/
+# is a separate package with its own workflow (opencode-plugin-checks.yml).
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/mem0-plugin/**'
+      - '!integrations/mem0-plugin/.opencode-plugin/**'
+      - '.github/workflows/mem0-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        working-directory: integrations/mem0-plugin
+        run: |
+          pip install -r requirements.txt
+          pip install pytest
+
+      - name: Verify hook entry points are executable
+        working-directory: integrations/mem0-plugin
+        run: |
+          missing=$(find scripts -name '*.sh' ! -name '_*' ! -perm -u+x -print)
+          if [ -n "$missing" ]; then
+            echo "Hook entry points must be executable:"
+            echo "$missing"
+            exit 1
+          fi
+
+      - name: Check hook manifests are valid JSON
+        working-directory: integrations/mem0-plugin
+        run: |
+          for f in plugin.json mcp_config.json hooks.json hooks/*.json; do
+            jq empty "$f" || (echo "Invalid JSON: $f" && exit 1)
+          done
+
+      - name: Run tests
+        working-directory: integrations/mem0-plugin
+        run: pytest -q

AGENTS.md

@@ -406,6 +406,7 @@ PR testing is orchestrated by a single entry point: **`ci-gate.yml` (CI Gate)**
 | Python CLI | `cli-python-ci.yml` | Push to main (on `cli/python/`), manual | Ruff lint + pytest + hatch build on Python 3.10, 3.11, 3.12 |
 | Node CLI | `cli-node-ci.yml` | Push to main (on `cli/node/`), manual | Biome lint + tsc + vitest + tsup build on Node 20, 22 |
 | OpenClaw | `openclaw-checks.yml` | Push to main (on `integrations/openclaw/`), manual | tsc + vitest (with Codecov) + tsup build on Node 20, 22 |
+| Mem0 Plugin | `mem0-plugin-checks.yml` | Push to main (on `integrations/mem0-plugin/`, excluding `.opencode-plugin/`), manual | pytest + hook entry-point exec bits + JSON manifest validation on Python 3.10, 3.11, 3.12 |
 | OpenCode Plugin | `opencode-plugin-checks.yml` | Push to main (on `integrations/mem0-plugin/.opencode-plugin/`), manual | Bun: tsc type-check + build + dist artifact check |
 | Pi Agent Plugin | `pi-agent-plugin-checks.yml` | Push to main (on `integrations/pi-agent-plugin/`), manual | tsc + vitest + tsup build (dist artifact check) on Node 20, 22 |
 | n8n Node | `n8n-nodes-mem0-checks.yml` | Push to main (on `integrations/n8n-nodes-mem0/`), manual | ESLint (n8n-nodes-base) + tsc build (dist artifact check) on Node 20 |

cli/README.md

@@ -60,9 +60,8 @@ mem0 delete <memory-id>
 | `mem0 entity` | List or delete entities (users, agents, apps, runs) |
 | `mem0 event` | Inspect background processing events (bulk deletes, large add jobs) |
 | `mem0 status` | Verify API connection and display current project |
-| `mem0 version` | Print the CLI version |
 
-Run `mem0 <command> --help` for detailed usage on any command.
+Run `mem0 <command> --help` for detailed usage on any command, or `mem0 --version` to print the CLI version.
 
 ## Agent mode
 

cli/cli-spec.json

@@ -207,7 +207,11 @@
         { "name": "immutable", "flags": ["--immutable"], "type": "boolean", "default": false, "help": "Prevent future updates." },
         { "name": "no_infer", "flags": ["--no-infer"], "type": "boolean", "default": false, "help": "Skip inference, store raw." },
         { "name": "expires", "flags": ["--expires"], "type": "string", "help": "Expiration date (YYYY-MM-DD)." },
-        { "name": "categories", "flags": ["--categories"], "type": "string", "help": "Categories (JSON array or comma-separated)." },
+        { "name": "categories", "flags": ["--categories"], "type": "string", "help": "Not supported on add, use --custom-categories instead." },
+        { "name": "custom_instructions", "flags": ["--custom-instructions"], "type": "string", "help": "Custom instructions for fact extraction." },
+        { "name": "custom_categories", "flags": ["--custom-categories"], "type": "string", "help": "Custom categories as a JSON array of {name: description} objects." },
+        { "name": "structured_data_schema", "flags": ["--structured-data-schema"], "type": "string", "help": "Schema for structured data extraction, as JSON." },
+        { "name": "timestamp", "flags": ["--timestamp"], "type": "integer", "help": "Unix timestamp for the memory." },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph memory extraction.", "panel": "Scope" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph memory extraction.", "panel": "Scope" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output format: text, json, quiet.", "panel": "Output" }
@@ -244,6 +248,9 @@
         { "name": "keyword", "flags": ["--keyword"], "type": "boolean", "default": false, "help": "Use keyword search.", "panel": "Search" },
         { "name": "filter_json", "flags": ["--filter"], "type": "string", "help": "Advanced filter expression (JSON).", "panel": "Search" },
         { "name": "fields", "flags": ["--fields"], "type": "string", "help": "Specific fields to return (comma-separated).", "panel": "Search" },
+        { "name": "show_expired", "flags": ["--show-expired"], "type": "boolean", "default": false, "help": "Include expired memories.", "panel": "Search" },
+        { "name": "reference_date", "flags": ["--reference-date"], "type": "string", "help": "Reference date for relative queries (YYYY-MM-DD or unix timestamp).", "panel": "Search" },
+        { "name": "latest_only", "flags": ["--latest-only"], "type": "boolean", "default": false, "help": "Only return the latest version of each memory.", "panel": "Search" },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in search.", "panel": "Search" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in search.", "panel": "Search" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, table.", "panel": "Output" }
@@ -296,6 +303,8 @@
         { "name": "category", "flags": ["--category"], "type": "string", "help": "Filter by category.", "panel": "Filters" },
         { "name": "after", "flags": ["--after"], "type": "string", "help": "Created after (YYYY-MM-DD).", "panel": "Filters" },
         { "name": "before", "flags": ["--before"], "type": "string", "help": "Created before (YYYY-MM-DD).", "panel": "Filters" },
+        { "name": "show_expired", "flags": ["--show-expired"], "type": "boolean", "default": false, "help": "Include expired memories.", "panel": "Filters" },
+        { "name": "latest_only", "flags": ["--latest-only"], "type": "boolean", "default": false, "help": "Only return the latest version of each memory.", "panel": "Filters" },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in listing.", "panel": "Filters" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in listing.", "panel": "Filters" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "table", "help": "Output: text, json, table.", "panel": "Output" }
@@ -329,6 +338,8 @@
       ],
       "options": [
         { "name": "metadata", "flags": ["--metadata", "-m"], "type": "string", "help": "Update metadata (JSON)." },
+        { "name": "expires", "flags": ["--expires"], "type": "string", "help": "Expiration date (YYYY-MM-DD)." },
+        { "name": "timestamp", "flags": ["--timestamp"], "type": "integer", "help": "Unix timestamp for the memory." },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
       ],
       "apiEndpoint": "update"
@@ -356,6 +367,7 @@
         { "name": "all", "flags": ["--all"], "type": "boolean", "default": false, "help": "Delete all memories matching scope filters." },
         { "name": "entity", "flags": ["--entity"], "type": "boolean", "default": false, "help": "Delete the entity itself and all its memories (cascade)." },
         { "name": "project", "flags": ["--project"], "type": "boolean", "default": false, "help": "With --all: delete ALL memories project-wide." },
+        { "name": "delete_linked", "flags": ["--delete-linked"], "type": "boolean", "default": false, "help": "Also delete memories linked to this memory." },
         { "name": "dry_run", "flags": ["--dry-run"], "type": "boolean", "default": false, "help": "Show what would be deleted without deleting." },
         { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Skip confirmation." },
         { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Scope to user.", "panel": "Scope" },

cli/node/README.md

@@ -232,14 +232,6 @@ Verify your API connection and display the current project.
 mem0 status
 ```
 
-### `mem0 version`
-
-Print the CLI version.
-
-```bash
-mem0 version
-```
-
 ## Agent mode
 
 Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
@@ -298,6 +290,8 @@ These flags are available on all commands:
 | `--base-url` | Override the configured API base URL for this request |
 | `-o, --output` | Set the output format |
 
+`mem0 --version` prints the CLI version. It is only valid before a subcommand, not after one.
+
 ## Environment variables
 
 | Variable | Description |

cli/node/development.md

@@ -51,7 +51,7 @@ pnpm link --global
 
 # Now use it like a normal CLI
 mem0 --help
-mem0 version
+mem0 --version
 ```
 
 > **Warning:** If you also have the Python CLI installed, both register the `mem0` command. The last one linked/installed wins. Unlink with `pnpm unlink --global`.

cli/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/cli",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "The official CLI for mem0 — the memory layer for AI agents",
   "type": "module",
   "bin": {

cli/node/src/backend/base.ts

@@ -14,7 +14,10 @@ export interface AddOptions {
 	immutable?: boolean;
 	infer?: boolean;
 	expires?: string;
-	categories?: string[];
+	customInstructions?: string;
+	customCategories?: Record<string, string>[];
+	structuredDataSchema?: Record<string, unknown>;
+	timestamp?: number;
 }
 
 export interface SearchOptions {
@@ -28,6 +31,9 @@ export interface SearchOptions {
 	keyword?: boolean;
 	filters?: Record<string, unknown>;
 	fields?: string[];
+	showExpired?: boolean;
+	referenceDate?: string | number;
+	latestOnly?: boolean;
 }
 
 export interface ListOptions {
@@ -40,6 +46,8 @@ export interface ListOptions {
 	category?: string;
 	after?: string;
 	before?: string;
+	showExpired?: boolean;
+	latestOnly?: boolean;
 }
 
 export interface DeleteOptions {
@@ -48,6 +56,12 @@ export interface DeleteOptions {
 	agentId?: string;
 	appId?: string;
 	runId?: string;
+	deleteLinked?: boolean;
+}
+
+export interface UpdateOptions {
+	expirationDate?: string;
+	timestamp?: number;
 }
 
 export interface EntityIds {
@@ -77,6 +91,7 @@ export interface Backend {
 		memoryId: string,
 		content?: string,
 		metadata?: Record<string, unknown>,
+		opts?: UpdateOptions,
 	): Promise<Record<string, unknown>>;
 
 	delete(

cli/node/src/backend/platform.ts

@@ -15,6 +15,7 @@ import {
 	type ListOptions,
 	NotFoundError,
 	type SearchOptions,
+	type UpdateOptions,
 } from "./base.js";
 
 function encodePathSegment(value: unknown): string {
@@ -150,7 +151,13 @@ export class PlatformBackend implements Backend {
 		if (opts.immutable) payload.immutable = true;
 		if (opts.infer === false) payload.infer = false;
 		if (opts.expires) payload.expiration_date = opts.expires;
-		if (opts.categories) payload.categories = opts.categories;
+		if (opts.customInstructions)
+			payload.custom_instructions = opts.customInstructions;
+		if (opts.customCategories)
+			payload.custom_categories = opts.customCategories;
+		if (opts.structuredDataSchema)
+			payload.structured_data_schema = opts.structuredDataSchema;
+		if (opts.timestamp !== undefined) payload.timestamp = opts.timestamp;
 		payload.source = "CLI";
 
 		return (await this._request("POST", "/v3/memories/add/", {
@@ -211,6 +218,10 @@ export class PlatformBackend implements Backend {
 		if (opts.rerank) payload.rerank = true;
 		if (opts.keyword) payload.keyword_search = true;
 		if (opts.fields) payload.fields = opts.fields;
+		if (opts.showExpired) payload.show_expired = true;
+		if (opts.referenceDate !== undefined)
+			payload.reference_date = opts.referenceDate;
+		if (opts.latestOnly) payload.latest_only = true;
 		payload.source = "CLI";
 
 		const result = (await this._request("POST", "/v3/memories/search/", {
@@ -265,6 +276,8 @@ export class PlatformBackend implements Backend {
 			extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
 		});
 		if (apiFilters) payload.filters = apiFilters;
+		if (opts.showExpired) payload.show_expired = true;
+		if (opts.latestOnly) payload.latest_only = true;
 		payload.source = "CLI";
 
 		const result = (await this._request("POST", "/v3/memories/", {
@@ -280,10 +293,13 @@ export class PlatformBackend implements Backend {
 		memoryId: string,
 		content?: string,
 		metadata?: Record<string, unknown>,
+		opts: UpdateOptions = {},
 	): Promise<Record<string, unknown>> {
 		const payload: Record<string, unknown> = {};
 		if (content) payload.text = content;
 		if (metadata) payload.metadata = metadata;
+		if (opts.expirationDate) payload.expiration_date = opts.expirationDate;
+		if (opts.timestamp !== undefined) payload.timestamp = opts.timestamp;
 		payload.source = "CLI";
 		return (await this._request(
 			"PUT",
@@ -309,12 +325,12 @@ export class PlatformBackend implements Backend {
 			})) as Record<string, unknown>;
 		}
 		if (memoryId) {
+			const params: Record<string, string> = { source: "CLI" };
+			if (opts.deleteLinked) params.delete_linked = "true";
 			return (await this._request(
 				"DELETE",
 				`/v1/memories/${encodePathSegment(memoryId)}/`,
-				{
-					params: { source: "CLI" },
-				},
+				{ params },
 			)) as Record<string, unknown>;
 		}
 		throw new Error("Either memoryId or --all is required");

cli/node/src/commands/memory.ts

@@ -21,16 +21,19 @@ import {
 	formatSingleMemory,
 	printResultSummary,
 } from "../output.js";
-import { isAgentMode, setCurrentCommand } from "../state.js";
+import { isAgentMode, setCurrentCommand, stdinIsPiped } from "../state.js";
 
-/** True only when stdin is an actual pipe or file redirect — never in agent mode. */
-function _stdinIsPiped(): boolean {
-	if (isAgentMode()) return false;
-	try {
-		const stat = fs.fstatSync(0);
-		return stat.isFIFO() || stat.isFile();
-	} catch {
-		return false;
+/** Exit 1 if value is not a future YYYY-MM-DD date. */
+function _validateExpires(value: string): void {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+		printError(
+			"Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31).",
+		);
+		process.exit(1);
+	}
+	if (new Date(value) <= new Date()) {
+		printError("--expires date must be in the future.");
+		process.exit(1);
 	}
 }
 
@@ -49,10 +52,22 @@ export async function cmdAdd(
 		infer?: boolean;
 		expires?: string;
 		categories?: string;
+		customInstructions?: string;
+		customCategories?: string;
+		structuredDataSchema?: string;
+		timestamp?: number;
 		output: string;
 	},
 ): Promise<void> {
 	setCurrentCommand("add");
+
+	if (opts.categories) {
+		printError(
+			"--categories is not supported on add. Use --custom-categories instead.",
+		);
+		process.exit(1);
+	}
+
 	let msgs: Record<string, unknown>[] | undefined;
 	let content = text;
 
@@ -78,7 +93,7 @@ export async function cmdAdd(
 		}
 	}
 	// Read from stdin only if stdin is an actual pipe or file redirect
-	else if (!content && _stdinIsPiped()) {
+	else if (!content && stdinIsPiped()) {
 		content = fs.readFileSync(0, "utf-8").trim();
 	}
 
@@ -93,20 +108,6 @@ export async function cmdAdd(
 		process.exit(1);
 	}
 
-	// Validate --expires
-	if (opts.expires) {
-		if (!/^\d{4}-\d{2}-\d{2}$/.test(opts.expires)) {
-			printError(
-				"Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31).",
-			);
-			process.exit(1);
-		}
-		if (new Date(opts.expires) <= new Date()) {
-			printError("--expires date must be in the future.");
-			process.exit(1);
-		}
-	}
-
 	let meta: Record<string, unknown> | undefined;
 	if (opts.metadata) {
 		try {
@@ -117,15 +118,28 @@ export async function cmdAdd(
 		}
 	}
 
-	let cats: string[] | undefined;
-	if (opts.categories) {
+	let customCats: Record<string, string>[] | undefined;
+	if (opts.customCategories) {
 		try {
-			cats = JSON.parse(opts.categories);
+			customCats = JSON.parse(opts.customCategories);
 		} catch {
-			cats = opts.categories.split(",").map((c) => c.trim());
+			printError("Invalid JSON in --custom-categories.");
+			process.exit(1);
 		}
 	}
 
+	let schema: Record<string, unknown> | undefined;
+	if (opts.structuredDataSchema) {
+		try {
+			schema = JSON.parse(opts.structuredDataSchema);
+		} catch {
+			printError("Invalid JSON in --structured-data-schema.");
+			process.exit(1);
+		}
+	}
+
+	if (opts.expires) _validateExpires(opts.expires);
+
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Adding memory...", async () => {
@@ -138,7 +152,10 @@ export async function cmdAdd(
 				immutable: opts.immutable,
 				infer: opts.infer !== false,
 				expires: opts.expires,
-				categories: cats,
+				customInstructions: opts.customInstructions,
+				customCategories: customCats,
+				structuredDataSchema: schema,
+				timestamp: opts.timestamp,
 			});
 		});
 	} catch (e) {
@@ -223,6 +240,9 @@ export async function cmdSearch(
 		keyword: boolean;
 		filterJson?: string;
 		fields?: string;
+		showExpired?: boolean;
+		referenceDate?: string;
+		latestOnly?: boolean;
 		output: string;
 	},
 ): Promise<void> {
@@ -271,6 +291,9 @@ export async function cmdSearch(
 				keyword: opts.keyword,
 				filters,
 				fields: fieldList,
+				showExpired: opts.showExpired,
+				referenceDate: opts.referenceDate,
+				latestOnly: opts.latestOnly,
 			});
 		});
 	} catch (e) {
@@ -364,6 +387,8 @@ export async function cmdList(
 		category?: string;
 		after?: string;
 		before?: string;
+		showExpired?: boolean;
+		latestOnly?: boolean;
 		output: string;
 	},
 ): Promise<void> {
@@ -391,6 +416,8 @@ export async function cmdList(
 				category: opts.category,
 				after: opts.after,
 				before: opts.before,
+				showExpired: opts.showExpired,
+				latestOnly: opts.latestOnly,
 			});
 		});
 	} catch (e) {
@@ -450,7 +477,12 @@ export async function cmdUpdate(
 	backend: Backend,
 	memoryId: string,
 	text: string | undefined,
-	opts: { metadata?: string; output: string },
+	opts: {
+		metadata?: string;
+		expires?: string;
+		timestamp?: number;
+		output: string;
+	},
 ): Promise<void> {
 	setCurrentCommand("update");
 	let meta: Record<string, unknown> | undefined;
@@ -463,11 +495,16 @@ export async function cmdUpdate(
 		}
 	}
 
+	if (opts.expires) _validateExpires(opts.expires);
+
 	const start = performance.now();
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Updating memory...", async () => {
-			return backend.update(memoryId, text, meta);
+			return backend.update(memoryId, text, meta, {
+				expirationDate: opts.expires,
+				timestamp: opts.timestamp,
+			});
 		});
 	} catch (e) {
 		printError(e instanceof Error ? e.message : String(e));
@@ -493,7 +530,12 @@ export async function cmdUpdate(
 export async function cmdDelete(
 	backend: Backend,
 	memoryId: string,
-	opts: { output: string; dryRun?: boolean; force?: boolean },
+	opts: {
+		output: string;
+		dryRun?: boolean;
+		force?: boolean;
+		deleteLinked?: boolean;
+	},
 ): Promise<void> {
 	setCurrentCommand("delete");
 	if (opts.dryRun) {
@@ -514,7 +556,7 @@ export async function cmdDelete(
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Deleting...", async () => {
-			return backend.delete(memoryId);
+			return backend.delete(memoryId, { deleteLinked: opts.deleteLinked });
 		});
 	} catch (e) {
 		printError(e instanceof Error ? e.message : String(e));

cli/node/src/commands/utils.ts

@@ -1,5 +1,5 @@
 /**
- * Utility commands: status, version, import.
+ * Utility commands: status, import.
  */
 
 import fs from "node:fs";
@@ -8,7 +8,6 @@ import type { Backend } from "../backend/base.js";
 import { colors, printError, printSuccess, timedStatus } from "../branding.js";
 import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
 import { setCurrentCommand } from "../state.js";
-import { CLI_VERSION } from "../version.js";
 
 const { brand, dim, success, error: errorColor } = colors;
 
@@ -82,10 +81,6 @@ export async function cmdStatus(
 	console.log();
 }
 
-export function cmdVersion(): void {
-	console.log(`  ${brand("◆ Mem0")} CLI v${CLI_VERSION}`);
-}
-
 export async function cmdImport(
 	backend: Backend,
 	filePath: string,

cli/node/src/index.ts

@@ -17,6 +17,7 @@ import {
 	isAgentMode,
 	setAgentMode,
 	setCurrentCommand,
+	stdinIsPiped,
 	takeNotice,
 } from "./state.js";
 import { captureEvent } from "./telemetry.js";
@@ -319,7 +320,25 @@ program
 	.option("--immutable", "Prevent future updates.", false)
 	.option("--no-infer", "Skip inference, store raw.")
 	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
-	.option("--categories <value>", "Categories (JSON array or comma-separated).")
+	.option(
+		"--categories <value>",
+		"Not supported on add, use --custom-categories instead.",
+	)
+	.option(
+		"--custom-instructions <text>",
+		"Custom instructions for fact extraction.",
+	)
+	.option(
+		"--custom-categories <json>",
+		"Custom categories as a JSON array of {name: description} objects.",
+	)
+	.option(
+		"--structured-data-schema <json>",
+		"Schema for structured data extraction, as JSON.",
+	)
+	.option("--timestamp <unix>", "Unix timestamp for the memory.", (v) =>
+		Number.parseInt(v),
+	)
 	.option("-o, --output <format>", "Output format: text, json, quiet.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -366,6 +385,16 @@ program
 	.option("--keyword", "Use keyword search.", false)
 	.option("--filter <json>", "Advanced filter expression (JSON).")
 	.option("--fields <list>", "Specific fields to return (comma-separated).")
+	.option("--show-expired", "Include expired memories.", false)
+	.option(
+		"--reference-date <date>",
+		"Reference date for relative queries (YYYY-MM-DD or unix timestamp).",
+	)
+	.option(
+		"--latest-only",
+		"Only return the latest version of each memory.",
+		false,
+	)
 	.option("-o, --output <format>", "Output: text, json, table.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -375,7 +404,7 @@ program
 	)
 	.action(async (query, opts) => {
 		let resolvedQuery = query;
-		if (!resolvedQuery && !process.stdin.isTTY) {
+		if (!resolvedQuery && stdinIsPiped()) {
 			resolvedQuery = fs.readFileSync(0, "utf-8").trim();
 		}
 		if (!resolvedQuery) {
@@ -398,6 +427,9 @@ program
 			keyword: opts.keyword,
 			filterJson: opts.filter,
 			fields: opts.fields,
+			showExpired: opts.showExpired,
+			referenceDate: opts.referenceDate,
+			latestOnly: opts.latestOnly,
 			output,
 		});
 	});
@@ -441,6 +473,12 @@ program
 	.option("--category <name>", "Filter by category.")
 	.option("--after <date>", "Created after (YYYY-MM-DD).")
 	.option("--before <date>", "Created before (YYYY-MM-DD).")
+	.option("--show-expired", "Include expired memories.", false)
+	.option(
+		"--latest-only",
+		"Only return the latest version of each memory.",
+		false,
+	)
 	.option("-o, --output <format>", "Output: text, json, table.", "table")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -464,6 +502,8 @@ program
 			category: opts.category,
 			after: opts.after,
 			before: opts.before,
+			showExpired: opts.showExpired,
+			latestOnly: opts.latestOnly,
 			output,
 		});
 	});
@@ -474,6 +514,10 @@ program
 	.command("update <memoryId> [text]")
 	.description("Update a memory's text or metadata.")
 	.option("-m, --metadata <json>", "Update metadata (JSON).")
+	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
+	.option("--timestamp <unix>", "Unix timestamp for the memory.", (v) =>
+		Number.parseInt(v),
+	)
 	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -483,7 +527,7 @@ program
 	)
 	.action(async (memoryId, text, opts) => {
 		let resolvedText = text;
-		if (!resolvedText && !opts.metadata && !process.stdin.isTTY) {
+		if (!resolvedText && stdinIsPiped()) {
 			resolvedText = fs.readFileSync(0, "utf-8").trim();
 		}
 		const { cmdUpdate } = await import("./commands/memory.js");
@@ -492,6 +536,8 @@ program
 		const output = isAgent ? "agent" : opts.output;
 		await cmdUpdate(backend, memoryId, resolvedText, {
 			metadata: opts.metadata,
+			expires: opts.expires,
+			timestamp: opts.timestamp,
 			output,
 		});
 	});
@@ -510,6 +556,11 @@ program
 	.option("--project", "With --all: delete ALL memories project-wide.", false)
 	.option("--dry-run", "Show what would be deleted without deleting.", false)
 	.option("--force", "Skip confirmation.", false)
+	.option(
+		"--delete-linked",
+		"Also delete memories linked to this memory.",
+		false,
+	)
 	.option("-u, --user-id <id>", "Scope to user.")
 	.option("--agent-id <id>", "Scope to agent.")
 	.option("--app-id <id>", "Scope to app.")
@@ -563,6 +614,7 @@ program
 				output,
 				dryRun: opts.dryRun,
 				force: opts.force,
+				deleteLinked: opts.deleteLinked,
 			});
 			return;
 		}
@@ -806,8 +858,8 @@ program
 	.addHelpText("after", "\nExamples:\n  $ mem0 help\n  $ mem0 help --json")
 	.action((opts) => {
 		// opts.json is set when `mem0 help --json` is used (subcommand flag).
-		// program.opts().json is set when the root --json global flag was used first.
-		if (opts.json || program.opts().json) {
+		// program.opts().json/.agent is set when a root global flag was used first.
+		if (opts.json || program.opts().json || program.opts().agent) {
 			// Load spec from parent directory
 			const __dirname = path.dirname(fileURLToPath(import.meta.url));
 			const specPath = path.join(__dirname, "..", "..", "cli-spec.json");

cli/node/src/output.ts

@@ -282,11 +282,24 @@ export function sanitizeAgentData(command: string, data: unknown): unknown {
 		}
 		case "search":
 			return (data as Record<string, unknown>[]).map((r) =>
-				pick(r, ["id", "memory", "score", "created_at", "categories"]),
+				pick(r, [
+					"id",
+					"memory",
+					"score",
+					"created_at",
+					"categories",
+					"expiration_date",
+				]),
 			);
 		case "list":
 			return (data as Record<string, unknown>[]).map((r) =>
-				pick(r, ["id", "memory", "created_at", "categories"]),
+				pick(r, [
+					"id",
+					"memory",
+					"created_at",
+					"categories",
+					"expiration_date",
+				]),
 			);
 		case "get": {
 			const r = data as Record<string, unknown>;
@@ -297,11 +310,12 @@ export function sanitizeAgentData(command: string, data: unknown): unknown {
 				"updated_at",
 				"categories",
 				"metadata",
+				"expiration_date",
 			]);
 		}
 		case "update": {
 			const r = data as Record<string, unknown>;
-			return pick(r, ["id", "memory"]);
+			return pick(r, ["id", "memory", "expiration_date"]);
 		}
 		case "delete":
 		case "delete-all":

cli/node/src/state.ts

@@ -3,6 +3,8 @@
  * read by commands and branding functions.
  */
 
+import fs from "node:fs";
+
 let _agentMode = false;
 let _currentCommand = "";
 let _pendingNotice = "";
@@ -38,3 +40,14 @@ export function takeNotice(): string {
 	_pendingNotice = "";
 	return msg;
 }
+
+/** True only when stdin is an actual pipe or file redirect (never in agent mode). */
+export function stdinIsPiped(): boolean {
+	if (isAgentMode()) return false;
+	try {
+		const stat = fs.fstatSync(0);
+		return stat.isFIFO() || stat.isFile();
+	} catch {
+		return false;
+	}
+}

cli/node/tests/cli-integration.test.ts

@@ -44,15 +44,25 @@ describe("CLI Integration — help and version", () => {
     expect(result.stdout).toContain("search");
   });
 
-  it("help --json produces valid JSON", () => {
-    const result = run(["help", "--json"]);
-    expect(result.exitCode).toBe(0);
-    const parsed = JSON.parse(result.stdout);
-    // spec may have cli.name or top-level name
-    const name = parsed.name ?? parsed.cli?.name;
-    expect(name).toBe("mem0");
+  it("prints the version with --version, and has no version subcommand", () => {
+    const flag = run(["--version"]);
+    expect(flag.exitCode).toBe(0);
+    expect(flag.stdout).toContain("Mem0");
+    expect(run(["version"]).exitCode).not.toBe(0);
   });
 
+  it.each([["help", "--json"], ["--json", "help"], ["--agent", "help"]])(
+    "%s %s produces valid JSON",
+    (...args) => {
+      const result = run(args);
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      // spec may have cli.name or top-level name
+      const name = parsed.name ?? parsed.cli?.name;
+      expect(name).toBe("mem0");
+    },
+  );
+
   it("shows add help", () => {
     const result = run(["add", "--help"]);
     expect(result.exitCode).toBe(0);

cli/node/tests/option-parity.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Drift test: every documented v3 add/search/list param must be reachable from the Node CLI.
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const OPENAPI_PATH = path.join(
+	__dirname,
+	"..",
+	"..",
+	"..",
+	"docs",
+	"openapi.json",
+);
+
+const KNOWN_UNSURFACED: Record<string, Record<string, string>> = {
+	"/v3/memories/add/": {
+		includes: "extraction hint, no CLI flag yet",
+		excludes: "extraction hint, no CLI flag yet",
+		enable_graph: "graph memory toggle, no CLI flag yet",
+		output_format: "response envelope is pinned by the CLI",
+		prompt_profile_id: "no CLI flag yet",
+		temporal_reasoning: "no CLI flag yet",
+		timezone: "no CLI flag yet",
+		observation_datetime: "no CLI flag yet, --timestamp backdates instead",
+		observation_date: "no CLI flag yet, --timestamp backdates instead",
+	},
+	"/v3/memories/search/": {
+		categories: "expressible through --filter",
+		metadata: "expressible through --filter",
+	},
+	"/v3/memories/": {
+		start_date: "covered by --after via filters.created_at.gte",
+		end_date: "covered by --before via filters.created_at.lte",
+		categories: "covered by --category via filters.categories",
+		fields: "no CLI flag yet",
+		keywords: "no CLI flag yet",
+	},
+};
+
+const ADD_MAPPING: Record<string, string[]> = {
+	messages: ["--messages", "--file", "text"],
+	user_id: ["--user-id"],
+	agent_id: ["--agent-id"],
+	app_id: ["--app-id"],
+	run_id: ["--run-id"],
+	metadata: ["--metadata"],
+	expiration_date: ["--expires"],
+	custom_instructions: ["--custom-instructions"],
+	custom_categories: ["--custom-categories"],
+	infer: ["--no-infer"],
+	immutable: ["--immutable"],
+	structured_data_schema: ["--structured-data-schema"],
+	timestamp: ["--timestamp"],
+};
+
+const SEARCH_MAPPING: Record<string, string[]> = {
+	query: ["query"],
+	filters: ["--filter", "--user-id", "--agent-id", "--run-id"],
+	show_expired: ["--show-expired"],
+	top_k: ["--top-k"],
+	threshold: ["--threshold"],
+	rerank: ["--rerank"],
+	reference_date: ["--reference-date"],
+	fields: ["--fields"],
+};
+
+const LIST_MAPPING: Record<string, string[]> = {
+	filters: [
+		"--user-id",
+		"--agent-id",
+		"--run-id",
+		"--category",
+		"--after",
+		"--before",
+	],
+	show_expired: ["--show-expired"],
+	page: ["--page"],
+	page_size: ["--page-size"],
+};
+
+function documentedFields(endpoint: string): string[] {
+	const spec = JSON.parse(fs.readFileSync(OPENAPI_PATH, "utf-8"));
+	const schema =
+		spec.paths[endpoint].post.requestBody.content["application/json"].schema;
+	return Object.keys(schema.properties);
+}
+
+function helpText(command: string): string {
+	return execSync(`npx tsx src/index.ts ${command} --help`, {
+		cwd: path.join(__dirname, ".."),
+		encoding: "utf-8",
+		timeout: 15000,
+	});
+}
+
+function assertAllReachable(
+	endpoint: string,
+	mapping: Record<string, string[]>,
+	command: string,
+) {
+	const documented = documentedFields(endpoint);
+	const help = helpText(command);
+	for (const field of documented) {
+		if (KNOWN_UNSURFACED[endpoint]?.[field]) continue;
+		const candidates = mapping[field];
+		expect(
+			candidates,
+			`${endpoint}: documented field "${field}" has no mapping entry for command "${command}"`,
+		).toBeDefined();
+		const reachable = candidates.some((flag) =>
+			flag.startsWith("--") ? help.includes(flag) : true,
+		);
+		expect(
+			reachable,
+			`${endpoint}: documented field "${field}" not reachable via any of ${JSON.stringify(candidates)} on command "${command}"`,
+		).toBe(true);
+	}
+}
+
+describe("Option parity: Node CLI reachability of documented v3 params", () => {
+	it("add covers documented fields", () => {
+		assertAllReachable("/v3/memories/add/", ADD_MAPPING, "add");
+	});
+
+	it("search covers documented fields", () => {
+		assertAllReachable("/v3/memories/search/", SEARCH_MAPPING, "search");
+	});
+
+	it("list covers documented fields", () => {
+		assertAllReachable("/v3/memories/", LIST_MAPPING, "list");
+	});
+});
+
+describe("stdin fallback uses the shared piped-stdin guard", () => {
+	const SOURCES = ["src/index.ts", "src/commands/memory.ts"];
+
+	for (const rel of SOURCES) {
+		it(`${rel} never checks process.stdin.isTTY directly`, () => {
+			const src = fs.readFileSync(path.join(__dirname, "..", rel), "utf-8");
+			expect(
+				src.includes("process.stdin.isTTY"),
+				`${rel}: use stdinIsPiped() from state.ts. A bare !isTTY check is also true for /dev/null and sockets, so readFileSync(0) crashes with EAGAIN in scripts, CI, and agent mode.`,
+			).toBe(false);
+		});
+
+		it(`${rel} guards every readFileSync(0) with stdinIsPiped()`, () => {
+			const src = fs.readFileSync(path.join(__dirname, "..", rel), "utf-8");
+			const lines = src.split("\n");
+			for (const [i, line] of lines.entries()) {
+				if (!line.includes("readFileSync(0")) continue;
+				const guard = lines.slice(Math.max(0, i - 3), i).join("\n");
+				expect(
+					guard.includes("stdinIsPiped()"),
+					`${rel}:${i + 1}: readFileSync(0) must be guarded by stdinIsPiped()`,
+				).toBe(true);
+			}
+		});
+	}
+});

cli/node/tests/platform-backend.test.ts

@@ -7,94 +7,231 @@ import { PlatformBackend } from "../src/backend/platform.js";
 import { createDefaultConfig } from "../src/config.js";
 
 function makeBackend(): PlatformBackend {
-  // apiKey/baseUrl only build request headers; every test spies on _request,
-  // so no real network calls are made.
-  return new PlatformBackend(createDefaultConfig().platform);
+	return new PlatformBackend(createDefaultConfig().platform);
 }
 
 function mockFetch() {
-  const fetchMock = vi.fn().mockResolvedValue({
-    ok: true,
-    status: 200,
-    headers: { get: vi.fn().mockReturnValue(null) },
-    json: vi.fn().mockResolvedValue({ message: "ok" }),
-  });
-  vi.stubGlobal("fetch", fetchMock);
-  return fetchMock;
+	const fetchMock = vi.fn().mockResolvedValue({
+		ok: true,
+		status: 200,
+		headers: { get: vi.fn().mockReturnValue(null) },
+		json: vi.fn().mockResolvedValue({ message: "ok" }),
+	});
+	vi.stubGlobal("fetch", fetchMock);
+	return fetchMock;
 }
 
 beforeEach(() => {
-  vi.restoreAllMocks();
-  vi.unstubAllGlobals();
+	vi.restoreAllMocks();
+	vi.unstubAllGlobals();
 });
 
 describe("deleteEntities", () => {
-  it("returns all results keyed by entity type for a multi-entity delete", async () => {
-    const backend = makeBackend();
-    const responses: Record<string, unknown> = {
-      "/v2/entities/user/alice/": { message: "user deleted" },
-      "/v2/entities/agent/bob/": { message: "agent deleted" },
-    };
-    const spy = vi
-      // biome-ignore lint/suspicious/noExplicitAny: spying on a private method
-      .spyOn(backend as any, "_request")
-      .mockImplementation(async (_method: string, path: string) => responses[path]);
+	it("returns all results keyed by entity type for a multi-entity delete", async () => {
+		const backend = makeBackend();
+		const responses: Record<string, unknown> = {
+			"/v2/entities/user/alice/": { message: "user deleted" },
+			"/v2/entities/agent/bob/": { message: "agent deleted" },
+		};
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockImplementation(
+				async (_method: string, path: string) => responses[path],
+			);
 
-    const result = await backend.deleteEntities({ userId: "alice", agentId: "bob" });
+		const result = await backend.deleteEntities({
+			userId: "alice",
+			agentId: "bob",
+		});
 
-    // Regression: previously only the last entity's response survived.
-    expect(result).toEqual({
-      user: { message: "user deleted" },
-      agent: { message: "agent deleted" },
-    });
-    expect(spy).toHaveBeenCalledTimes(2);
-  });
+		expect(result).toEqual({
+			user: { message: "user deleted" },
+			agent: { message: "agent deleted" },
+		});
+		expect(spy).toHaveBeenCalledTimes(2);
+	});
 
-  it("keys a single-entity delete by its type", async () => {
-    const backend = makeBackend();
-    // biome-ignore lint/suspicious/noExplicitAny: spying on a private method
-    vi.spyOn(backend as any, "_request").mockResolvedValue({ message: "user deleted" });
+	it("keys a single-entity delete by its type", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		vi.spyOn(backend as any, "_request").mockResolvedValue({
+			message: "user deleted",
+		});
 
-    const result = await backend.deleteEntities({ userId: "alice" });
-    expect(result).toEqual({ user: { message: "user deleted" } });
-  });
+		const result = await backend.deleteEntities({ userId: "alice" });
+		expect(result).toEqual({ user: { message: "user deleted" } });
+	});
 
-  it("throws when no entity id is provided", async () => {
-    const backend = makeBackend();
-    await expect(backend.deleteEntities({})).rejects.toThrow(
-      "At least one entity ID is required",
-    );
-  });
+	it("throws when no entity id is provided", async () => {
+		const backend = makeBackend();
+		await expect(backend.deleteEntities({})).rejects.toThrow(
+			"At least one entity ID is required",
+		);
+	});
+});
+
+describe("PlatformBackend option-parity payloads (MEM-5893)", () => {
+	it("add: custom_instructions, custom_categories, structured_data_schema, timestamp reach the payload alongside existing fields", async () => {
+		const backend = makeBackend();
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockResolvedValue({ results: [] });
+
+		await backend.add("hello", undefined, {
+			userId: "alice",
+			metadata: { source: "test" },
+			expires: "2099-01-01",
+			customInstructions: "Extract only preferences.",
+			customCategories: [{ prefs: "user preferences" }],
+			structuredDataSchema: { type: "object" },
+			timestamp: 1700000000,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.custom_instructions).toBe("Extract only preferences.");
+		expect(payload.custom_categories).toEqual([{ prefs: "user preferences" }]);
+		expect(payload.structured_data_schema).toEqual({ type: "object" });
+		expect(payload.timestamp).toBe(1700000000);
+		expect(payload.metadata).toEqual({ source: "test" });
+		expect(payload.expiration_date).toBe("2099-01-01");
+	});
+
+	it("add: omitted optional fields are absent from the payload", async () => {
+		const backend = makeBackend();
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockResolvedValue({ results: [] });
+
+		await backend.add("hello", undefined, { userId: "alice" });
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload).not.toHaveProperty("custom_instructions");
+		expect(payload).not.toHaveProperty("custom_categories");
+		expect(payload).not.toHaveProperty("structured_data_schema");
+		expect(payload).not.toHaveProperty("timestamp");
+	});
+
+	it("search: show_expired, reference_date, latest_only reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {
+			showExpired: true,
+			referenceDate: "2024-01-01",
+			latestOnly: true,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.show_expired).toBe(true);
+		expect(payload.reference_date).toBe("2024-01-01");
+		expect(payload.latest_only).toBe(true);
+	});
+
+	it("search: keyword_search and fields reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {
+			keyword: true,
+			fields: ["memory", "score"],
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.keyword_search).toBe(true);
+		expect(payload.fields).toEqual(["memory", "score"]);
+	});
+
+	it("search: omitted keyword and fields are absent from the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload).not.toHaveProperty("keyword_search");
+		expect(payload).not.toHaveProperty("fields");
+	});
+
+	it("listMemories: show_expired and latest_only are top-level, not nested inside filters", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.listMemories({
+			userId: "alice",
+			showExpired: true,
+			latestOnly: true,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.show_expired).toBe(true);
+		expect(payload.latest_only).toBe(true);
+		expect(payload.filters ?? {}).not.toHaveProperty("show_expired");
+		expect(payload.filters ?? {}).not.toHaveProperty("latest_only");
+	});
+
+	it("update: expiration_date and timestamp reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue({});
+
+		await backend.update("mem-123", undefined, undefined, {
+			expirationDate: "2099-01-01",
+			timestamp: 1700000000,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.expiration_date).toBe("2099-01-01");
+		expect(payload.timestamp).toBe(1700000000);
+	});
+
+	it("delete: delete_linked is a query param, not part of the JSON body", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue({});
+
+		await backend.delete("mem-123", { deleteLinked: true });
+
+		const opts = spy.mock.calls[0][2];
+		expect(opts.params.delete_linked).toBe("true");
+		expect(opts.json).toBeUndefined();
+	});
 });
 
 describe("PlatformBackend path encoding", () => {
-  it("encodes memory IDs before interpolating them into paths", async () => {
-    const fetchMock = mockFetch();
-    const backend = makeBackend();
+	it("encodes memory IDs before interpolating them into paths", async () => {
+		const fetchMock = mockFetch();
+		const backend = makeBackend();
 
-    await backend.get("mem/a?b#c");
-    await backend.update("mem/a?b#c", "updated");
-    await backend.delete("mem/a?b#c");
+		await backend.get("mem/a?b#c");
+		await backend.update("mem/a?b#c", "updated");
+		await backend.delete("mem/a?b#c");
 
-    const urls = fetchMock.mock.calls.map((call) => call[0]);
-    expect(urls).toEqual([
-      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
-      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/",
-      "https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
-    ]);
-  });
+		const urls = fetchMock.mock.calls.map((call) => call[0]);
+		expect(urls).toEqual([
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/",
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+		]);
+	});
 
-  it("encodes entity and event IDs before interpolating them into paths", async () => {
-    const fetchMock = mockFetch();
-    const backend = makeBackend();
+	it("encodes entity and event IDs before interpolating them into paths", async () => {
+		const fetchMock = mockFetch();
+		const backend = makeBackend();
 
-    await backend.deleteEntities({ userId: "org/team?active#frag" });
-    await backend.getEvent("evt/a?b#c");
+		await backend.deleteEntities({ userId: "org/team?active#frag" });
+		await backend.getEvent("evt/a?b#c");
 
-    const urls = fetchMock.mock.calls.map((call) => call[0]);
-    expect(urls).toEqual([
-      "https://api.mem0.ai/v2/entities/user/org%2Fteam%3Factive%23frag/?source=CLI",
-      "https://api.mem0.ai/v1/event/evt%2Fa%3Fb%23c/",
-    ]);
-  });
+		const urls = fetchMock.mock.calls.map((call) => call[0]);
+		expect(urls).toEqual([
+			"https://api.mem0.ai/v2/entities/user/org%2Fteam%3Factive%23frag/?source=CLI",
+			"https://api.mem0.ai/v1/event/evt%2Fa%3Fb%23c/",
+		]);
+	});
 });

cli/python/README.md

@@ -241,14 +241,6 @@ Verify your API connection and display the current project.
 mem0 status
 ```
 
-### `mem0 version`
-
-Print the CLI version.
-
-```bash
-mem0 version
-```
-
 ## Agent mode
 
 Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
@@ -307,6 +299,8 @@ These flags are available on all commands:
 | `--base-url` | Override the configured API base URL for this request |
 | `-o, --output` | Set the output format |
 
+`mem0 --version` prints the CLI version. It is only valid before a subcommand, not after one.
+
 ## Environment variables
 
 | Variable | Description |

cli/python/development.md

@@ -80,7 +80,7 @@ mem0 --help
 # Using Python directly (with venv activated)
 source .venv/bin/activate
 mem0 --help
-mem0 version
+mem0 --version
 
 # Or run without activating
 .venv/bin/mem0 --help

cli/python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0-cli"
-version = "0.2.10"
+version = "0.2.11"
 description = "The official CLI for mem0 — the memory layer for AI agents"
 readme = "README.md"
 license = "Apache-2.0"

cli/python/src/mem0_cli/__init__.py

@@ -1,3 +1,3 @@
 """mem0 CLI — the command-line interface for the mem0 memory layer."""
 
-__version__ = "0.2.10"
+__version__ = "0.2.11"

cli/python/src/mem0_cli/app.py

@@ -273,7 +273,21 @@ def add(
     no_infer: bool = typer.Option(False, "--no-infer", help="Skip inference, store raw."),
     expires: str | None = typer.Option(None, "--expires", help="Expiration date (YYYY-MM-DD)."),
     categories: str | None = typer.Option(
-        None, "--categories", help="Categories (JSON array or comma-separated)."
+        None, "--categories", help="Not supported on add, use --custom-categories instead."
+    ),
+    custom_instructions: str | None = typer.Option(
+        None, "--custom-instructions", help="Custom instructions for fact extraction."
+    ),
+    custom_categories: str | None = typer.Option(
+        None,
+        "--custom-categories",
+        help="Custom categories as a JSON array of {name: description} objects.",
+    ),
+    structured_data_schema: str | None = typer.Option(
+        None, "--structured-data-schema", help="Schema for structured data extraction, as JSON."
+    ),
+    timestamp: int | None = typer.Option(
+        None, "--timestamp", help="Unix timestamp for the memory."
     ),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output format: text, json, quiet.", rich_help_panel="Output"
@@ -312,6 +326,10 @@ def add(
         no_infer=no_infer,
         expires=expires,
         categories=categories,
+        custom_instructions=custom_instructions,
+        custom_categories=custom_categories,
+        structured_data_schema=structured_data_schema,
+        timestamp=timestamp,
         output=output,
     )
 
@@ -355,6 +373,21 @@ def search(
         help="Specific fields to return (comma-separated).",
         rich_help_panel="Search",
     ),
+    show_expired: bool = typer.Option(
+        False, "--show-expired", help="Include expired memories.", rich_help_panel="Search"
+    ),
+    reference_date: str | None = typer.Option(
+        None,
+        "--reference-date",
+        help="Reference date for relative queries (YYYY-MM-DD or unix timestamp).",
+        rich_help_panel="Search",
+    ),
+    latest_only: bool = typer.Option(
+        False,
+        "--latest-only",
+        help="Only return the latest version of each memory.",
+        rich_help_panel="Search",
+    ),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output: text, json, table.", rich_help_panel="Output"
     ),
@@ -398,6 +431,9 @@ def search(
         keyword=keyword,
         filter_json=filter_json,
         fields=fields,
+        show_expired=show_expired,
+        reference_date=reference_date,
+        latest_only=latest_only,
         output=output,
     )
 
@@ -464,6 +500,15 @@ def list_cmd(
     before: str | None = typer.Option(
         None, "--before", help="Created before (YYYY-MM-DD).", rich_help_panel="Filters"
     ),
+    show_expired: bool = typer.Option(
+        False, "--show-expired", help="Include expired memories.", rich_help_panel="Filters"
+    ),
+    latest_only: bool = typer.Option(
+        False,
+        "--latest-only",
+        help="Only return the latest version of each memory.",
+        rich_help_panel="Filters",
+    ),
     output: str = typer.Option(
         "table", "--output", "-o", help="Output: text, json, table.", rich_help_panel="Output"
     ),
@@ -497,6 +542,8 @@ def list_cmd(
         category=category,
         after=after,
         before=before,
+        show_expired=show_expired,
+        latest_only=latest_only,
         output=output,
     )
 
@@ -509,6 +556,10 @@ def update(
     memory_id: str = typer.Argument(..., help="Memory ID to update."),
     text: str | None = typer.Argument(None, help="New memory text."),
     metadata: str | None = typer.Option(None, "--metadata", "-m", help="Update metadata (JSON)."),
+    expires: str | None = typer.Option(None, "--expires", help="Expiration date (YYYY-MM-DD)."),
+    timestamp: int | None = typer.Option(
+        None, "--timestamp", help="Unix timestamp for the memory."
+    ),
     output: str = typer.Option(
         "text", "--output", "-o", help="Output: text, json, quiet.", rich_help_panel="Output"
     ),
@@ -537,7 +588,15 @@ def update(
         text = _read_stdin()
 
     backend = _get_backend(api_key, base_url)
-    cmd_update(backend, memory_id, text, metadata=metadata, output=output)
+    cmd_update(
+        backend,
+        memory_id,
+        text,
+        metadata=metadata,
+        expires=expires,
+        timestamp=timestamp,
+        output=output,
+    )
 
 
 # ── Memory: delete ────────────────────────────────────────────────────────
@@ -559,6 +618,9 @@ def delete(
         False, "--dry-run", help="Show what would be deleted without deleting."
     ),
     force: bool = typer.Option(False, "--force", help="Skip confirmation."),
+    delete_linked: bool = typer.Option(
+        False, "--delete-linked", help="Also delete memories linked to this memory."
+    ),
     user_id: str | None = typer.Option(
         None, "--user-id", "-u", help="Scope to user.", rich_help_panel="Scope"
     ),
@@ -616,7 +678,14 @@ def delete(
         from mem0_cli.commands.memory import cmd_delete
 
         backend = _get_backend(api_key, base_url)
-        cmd_delete(backend, memory_id, dry_run=dry_run, force=force, output=output)
+        cmd_delete(
+            backend,
+            memory_id,
+            dry_run=dry_run,
+            force=force,
+            delete_linked=delete_linked,
+            output=output,
+        )
 
     elif all_:
         _fire_telemetry("delete", {"delete_mode": "all"})
@@ -1068,7 +1137,11 @@ def _build_help_json() -> dict:
                 "--immutable": "Prevent future updates.",
                 "--no-infer": "Skip inference, store raw.",
                 "--expires": "Expiration date (YYYY-MM-DD).",
-                "--categories": "Categories (JSON array or comma-separated).",
+                "--categories": "Not supported on add, use --custom-categories instead.",
+                "--custom-instructions": "Custom instructions for fact extraction.",
+                "--custom-categories": "Custom categories as a JSON array of {name: description} objects.",
+                "--structured-data-schema": "Schema for structured data extraction, as JSON.",
+                "--timestamp": "Unix timestamp for the memory.",
                 "--graph": "Enable graph memory extraction.",
                 "--no-graph": "Disable graph memory extraction.",
                 "--output, -o": "Output format: text, json, quiet.",
@@ -1087,6 +1160,9 @@ def _build_help_json() -> dict:
                 "--keyword": "Use keyword search instead of semantic.",
                 "--filter": "Advanced filter expression (JSON).",
                 "--fields": "Specific fields to return (comma-separated).",
+                "--show-expired": "Include expired memories.",
+                "--reference-date": "Reference date for relative queries (YYYY-MM-DD or unix timestamp).",
+                "--latest-only": "Only return the latest version of each memory.",
                 "--graph": "Enable graph in search.",
                 "--no-graph": "Disable graph in search.",
                 "--output, -o": "Output format: text, json, table.",
@@ -1110,6 +1186,8 @@ def _build_help_json() -> dict:
                 "--category": "Filter by category.",
                 "--after": "Created after (YYYY-MM-DD).",
                 "--before": "Created before (YYYY-MM-DD).",
+                "--show-expired": "Include expired memories.",
+                "--latest-only": "Only return the latest version of each memory.",
                 "--graph": "Enable graph in listing.",
                 "--no-graph": "Disable graph in listing.",
                 "--output, -o": "Output format: text, json, table.",
@@ -1124,6 +1202,8 @@ def _build_help_json() -> dict:
             },
             "options": {
                 "--metadata, -m": "Update metadata (JSON).",
+                "--expires": "Expiration date (YYYY-MM-DD).",
+                "--timestamp": "Unix timestamp for the memory.",
                 "--output, -o": "Output format: text, json, quiet.",
             },
         },
@@ -1140,6 +1220,7 @@ def _build_help_json() -> dict:
                 "--all": "Delete all memories matching scope filters.",
                 "--entity": "Delete the entity itself and all its memories (cascade).",
                 "--project": "With --all: delete ALL memories project-wide.",
+                "--delete-linked": "Also delete memories linked to this memory.",
                 "--dry-run": "Show what would be deleted without deleting.",
                 "--force": "Skip confirmation.",
                 "--user-id, -u": "Scope to user.",
@@ -1269,8 +1350,10 @@ def help(
       mem0 help
       mem0 help --json
     """
-    if json:
-        console.print(_json.dumps(_build_help_json(), indent=2))
+    from mem0_cli.state import is_agent_mode
+
+    if json or is_agent_mode():
+        console.print_json(_json.dumps(_build_help_json()))
     else:
         console.print(
             f"[{BRAND_COLOR}]◆ mem0 CLI[/] v{__version__} — The Memory Layer for AI Agents\n"

cli/python/src/mem0_cli/backend/base.py

@@ -25,7 +25,10 @@ class Backend(ABC):
         immutable: bool = False,
         infer: bool = True,
         expires: str | None = None,
-        categories: list[str] | None = None,
+        custom_instructions: str | None = None,
+        custom_categories: list[dict] | None = None,
+        structured_data_schema: dict | None = None,
+        timestamp: int | None = None,
     ) -> dict: ...
 
     @abstractmethod
@@ -43,6 +46,9 @@ class Backend(ABC):
         keyword: bool = False,
         filters: dict | None = None,
         fields: list[str] | None = None,
+        show_expired: bool = False,
+        reference_date: str | None = None,
+        latest_only: bool = False,
     ) -> list[dict]: ...
 
     @abstractmethod
@@ -61,11 +67,19 @@ class Backend(ABC):
         category: str | None = None,
         after: str | None = None,
         before: str | None = None,
+        show_expired: bool = False,
+        latest_only: bool = False,
     ) -> list[dict]: ...
 
     @abstractmethod
     def update(
-        self, memory_id: str, content: str | None = None, metadata: dict | None = None
+        self,
+        memory_id: str,
+        content: str | None = None,
+        metadata: dict | None = None,
+        *,
+        expiration_date: str | None = None,
+        timestamp: int | None = None,
     ) -> dict: ...
 
     @abstractmethod
@@ -78,6 +92,7 @@ class Backend(ABC):
         agent_id: str | None = None,
         app_id: str | None = None,
         run_id: str | None = None,
+        delete_linked: bool = False,
     ) -> dict: ...
 
     @abstractmethod

cli/python/src/mem0_cli/backend/platform.py

@@ -87,7 +87,10 @@ class PlatformBackend(Backend):
         immutable: bool = False,
         infer: bool = True,
         expires: str | None = None,
-        categories: list[str] | None = None,
+        custom_instructions: str | None = None,
+        custom_categories: list[dict] | None = None,
+        structured_data_schema: dict | None = None,
+        timestamp: int | None = None,
     ) -> dict:
         payload: dict[str, Any] = {}
 
@@ -112,8 +115,14 @@ class PlatformBackend(Backend):
             payload["infer"] = False
         if expires:
             payload["expiration_date"] = expires
-        if categories:
-            payload["categories"] = categories
+        if custom_instructions:
+            payload["custom_instructions"] = custom_instructions
+        if custom_categories:
+            payload["custom_categories"] = custom_categories
+        if structured_data_schema:
+            payload["structured_data_schema"] = structured_data_schema
+        if timestamp is not None:
+            payload["timestamp"] = timestamp
         payload["source"] = "CLI"
 
         return self._request("POST", "/v3/memories/add/", json=payload)
@@ -173,6 +182,9 @@ class PlatformBackend(Backend):
         keyword: bool = False,
         filters: dict | None = None,
         fields: list[str] | None = None,
+        show_expired: bool = False,
+        reference_date: str | None = None,
+        latest_only: bool = False,
     ) -> list[dict]:
         payload: dict[str, Any] = {"query": query, "top_k": top_k, "threshold": threshold}
 
@@ -191,6 +203,12 @@ class PlatformBackend(Backend):
             payload["keyword_search"] = True
         if fields:
             payload["fields"] = fields
+        if show_expired:
+            payload["show_expired"] = True
+        if reference_date is not None:
+            payload["reference_date"] = reference_date
+        if latest_only:
+            payload["latest_only"] = True
         payload["source"] = "CLI"
 
         result = self._request("POST", "/v3/memories/search/", json=payload)
@@ -219,6 +237,8 @@ class PlatformBackend(Backend):
         category: str | None = None,
         after: str | None = None,
         before: str | None = None,
+        show_expired: bool = False,
+        latest_only: bool = False,
     ) -> list[dict]:
         payload: dict[str, Any] = {}
         params = {"page": str(page), "page_size": str(page_size)}
@@ -241,6 +261,10 @@ class PlatformBackend(Backend):
         )
         if api_filters:
             payload["filters"] = api_filters
+        if show_expired:
+            payload["show_expired"] = True
+        if latest_only:
+            payload["latest_only"] = True
         payload["source"] = "CLI"
 
         result = self._request("POST", "/v3/memories/", json=payload, params=params)
@@ -251,13 +275,23 @@ class PlatformBackend(Backend):
         )
 
     def update(
-        self, memory_id: str, content: str | None = None, metadata: dict | None = None
+        self,
+        memory_id: str,
+        content: str | None = None,
+        metadata: dict | None = None,
+        *,
+        expiration_date: str | None = None,
+        timestamp: int | None = None,
     ) -> dict:
         payload: dict[str, Any] = {}
         if content:
             payload["text"] = content
         if metadata:
             payload["metadata"] = metadata
+        if expiration_date:
+            payload["expiration_date"] = expiration_date
+        if timestamp is not None:
+            payload["timestamp"] = timestamp
         payload["source"] = "CLI"
         return self._request(
             "PUT",
@@ -274,6 +308,7 @@ class PlatformBackend(Backend):
         agent_id: str | None = None,
         app_id: str | None = None,
         run_id: str | None = None,
+        delete_linked: bool = False,
     ) -> dict:
         if all:
             params: dict[str, str] = {"source": "CLI"}
@@ -287,10 +322,13 @@ class PlatformBackend(Backend):
                 params["run_id"] = run_id
             return self._request("DELETE", "/v1/memories/", params=params)
         elif memory_id:
+            params = {"source": "CLI"}
+            if delete_linked:
+                params["delete_linked"] = "true"
             return self._request(
                 "DELETE",
                 f"/v1/memories/{_encode_path_segment(memory_id)}/",
-                params={"source": "CLI"},
+                params=params,
             )
         else:
             raise ValueError("Either memory_id or --all is required")

cli/python/src/mem0_cli/commands/memory.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import stat as _stat_mod
 import sys
 import time as _time
+from datetime import date
 from pathlib import Path
 
 import typer
@@ -47,6 +49,18 @@ def _stdin_is_piped() -> bool:
         return False
 
 
+def _validate_expires(value: str) -> None:
+    """Exit 1 if value is not a future YYYY-MM-DD date."""
+    if not re.match(r"^\d{4}-\d{2}-\d{2}$", value):
+        print_error(
+            err_console, "Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31)."
+        )
+        raise typer.Exit(1)
+    if date.fromisoformat(value) <= date.today():
+        print_error(err_console, "--expires date must be in the future.")
+        raise typer.Exit(1)
+
+
 def cmd_add(
     backend: Backend,
     text: str | None,
@@ -62,6 +76,10 @@ def cmd_add(
     no_infer: bool,
     expires: str | None,
     categories: str | None,
+    custom_instructions: str | None = None,
+    custom_categories: str | None = None,
+    structured_data_schema: str | None = None,
+    timestamp: int | None = None,
     output: str = "text",
 ) -> None:
     """Add a memory."""
@@ -70,6 +88,13 @@ def cmd_add(
     set_current_command("add")
     if is_agent_mode():
         output = "agent"
+
+    if categories:
+        print_error(
+            err_console, "--categories is not supported on add. Use --custom-categories instead."
+        )
+        raise typer.Exit(1)
+
     msgs = None
     content = text
 
@@ -108,27 +133,24 @@ def cmd_add(
             print_error(err_console, "Invalid JSON in --metadata.")
             raise typer.Exit(1) from None
 
-    cats = None
-    if categories:
+    custom_cats = None
+    if custom_categories:
         try:
-            cats = json.loads(categories)
+            custom_cats = json.loads(custom_categories)
         except json.JSONDecodeError:
-            cats = [c.strip() for c in categories.split(",")]
+            print_error(err_console, "Invalid JSON in --custom-categories.")
+            raise typer.Exit(1) from None
+
+    schema = None
+    if structured_data_schema:
+        try:
+            schema = json.loads(structured_data_schema)
+        except json.JSONDecodeError:
+            print_error(err_console, "Invalid JSON in --structured-data-schema.")
+            raise typer.Exit(1) from None
 
-    # Validate --expires
     if expires:
-        import re
-
-        if not re.match(r"^\d{4}-\d{2}-\d{2}$", expires):
-            print_error(
-                err_console, "Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31)."
-            )
-            raise typer.Exit(1)
-        from datetime import date
-
-        if date.fromisoformat(expires) <= date.today():
-            print_error(err_console, "--expires date must be in the future.")
-            raise typer.Exit(1)
+        _validate_expires(expires)
 
     with timed_status(err_console, "Adding memory...") as ts:
         try:
@@ -143,7 +165,10 @@ def cmd_add(
                 immutable=immutable,
                 infer=not no_infer,
                 expires=expires,
-                categories=cats,
+                custom_instructions=custom_instructions,
+                custom_categories=custom_cats,
+                structured_data_schema=schema,
+                timestamp=timestamp,
             )
         except Exception as e:
             ts.error_msg = str(e)
@@ -224,6 +249,9 @@ def cmd_search(
     keyword: bool,
     filter_json: str | None,
     fields: str | None,
+    show_expired: bool = False,
+    reference_date: str | None = None,
+    latest_only: bool = False,
     output: str = "text",
 ) -> None:
     """Search memories."""
@@ -266,6 +294,9 @@ def cmd_search(
                 keyword=keyword,
                 filters=filters,
                 fields=field_list,
+                show_expired=show_expired,
+                reference_date=reference_date,
+                latest_only=latest_only,
             )
         except Exception as e:
             print_error(err_console, str(e))
@@ -352,6 +383,8 @@ def cmd_list(
     category: str | None,
     after: str | None,
     before: str | None,
+    show_expired: bool = False,
+    latest_only: bool = False,
     output: str = "table",
 ) -> None:
     """List memories."""
@@ -380,6 +413,8 @@ def cmd_list(
                 category=category,
                 after=after,
                 before=before,
+                show_expired=show_expired,
+                latest_only=latest_only,
             )
         except Exception as e:
             print_error(err_console, str(e))
@@ -446,6 +481,8 @@ def cmd_update(
     text: str | None,
     *,
     metadata: str | None,
+    expires: str | None = None,
+    timestamp: int | None = None,
     output: str,
 ) -> None:
     """Update a memory."""
@@ -462,10 +499,19 @@ def cmd_update(
             print_error(err_console, "Invalid JSON in --metadata.")
             raise typer.Exit(1) from None
 
+    if expires:
+        _validate_expires(expires)
+
     _start = _time.perf_counter()
     with timed_status(err_console, "Updating memory...") as _ts:
         try:
-            result = backend.update(memory_id, content=text, metadata=meta)
+            result = backend.update(
+                memory_id,
+                content=text,
+                metadata=meta,
+                expiration_date=expires,
+                timestamp=timestamp,
+            )
         except Exception as e:
             print_error(err_console, str(e))
             raise typer.Exit(1) from None
@@ -490,6 +536,7 @@ def cmd_delete(
     *,
     dry_run: bool = False,
     force: bool = False,
+    delete_linked: bool = False,
     output: str,
 ) -> None:
     """Delete a single memory by ID."""
@@ -512,7 +559,7 @@ def cmd_delete(
     _start = _time.perf_counter()
     with timed_status(err_console, "Deleting...") as _ts:
         try:
-            result = backend.delete(memory_id=memory_id)
+            result = backend.delete(memory_id=memory_id, delete_linked=delete_linked)
         except Exception as e:
             print_error(err_console, str(e))
             raise typer.Exit(1) from None

cli/python/src/mem0_cli/output.py

@@ -262,16 +262,32 @@ def sanitize_agent_data(command: str, data: Any) -> Any:
         return result
 
     if command == "search":
-        return [pick(r, ["id", "memory", "score", "created_at", "categories"]) for r in data]
+        return [
+            pick(r, ["id", "memory", "score", "created_at", "categories", "expiration_date"])
+            for r in data
+        ]
 
     if command == "list":
-        return [pick(r, ["id", "memory", "created_at", "categories"]) for r in data]
+        return [
+            pick(r, ["id", "memory", "created_at", "categories", "expiration_date"]) for r in data
+        ]
 
     if command == "get":
-        return pick(data, ["id", "memory", "created_at", "updated_at", "categories", "metadata"])
+        return pick(
+            data,
+            [
+                "id",
+                "memory",
+                "created_at",
+                "updated_at",
+                "categories",
+                "metadata",
+                "expiration_date",
+            ],
+        )
 
     if command == "update":
-        return pick(data, ["id", "memory"])
+        return pick(data, ["id", "memory", "expiration_date"])
 
     if command in ("delete", "delete-all", "entity delete"):
         return data

cli/python/tests/test_cli_integration.py

@@ -7,6 +7,7 @@ boundaries).
 
 from __future__ import annotations
 
+import json
 import os
 import re
 import subprocess
@@ -84,6 +85,31 @@ class TestCLIIntegration:
         assert "add" in result.stdout
         assert "search" in result.stdout
 
+    def test_version_flag_only(self):
+        from mem0_cli import __version__
+
+        flag = _run(["--version"])
+        assert flag.returncode == 0
+        assert __version__ in flag.stdout
+        assert _run(["version"]).returncode != 0
+
+    @pytest.mark.parametrize(
+        "args",
+        [["help", "--json"], ["--json", "help"], ["help", "--agent"], ["--agent", "help"]],
+    )
+    def test_help_json_produces_valid_json(self, args):
+        result = _run(args)
+        assert result.returncode == 0
+        spec = json.loads(result.stdout)
+        assert spec["name"] == "mem0"
+        assert "add" in spec["commands"]
+
+    def test_help_without_json_is_text(self):
+        result = _run(["help"])
+        assert result.returncode == 0
+        with pytest.raises(json.JSONDecodeError):
+            json.loads(result.stdout)
+
     def test_add_help(self):
         result = _run(["add", "--help"])
         assert result.returncode == 0

cli/python/tests/test_commands.py

@@ -252,12 +252,13 @@ class TestAddCommand:
             )
         mock_backend.add.assert_called_once()
 
-    def test_add_categories_csv(self, mock_backend):
+    def test_add_categories_rejected(self, mock_backend):
         console, _buf = _make_console()
-        err_console, _err_buf = _make_err_console()
+        err_console, err_buf = _make_err_console()
         with (
             patch("mem0_cli.commands.memory.console", console),
             patch("mem0_cli.commands.memory.err_console", err_console),
+            pytest.raises((SystemExit, TyperExit)),
         ):
             cmd_add(
                 mock_backend,
@@ -275,7 +276,93 @@ class TestAddCommand:
                 categories="health,prefs",
                 output="text",
             )
-        mock_backend.add.assert_called_once()
+        assert "--custom-categories" in err_buf.getvalue()
+        mock_backend.add.assert_not_called()
+
+    def test_add_invalid_custom_categories_json(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+            pytest.raises((SystemExit, TyperExit)),
+        ):
+            cmd_add(
+                mock_backend,
+                "test",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
+                custom_categories="not-json",
+                output="text",
+            )
+        assert "--custom-categories" in err_buf.getvalue()
+        mock_backend.add.assert_not_called()
+
+    def test_add_invalid_structured_data_schema_json(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+            pytest.raises((SystemExit, TyperExit)),
+        ):
+            cmd_add(
+                mock_backend,
+                "test",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata=None,
+                immutable=False,
+                no_infer=False,
+                expires=None,
+                categories=None,
+                structured_data_schema="not-json",
+                output="text",
+            )
+        assert "--structured-data-schema" in err_buf.getvalue()
+        mock_backend.add.assert_not_called()
+
+    def test_add_regression_metadata_expiration_custom_categories_together(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_add(
+                mock_backend,
+                "test",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                messages=None,
+                file=None,
+                metadata='{"source": "test"}',
+                immutable=False,
+                no_infer=False,
+                expires="2099-01-01",
+                categories=None,
+                custom_categories='[{"prefs": "user preferences"}]',
+                output="text",
+            )
+        call_kwargs = mock_backend.add.call_args.kwargs
+        assert call_kwargs["metadata"] == {"source": "test"}
+        assert call_kwargs["expires"] == "2099-01-01"
+        assert call_kwargs["custom_categories"] == [{"prefs": "user preferences"}]
 
 
 class TestAddDeduplicatesPending:
@@ -464,6 +551,36 @@ class TestSearchCommand:
             )
         mock_backend.search.assert_called_once()
 
+    def test_search_new_flags_reach_backend(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_search(
+                mock_backend,
+                "preferences",
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                top_k=10,
+                threshold=0.3,
+                rerank=False,
+                keyword=False,
+                filter_json=None,
+                fields=None,
+                show_expired=True,
+                reference_date="2024-01-01",
+                latest_only=True,
+                output="text",
+            )
+        call_kwargs = mock_backend.search.call_args.kwargs
+        assert call_kwargs["show_expired"] is True
+        assert call_kwargs["reference_date"] == "2024-01-01"
+        assert call_kwargs["latest_only"] is True
+
 
 class TestGetCommand:
     def test_get_text(self, mock_backend):
@@ -561,6 +678,32 @@ class TestListCommand:
         output = buf.getvalue()
         assert "No memories found" in output
 
+    def test_list_new_flags_reach_backend(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_list(
+                mock_backend,
+                user_id="alice",
+                agent_id=None,
+                app_id=None,
+                run_id=None,
+                page=1,
+                page_size=100,
+                category=None,
+                after=None,
+                before=None,
+                show_expired=True,
+                latest_only=True,
+                output="table",
+            )
+        call_kwargs = mock_backend.list_memories.call_args.kwargs
+        assert call_kwargs["show_expired"] is True
+        assert call_kwargs["latest_only"] is True
+
 
 class TestUpdateCommand:
     def test_update(self, mock_backend):
@@ -585,6 +728,26 @@ class TestUpdateCommand:
         output = buf.getvalue()
         assert '"memory"' in output
 
+    def test_update_new_fields_reach_backend(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_update(
+                mock_backend,
+                "abc-123",
+                "New text",
+                metadata=None,
+                expires="2099-01-01",
+                timestamp=1700000000,
+                output="text",
+            )
+        call_kwargs = mock_backend.update.call_args.kwargs
+        assert call_kwargs["expiration_date"] == "2099-01-01"
+        assert call_kwargs["timestamp"] == 1700000000
+
 
 class TestDeleteCommand:
     def test_delete_single(self, mock_backend):
@@ -610,6 +773,17 @@ class TestDeleteCommand:
         assert "dry run" in output.lower()
         mock_backend.delete.assert_not_called()
 
+    def test_delete_linked_reaches_backend(self, mock_backend):
+        console, _buf = _make_console()
+        err_console, _err_buf = _make_err_console()
+        with (
+            patch("mem0_cli.commands.memory.console", console),
+            patch("mem0_cli.commands.memory.err_console", err_console),
+        ):
+            cmd_delete(mock_backend, "abc-123", delete_linked=True, output="text")
+        call_kwargs = mock_backend.delete.call_args.kwargs
+        assert call_kwargs["delete_linked"] is True
+
 
 class TestDeleteAllCommand:
     def test_delete_all_force(self, mock_backend):

cli/python/tests/test_option_parity.py

@@ -0,0 +1,102 @@
+"""Drift test: every documented v3 add/search/list param must be reachable from the Python CLI."""
+
+import json
+from pathlib import Path
+
+import typer.main
+
+from mem0_cli.app import app
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+OPENAPI_PATH = REPO_ROOT / "docs" / "openapi.json"
+
+KNOWN_UNSURFACED: dict[tuple[str, str], str] = {
+    ("/v3/memories/add/", "includes"): "extraction hint, no CLI flag yet",
+    ("/v3/memories/add/", "excludes"): "extraction hint, no CLI flag yet",
+    ("/v3/memories/add/", "enable_graph"): "graph memory toggle, no CLI flag yet",
+    ("/v3/memories/add/", "output_format"): "response envelope is pinned by the CLI",
+    ("/v3/memories/add/", "prompt_profile_id"): "no CLI flag yet",
+    ("/v3/memories/add/", "temporal_reasoning"): "no CLI flag yet",
+    ("/v3/memories/add/", "timezone"): "no CLI flag yet",
+    ("/v3/memories/add/", "observation_datetime"): "no CLI flag yet, --timestamp backdates instead",
+    ("/v3/memories/add/", "observation_date"): "no CLI flag yet, --timestamp backdates instead",
+    ("/v3/memories/search/", "categories"): "expressible through --filter",
+    ("/v3/memories/search/", "metadata"): "expressible through --filter",
+    ("/v3/memories/", "start_date"): "covered by --after via filters.created_at.gte",
+    ("/v3/memories/", "end_date"): "covered by --before via filters.created_at.lte",
+    ("/v3/memories/", "categories"): "covered by --category via filters.categories",
+    ("/v3/memories/", "fields"): "no CLI flag yet",
+    ("/v3/memories/", "keywords"): "no CLI flag yet",
+}
+
+ADD_MAPPING: dict[str, list[str]] = {
+    "messages": ["messages", "file", "text"],
+    "user_id": ["user_id"],
+    "agent_id": ["agent_id"],
+    "app_id": ["app_id"],
+    "run_id": ["run_id"],
+    "metadata": ["metadata"],
+    "expiration_date": ["expires"],
+    "custom_instructions": ["custom_instructions"],
+    "custom_categories": ["custom_categories"],
+    "infer": ["no_infer"],
+    "immutable": ["immutable"],
+    "structured_data_schema": ["structured_data_schema"],
+    "timestamp": ["timestamp"],
+}
+
+SEARCH_MAPPING: dict[str, list[str]] = {
+    "query": ["query"],
+    "filters": ["filter_json", "user_id", "agent_id", "run_id"],
+    "show_expired": ["show_expired"],
+    "top_k": ["top_k"],
+    "threshold": ["threshold"],
+    "rerank": ["rerank"],
+    "reference_date": ["reference_date"],
+    "fields": ["fields"],
+}
+
+LIST_MAPPING: dict[str, list[str]] = {
+    "filters": ["user_id", "agent_id", "run_id", "category", "after", "before"],
+    "show_expired": ["show_expired"],
+    "page": ["page"],
+    "page_size": ["page_size"],
+}
+
+
+def _documented_fields(endpoint: str) -> set[str]:
+    spec = json.loads(OPENAPI_PATH.read_text())
+    schema = spec["paths"][endpoint]["post"]["requestBody"]["content"]["application/json"]["schema"]
+    return set(schema["properties"])
+
+
+def _cli_param_names(command_name: str) -> set[str]:
+    click_app = typer.main.get_command(app)
+    command = click_app.commands[command_name]
+    return {param.name for param in command.params}
+
+
+def _assert_all_reachable(endpoint: str, mapping: dict[str, list[str]], command_name: str) -> None:
+    documented = _documented_fields(endpoint)
+    reachable = _cli_param_names(command_name)
+    for field in documented:
+        if (endpoint, field) in KNOWN_UNSURFACED:
+            continue
+        candidates = mapping.get(field)
+        assert candidates, (
+            f"{endpoint}: documented field {field!r} has no mapping entry for command {command_name!r}"
+        )
+        assert any(candidate in reachable for candidate in candidates), (
+            f"{endpoint}: documented field {field!r} not reachable via any of {candidates} on command {command_name!r}"
+        )
+
+
+class TestOptionParity:
+    def test_add_covers_documented_fields(self):
+        _assert_all_reachable("/v3/memories/add/", ADD_MAPPING, "add")
+
+    def test_search_covers_documented_fields(self):
+        _assert_all_reachable("/v3/memories/search/", SEARCH_MAPPING, "search")
+
+    def test_list_covers_documented_fields(self):
+        _assert_all_reachable("/v3/memories/", LIST_MAPPING, "list")

cli/python/tests/test_platform_backend_options.py

@@ -0,0 +1,109 @@
+"""Tests that the MEM-5893 option-parity flags reach the correct request payload/params."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from mem0_cli.backend.platform import PlatformBackend
+from mem0_cli.config import PlatformConfig
+
+
+def _make_backend() -> PlatformBackend:
+    return PlatformBackend(PlatformConfig(api_key="test-key", base_url="https://api.mem0.ai"))
+
+
+class TestAddOptions:
+    def test_new_fields_and_existing_fields_land_in_payload_together(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value={"results": []}) as mock_request:
+            backend.add(
+                content="hello",
+                user_id="alice",
+                metadata={"source": "test"},
+                expires="2099-01-01",
+                custom_instructions="Extract only preferences.",
+                custom_categories=[{"prefs": "user preferences"}],
+                structured_data_schema={"type": "object"},
+                timestamp=1700000000,
+            )
+        payload = mock_request.call_args.kwargs["json"]
+        assert payload["custom_instructions"] == "Extract only preferences."
+        assert payload["custom_categories"] == [{"prefs": "user preferences"}]
+        assert payload["structured_data_schema"] == {"type": "object"}
+        assert payload["timestamp"] == 1700000000
+        assert payload["metadata"] == {"source": "test"}
+        assert payload["expiration_date"] == "2099-01-01"
+
+    def test_omitted_fields_are_absent_from_payload(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value={"results": []}) as mock_request:
+            backend.add(content="hello", user_id="alice")
+        payload = mock_request.call_args.kwargs["json"]
+        assert "custom_instructions" not in payload
+        assert "custom_categories" not in payload
+        assert "structured_data_schema" not in payload
+        assert "timestamp" not in payload
+
+
+class TestSearchOptions:
+    def test_show_expired_reference_date_latest_only_reach_payload(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value=[]) as mock_request:
+            backend.search(
+                "query",
+                show_expired=True,
+                reference_date="2024-01-01",
+                latest_only=True,
+            )
+        payload = mock_request.call_args.kwargs["json"]
+        assert payload["show_expired"] is True
+        assert payload["reference_date"] == "2024-01-01"
+        assert payload["latest_only"] is True
+
+    def test_keyword_and_fields_reach_payload(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value=[]) as mock_request:
+            backend.search("query", keyword=True, fields=["memory", "score"])
+        payload = mock_request.call_args.kwargs["json"]
+        assert payload["keyword_search"] is True
+        assert payload["fields"] == ["memory", "score"]
+
+    def test_keyword_and_fields_omitted_are_absent_from_payload(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value=[]) as mock_request:
+            backend.search("query")
+        payload = mock_request.call_args.kwargs["json"]
+        assert "keyword_search" not in payload
+        assert "fields" not in payload
+
+
+class TestListOptions:
+    def test_show_expired_and_latest_only_are_top_level_not_in_filters(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value=[]) as mock_request:
+            backend.list_memories(user_id="alice", show_expired=True, latest_only=True)
+        payload = mock_request.call_args.kwargs["json"]
+        assert payload["show_expired"] is True
+        assert payload["latest_only"] is True
+        assert "show_expired" not in payload.get("filters", {})
+        assert "latest_only" not in payload.get("filters", {})
+
+
+class TestUpdateOptions:
+    def test_expires_and_timestamp_reach_payload(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value={}) as mock_request:
+            backend.update("mem-123", expiration_date="2099-01-01", timestamp=1700000000)
+        payload = mock_request.call_args.kwargs["json"]
+        assert payload["expiration_date"] == "2099-01-01"
+        assert payload["timestamp"] == 1700000000
+
+
+class TestDeleteOptions:
+    def test_delete_linked_is_a_query_param_not_json_body(self):
+        backend = _make_backend()
+        with patch.object(backend, "_request", return_value={}) as mock_request:
+            backend.delete(memory_id="mem-123", delete_linked=True)
+        call = mock_request.call_args
+        assert call.kwargs["params"]["delete_linked"] == "true"
+        assert "json" not in call.kwargs

docs/changelog/sdk.mdx

@@ -7,6 +7,26 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">
 
+<Update label="2026-08-04" description="v2.0.16">
+
+**New Features:**
+- **Client:** Add `reference_date`, `latest_only`, and `keyword_search` to `SearchMemoryOptions`, and `latest_only` to `GetAllMemoryOptions`, keeping the Python client's typed options in sync with the Platform API and the CLIs ([#6696](https://github.com/mem0ai/mem0/pull/6696))
+
+**Bug Fixes:**
+- **Core:** Stop `add()` metadata from setting a memory's identity scope. `_build_filters_and_metadata()` now strips `user_id`, `agent_id`, `run_id`, and `actor_id` from caller-supplied `metadata` before building the creation template, so metadata can no longer place a memory into a scope that was never passed through the entity params ([#6656](https://github.com/mem0ai/mem0/pull/6656))
+- **Vector Stores:** Validate Upstash filter keys and values in `search()`, `keyword_search()`, and `list()`. Filter keys must match a safe identifier pattern, values must be `str`/`int`/`float`/`bool`, and string values containing a double quote or backslash are now rejected instead of being interpolated unescaped into the generated query string ([#5981](https://github.com/mem0ai/mem0/pull/5981))
+- **Embeddings:** `FastEmbedEmbedding.embed()` now converts its result with `.tolist()` before returning, so callers get a plain `List[float]` instead of a numpy array ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Embeddings:** `HuggingFaceEmbedding` now passes `api_key` to the OpenAI-compatible client when `huggingface_base_url` is set. The configured key was previously dropped, so the client fell back to `OPENAI_API_KEY` from the environment or raised `OpenAIError` at construction when that was unset ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Embeddings:** Replace Ollama's interactive `pip install` prompt on import with a plain `ImportError`. Importing `mem0.embeddings.ollama` without the `ollama` package previously blocked on stdin and then called `sys.exit(1)`, killing the host process instead of raising ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Core:** `remove_code_blocks()` now returns an empty string for `None` input instead of raising `AttributeError` ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Core:** `parse_vision_messages()` now chains the original exception (`raise ... from e`) when an image download fails, so the root cause is preserved in the traceback ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Core:** `process_telemetry_filters(None)` now returns `([], {})`, matching the two-value tuple every caller unpacks, instead of `{}` ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Core:** `LlmFactory.create()` no longer mutates the caller's config dict in place via `.update(kwargs)`; the merge now builds a new dict ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Rerankers:** The Cohere, HuggingFace, SentenceTransformer, and Zero Entropy rerankers' failure-fallback path no longer mutates the caller's document dicts in place when stamping `rerank_score`; it now falls back on copies ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+- **Vector Stores:** Remove `logging.basicConfig()` calls from the MongoDB and Vertex AI Vector Search providers, so selecting either provider no longer reconfigures the host application's root logger as a side effect ([#6770](https://github.com/mem0ai/mem0/pull/6770))
+
+</Update>
+
 <Update label="2026-08-01" description="v2.0.15">
 
 **Bug Fixes:**
@@ -1169,6 +1189,19 @@ See the [OSS v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-
 
 <Tab title="TypeScript">
 
+<Update label="2026-08-04" description="v3.1.4">
+
+**New Features:**
+- **Client:** Add `referenceDate` and `keywordSearch` to `SearchMemoryOptions`, keeping the TypeScript client's typed search options in sync with the Platform API ([#6696](https://github.com/mem0ai/mem0/pull/6696))
+
+**Bug Fixes:**
+- **Client:** Take the `/v1/ping/` identity/telemetry call off the request critical path. Every method previously did `if (this.telemetryId === "") await this.ping();`, blocking the first call on each client instance on a network round trip; the ping now resolves in the background through a shared, credentials-keyed promise cache (FIFO-capped at 50 entries), so concurrent clients on the same host/API key share one ping instead of issuing one each, and a failed ping is not cached so the process can retry ([#6788](https://github.com/mem0ai/mem0/pull/6788))
+- **Client:** `deleteUsers()` now issues its per-entity DELETE requests through the shared `fetch()`-based helper instead of the axios instance, which defaulted to `keepAlive: false`. Deleting every user, agent, app, and run now reuses pooled connections instead of paying a fresh TCP/TLS handshake per entity ([#6788](https://github.com/mem0ai/mem0/pull/6788))
+- **Memory (OSS):** Stop `add()` metadata from setting or overwriting a memory's identity scope. Metadata now runs through the same `stripIdentityKeys()` helper as `update()`, so `user_id`/`agent_id`/`run_id` (snake_case or camelCase) and `actor_id` passed in metadata can no longer place a memory into a scope the caller didn't request through `userId`/`agentId`/`runId`/`filters` ([#6377](https://github.com/mem0ai/mem0/pull/6377))
+- **Vector Stores:** Fix Redis `search()` and `list()` building an invalid, empty RediSearch filter expression when `filters` was an empty object or contained only null/undefined values. The shared `buildRedisFilterExpr()` helper now falls back to `"*"` (match all) instead of joining zero conditions into `""` ([#6014](https://github.com/mem0ai/mem0/pull/6014))
+
+</Update>
+
 <Update label="2026-08-01" description="v3.1.3">
 
 **New Features:**
@@ -1748,6 +1781,26 @@ See the [TypeScript SDK migration guide](https://docs.mem0.ai/migration/ts-v2-to
 
 <Tab title="CLI">
 
+<Update label="2026-08-04" description="Python v0.2.11 / Node v0.2.12">
+
+**New Features:**
+- **`add`:** New `--custom-instructions`, `--custom-categories`, `--structured-data-schema`, and `--timestamp` flags, matching the Platform `/v3/memories/add/` payload fields (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+- **`search`:** New `--show-expired`, `--reference-date`, and `--latest-only` flags, forwarded to `/v3/memories/search/` as `show_expired`, `reference_date`, and `latest_only` (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+- **`list`:** New `--show-expired` and `--latest-only` flags (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+- **`update`:** New `--expires` and `--timestamp` flags (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+- **`delete`:** New `--delete-linked` flag to also delete memories linked to the target memory (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+
+**Bug Fixes:**
+- **`help --json`:** Emit JSON automatically under agent mode (`--agent`), not only when `--json` is passed explicitly. Python checks `is_agent_mode()` and now renders through `console.print_json()` instead of a plain `console.print(json.dumps(...))` call; Node also checks the root `--agent` flag in addition to the subcommand's `--json` flag (Python and Node [#6773](https://github.com/mem0ai/mem0/pull/6773))
+
+**Changes:**
+- **`add`:** `--categories` is no longer forwarded on `add`. The `/v3/memories/add/` payload has no `categories` field (only `custom_categories`), so the CLI was sending a key the endpoint does not accept. Passing the flag now exits 1 with a message pointing to `--custom-categories` (Python and Node [#6696](https://github.com/mem0ai/mem0/pull/6696))
+
+**Security:**
+- **Dependencies (Node):** Tighten the `postcss` pnpm override from `<8.5.10 → >=8.5.10` to `<8.5.18 → >=8.5.18 <9.0.0`, closing a newer CVE range the previous floor didn't cover, as part of a wider dependency patch sweep across the pnpm workspaces ([#6639](https://github.com/mem0ai/mem0/pull/6639))
+
+</Update>
+
 <Update label="2026-07-13" description="Python v0.2.10 / Node v0.2.11">
 
 **Bug Fixes:**
@@ -1913,6 +1966,19 @@ A full-featured command-line interface for Mem0, available in both Python and No
 <Tabs>
 <Tab title="Mem0 Plugin">
 
+<Update label="2026-08-04" description="mem0-plugin v0.2.14">
+
+**Fixes:**
+- **Settings loading no longer crashes on a malformed `settings.json`:** If `~/.mem0/settings.json` parsed as valid JSON but wasn't an object (a list or a bare string, for example), `load_settings()` called `.items()` on it and raised. `resolve_config()` guards only against `ImportError`, so the failure escaped into every hook that resolves identity, not just setup. Settings loading now keeps the defaults instead. Setup also stopped claiming it "Created" the settings file when one already existed; it only prints that when it actually wrote one. Shared across Claude Code, Cursor, Codex, and Antigravity.
+
+**New Features:**
+- **Unknown settings key warning:** Setup now flags keys in `settings.json` that the plugin doesn't recognize, so a typo'd setting no longer fails silently.
+
+**Removed:**
+- Dropped the `mem0_doc_search` "openmemory" section now that OpenMemory has been removed from the docs site, so the skill no longer links to pages that don't exist.
+
+</Update>
+
 <Update label="2026-07-14" description="mem0-plugin v0.2.13">
 
 **Fixes:**
@@ -2252,6 +2318,19 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
 
 <Tab title="Antigravity">
 
+<Update label="2026-08-04" description="Antigravity plugin v0.1.6">
+
+**Fixes:**
+- **Settings loading no longer crashes on a malformed `settings.json`:** If `~/.mem0/settings.json` parsed as valid JSON but wasn't an object, every hook that resolves identity previously raised, not just setup. It now keeps the defaults instead, and setup only reports it "Created" the settings file when it actually wrote one.
+
+**Improvements:**
+- **Unknown settings key warning:** Setup now flags keys in `settings.json` it doesn't recognize instead of ignoring them silently.
+
+**Removed:**
+- Dropped the doc-search skill's "openmemory" section now that OpenMemory has been removed from the docs site.
+
+</Update>
+
 <Update label="2026-07-14" description="Antigravity plugin v0.1.5">
 
 **Fixes:**
@@ -2722,6 +2801,13 @@ Existing memories written by the previous versions are not rewritten. If your me
 
 <Tab title="n8n">
 
+<Update label="2026-08-04" description="n8n-nodes-mem0 v0.1.2">
+
+**Changes:**
+- **Package contact:** `author.email` in the published package is now `integrations@mem0.ai` (was `founders@mem0.ai`), so npm and n8n Creator Portal correspondence reaches the integrations team directly. No functional changes ([#6791](https://github.com/mem0ai/mem0/pull/6791))
+
+</Update>
+
 <Update label="2026-07-30" description="n8n-nodes-mem0 v0.1.1">
 
 **Changes:**
@@ -2751,6 +2837,14 @@ Existing memories written by the previous versions are not rewritten. If your me
 
 <Tab title="Zapier">
 
+<Update label="2026-08-04" description="Zapier app v0.1.1">
+
+**Bug Fixes:**
+- **Add Memory:** **User ID** is now a required field. Mem0 rejects a write that carries no entity ID, so a Zap left blank failed at the API instead of in the editor. If you scoped memories only by Agent ID or Run ID, set a User ID as well ([#6790](https://github.com/mem0ai/mem0/pull/6790))
+- **Deployment:** Add a root `index.js` that re-exports the compiled app from `dist/`, and point `main` at it. Zapier's Lambda wrapper loads `<root>/index.js` and ignores the `package.json` `main` field, so the deployed app could not resolve its entry point ([#6789](https://github.com/mem0ai/mem0/pull/6789))
+
+</Update>
+
 <Update label="2026-07-29" description="Zapier app v0.1.0">
 
 **Initial release** of the Mem0 Zapier app, built on the Zapier Platform CLI ([#6518](https://github.com/mem0ai/mem0/pull/6518))

docs/docs.json

@@ -85,7 +85,8 @@
                           "platform/features/advanced-retrieval",
                           "platform/advanced-memory-operations",
                           "platform/features/custom-instructions",
-                          "platform/features/memory-decay"
+                          "platform/features/memory-decay",
+                          "platform/features/dream"
                         ]
                       },
                       {

docs/llms.txt

@@ -207,6 +207,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 - [Temporal Reasoning](https://docs.mem0.ai/platform/features/temporal-reasoning) [Platform]: Use when time-aware searches like last week, upcoming, or right now need better result ordering.
 - [Custom Instructions](https://docs.mem0.ai/platform/features/custom-instructions) [Platform]: Use when tailoring what Mem0 extracts and stores on Platform.
 - [Memory Decay](https://docs.mem0.ai/platform/features/memory-decay) [Platform]: Use when search results should boost recently-reinforced memories and dampen stale ones. Opt in per project; applies at search time and never filters candidates out.
+- [Dream](https://docs.mem0.ai/platform/features/dream) [Platform]: Use when long-lived user memory should stay coherent on its own - synthesizing recurring patterns, superseding outdated facts, and merging duplicates in the background. Synthesis is opt-in (Pro+); Supersede and Merge are always on.
 - [Advanced Memory Operations](https://docs.mem0.ai/platform/advanced-memory-operations) [Platform]: Use when basic CRUD is not enough - batch ops, complex filters, workflows.
 
 ### Features - Data Management

docs/platform/cli.mdx

@@ -122,12 +122,20 @@ echo "Loves hiking on weekends" | mem0 add --user-id alice
 | `--messages` | Conversation messages as JSON |
 | `-f, --file` | Read messages from a JSON file |
 | `-m, --metadata` | Custom metadata as JSON |
-| `--categories` | Categories (JSON array or comma-separated) |
+| `--categories` | Rejected on `add`. Use `--custom-categories` instead |
+| `--custom-categories` | Custom categories as a JSON array of `{name: description}` objects |
+| `--custom-instructions` | Custom instructions for fact extraction |
+| `--structured-data-schema` | Schema for structured data extraction, as JSON |
+| `--timestamp` | Unix timestamp for the memory |
 | `--expires` | Expiration date, after which the memory stops being returned |
 | `--immutable` | Store the memory so it can never be updated or overwritten |
 | `--no-infer` | Store the text exactly as given, skipping fact extraction |
 | `-o, --output` | Output format: `text`, `json`, `quiet` |
 
+<Note>
+`--categories` is not supported on `add` and exits with an error pointing at `--custom-categories`.
+</Note>
+
 ### `mem0 search`
 
 Search memories using natural language.
@@ -149,6 +157,9 @@ mem0 search "preferred tools" --user-id alice --output json --top-k 5
 | `--keyword` | Use keyword search instead of semantic |
 | `--filter` | Advanced filter expression (JSON) |
 | `--fields` | Return only the named fields |
+| `--show-expired` | Include expired memories |
+| `--reference-date` | Reference date for relative queries (`YYYY-MM-DD` or Unix timestamp) |
+| `--latest-only` | Only return the latest version of each memory |
 | `-o, --output` | Output format: `text`, `json`, `table` |
 
 ### `mem0 list`
@@ -172,6 +183,8 @@ mem0 list --user-id alice --after 2024-01-01 --page-size 50
 | `--category` | Filter by category |
 | `--after` | Created after date (YYYY-MM-DD) |
 | `--before` | Created before date (YYYY-MM-DD) |
+| `--show-expired` | Include expired memories |
+| `--latest-only` | Only return the latest version of each memory |
 | `-o, --output` | Output format: `text`, `json`, `table` |
 
 ### `mem0 get`
@@ -200,6 +213,8 @@ echo "new text" | mem0 update <memory-id>
 | Flag | Description |
 |------|-------------|
 | `-m, --metadata` | Replace the memory's metadata with this JSON |
+| `--expires` | Expiration date (YYYY-MM-DD) |
+| `--timestamp` | Unix timestamp for the memory |
 | `-o, --output` | Output format: `text`, `json`, `quiet` |
 
 ### `mem0 delete`
@@ -229,6 +244,7 @@ mem0 delete --all --user-id alice --dry-run
 | `--all` | Delete all memories matching scope filters |
 | `--entity` | Delete the entity and all its memories |
 | `--project` | With `--all`: delete all memories project-wide |
+| `--delete-linked` | Also delete memories linked to this memory |
 | `--dry-run` | Preview without deleting |
 | `--force` | Skip confirmation prompt |
 

docs/platform/features/dream.mdx

@@ -0,0 +1,164 @@
+---
+title: Dream
+description: "Dream keeps a user's memory clean over time by distilling recurring patterns, retiring outdated facts, and merging duplicates in the background."
+---
+
+# Dream
+
+As an application talks to the same user over weeks and months, their memory grows. Some of that growth is signal, meaning new facts worth keeping. A lot of it is noise: the same preference stated three different ways, an old fact that a newer one has quietly replaced, or a set of small observations that only mean something when you look at them together.
+
+**Dream** is the background layer that keeps a user's memory coherent as it grows. It continuously reviews each user's memories and does three things. It synthesizes higher-order patterns, supersedes outdated facts, and merges duplicates. The result is that what you read back stays sharp instead of drifting into a pile of overlapping, stale entries.
+
+<Info>
+  **Dream matters when…**
+  - Your users interact with your product over a long period and accumulate a lot of memories.
+  - You want retrieval to return the *current* truth about a user, not a mix of old and new contradictory facts.
+  - You want higher-level insights ("this user consistently prefers X") without writing your own summarization layer.
+</Info>
+
+## The three actions of Dream
+
+Dream is made of three independent actions. Two of them, Supersede and Merge, keep memory clean and run automatically for everyone. The third, Synthesis, produces new insight and is a toggle you turn on per project.
+
+| Action | What it does | When it runs | Availability |
+|---|---|---|---|
+| **Synthesis** | Distills a user's memories into higher-order **pattern memories** | On a schedule, in the background | Opt-in (Pro and above) |
+| **Supersede** | Marks an older fact as outdated when a newer one contradicts it | As memories are added | Always on, all plans |
+| **Merge** | Folds a duplicate into a single canonical memory | As memories are added | Always on, all plans |
+
+### Synthesis
+
+Over time a user's memories often *imply* something larger than any single entry. Ten separate notes about early-morning meetings, workout logs, and coffee orders together say "this user is an early riser." **Synthesis** finds those recurring threads and writes them back as new **pattern memories**: concise, higher-order facts that capture what the individual memories only hint at.
+
+- Pattern memories are added *alongside* your existing memories, never in place of them. The source memories stay exactly where they are.
+- Each pattern memory keeps a link back to the specific memories it was distilled from, so an insight is always traceable to its evidence.
+- Synthesis is additive and idempotent. Re-running it will not create duplicate patterns for the same underlying evidence.
+
+**Example.** These four memories accumulate for the same user over time:
+
+- *"User runs approximately 40 kilometers per week and is currently training for a marathon."*
+- *"User lifts weights at the gym three times a week, primarily focusing on legs and back."*
+- *"User tracks all workouts using a Garmin Forerunner watch."*
+- *"User's goal for 2026 is to run a sub-4-hour marathon."*
+
+Synthesis distills them into one pattern memory, kept alongside the originals:
+
+> *"User follows a structured fitness routine that includes weekly long runs (≈40 km), regular leg-and-back strength training, tracks workouts with a Garmin device, and pursues progressive marathon time goals."*
+
+Each source memory stays exactly where it was, and the new pattern links back to all of them as its evidence.
+
+<Note>
+  Synthesis only considers memories created **after** you enable it for a project. Turning it on sets a forward boundary, so historical memories aren't reprocessed in bulk on day one. Everything added from that point on is eligible.
+</Note>
+
+<Note>
+  Synthesis only looks at memories scoped to a **`user_id` alone**. Memories that also carry another entity (an `agent_id`, `run_id`, or `app_id`) are left out of a user's synthesis run. This keeps each run tied to a single user's own memories and avoids cross-referencing across agents, runs, or apps. So a memory has to be user-scoped, with no other entity attached, to be eligible for a pattern.
+</Note>
+
+### Supersede
+
+When a user tells you something that **contradicts** an earlier memory ("I moved to Berlin" after an earlier "I live in Lisbon"), Dream marks the older memory as **superseded** and links it to the newer fact that replaced it. Superseded memories are not deleted and not hidden by default. A normal `search` or `get` still returns them alongside your active memories, badged as superseded, so you keep the full history. When you want only the current truth, ask for it explicitly with `latest_only=true` (see [How reads change](#how-reads-change-with-dream) below). Supersede runs automatically as part of adding memories, on every plan.
+
+**Example.** The user has an existing memory *"User drives a 2019 Subaru Outback."* Later they mention selling it, producing a new memory *"User sold their 2019 Subaru Outback and bought a Tesla Model 3."* Dream marks the Subaru memory as superseded and links it to the newer one. A default `search` returns both: the Tesla memory as active, and the Subaru one labelled superseded. Passing `latest_only=true` returns only *"User sold their 2019 Subaru Outback and bought a Tesla Model 3."*
+
+### Merge
+
+When a new memory is effectively a **duplicate** of one you already have, Dream keeps a single canonical memory instead of two near-identical copies. When a duplicate is stored as its own memory, Dream marks it **merged** and links it to the canonical one. The merged record is hidden from reads by default (you get the one canonical memory), retained rather than deleted, and surfaced with `include_merged=true`. Merge runs automatically as memories are added, on every plan, and keeps your memory set compact without you deduplicating by hand.
+
+In practice, most exact or near-duplicate restatements of a fact you already have are recognised and deduplicated as the memory is added. No second copy is created, so you simply keep the one memory. A distinct `merged` record appears when a fuller version of an existing fact arrives and folds the barer one in.
+
+**Example.** The user has an existing memory *"User has a dog named Rex."* Later they mention *"My dog Rex is a 3-year-old golden retriever."* The richer statement is stored and Dream marks the barer *"User has a dog named Rex"* as **merged** into it. A default read returns the single canonical memory *"User's dog Rex is a 3-year-old golden retriever"*, and `include_merged=true` also returns the merged original.
+
+<Info>
+  **Nothing Dream does is destructive.** Superseded and merged memories are retained, never erased. Every change is recorded and reviewable, so you always know why a memory was retired or combined.
+</Info>
+
+## How reads change with Dream
+
+Dream doesn't change the shape of your `add`, `search`, or `get` calls, so you don't touch your application code. What it changes is *which* memories a read returns by default, and it gives you two flags to widen or narrow that set:
+
+| Read mode | Active | Superseded | Merged |
+|---|:---:|:---:|:---:|
+| **Default** (`search` / `get`) | ✓ | ✓ | ✗ |
+| **`latest_only=true`** | ✓ | — | — |
+| **`include_merged=true`** | ✓ | ✓ | ✓ |
+
+- **By default**, a read returns active plus superseded memories (superseded ones are still there, labelled as history) and hides merged duplicates. Synthesized pattern memories are returned alongside these too.
+- **`latest_only=true`** narrows the result to active memories only, meaning the current truth, with superseded and merged both excluded. Use this when you want the cleanest possible snapshot of the user right now.
+- **`include_merged=true`** returns everything, including the merged duplicates, when you need the complete picture.
+
+## Enabling Dream
+
+Supersede and Merge require no setup. They're always on for every project on every plan.
+
+Synthesis is opt-in per project:
+
+1. Open the **[Dream settings for your project](https://app.mem0.ai/dashboard/dream)** in the Mem0 dashboard.
+2. Toggle **Synthesis** on.
+
+Synthesis is a per-project setting, so you can enable it for one project and compare against another with it off. You can turn it off at any time. Doing so is fully reversible and leaves every existing memory (including already-synthesized patterns) untouched.
+
+From the [Dream page](https://app.mem0.ai/dashboard/dream) you can also review what Dream has done: recent synthesis runs, the patterns produced and their source memories, and the memories that were superseded or merged.
+
+## Plan availability
+
+| Capability | Free | Starter | Pro | Enterprise |
+|---|:---:|:---:|:---:|:---:|
+| **Supersede** (outdated facts flagged) | ✓ | ✓ | ✓ | ✓ |
+| **Merge** (duplicates folded, hidden by default) | ✓ | ✓ | ✓ | ✓ |
+| **Synthesis** (pattern memories written) | — | — | ✓ | ✓ |
+| **Dream dashboard** (runs, activity) | — | — | ✓ | ✓ |
+
+Synthesis requires a **Pro plan or higher**. Enterprise plans also get a faster, configurable schedule (see below).
+
+## How often Dream runs, and what delay to expect
+
+Different actions run on different clocks, so the delay you should expect depends on which action.
+
+### Supersede & Merge, as memories are added
+
+Supersede and Merge are part of the memory-addition pipeline. They're evaluated when a memory is added, so an outdated fact is superseded or a duplicate is merged as part of that add being processed, on the same timescale as the memory becoming searchable. There's no separate schedule to wait for.
+
+### Synthesis, on a schedule in the background
+
+Synthesis runs as a scheduled background job per user, not on every add. Two conditions gate it:
+
+- **Enough to work with:** a user must have at least **20** memories before Synthesis considers them. Below that threshold there isn't a meaningful pattern to distill yet.
+- **Cadence elapsed:** each user is re-synthesized at most once per cadence window.
+
+| Plan | Synthesis cadence (per user) |
+|---|---|
+| Pro | Every **7 days** |
+| Enterprise | **Daily** (and configurable) |
+
+Because Synthesis is processed in batches in the background, **expect new pattern memories to appear within roughly 24 hours of a scheduled run**, not instantly. In practice, the end-to-end delay from crossing a cadence window to seeing new patterns is up to about a day. This background design is deliberate: it keeps Synthesis from adding any latency to your live `add` and `search` calls.
+
+<Warning>
+  Synthesis is **not** real-time. If you enable it today, the first pattern memories for an eligible user will appear on the next scheduled run for that user (governed by the cadence above), and can take up to ~24 hours to complete once that run starts. Supersede and Merge, by contrast, keep pace with your adds.
+</Warning>
+
+## FAQ
+
+**Does Dream delete any of my memories?**
+No. Nothing Dream does is destructive. Superseded memories stay visible in default reads (labelled as history), merged duplicates are hidden by default but retained, and synthesized patterns are added alongside your existing memories, never in place of them. Every change is reviewable from the dashboard.
+
+**How do I get only the current facts, without the superseded ones?**
+Pass `latest_only=true` on your read. Superseded and merged memories are both excluded, leaving only active memories. By default (no flag) superseded memories are included so you keep the full history.
+
+**Do I need to change my code to use Dream?**
+No. Supersede and Merge are always on, and enabling Synthesis is a project setting. Your `add`, `search`, and `get` calls are unchanged. Dream shapes the memory set behind the same API.
+
+**Will Synthesis reprocess all my old memories when I turn it on?**
+No. Enabling Synthesis sets a forward boundary, so only memories created after you turn it on are eligible. This avoids a bulk reprocess of your entire history on day one.
+
+**Why don't I see pattern memories immediately after enabling Synthesis?**
+Synthesis runs on a schedule (every 7 days on Pro, daily on Enterprise) and only for users with at least 20 memories. Patterns appear on the next scheduled run for an eligible user and can take up to ~24 hours to complete once that run starts.
+
+**Which memories does Synthesis include?**
+Only memories scoped to a `user_id` on its own. If a memory also carries an `agent_id`, `run_id`, or `app_id`, it's excluded from that user's synthesis run. This keeps each run confined to a single user's memories and prevents any cross-referencing across agents, runs, or apps. Supersede and Merge are not affected by this and run across your memories as usual.
+
+**Are synthesized pattern memories traceable?**
+Yes. Every pattern memory links back to the specific source memories it was distilled from, so you can always see the evidence behind an insight from the Dream dashboard.
+
+**Can I turn Synthesis off?**
+Yes, at any time, per project. Turning it off is fully reversible and leaves all existing memories, including already-synthesized patterns, untouched.

docs/platform/features/entity-scoped-memory.mdx

@@ -83,7 +83,7 @@ Passing both `user_id` and `agent_id` to `client.add` does **not** produce recor
 As a result, `{"AND": [{"user_id": ...}, {"agent_id": ...}]}` returns nothing for memories created this way. Use `OR` to match either scope. Records with both fields populated only come from [Direct Import](/platform/features/direct-import) (`infer=False`), which writes your text verbatim without attribution splitting.
 </Warning>
 
-The HTTP equivalent uses `POST /v1/memories/` with the same identifiers in the JSON body. See the Add Memories API reference for REST details.
+The HTTP equivalent uses `POST /v3/memories/add/` with the same identifiers in the JSON body. See the [Add Memories](/api-reference/memory/add-memories) API reference for REST details.
 
 ## See it in action
 

docs/platform/features/temporal-reasoning.mdx

@@ -1,139 +1,80 @@
 ---
 title: Temporal Reasoning
-description: "Time-aware memory retrieval for Mem0 Platform v3 so queries like 'last week', 'upcoming', and 'right now' return the right memories."
+description: "Boost memories whose dates match the time in a search."
 badge: "v3"
 ---
 
-Some memories matter because of **when** they happened, not just because they sound similar. Temporal Reasoning lets Mem0 Platform v3 understand time-aware queries and return the most contextually appropriate results.
+Temporal Reasoning gives a ranking boost to memories whose event dates match the time in a search. Event dates are when something described in a memory happened or will happen. It runs automatically on Mem0 Platform v3.
 
-<Info>
-  **Use Temporal Reasoning when…**
-  - Users ask questions like "what happened last week?" or "what do I have coming up?"
-  - Your app stores both past events and future plans for the same person
-  - You want time-aware retrieval without building your own date-parsing layer
-</Info>
+It is not available in the OSS SDK.
 
-<Warning>
-  Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints.
-</Warning>
+Dates from new memories usually affect search within a few seconds.
 
-## Configure access
+## Time-aware searches
 
-Confirm your `MEM0_API_KEY` is set and that you are using the v3 Platform client:
+Queries can include expressions such as `yesterday`, `last week`, `tomorrow`, `currently`, and `as of March 2025`. Mem0 compares them with dates and date ranges found in stored memories.
 
-```python
-from mem0 import MemoryClient
+## Example
 
-client = MemoryClient(api_key="your-api-key")
-```
+Suppose a user has these memories:
 
-## How it works
+- "Yesterday I met Maya at the Orion conference in Paris."
+- "Last week I met Maya at the Orion conference in Tokyo."
+- "Last year I met Maya at the Orion conference in Lisbon."
 
-When a memory describes an event, a future plan, or an ongoing state, Temporal Reasoning recognizes the time context so the right results surface at search time.
-
-A query like `what did I do last week?` should return a completed past event: not an upcoming appointment and not a stable fact that hasn't changed. Temporal Reasoning handles that distinction automatically.
-
-### Memory types Temporal Reasoning handles
-
-| Type | What it represents | Example |
-| --- | --- | --- |
-| Dated occurrence | Something that happened at a known time | "I finished the Q1 review on March 10, 2025." |
-| Future plan | A future commitment or scheduled item | "I have a dentist appointment on March 18, 2025." |
-| Ongoing state | A fact that remains true over time | "I am the product lead at Acme Corp." |
-| Relationship | A durable connection between people or entities | "Priya manages Jordan." |
-| Preference | A stable preference or habit | "I prefer morning meetings." |
-
-Results come back in the normal search response shape: Temporal Reasoning affects ranking, not the response format.
-
-## Configure it
-
-Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle.
-
-Two parameters give you precise control when you need it:
-
-- `observation_date` (or `observation_datetime`, which takes priority when both are set) on `add()`: anchors an imported memory to the time it actually happened. Pair with `timezone` when resolving a date-only value.
-- `timestamp` on `add()`: a Unix epoch that sets the memory's creation time. When present it takes priority over `observation_datetime` and `observation_date` as the anchor Temporal Reasoning ranks against, so pass only the one you want to win.
-- `reference_date` on `search()`: resolves relative phrases like `last week` against a fixed point in time
+Searching for `Which city did I meet Maya in at the Orion conference last week?` gives the Tokyo memory a temporal boost and ranks it first.
 
 <CodeGroup>
 ```python Python
-from mem0 import MemoryClient
-
-client = MemoryClient(api_key="your-api-key")
-
-client.add(
-    [{"role": "user", "content": "I finished the Q1 review on March 10, 2025."}],
-    user_id="jordan",
-    observation_date="2025-03-10",
-)
-
 results = client.search(
-    "what did I do last week?",
-    filters={"user_id": "jordan"},
+    "Which city did I meet Maya in at the Orion conference last week?",
+    filters={"user_id": "maya-demo"},
+)
+```
+
+```javascript JavaScript
+const results = await client.search(
+  "Which city did I meet Maya in at the Orion conference last week?",
+  { filters: { user_id: "maya-demo" } }
+);
+```
+</CodeGroup>
+
+Search returns the usual memory results, reordered using the temporal boost.
+
+## Search from a specific time
+
+Use `reference_date` to simulate searching at a specific date and time. Mem0 treats it as the current time for that search.
+
+<CodeGroup>
+```python Python
+results = client.search(
+    "What happened last week?",
+    filters={"user_id": "user-123"},
     reference_date="2025-03-21T00:00:00Z",
 )
 ```
 
 ```javascript JavaScript
-import { MemoryClient } from "mem0ai";
-
-const client = new MemoryClient({ apiKey: "your-api-key" });
-
-await client.add(
-  [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
-  {
-    userId: "jordan",
-    observationDate: "2025-03-10",
-  }
-);
-
-const results = await client.search("what did I do last week?", {
-  filters: { user_id: "jordan" },
+const results = await client.search("What happened last week?", {
+  filters: { user_id: "user-123" },
   referenceDate: "2025-03-21T00:00:00Z",
 });
 ```
 </CodeGroup>
 
-<Tip>
-  `reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time.
-</Tip>
+## Parameters
 
-## Supported query patterns
+| Action | Python | TypeScript | Purpose |
+| --- | --- | --- | --- |
+| Add memories | `timestamp` | `timestamp` | Preserve the original time of an imported conversation. |
+| Search memories | `reference_date` | `referenceDate` | Simulate searching at a specific date and time. |
 
-<AccordionGroup>
-  <Accordion title="Historical questions">
-    Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10`
-  </Accordion>
-  <Accordion title="Upcoming questions">
-    Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?`
-  </Accordion>
-  <Accordion title="Current-state questions">
-    Examples: `right now`, `currently`, `where do I work now?`
-  </Accordion>
-  <Accordion title="As-of questions">
-    Examples: `as of March 2025`, `where was I living as of 2024?`
-  </Accordion>
-  <Accordion title="Duration questions">
-    Examples: `how long have I lived here?`, `since when have I worked there?`
-  </Accordion>
-</AccordionGroup>
-
-## Verify the feature is working
-
-- Run a temporal search with a time-aware query (e.g., "what did I do last week?") and confirm the memory that fits the time window ranks first.
-- Use `reference_date` in test queries so relative phrases resolve consistently across runs.
-- For backfilled data, pass `timestamp` on `add()` to confirm the memory reflects the right point in time.
-
-## Best practices
-
-- Use explicit dates in source conversations when events or plans matter temporally.
-- Pass `observation_date` (or `observation_datetime`) during historical imports so the ingestion time does not become the only time anchor. Do not also pass `timestamp` on those calls, since it overrides both as the ranking anchor.
-- Scope searches with `filters` so time-aware ranking operates inside the right user boundary.
-- Use `reference_date` in automated tests and reproducible demos.
+For all search inputs and returned fields, see the [Search Memories API reference](/api-reference/memory/search-memories).
 
 <CardGroup cols={1}>
   <Card title="Memory Timestamps" icon="calendar" href="/platform/features/timestamp">
-    Anchor imported memories to when they actually happened.
+    Preserve the original time of imported memories.
   </Card>
 </CardGroup>
 

integrations/mem0-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "mem0",
   "name": "mem0",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Persistent semantic memory for Antigravity agents. Cross-session, user-level recall via the Mem0 Platform MCP server. 16 slash commands, lifecycle hooks for auto-capture and metadata enforcement.",
   "author": { "name": "Mem0", "email": "support@mem0.ai" },
   "publisher": "mem0ai",

integrations/mem0-plugin/scripts/load_settings.py

@@ -27,24 +27,45 @@ def load_settings() -> dict:
         try:
             with open(SETTINGS_PATH) as f:
                 user = json.load(f)
-            settings.update({k: v for k, v in user.items() if k in DEFAULTS})
         except (json.JSONDecodeError, OSError):
-            pass
+            return settings
+        if isinstance(user, dict):
+            settings.update({k: v for k, v in user.items() if k in DEFAULTS})
     return settings
 
 
-def create_default_settings() -> None:
+def create_default_settings() -> bool:
+    """Write the default settings file if absent. Returns True if it was created."""
     SETTINGS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if SETTINGS_PATH.exists():
+        return False
+    with open(SETTINGS_PATH, "w") as f:
+        json.dump(DEFAULTS, f, indent=2)
+        f.write("\n")
+    return True
+
+
+def unknown_keys() -> list[str]:
+    """Keys present in the user's settings file that no code reads."""
     if not SETTINGS_PATH.exists():
-        with open(SETTINGS_PATH, "w") as f:
-            json.dump(DEFAULTS, f, indent=2)
-            f.write("\n")
+        return []
+    try:
+        with open(SETTINGS_PATH) as f:
+            user = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return []
+    if not isinstance(user, dict):
+        return []
+    return sorted(k for k in user if k not in DEFAULTS)
 
 
 if __name__ == "__main__":
     import sys
     if len(sys.argv) > 1 and sys.argv[1] == "init":
-        create_default_settings()
-        print(f"Created {SETTINGS_PATH}")
+        if create_default_settings():
+            print(f"Created {SETTINGS_PATH}")
+        ignored = unknown_keys()
+        if ignored:
+            print(f"Ignoring unrecognized settings in {SETTINGS_PATH}: {', '.join(ignored)}")
     else:
         print(json.dumps(load_settings()))

integrations/mem0-plugin/tests/conftest.py

@@ -23,15 +23,14 @@ def _scripts_on_path():
 
 
 @pytest.fixture(autouse=True)
-def _clean_project_map(monkeypatch):
-    """Remove project_map.json and clear MEM0_PROJECT_ID before each test."""
+def _isolated_home(tmp_path, monkeypatch):
+    """Point HOME at a tmp dir so ~/.mem0 writes never touch the real home."""
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.delenv("MEM0_PROJECT_ID", raising=False)
-    map_path = os.path.expanduser("~/.mem0/project_map.json")
-    if os.path.isfile(map_path):
-        os.remove(map_path)
-    yield
-    if os.path.isfile(map_path):
-        os.remove(map_path)
+    yield home
 
 
 @pytest.fixture()

integrations/mem0-plugin/tests/test_load_settings.py

@@ -0,0 +1,86 @@
+"""Tests for scripts/load_settings.py."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+
+@pytest.fixture()
+def settings(tmp_path, monkeypatch):
+    import load_settings
+
+    path = tmp_path / ".mem0" / "settings.json"
+    monkeypatch.setattr(load_settings, "SETTINGS_PATH", path)
+    return load_settings
+
+
+def test_creates_file_when_absent(settings):
+    assert settings.create_default_settings() is True
+    assert settings.SETTINGS_PATH.exists()
+    assert json.loads(settings.SETTINGS_PATH.read_text()) == settings.DEFAULTS
+
+
+def test_does_not_recreate_or_overwrite_existing(settings):
+    settings.SETTINGS_PATH.parent.mkdir(parents=True)
+    settings.SETTINGS_PATH.write_text('{"search_limit": 42}')
+
+    assert settings.create_default_settings() is False
+    assert json.loads(settings.SETTINGS_PATH.read_text()) == {"search_limit": 42}
+
+
+def test_user_values_override_defaults(settings):
+    settings.SETTINGS_PATH.parent.mkdir(parents=True)
+    settings.SETTINGS_PATH.write_text('{"search_limit": 3, "auto_save": false}')
+
+    loaded = settings.load_settings()
+    assert loaded["search_limit"] == 3
+    assert loaded["auto_save"] is False
+    assert loaded["global_search"] == settings.DEFAULTS["global_search"]
+
+
+def test_unknown_keys_are_dropped_but_reported(settings):
+    settings.SETTINGS_PATH.parent.mkdir(parents=True)
+    settings.SETTINGS_PATH.write_text('{"skip_tools": ["Read"], "output_style": "compact"}')
+
+    assert "skip_tools" not in settings.load_settings()
+    assert settings.unknown_keys() == ["output_style", "skip_tools"]
+
+
+def test_unknown_keys_empty_for_clean_file(settings):
+    settings.create_default_settings()
+    assert settings.unknown_keys() == []
+
+
+@pytest.mark.parametrize("body", ["{not json", '["a", "list"]'])
+def test_malformed_file_falls_back_to_defaults(settings, body):
+    settings.SETTINGS_PATH.parent.mkdir(parents=True)
+    settings.SETTINGS_PATH.write_text(body)
+
+    assert settings.load_settings() == settings.DEFAULTS
+    assert settings.unknown_keys() == []
+
+
+def test_init_announces_creation_only_once(_isolated_home):
+    import load_settings
+
+    home = _isolated_home
+
+    def run_init():
+        return subprocess.run(
+            [sys.executable, load_settings.__file__, "init"],
+            capture_output=True,
+            text=True,
+            check=True,
+            env={**os.environ, "HOME": str(home)},
+        ).stdout
+
+    first = run_init()
+    second = run_init()
+
+    assert "Created" in first
+    assert "Created" not in second

integrations/n8n-nodes-mem0/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/n8n-nodes-mem0",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "n8n community node for Mem0 — the memory layer for AI agents. Add, search, get, update, and delete long-term memories.",
   "keywords": [
     "n8n-community-node-package",
@@ -14,7 +14,7 @@
   "homepage": "https://mem0.ai",
   "author": {
     "name": "Mem0",
-    "email": "founders@mem0.ai"
+    "email": "integrations@mem0.ai"
   },
   "repository": {
     "type": "git",

integrations/zapier-mem0/index.js

@@ -0,0 +1,3 @@
+// Zapier's Lambda wrapper requires `<root>/index.js` and ignores package.json
+// "main", so re-export the compiled app from the root. Run `npm run build` first.
+module.exports = require('./dist/index.js');

integrations/zapier-mem0/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/zapier",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Zapier integration for Mem0 — the memory layer for AI agents.",
   "keywords": [
     "zapier",
@@ -20,7 +20,7 @@
     "directory": "integrations/zapier-mem0"
   },
   "license": "Apache-2.0",
-  "main": "dist/index.js",
+  "main": "index.js",
   "scripts": {
     "build": "tsc",
     "test": "jest --testTimeout 180000",

integrations/zapier-mem0/src/creates/add_memory.ts

@@ -115,7 +115,7 @@ export default {
 				choices: { user: 'User', assistant: 'Assistant', system: 'System' },
 				default: 'user',
 			},
-			{ key: 'user_id', label: 'User ID', type: 'string' },
+			{ key: 'user_id', label: 'User ID', type: 'string', required: true, helpText: 'Scope this memory to a user. Mem0 requires at least one entity ID.' },
 			{ key: 'agent_id', label: 'Agent ID', type: 'string' },
 			{ key: 'run_id', label: 'Run ID', type: 'string' },
 			{ key: 'metadata', label: 'Metadata (JSON)', type: 'string' },

mem0-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0ai",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "The Memory Layer For Your AI Apps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

mem0-ts/src/client/mem0.ts

@@ -83,6 +83,16 @@ interface ClientOptions {
   host?: string;
 }
 
+interface ClientIdentity {
+  telemetryId: string;
+  organizationId: string | number | null;
+  projectId: string | number | null;
+}
+
+// Shares one ping per (host, api key) across clients; FIFO-capped.
+const IDENTITY_CACHE_MAX = 50;
+const identityByCredentials = new Map<string, Promise<ClientIdentity>>();
+
 export default class MemoryClient {
   apiKey: string;
   host: string;
@@ -91,6 +101,7 @@ export default class MemoryClient {
   headers: Record<string, string>;
   client: any;
   telemetryId: string;
+  private initialized: Promise<void>;
 
   _validateApiKey(): any {
     if (!this.apiKey) {
@@ -122,11 +133,39 @@ export default class MemoryClient {
     });
 
     this._validateApiKey();
+
     this.telemetryId = "";
-    this._initializeClient();
+
+    // Requests never wait on this; only telemetry does.
+    this.initialized = this._resolveIdentity();
   }
 
-  private async _initializeClient() {
+  // One ping per credential pair per process, shared via identityByCredentials.
+  private _resolveIdentity(): Promise<void> {
+    const credentials = `${this.host}\u0000${this.apiKey}`;
+    let shared = identityByCredentials.get(credentials);
+    if (!shared) {
+      shared = this._initializeClient();
+      if (identityByCredentials.size >= IDENTITY_CACHE_MAX) {
+        identityByCredentials.delete(
+          identityByCredentials.keys().next().value!,
+        );
+      }
+      identityByCredentials.set(credentials, shared);
+      // A failed ping must not be cached, or the process never recovers.
+      shared.then((identity) => {
+        if (!identity.telemetryId) identityByCredentials.delete(credentials);
+      });
+    }
+    return shared.then((identity) => {
+      this.telemetryId = identity.telemetryId;
+      if (identity.organizationId != null)
+        this.organizationId = identity.organizationId;
+      if (identity.projectId != null) this.projectId = identity.projectId;
+    });
+  }
+
+  private async _initializeClient(): Promise<ClientIdentity> {
     try {
       await this.ping();
 
@@ -148,6 +187,12 @@ export default class MemoryClient {
         stack: error?.stack || "No stack trace",
       });
     }
+
+    return {
+      telemetryId: this.telemetryId,
+      organizationId: this.organizationId,
+      projectId: this.projectId,
+    };
   }
 
   private async _maybeAliasAnonToEmail(): Promise<void> {
@@ -175,13 +220,18 @@ export default class MemoryClient {
   }
 
   private _captureEvent(methodName: string, args: any[]) {
-    captureClientEvent(methodName, this, {
-      success: true,
-      args_count: args.length,
-      keys: args.length > 0 ? args[0] : [],
-    }).catch((error: any) => {
-      console.error("Failed to capture event:", error);
-    });
+    // Deferred until ping() has resolved telemetryId, off the request path.
+    this.initialized
+      .then(() =>
+        captureClientEvent(methodName, this, {
+          success: true,
+          args_count: args.length,
+          keys: args.length > 0 ? args[0] : [],
+        }),
+      )
+      .catch((error: any) => {
+        console.error("Failed to capture event:", error);
+      });
   }
 
   async _fetchWithErrorHandling(url: string, options: any): Promise<any> {
@@ -262,8 +312,6 @@ export default class MemoryClient {
       throw new Error("Cannot process an empty messages payload.");
     }
 
-    if (this.telemetryId === "") await this.ping();
-
     const payload = this._preparePayload(messages, options);
     const payloadKeys = Object.keys(payload);
     this._captureEvent("add", [payloadKeys]);
@@ -304,7 +352,6 @@ export default class MemoryClient {
       );
     }
 
-    if (this.telemetryId === "") await this.ping();
     const payload: Record<string, any> = {};
     if (text !== undefined) payload.text = text;
     if (metadata !== undefined) payload.metadata = metadata;
@@ -326,7 +373,6 @@ export default class MemoryClient {
   }
 
   async get(memoryId: string): Promise<Memory> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("get", []);
     return this._fetchWithErrorHandling(
       `${this.host}/v1/memories/${encodePathSegment(memoryId)}/`,
@@ -340,7 +386,6 @@ export default class MemoryClient {
     // Reject top-level entity params - must use filters instead
     rejectTopLevelEntityParams(options as Record<string, any>, "getAll");
 
-    if (this.telemetryId === "") await this.ping();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("get_all", [payloadKeys]);
     const { page, pageSize, filters, ...rest } = options ?? {};
@@ -369,7 +414,6 @@ export default class MemoryClient {
     // Reject top-level entity params - must use filters instead
     rejectTopLevelEntityParams(options as Record<string, any>, "search");
 
-    if (this.telemetryId === "") await this.ping();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("search", [payloadKeys]);
     const { filters, ...rest } = options ?? {};
@@ -395,7 +439,6 @@ export default class MemoryClient {
     memoryId: string,
     options: DeleteMemoryOptions = {},
   ): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("delete", [Object.keys(options || {})]);
     const snakeOptions = camelToSnakeKeys(this._prepareParams(options));
     // @ts-ignore
@@ -412,7 +455,6 @@ export default class MemoryClient {
   async deleteAll(
     options: DeleteAllMemoryOptions = {},
   ): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("delete_all", [payloadKeys]);
     const snakeOptions = camelToSnakeKeys(this._prepareParams(options));
@@ -429,7 +471,6 @@ export default class MemoryClient {
   }
 
   async history(memoryId: string): Promise<Array<MemoryHistory>> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("history", []);
     const response = await this._fetchWithErrorHandling(
       `${this.host}/v1/memories/${encodePathSegment(memoryId)}/history/`,
@@ -444,7 +485,6 @@ export default class MemoryClient {
     page?: number;
     pageSize?: number;
   }): Promise<AllUsers> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("users", []);
     let url = `${this.host}/v1/entities/`;
     const params: string[] = [];
@@ -464,7 +504,6 @@ export default class MemoryClient {
     entity_id: number;
     entity_type: string;
   }): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("delete_user", []);
     if (!data.entity_type) {
       data.entity_type = "user";
@@ -487,8 +526,6 @@ export default class MemoryClient {
       runId?: string;
     } = {},
   ): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
-
     let to_delete: Array<{ type: string; name: string }> = [];
     const { userId, agentId, appId, runId } = params;
 
@@ -514,8 +551,14 @@ export default class MemoryClient {
 
     for (const entity of to_delete) {
       try {
-        await this.client.delete(
-          `/v2/entities/${encodePathSegment(entity.type)}/${encodePathSegment(entity.name)}/`,
+        // fetch() reuses the pooled connection; axios here defaulted to
+        // keepAlive: false, one handshake per entity.
+        await this._fetchWithErrorHandling(
+          `${this.host}/v2/entities/${encodePathSegment(entity.type)}/${encodePathSegment(entity.name)}/`,
+          {
+            method: "DELETE",
+            headers: this.headers,
+          },
         );
       } catch (error: any) {
         throw new APIError(
@@ -537,7 +580,6 @@ export default class MemoryClient {
   }
 
   async batchUpdate(memories: Array<MemoryUpdateBody>): Promise<string> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("batch_update", []);
     const memoriesBody = memories.map((memory) => ({
       memory_id: memory.memoryId,
@@ -555,7 +597,6 @@ export default class MemoryClient {
   }
 
   async batchDelete(memories: Array<string>): Promise<string> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("batch_delete", []);
     const memoriesBody = memories.map((memory) => ({
       memory_id: memory,
@@ -572,7 +613,6 @@ export default class MemoryClient {
   }
 
   async getProject(options: ProjectOptions): Promise<ProjectResponse> {
-    if (this.telemetryId === "") await this.ping();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("get_project", [payloadKeys]);
     const { fields } = options;
@@ -598,7 +638,6 @@ export default class MemoryClient {
   async updateProject(
     prompts: PromptUpdatePayload,
   ): Promise<Record<string, any>> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("update_project", []);
     if (!(this.organizationId && this.projectId)) {
       throw new Error(
@@ -619,7 +658,6 @@ export default class MemoryClient {
 
   // WebHooks
   async getWebhooks(data?: { projectId?: string }): Promise<Array<Webhook>> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("get_webhooks", []);
     const project_id = data?.projectId || this.projectId;
     const response = await this._fetchWithErrorHandling(
@@ -632,7 +670,6 @@ export default class MemoryClient {
   }
 
   async createWebhook(webhook: WebhookCreatePayload): Promise<Webhook> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("create_webhook", []);
     const body = {
       name: webhook.name,
@@ -653,7 +690,6 @@ export default class MemoryClient {
   async updateWebhook(
     webhook: WebhookUpdatePayload,
   ): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("update_webhook", []);
     const body: Record<string, any> = {};
     if (webhook.name != null) body.name = webhook.name;
@@ -673,7 +709,6 @@ export default class MemoryClient {
   async deleteWebhook(data: {
     webhookId: string;
   }): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("delete_webhook", []);
     const webhook_id = data.webhookId || data;
     const response = await this._fetchWithErrorHandling(
@@ -687,7 +722,6 @@ export default class MemoryClient {
   }
 
   async feedback(data: FeedbackPayload): Promise<{ message: string }> {
-    if (this.telemetryId === "") await this.ping();
     const payloadKeys = Object.keys(data || {});
     this._captureEvent("feedback", [payloadKeys]);
     const response = await this._fetchWithErrorHandling(
@@ -704,7 +738,6 @@ export default class MemoryClient {
   async createMemoryExport(
     data: CreateMemoryExportPayload,
   ): Promise<{ message: string; id: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("create_memory_export", []);
 
     if (!data.filters || !data.schema) {
@@ -734,7 +767,6 @@ export default class MemoryClient {
   async getMemoryExport(
     data: GetMemoryExportPayload,
   ): Promise<{ message: string; id: string }> {
-    if (this.telemetryId === "") await this.ping();
     this._captureEvent("get_memory_export", []);
 
     if (!data.memoryExportId && !data.filters) {

mem0-ts/src/client/mem0.types.ts

@@ -27,6 +27,8 @@ export interface SearchMemoryOptions {
   fields?: string[];
   categories?: string[];
   showExpired?: boolean;
+  referenceDate?: string | number;
+  keywordSearch?: boolean;
 }
 
 export interface GetAllMemoryOptions {

mem0-ts/src/client/tests/memoryClient.search.test.ts

@@ -99,6 +99,42 @@ describe("MemoryClient - search()", () => {
     expect(getFetchBody(call!).show_expired).toBe(true);
   });
 
+  test("serializes referenceDate as reference_date (MEM-5893)", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v3/memories/search/", {
+      status: 200,
+      body: { results: [] },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.search("test", {
+      filters: { user_id: "u1" },
+      referenceDate: "2024-01-01",
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/search/", "POST");
+    expect(getFetchBody(call!).reference_date).toBe("2024-01-01");
+  });
+
+  test("serializes keywordSearch as keyword_search (MEM-5893)", async () => {
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v3/memories/search/", {
+      status: 200,
+      body: { results: [] },
+    });
+    const mock = setupMockFetch(extra);
+
+    const client = new MemoryClient({ apiKey: TEST_API_KEY });
+    await client.search("test", {
+      filters: { user_id: "u1" },
+      keywordSearch: true,
+    });
+
+    const call = findFetchCall(mock, "/v3/memories/search/", "POST");
+    expect(getFetchBody(call!).keyword_search).toBe(true);
+  });
+
   test("passes complex OR filters through to the API body", async () => {
     const extra = new Map<string, { status: number; body: unknown }>();
     extra.set("/v3/memories/search/", {

mem0-ts/src/client/tests/memoryClient.users.test.ts

@@ -98,16 +98,23 @@ describe("MemoryClient - deleteUser() (deprecated)", () => {
 
 describe("MemoryClient - deleteUsers()", () => {
   test("URL-encodes entity path segments", async () => {
-    setupMockFetch();
+    const extra = new Map<string, { status: number; body: unknown }>();
+    extra.set("/v2/entities/user/org%2Fteam%3Factive%23frag/", {
+      status: 200,
+      body: { message: "Entity deleted successfully!" },
+    });
+    const mock = setupMockFetch(extra);
+
     const client = new MemoryClient({ apiKey: TEST_API_KEY });
-    client.telemetryId = "test@example.com";
-    const deleteMock = jest.fn().mockResolvedValue({});
-    client.client = { delete: deleteMock };
 
     await client.deleteUsers({ userId: "org/team?active#frag" });
 
-    expect(deleteMock).toHaveBeenCalledWith(
-      "/v2/entities/user/org%2Fteam%3Factive%23frag/",
-    );
+    expect(
+      findFetchCall(
+        mock,
+        "/v2/entities/user/org%2Fteam%3Factive%23frag/",
+        "DELETE",
+      ),
+    ).toBeDefined();
   });
 });

mem0-ts/src/oss/src/memory/index.ts

@@ -100,11 +100,20 @@ const ENTITY_PARAMS = [
   "agentId",
   "runId",
 ];
-
-// Identity keys stripped from update() metadata: ENTITY_PARAMS covers user_id/agent_id/run_id
-// in both casings (the default store promotes camelCase on read); actor_id has no camelCase alias.
+// Identity keys stripped from caller metadata in add() and update(): ENTITY_PARAMS covers
+// user_id/agent_id/run_id in both casings (the default store promotes camelCase on read);
+// actor_id has no camelCase alias.
 const IDENTITY_KEYS = [...ENTITY_PARAMS, "actor_id"];
 
+// Caller metadata must not overwrite or inject an identity scope (#6342 / #6367 / #6371).
+function stripIdentityKeys(
+  metadata: Record<string, any> = {},
+): Record<string, any> {
+  return Object.fromEntries(
+    Object.entries(metadata).filter(([key]) => !IDENTITY_KEYS.includes(key)),
+  );
+}
+
 // Batch size for deleteAll pagination. Larger than most vector store default
 // page limits (~100) to minimize roundtrips while bounded to avoid memory pressure.
 const DELETE_ALL_BATCH_SIZE = 1000;
@@ -740,7 +749,8 @@ export class Memory {
       has_filters: !!config.filters,
       infer: config.infer,
     });
-    const { metadata = {}, filters = {}, infer = true } = config;
+    const { filters = {}, infer = true } = config;
+    const metadata = stripIdentityKeys(config.metadata);
 
     // Validate and trim entity IDs
     const userId = validateAndTrimEntityId(config.userId, "userId");
@@ -751,6 +761,9 @@ export class Memory {
     if (userId) filters.user_id = metadata.user_id = userId;
     if (agentId) filters.agent_id = metadata.agent_id = agentId;
     if (runId) filters.run_id = metadata.run_id = runId;
+    if (filters.user_id) metadata.user_id = filters.user_id;
+    if (filters.agent_id) metadata.agent_id = filters.agent_id;
+    if (filters.run_id) metadata.run_id = filters.run_id;
 
     // Normalize expiration date into the stored metadata (round-trips via get()).
     if (config.expirationDate != null) {
@@ -1971,10 +1984,7 @@ export class Memory {
       existingEmbeddings[newData] ||
       (await this.embedder.embed(newData, "update"));
 
-    // Caller metadata must not overwrite or inject an identity scope (#6342 / #6367).
-    const sanitizedMetadata = Object.fromEntries(
-      Object.entries(metadata).filter(([k]) => !IDENTITY_KEYS.includes(k)),
-    );
+    const sanitizedMetadata = stripIdentityKeys(metadata);
 
     const newMetadata = {
       ...existingMemory.payload,

mem0-ts/src/oss/src/vector_stores/redis.ts

@@ -133,6 +133,18 @@ function toSnakeCase(obj: Record<string, any>): Record<string, any> {
   );
 }
 
+// Build a RediSearch pre-filter expression from filters. Returns "*" (match
+// all) when there are no usable conditions — including an empty filters object
+// or one whose values are all null/undefined — since an empty expression is an
+// invalid RediSearch query (e.g. ` =>[KNN ...]`).
+export function buildRedisFilterExpr(filters?: SearchFilters): string {
+  if (!filters) return "*";
+  const conditions = Object.entries(toSnakeCase(filters))
+    .filter(([, value]) => value !== null && value !== undefined)
+    .map(([key, value]) => `@${key}:{${escapeRedisTagValue(value)}}`);
+  return conditions.length > 0 ? conditions.join(" ") : "*";
+}
+
 // Utility function to convert object keys to camelCase
 function toCamelCase(obj: Record<string, any>): Record<string, any> {
   if (typeof obj !== "object" || obj === null) return obj;
@@ -406,13 +418,7 @@ export class RedisDB implements VectorStore {
     filters?: SearchFilters,
   ): Promise<VectorStoreResult[]> {
     await this.initialize();
-    const snakeFilters = filters ? toSnakeCase(filters) : undefined;
-    const filterExpr = snakeFilters
-      ? Object.entries(snakeFilters)
-          .filter(([_, value]) => value !== null && value !== undefined)
-          .map(([key, value]) => `@${key}:{${escapeRedisTagValue(value)}}`)
-          .join(" ")
-      : "*";
+    const filterExpr = buildRedisFilterExpr(filters);
 
     const queryVector = new Float32Array(query).buffer;
 
@@ -655,13 +661,7 @@ export class RedisDB implements VectorStore {
     topK: number = 100,
   ): Promise<[VectorStoreResult[], number]> {
     await this.initialize();
-    const snakeFilters = filters ? toSnakeCase(filters) : undefined;
-    const filterExpr = snakeFilters
-      ? Object.entries(snakeFilters)
-          .filter(([_, value]) => value !== null && value !== undefined)
-          .map(([key, value]) => `@${key}:{${escapeRedisTagValue(value)}}`)
-          .join(" ")
-      : "*";
+    const filterExpr = buildRedisFilterExpr(filters);
 
     const searchOptions = {
       SORTBY: "created_at",

mem0-ts/src/oss/tests/memory.add.test.ts

@@ -8,55 +8,78 @@ import type { MemoryConfig, MemoryItem, SearchResult } from "../src/types";
 
 jest.setTimeout(15000);
 
-// Mock Google modules to prevent @google/genai crash in CI
-jest.mock("../src/embeddings/google", () => ({
-  GoogleEmbedder: jest.fn(),
-}));
-jest.mock("../src/llms/google", () => ({
-  GoogleLLM: jest.fn(),
-}));
+jest.mock("../src/utils/factory", () => {
+  const { MemoryVectorStore } = jest.requireActual(
+    "../src/vector_stores/memory",
+  );
+  const { MemoryHistoryManager } = jest.requireActual(
+    "../src/storage/MemoryHistoryManager",
+  );
+  const testEmbedding = new Array(1536).fill(0.1);
 
-jest.mock("../src/llms/openai", () => ({
-  OpenAILLM: jest.fn().mockImplementation(() => ({
-    generateResponse: jest
-      .fn()
-      .mockImplementation(
-        (messages: Array<{ role: string; content: string }>) => {
-          // V3 pipeline: single LLM call with additive extraction prompt.
-          const userMsg = messages.find((m) => m.role === "user");
-          const content = userMsg?.content ?? "";
-          const newMsgMatch = content.match(
-            /## New Messages\n([\s\S]*?)(?=\n##|$)/,
+  class MockEmbedder {
+    embeddingDims = 1536;
+
+    async embed(): Promise<number[]> {
+      return testEmbedding;
+    }
+
+    async embedBatch(texts: string[]): Promise<number[][]> {
+      return texts.map(() => testEmbedding);
+    }
+  }
+
+  class MockLLM {
+    async generateResponse(messages: Array<{ role: string; content: string }>) {
+      const userMsg = messages.find((m) => m.role === "user");
+      const content = userMsg?.content ?? "";
+      const newMsgMatch = content.match(
+        /## New Messages\n([\s\S]*?)(?=\n##|$)/,
+      );
+      const extracted = newMsgMatch
+        ? newMsgMatch[1].trim()
+        : "extracted fact from input";
+
+      return JSON.stringify({
+        memory: [
+          {
+            id: "0",
+            text: extracted,
+            attributed_to: "user",
+          },
+        ],
+      });
+    }
+  }
+
+  return {
+    __esModule: true,
+    EmbedderFactory: {
+      create: jest.fn(() => new MockEmbedder()),
+    },
+    LLMFactory: {
+      create: jest.fn(() => new MockLLM()),
+    },
+    VectorStoreFactory: {
+      create: jest.fn((provider: string, config: any) => {
+        if (provider.toLowerCase() !== "memory") {
+          throw new Error(
+            `Unsupported vector store provider in test: ${provider}`,
           );
-          const extracted = newMsgMatch
-            ? newMsgMatch[1].trim()
-            : "extracted fact from input";
-          return JSON.stringify({
-            memory: [
-              {
-                id: "0",
-                text: extracted,
-                attributed_to: "user",
-              },
-            ],
-          });
-        },
-      ),
-  })),
-}));
-
-const mockEmbedding = new Array(1536).fill(0.1);
-jest.mock("../src/embeddings/openai", () => ({
-  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
-    embed: jest.fn().mockResolvedValue(mockEmbedding),
-    embedBatch: jest
-      .fn()
-      .mockImplementation((texts: string[]) =>
-        Promise.resolve(texts.map(() => mockEmbedding)),
-      ),
-    embeddingDims: 1536,
-  })),
-}));
+        }
+        return new MemoryVectorStore(config);
+      }),
+    },
+    HistoryManagerFactory: {
+      create: jest.fn(() => new MemoryHistoryManager()),
+    },
+    RerankerFactory: {
+      create: jest.fn(() => {
+        throw new Error("RerankerFactory is not used in memory.add.test.ts");
+      }),
+    },
+  };
+});
 
 function createMemory(overrides: Partial<MemoryConfig> = {}): Memory {
   return new Memory({
@@ -172,6 +195,138 @@ describe("Memory - add()", () => {
     );
   });
 
+  test("does not allow metadata to set identity scope", async () => {
+    const result: SearchResult = await memory.add("I am a software engineer", {
+      userId: "u1",
+      metadata: {
+        agent_id: "other",
+        agentId: "other-camel",
+        run_id: "other-run",
+        runId: "other-run-camel",
+        actor_id: "x",
+        source: "issue-6371",
+        nested: { preserved: true },
+      },
+    });
+    const stored: MemoryItem | null = await memory.get(result.results[0].id);
+
+    expect(stored).toEqual(
+      expect.objectContaining({
+        user_id: "u1",
+        metadata: expect.objectContaining({
+          source: "issue-6371",
+          nested: { preserved: true },
+        }),
+      }),
+    );
+    expect(stored).not.toHaveProperty("agent_id");
+    expect(stored).not.toHaveProperty("run_id");
+    expect(stored!.metadata).not.toHaveProperty("agent_id");
+    expect(stored!.metadata).not.toHaveProperty("agentId");
+    expect(stored!.metadata).not.toHaveProperty("run_id");
+    expect(stored!.metadata).not.toHaveProperty("runId");
+    expect(stored!.metadata).not.toHaveProperty("actor_id");
+  });
+
+  test.each([
+    ["userId", { userId: "u1" }, true, "user_id", "u1"],
+    ["agentId", { agentId: "a1" }, false, "agent_id", "a1"],
+    ["runId", { runId: "r1" }, true, "run_id", "r1"],
+  ] as const)(
+    "preserves typed %s scope while stripping conflicting metadata identities",
+    async (_mode, scope, infer, canonicalKey, canonicalValue) => {
+      const result: SearchResult = await memory.add("scoped content", {
+        ...scope,
+        infer,
+        metadata: {
+          user_id: "metadata-user",
+          userId: "metadata-user-camel",
+          agent_id: "metadata-agent",
+          agentId: "metadata-agent-camel",
+          run_id: "metadata-run",
+          runId: "metadata-run-camel",
+          actor_id: "metadata-actor",
+          ordinary: "preserved",
+        },
+      });
+      const stored: MemoryItem | null = await memory.get(result.results[0].id);
+
+      expect(stored).toHaveProperty(canonicalKey, canonicalValue);
+      for (const key of ["user_id", "agent_id", "run_id"]) {
+        if (key !== canonicalKey) {
+          expect(stored).not.toHaveProperty(key);
+        }
+      }
+      expect(stored!.metadata).toEqual(
+        expect.objectContaining({ ordinary: "preserved" }),
+      );
+      for (const key of [
+        "user_id",
+        "userId",
+        "agent_id",
+        "agentId",
+        "run_id",
+        "runId",
+        "actor_id",
+      ]) {
+        if (key !== canonicalKey) {
+          expect(stored!.metadata).not.toHaveProperty(key);
+        }
+      }
+    },
+  );
+
+  test.each([
+    [true, "user_id", "filter-user"],
+    [false, "user_id", "filter-user"],
+    [false, "agent_id", "filter-agent"],
+    [false, "run_id", "filter-run"],
+  ] as const)(
+    "preserves infer=%s %s filters scope after sanitization",
+    async (infer, filterKey, filterValue) => {
+      const result: SearchResult = await memory.add("filter-scoped content", {
+        filters: { [filterKey]: filterValue },
+        infer,
+        metadata: {
+          user_id: "metadata-user",
+          userId: "metadata-user-camel",
+          agent_id: "metadata-agent",
+          agentId: "metadata-agent-camel",
+          run_id: "metadata-run",
+          runId: "metadata-run-camel",
+          actor_id: "metadata-actor",
+          ordinary: "preserved",
+        },
+      });
+      const stored: MemoryItem | null = await memory.get(result.results[0].id);
+
+      expect(stored).toHaveProperty(filterKey, filterValue);
+      for (const key of ["user_id", "agent_id", "run_id"]) {
+        if (key !== filterKey) {
+          expect(stored).not.toHaveProperty(key);
+        }
+      }
+      expect(stored!.metadata).toEqual(
+        expect.objectContaining({
+          [filterKey]: filterValue,
+          ordinary: "preserved",
+        }),
+      );
+      for (const key of [
+        "user_id",
+        "userId",
+        "agent_id",
+        "agentId",
+        "run_id",
+        "runId",
+        "actor_id",
+      ]) {
+        if (key === filterKey) continue;
+        expect(stored!.metadata).not.toHaveProperty(key);
+      }
+    },
+  );
+
   test("with infer=false skips LLM and stores messages directly", async () => {
     const result: SearchResult = await memory.add("Direct storage content", {
       userId,

mem0-ts/src/oss/tests/redis.filter-expr.test.ts

@@ -0,0 +1,35 @@
+import { buildRedisFilterExpr } from "../src/vector_stores/redis";
+
+describe("buildRedisFilterExpr", () => {
+  it("returns '*' when filters is undefined", () => {
+    expect(buildRedisFilterExpr(undefined)).toBe("*");
+  });
+
+  it("returns '*' for an empty filters object", () => {
+    // Regression: previously produced "" -> invalid RediSearch query
+    // (` =>[KNN ...]`).
+    expect(buildRedisFilterExpr({})).toBe("*");
+  });
+
+  it("returns '*' when every filter value is null/undefined", () => {
+    expect(
+      buildRedisFilterExpr({ user_id: null as any, agent_id: undefined }),
+    ).toBe("*");
+  });
+
+  it("builds a tag clause for a single filter", () => {
+    expect(buildRedisFilterExpr({ user_id: "alice" })).toBe("@user_id:{alice}");
+  });
+
+  it("snake-cases keys and joins multiple clauses", () => {
+    expect(buildRedisFilterExpr({ userId: "alice", runId: "r1" })).toBe(
+      "@user_id:{alice} @run_id:{r1}",
+    );
+  });
+
+  it("drops null/undefined values but keeps the rest", () => {
+    expect(
+      buildRedisFilterExpr({ user_id: "alice", agent_id: null as any }),
+    ).toBe("@user_id:{alice}");
+  });
+});

mem0/client/types.py

@@ -52,6 +52,11 @@ class SearchMemoryOptions(BaseModel):
     fields: Optional[List[str]] = Field(default=None, description="Fields to include in the response")
     categories: Optional[List[str]] = Field(default=None, description="Categories to filter by")
     show_expired: Optional[bool] = Field(default=None, description="Whether to include expired memories")
+    reference_date: Optional[Union[str, int]] = Field(
+        default=None, description="Reference date for relative time queries (YYYY-MM-DD or Unix timestamp)"
+    )
+    latest_only: Optional[bool] = Field(default=None, description="Whether to only return the latest memory version")
+    keyword_search: Optional[bool] = Field(default=None, description="Whether to use keyword search")
 
 
 class GetAllMemoryOptions(BaseModel):
@@ -74,6 +79,7 @@ class GetAllMemoryOptions(BaseModel):
     )
     categories: Optional[List[str]] = Field(default=None, description="Categories to filter by")
     show_expired: Optional[bool] = Field(default=None, description="Whether to include expired memories")
+    latest_only: Optional[bool] = Field(default=None, description="Whether to only return the latest memory version")
 
 
 class DeleteAllMemoryOptions(BaseModel):

mem0/embeddings/fastembed.py

@@ -1,7 +1,7 @@
-from typing import Optional, Literal
+from typing import Literal, Optional
 
-from mem0.embeddings.base import EmbeddingBase
 from mem0.configs.embeddings.base import BaseEmbedderConfig
+from mem0.embeddings.base import EmbeddingBase
 
 try:
     from fastembed import TextEmbedding
@@ -29,4 +29,4 @@ class FastEmbedEmbedding(EmbeddingBase):
         """
         text = text.replace("\n", " ")
         embeddings = list(self.dense_model.embed(text))
-        return embeddings[0]
+        return embeddings[0].tolist()

mem0/embeddings/huggingface.py

@@ -17,7 +17,7 @@ class HuggingFaceEmbedding(EmbeddingBase):
         super().__init__(config)
 
         if self.config.huggingface_base_url:
-            self.client = OpenAI(base_url=self.config.huggingface_base_url)
+            self.client = OpenAI(base_url=self.config.huggingface_base_url, api_key=self.config.api_key)
             self.config.model = self.config.model or "tei"
         else:
             self.config.model = self.config.model or "multi-qa-MiniLM-L6-cos-v1"

mem0/embeddings/ollama.py

@@ -1,5 +1,3 @@
-import subprocess
-import sys
 from typing import Literal, Optional
 
 from mem0.configs.embeddings.base import BaseEmbedderConfig
@@ -8,17 +6,7 @@ from mem0.embeddings.base import EmbeddingBase
 try:
     from ollama import Client
 except ImportError:
-    user_input = input("The 'ollama' library is required. Install it now? [y/N]: ")
-    if user_input.lower() == "y":
-        try:
-            subprocess.check_call([sys.executable, "-m", "pip", "install", "ollama"])
-            from ollama import Client
-        except subprocess.CalledProcessError:
-            print("Failed to install 'ollama'. Please install it manually using 'pip install ollama'.")
-            sys.exit(1)
-    else:
-        print("The required 'ollama' library is not installed.")
-        sys.exit(1)
+    raise ImportError("The 'ollama' library is required. Please install it using 'pip install ollama'.")
 
 
 class OllamaEmbedding(EmbeddingBase):

mem0/memory/main.py

@@ -135,18 +135,30 @@ _SENSITIVE_SUFFIXES = (
 ENTITY_PARAMS = frozenset({"user_id", "agent_id", "run_id"})
 DELETE_ALL_BATCH_SIZE = 1000
 
-# Tenant-scoping fields that update() must never let caller-supplied metadata overwrite (issues #4490, #6277).
+# Tenant-scoping fields that caller-supplied metadata must never set, on either the
+# creation or the update path (issues #4490, #6277, #6655).
 _IDENTITY_KEYS = ENTITY_PARAMS | {"actor_id"}
 
 
-def _strip_identity_keys(metadata: Dict[str, Any], existing_payload: Dict[str, Any]) -> Dict[str, Any]:
-    """Drop identity keys from caller metadata; they are immutable after creation (issues #4490, #6277)."""
+def _strip_identity_keys(
+    metadata: Dict[str, Any],
+    existing_payload: Dict[str, Any],
+    *,
+    context: str = "update()",
+) -> Dict[str, Any]:
+    """Drop identity keys from caller metadata; scope is set by the entity params, not metadata.
+
+    On the update path `existing_payload` carries the memory's current scope, so
+    re-sending an identical value is silently accepted; only a changed value warns.
+    On the creation path there is no prior payload, so pass an empty dict and every
+    identity key present in `metadata` is dropped with a warning.
+    """
     clean = {}
     for key, value in metadata.items():
         if key not in _IDENTITY_KEYS:
             clean[key] = value
         elif value != existing_payload.get(key):
-            logger.warning(f"update(): ignoring metadata['{key}'] - identity fields are immutable after creation")
+            logger.warning(f"{context}: ignoring metadata['{key}'] - identity fields cannot be set through metadata")
     return clean
 
 
@@ -315,7 +327,9 @@ def _build_filters_and_metadata(
     for flexible session scoping and optionally narrows queries to a specific `actor_id`. It returns two dicts:
 
     1. `base_metadata_template`: Used as a template for metadata when storing new memories.
-       It includes all provided session identifier(s) and any `input_metadata`.
+       It includes all provided session identifier(s) and any `input_metadata`. Identity
+       scope is set from the entity params only; identity keys in `input_metadata` are
+       dropped, so freeform metadata cannot place a memory into an unrequested scope.
     2. `effective_query_filters`: Used for querying existing memories. It includes all
        provided session identifier(s), any `input_filters`, and a resolved actor
        identifier for targeted filtering if specified by any actor-related inputs.
@@ -343,7 +357,12 @@ def _build_filters_and_metadata(
               scoped to the provided session(s) and potentially a resolved actor.
     """
 
-    base_metadata_template = deepcopy(input_metadata) if input_metadata else {}
+    # Identity scope is set below from the entity params only. Stripping the keys here
+    # stops caller metadata from placing a memory into a scope the caller did not pass,
+    # which the re-pins below cannot prevent for a param that was left unset (issue #6655).
+    base_metadata_template = (
+        _strip_identity_keys(deepcopy(input_metadata), {}, context="add()") if input_metadata else {}
+    )
     effective_query_filters = deepcopy(input_filters) if input_filters else {}
 
     # ---------- validate and add all provided session ids ----------

mem0/memory/utils.py

@@ -121,6 +121,8 @@ def remove_code_blocks(content: str) -> str:
     - If a code block is detected, it returns only the inner content, stripping out the markers.
     - If no code block markers are found, the original content is returned as-is.
     """
+    if content is None:
+        return ""
     pattern = r"^```[a-zA-Z0-9]*\n([\s\S]*?)\n```$"
     match = re.match(pattern, content.strip())
     match_res=match.group(1).strip() if match else content.strip()
@@ -213,8 +215,8 @@ def parse_vision_messages(messages, llm=None, vision_details="auto"):
             try:
                 description = get_image_description(image_url, llm, vision_details)
                 returned_messages.append({"role": role, "content": description})
-            except Exception:
-                raise Exception(f"Error while downloading {image_url}.")
+            except Exception as e:
+                raise Exception(f"Error while downloading {image_url}.") from e
         else:
             # Regular text content
             returned_messages.append(msg)
@@ -227,7 +229,7 @@ def process_telemetry_filters(filters):
     Process the telemetry filters
     """
     if filters is None:
-        return {}
+        return [], {}
 
     encoded_ids = {}
     if "user_id" in filters:

mem0/reranker/cohere_reranker.py

@@ -1,6 +1,6 @@
 import logging
 import os
-from typing import List, Dict, Any
+from typing import Any, Dict, List
 
 from mem0.reranker.base import BaseReranker
 
@@ -84,7 +84,10 @@ class CohereReranker(BaseReranker):
         except Exception as e:
             # Fallback to original order if reranking fails
             logger.warning("Cohere reranking failed, falling back to original order: %s", e)
+            fallback_docs = []
             for doc in documents:
-                doc['rerank_score'] = 0.0
+                fallback_doc = doc.copy()
+                fallback_doc['rerank_score'] = 0.0
+                fallback_docs.append(fallback_doc)
             final_top_k = top_k or self.config.top_k
-            return documents[:final_top_k] if final_top_k else documents
+            return fallback_docs[:final_top_k] if final_top_k else fallback_docs

mem0/reranker/huggingface_reranker.py

@@ -1,14 +1,15 @@
 import logging
-from typing import List, Dict, Any, Union
+from typing import Any, Dict, List, Union
+
 import numpy as np
 
-from mem0.reranker.base import BaseReranker
 from mem0.configs.rerankers.base import BaseRerankerConfig
 from mem0.configs.rerankers.huggingface import HuggingFaceRerankerConfig
+from mem0.reranker.base import BaseReranker
 
 try:
-    from transformers import AutoTokenizer, AutoModelForSequenceClassification
     import torch
+    from transformers import AutoModelForSequenceClassification, AutoTokenizer
     TRANSFORMERS_AVAILABLE = True
 except ImportError:
     TRANSFORMERS_AVAILABLE = False
@@ -163,7 +164,10 @@ class HuggingFaceReranker(BaseReranker):
         except Exception as e:
             # Fallback to original order if reranking fails
             logger.warning("HuggingFace reranking failed, falling back to original order: %s", e)
+            fallback_docs = []
             for doc in documents:
-                doc['rerank_score'] = 0.0
+                fallback_doc = doc.copy()
+                fallback_doc['rerank_score'] = 0.0
+                fallback_docs.append(fallback_doc)
             final_top_k = top_k or self.config.top_k
-            return documents[:final_top_k] if final_top_k else documents
+            return fallback_docs[:final_top_k] if final_top_k else fallback_docs

mem0/reranker/sentence_transformer_reranker.py

@@ -1,10 +1,13 @@
 import logging
-from typing import List, Dict, Any, Union
+from typing import Any, Dict, List, Union
+
 import numpy as np
 
-from mem0.reranker.base import BaseReranker
 from mem0.configs.rerankers.base import BaseRerankerConfig
-from mem0.configs.rerankers.sentence_transformer import SentenceTransformerRerankerConfig
+from mem0.configs.rerankers.sentence_transformer import (
+    SentenceTransformerRerankerConfig,
+)
+from mem0.reranker.base import BaseReranker
 
 try:
     from sentence_transformers import CrossEncoder
@@ -108,7 +111,10 @@ class SentenceTransformerReranker(BaseReranker):
         except Exception as e:
             # Fallback to original order if reranking fails
             logger.warning("SentenceTransformer reranking failed, falling back to original order: %s", e)
+            fallback_docs = []
             for doc in documents:
-                doc['rerank_score'] = 0.0
+                fallback_doc = doc.copy()
+                fallback_doc['rerank_score'] = 0.0
+                fallback_docs.append(fallback_doc)
             final_top_k = top_k or self.config.top_k
-            return documents[:final_top_k] if final_top_k else documents
+            return fallback_docs[:final_top_k] if final_top_k else fallback_docs

mem0/reranker/zero_entropy_reranker.py

@@ -1,6 +1,6 @@
 import logging
 import os
-from typing import List, Dict, Any
+from typing import Any, Dict, List
 
 from mem0.reranker.base import BaseReranker
 
@@ -95,7 +95,10 @@ class ZeroEntropyReranker(BaseReranker):
         except Exception as e:
             # Fallback to original order if reranking fails
             logger.warning("Zero Entropy reranking failed, falling back to original order: %s", e)
+            fallback_docs = []
             for doc in documents:
-                doc['rerank_score'] = 0.0
+                fallback_doc = doc.copy()
+                fallback_doc['rerank_score'] = 0.0
+                fallback_docs.append(fallback_doc)
             final_top_k = top_k or self.config.top_k
-            return documents[:final_top_k] if final_top_k else documents
+            return fallback_docs[:final_top_k] if final_top_k else fallback_docs

mem0/utils/factory.py

@@ -19,7 +19,9 @@ from mem0.configs.rerankers.base import BaseRerankerConfig
 from mem0.configs.rerankers.cohere import CohereRerankerConfig
 from mem0.configs.rerankers.huggingface import HuggingFaceRerankerConfig
 from mem0.configs.rerankers.llm import LLMRerankerConfig
-from mem0.configs.rerankers.sentence_transformer import SentenceTransformerRerankerConfig
+from mem0.configs.rerankers.sentence_transformer import (
+    SentenceTransformerRerankerConfig,
+)
 from mem0.configs.rerankers.zero_entropy import ZeroEntropyRerankerConfig
 from mem0.embeddings.mock import MockEmbeddings
 
@@ -86,7 +88,7 @@ class LlmFactory:
             config = config_class(**kwargs)
         elif isinstance(config, dict):
             # Merge dict config with kwargs
-            config.update(kwargs)
+            config = {**config, **kwargs}
             config = config_class(**config)
         elif isinstance(config, BaseLlmConfig):
             # Convert base config to provider-specific config if needed

mem0/vector_stores/mongodb.py

@@ -15,7 +15,6 @@ except ImportError:
 from mem0.vector_stores.base import VectorStoreBase
 
 logger = logging.getLogger(__name__)
-logging.basicConfig(level=logging.INFO)
 
 _DRIVER_METADATA = DriverInfo(name="Mem0", version=version("mem0ai"))
 

mem0/vector_stores/upstash_vector.py

@@ -1,5 +1,6 @@
 import logging
-from typing import Dict, List, Optional
+import re
+from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel
 
@@ -13,6 +14,23 @@ except ImportError:
 
 logger = logging.getLogger(__name__)
 
+_SAFE_FILTER_KEY = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*\Z")
+
+
+def _validate_filter(key: str, value: Any) -> None:
+    if not isinstance(key, str) or not _SAFE_FILTER_KEY.fullmatch(key):
+        raise ValueError(f"Invalid filter key: {key!r}")
+    if not isinstance(value, (str, int, float, bool)):
+        raise ValueError(
+            f"Filter value for {key!r} must be str, int, float, or bool, "
+            f"got {type(value).__name__}"
+        )
+    if isinstance(value, str) and ('"' in value or "\\" in value):
+        raise ValueError(
+            f"Filter value for {key!r} contains prohibited characters "
+            f"(double quote or backslash): {value!r}"
+        )
+
 
 class OutputData(BaseModel):
     id: Optional[str]  # memory id
@@ -92,7 +110,9 @@ class UpstashVector(VectorStoreBase):
         )
 
     def _stringify(self, x):
-        return f'"{x}"' if isinstance(x, str) else x
+        if isinstance(x, str):
+            return f'"{x}"'
+        return x
 
     def search(
         self,
@@ -113,6 +133,9 @@ class UpstashVector(VectorStoreBase):
             List[OutputData]: Search results.
         """
 
+        if filters:
+            for k, v in filters.items():
+                _validate_filter(k, v)
         filters_str = " AND ".join([f"{k} = {self._stringify(v)}" for k, v in filters.items()]) if filters else None
 
         response = []
@@ -160,13 +183,16 @@ class UpstashVector(VectorStoreBase):
         Returns:
             List[OutputData]: Search results, or None if sparse/BM25 search is not supported.
         """
-        try:
-            filters_str = (
-                " AND ".join([f"{k} = {self._stringify(v)}" for k, v in filters.items()])
-                if filters
-                else None
-            )
+        if filters:
+            for k, v in filters.items():
+                _validate_filter(k, v)
+        filters_str = (
+            " AND ".join([f"{k} = {self._stringify(v)}" for k, v in filters.items()])
+            if filters
+            else None
+        )
 
+        try:
             response = self.client.query(
                 data=query,
                 top_k=top_k,
@@ -252,6 +278,9 @@ class UpstashVector(VectorStoreBase):
         Returns:
             List[OutputData]: Search results.
         """
+        if filters:
+            for k, v in filters.items():
+                _validate_filter(k, v)
         filters_str = " AND ".join([f"{k} = {self._stringify(v)}" for k, v in filters.items()]) if filters else None
 
         info = self.client.info()

mem0/vector_stores/vertex_ai_vector_search.py

@@ -22,7 +22,6 @@ from mem0.configs.vector_stores.vertex_ai_vector_search import (
 from mem0.vector_stores.base import VectorStoreBase
 
 # Configure logging
-logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)
 
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0ai"
-version = "2.0.15"
+version = "2.0.16"
 description = "Long-term memory for AI Agents"
 authors = [
     { name = "Mem0", email = "support@mem0.ai" }

tests/embeddings/test_huggingface_embeddings.py

@@ -94,7 +94,7 @@ def test_embed_with_huggingface_base_url():
         embedder = HuggingFaceEmbedding(config)
         result = embedder.embed("Hello from custom endpoint")
 
-        mock_openai.assert_called_once_with(base_url="http://localhost:8080")
+        mock_openai.assert_called_once_with(base_url="http://localhost:8080", api_key=None)
         mock_client.embeddings.create.assert_called_once_with(
             input="Hello from custom endpoint",
             model="my-custom-model",
@@ -103,6 +103,18 @@ def test_embed_with_huggingface_base_url():
         assert result == [0.1, 0.2, 0.3]
 
 
+def test_embed_with_huggingface_base_url_forwards_api_key():
+    config = BaseEmbedderConfig(
+        huggingface_base_url="http://localhost:8080",
+        model="my-custom-model",
+        api_key="tei-token",
+    )
+    with patch("mem0.embeddings.huggingface.OpenAI") as mock_openai:
+        HuggingFaceEmbedding(config)
+
+        mock_openai.assert_called_once_with(base_url="http://localhost:8080", api_key="tei-token")
+
+
 def test_embed_batch_sentence_transformer(mock_sentence_transformer):
     config = BaseEmbedderConfig()
     embedder = HuggingFaceEmbedding(config)

tests/memory/test_main.py

@@ -453,6 +453,95 @@ def test_update_memory_metadata_cannot_change_identity_fields(mocker, caplog):
     assert "ignoring metadata['user_id']" in caplog.text
 
 
+_ATTACKER_ADD_METADATA = {
+    "agent_id": "victim-agent",
+    "run_id": "victim-run",
+    "actor_id": "victim-actor",
+    "category": "sports",
+}
+
+
+def _captured_add_metadata(memory, mocker, **add_kwargs):
+    """Run add() with the pipeline stubbed and return the metadata template it produced."""
+    captured = {}
+
+    def _capture(messages, metadata, filters, infer, **kwargs):
+        captured.update(metadata)
+        return []
+
+    mocker.patch.object(memory, "_add_to_vector_store", side_effect=_capture)
+    memory.add("I like coffee", infer=False, **add_kwargs)
+    return captured
+
+
+def test_add_metadata_cannot_set_identity_fields(mocker, caplog):
+    """Regression (issue #6655): add() metadata must not inject identity scope.
+
+    The caller scopes by user_id only, so the agent_id/run_id re-pins in
+    _build_filters_and_metadata never fire and cannot defend the payload.
+    """
+    memory = _build_memory_instance(mocker, Memory)
+
+    with caplog.at_level(logging.WARNING, logger="mem0.memory.main"):
+        metadata = _captured_add_metadata(
+            memory, mocker, user_id="attacker", metadata=dict(_ATTACKER_ADD_METADATA)
+        )
+
+    assert metadata["user_id"] == "attacker"
+    for key in ("agent_id", "run_id", "actor_id"):
+        assert key not in metadata, f"{key} was injected through add() metadata"
+    # Non-identity metadata is untouched.
+    assert metadata["category"] == "sports"
+    assert "ignoring metadata['agent_id']" in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_async_add_metadata_cannot_set_identity_fields(mocker):
+    """Async counterpart of test_add_metadata_cannot_set_identity_fields."""
+    memory = _build_memory_instance(mocker, AsyncMemory)
+    captured = {}
+
+    async def _capture(messages, metadata, filters, infer, **kwargs):
+        captured.update(metadata)
+        return []
+
+    mocker.patch.object(memory, "_add_to_vector_store", side_effect=_capture)
+    await memory.add(
+        "I like coffee",
+        user_id="attacker",
+        metadata=dict(_ATTACKER_ADD_METADATA),
+        infer=False,
+    )
+
+    assert captured["user_id"] == "attacker"
+    for key in ("agent_id", "run_id", "actor_id"):
+        assert key not in captured, f"{key} was injected through async add() metadata"
+    assert captured["category"] == "sports"
+
+
+def test_add_entity_params_still_set_scope(mocker):
+    """The documented top-level params remain the only way to set scope."""
+    memory = _build_memory_instance(mocker, Memory)
+
+    metadata = _captured_add_metadata(
+        memory, mocker, user_id="u1", agent_id="a1", run_id="r1", metadata={"category": "sports"}
+    )
+
+    assert metadata["user_id"] == "u1"
+    assert metadata["agent_id"] == "a1"
+    assert metadata["run_id"] == "r1"
+    assert metadata["category"] == "sports"
+
+
+def test_add_without_metadata_is_unaffected(mocker):
+    """No metadata argument means no stripping and no behaviour change."""
+    memory = _build_memory_instance(mocker, Memory)
+
+    metadata = _captured_add_metadata(memory, mocker, user_id="u1")
+
+    assert metadata == {"user_id": "u1"}
+
+
 @pytest.mark.asyncio
 async def test_async_update_memory_metadata_cannot_change_identity_fields(mocker):
     """Async counterpart of test_update_memory_metadata_cannot_change_identity_fields."""

tests/memory/test_memory_utils.py

@@ -1,9 +1,12 @@
-import pytest
 from unittest.mock import Mock
 
+import pytest
+
 from mem0.memory.utils import (
     parse_messages,
     parse_vision_messages,
+    process_telemetry_filters,
+    remove_code_blocks,
     remove_spaces_from_entities,
     sanitize_relationship_for_cypher,
 )
@@ -114,6 +117,17 @@ class TestParseVisionMessages:
             parse_vision_messages(messages, llm=mock_llm)
         mock_llm.generate_response.assert_not_called()
 
+    def test_download_failure_preserves_original_exception(self):
+        mock_llm = Mock()
+        mock_llm.generate_response.side_effect = ValueError("network down")
+        messages = [
+            {"role": "user", "content": {"type": "image_url", "image_url": {"url": "https://example.com/img.png"}}}
+        ]
+        with pytest.raises(Exception) as exc_info:
+            parse_vision_messages(messages, llm=mock_llm)
+        assert isinstance(exc_info.value.__cause__, ValueError)
+        assert "network down" in str(exc_info.value.__cause__)
+
 
 class TestRemoveSpacesFromEntities:
     """
@@ -168,3 +182,13 @@ class TestRemoveSpacesFromEntities:
         f = remove_spaces_from_entities([dict(base)], sanitize_relationship=False)[0]["relationship"]
         assert t == sanitize_relationship_for_cypher("a/b")
         assert f == "a/b"
+
+
+class TestProcessTelemetryFilters:
+    def test_none_filters_returns_empty_list_and_dict(self):
+        assert process_telemetry_filters(None) == ([], {})
+
+
+class TestRemoveCodeBlocks:
+    def test_none_content_returns_empty_string(self):
+        assert remove_code_blocks(None) == ""

tests/rerankers/conftest.py

@@ -1,3 +1,5 @@
+import sys
+from types import ModuleType
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -9,3 +11,33 @@ def mock_llm():
         mock_llm_instance = MagicMock()
         mock_factory.create.return_value = mock_llm_instance
         yield mock_factory, mock_llm_instance
+
+
+@pytest.fixture
+def mock_cohere(monkeypatch):
+    """Provide a fake ``cohere`` module so CohereReranker imports/constructs."""
+    fake_cohere = ModuleType("cohere")
+    fake_client = MagicMock()
+    fake_cohere.Client = MagicMock(return_value=fake_client)
+    monkeypatch.setitem(sys.modules, "cohere", fake_cohere)
+
+    import mem0.reranker.cohere_reranker as cohere_reranker
+
+    monkeypatch.setattr(cohere_reranker, "cohere", fake_cohere, raising=False)
+    monkeypatch.setattr(cohere_reranker, "COHERE_AVAILABLE", True, raising=False)
+    return cohere_reranker, fake_client
+
+
+@pytest.fixture
+def mock_zero_entropy(monkeypatch):
+    """Provide a fake ``zeroentropy`` module so ZeroEntropyReranker imports."""
+    fake_module = ModuleType("zeroentropy")
+    fake_client = MagicMock()
+    fake_module.ZeroEntropy = MagicMock(return_value=fake_client)
+    monkeypatch.setitem(sys.modules, "zeroentropy", fake_module)
+
+    import mem0.reranker.zero_entropy_reranker as zero_entropy_reranker
+
+    monkeypatch.setattr(zero_entropy_reranker, "ZeroEntropy", fake_module.ZeroEntropy, raising=False)
+    monkeypatch.setattr(zero_entropy_reranker, "ZERO_ENTROPY_AVAILABLE", True, raising=False)
+    return zero_entropy_reranker, fake_client

tests/rerankers/test_reranker_fallback_no_mutation.py

@@ -0,0 +1,75 @@
+"""Regression tests pinning that the reranker fallback path never mutates caller-owned documents."""
+
+from unittest.mock import MagicMock, patch
+
+from mem0.configs.rerankers.cohere import CohereRerankerConfig
+from mem0.configs.rerankers.huggingface import HuggingFaceRerankerConfig
+from mem0.configs.rerankers.sentence_transformer import (
+    SentenceTransformerRerankerConfig,
+)
+from mem0.configs.rerankers.zero_entropy import ZeroEntropyRerankerConfig
+from mem0.reranker.huggingface_reranker import HuggingFaceReranker
+from mem0.reranker.sentence_transformer_reranker import SentenceTransformerReranker
+
+
+def _docs(n):
+    return [{"memory": f"doc{i}"} for i in range(n)]
+
+
+class TestCohereFallbackNoMutation:
+    def test_fallback_does_not_mutate_original_documents(self, mock_cohere):
+        module, fake_client = mock_cohere
+        fake_client.rerank.side_effect = RuntimeError("API error")
+
+        reranker = module.CohereReranker(CohereRerankerConfig(api_key="test-key"))
+        documents = _docs(3)
+        result = reranker.rerank("query", documents)
+
+        assert all("rerank_score" not in doc for doc in documents)
+        assert all(doc["rerank_score"] == 0.0 for doc in result)
+
+
+class TestZeroEntropyFallbackNoMutation:
+    def test_fallback_does_not_mutate_original_documents(self, mock_zero_entropy):
+        module, fake_client = mock_zero_entropy
+        fake_client.models.rerank.side_effect = RuntimeError("API error")
+
+        reranker = module.ZeroEntropyReranker(ZeroEntropyRerankerConfig(api_key="test-key"))
+        documents = _docs(3)
+        result = reranker.rerank("query", documents)
+
+        assert all("rerank_score" not in doc for doc in documents)
+        assert all(doc["rerank_score"] == 0.0 for doc in result)
+
+
+class TestHuggingFaceFallbackNoMutation:
+    def test_fallback_does_not_mutate_original_documents(self):
+        with (
+            patch("mem0.reranker.huggingface_reranker.AutoTokenizer") as mock_tokenizer_cls,
+            patch("mem0.reranker.huggingface_reranker.AutoModelForSequenceClassification") as mock_model_cls,
+        ):
+            mock_tokenizer = MagicMock(side_effect=RuntimeError("tokenizer error"))
+            mock_tokenizer_cls.from_pretrained.return_value = mock_tokenizer
+            mock_model_cls.from_pretrained.return_value = MagicMock()
+
+            reranker = HuggingFaceReranker(HuggingFaceRerankerConfig())
+            documents = _docs(3)
+            result = reranker.rerank("query", documents)
+
+        assert all("rerank_score" not in doc for doc in documents)
+        assert all(doc["rerank_score"] == 0.0 for doc in result)
+
+
+class TestSentenceTransformerFallbackNoMutation:
+    def test_fallback_does_not_mutate_original_documents(self):
+        with patch("mem0.reranker.sentence_transformer_reranker.CrossEncoder") as mock_cross_encoder_cls:
+            mock_model = MagicMock()
+            mock_model.predict.side_effect = RuntimeError("predict error")
+            mock_cross_encoder_cls.return_value = mock_model
+
+            reranker = SentenceTransformerReranker(SentenceTransformerRerankerConfig())
+            documents = _docs(3)
+            result = reranker.rerank("query", documents)
+
+        assert all("rerank_score" not in doc for doc in documents)
+        assert all(doc["rerank_score"] == 0.0 for doc in result)

tests/rerankers/test_reranker_fallback_topk.py

@@ -1,52 +1,9 @@
-"""Regression tests for the reranker fallback path honoring ``config.top_k``.
-
-When the underlying rerank call fails, the reranker falls back to returning the
-documents in their original order. That fallback must still respect the
-configured ``top_k`` limit, exactly like the success path does. The HuggingFace
-and SentenceTransformer rerankers already behave this way; these tests pin the
-same contract for the Cohere and ZeroEntropy rerankers.
-"""
-
-import sys
-from types import ModuleType
-from unittest.mock import MagicMock
-
-import pytest
+"""Regression tests pinning that the reranker fallback path still honors ``config.top_k``."""
 
 from mem0.configs.rerankers.cohere import CohereRerankerConfig
 from mem0.configs.rerankers.zero_entropy import ZeroEntropyRerankerConfig
 
 
-@pytest.fixture
-def mock_cohere(monkeypatch):
-    """Provide a fake ``cohere`` module so CohereReranker imports/constructs."""
-    fake_cohere = ModuleType("cohere")
-    fake_client = MagicMock()
-    fake_cohere.Client = MagicMock(return_value=fake_client)
-    monkeypatch.setitem(sys.modules, "cohere", fake_cohere)
-
-    import mem0.reranker.cohere_reranker as cohere_reranker
-
-    monkeypatch.setattr(cohere_reranker, "cohere", fake_cohere, raising=False)
-    monkeypatch.setattr(cohere_reranker, "COHERE_AVAILABLE", True, raising=False)
-    return cohere_reranker, fake_client
-
-
-@pytest.fixture
-def mock_zero_entropy(monkeypatch):
-    """Provide a fake ``zeroentropy`` module so ZeroEntropyReranker imports."""
-    fake_module = ModuleType("zeroentropy")
-    fake_client = MagicMock()
-    fake_module.ZeroEntropy = MagicMock(return_value=fake_client)
-    monkeypatch.setitem(sys.modules, "zeroentropy", fake_module)
-
-    import mem0.reranker.zero_entropy_reranker as zero_entropy_reranker
-
-    monkeypatch.setattr(zero_entropy_reranker, "ZeroEntropy", fake_module.ZeroEntropy, raising=False)
-    monkeypatch.setattr(zero_entropy_reranker, "ZERO_ENTROPY_AVAILABLE", True, raising=False)
-    return zero_entropy_reranker, fake_client
-
-
 def _docs(n):
     return [{"memory": f"doc{i}"} for i in range(n)]
 

tests/test_client.py

@@ -8,6 +8,8 @@ import httpx
 import pytest
 import requests
 
+from mem0.client.types import GetAllMemoryOptions, SearchMemoryOptions
+
 
 @pytest.fixture
 def mock_memory_client():
@@ -130,6 +132,55 @@ class TestGetAllEntityParamRejection:
         )
 
 
+class TestSearchTypedOptionsParity:
+    """MEM-5893: SearchMemoryOptions' new typed fields serialize to their v3 snake_case keys."""
+
+    def test_search_options_pass_reference_date_latest_only_keyword_search(self, mock_memory_client):
+        """search(options=SearchMemoryOptions(...)) should forward the new fields verbatim."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"results": []}
+        mock_response.raise_for_status.return_value = None
+        mock_memory_client.client.post.return_value = mock_response
+
+        options = SearchMemoryOptions(
+            filters={"user_id": "u1"},
+            reference_date="2024-01-01",
+            latest_only=True,
+            keyword_search=True,
+        )
+        mock_memory_client.search("test query", options=options)
+
+        mock_memory_client.client.post.assert_called_once_with(
+            "/v3/memories/search/",
+            json={
+                "query": "test query",
+                "filters": {"user_id": "u1"},
+                "reference_date": "2024-01-01",
+                "latest_only": True,
+                "keyword_search": True,
+            },
+        )
+
+
+class TestGetAllTypedOptionsParity:
+    """MEM-5893: GetAllMemoryOptions.latest_only serializes to its v3 snake_case key."""
+
+    def test_get_all_options_pass_latest_only(self, mock_memory_client):
+        """get_all(options=GetAllMemoryOptions(...)) should forward latest_only verbatim."""
+        mock_response = MagicMock()
+        mock_response.json.return_value = {"results": []}
+        mock_response.raise_for_status.return_value = None
+        mock_memory_client.client.post.return_value = mock_response
+
+        options = GetAllMemoryOptions(filters={"user_id": "u1"}, latest_only=True)
+        mock_memory_client.get_all(options=options)
+
+        mock_memory_client.client.post.assert_called_once_with(
+            "/v3/memories/",
+            json={"filters": {"user_id": "u1"}, "latest_only": True},
+        )
+
+
 class TestUpdateExpirationDate:
     """Tests for update expiration_date payload handling."""
 

tests/utils/test_factory.py

@@ -51,3 +51,12 @@ def test_base_to_provider_without_reasoning_fields_still_builds():
 
     assert isinstance(built, AnthropicConfig)
     assert built.model == "claude-3-5-sonnet-20240620"
+
+
+def test_dict_config_not_mutated_by_kwargs():
+    config = {"model": "gpt-4o-mini"}
+
+    with patch("mem0.utils.factory.load_class", return_value=Mock(return_value=Mock())):
+        LlmFactory.create("openai", config, api_key="secret")
+
+    assert config == {"model": "gpt-4o-mini"}

tests/vector_stores/test_upstash_vector.py

@@ -5,7 +5,7 @@ from unittest.mock import MagicMock, call, patch
 import pytest
 
 from mem0.configs.vector_stores.upstash_vector import UpstashVectorConfig
-from mem0.vector_stores.upstash_vector import UpstashVector
+from mem0.vector_stores.upstash_vector import UpstashVector, _validate_filter
 
 
 @dataclass
@@ -228,6 +228,57 @@ def test_update_vector_with_embeddings(upstash_instance_with_embeddings):
     )
 
 
+def test_filter_rejects_dict_value():
+    with pytest.raises(ValueError):
+        _validate_filter("user_id", {"$ne": ""})
+
+
+def test_filter_rejects_list_value():
+    with pytest.raises(ValueError):
+        _validate_filter("user_id", ["alice", "bob"])
+
+
+def test_filter_rejects_invalid_key():
+    with pytest.raises(ValueError):
+        _validate_filter("user_id; DROP", "alice")
+
+
+def test_filter_accepts_scalars():
+    _validate_filter("user_id", "alice")
+    _validate_filter("count", 42)
+    _validate_filter("score", 0.95)
+    _validate_filter("active", True)
+
+
+def test_filter_rejects_double_quote_in_value():
+    with pytest.raises(ValueError, match="prohibited characters"):
+        _validate_filter("user_id", 'alice" OR 1=1 --')
+
+
+def test_filter_rejects_backslash_in_value():
+    with pytest.raises(ValueError, match="prohibited characters"):
+        _validate_filter("user_id", "alice\\bob")
+
+
+def test_search_rejects_dict_filter(upstash_instance):
+    with pytest.raises(ValueError):
+        upstash_instance.search(
+            query="test", vectors=[[0.1]], filters={"user_id": {"$ne": ""}}
+        )
+
+
+def test_keyword_search_raises_on_invalid_filter(upstash_instance):
+    with pytest.raises(ValueError):
+        upstash_instance.keyword_search(
+            query="test", filters={"user_id": 'alice" OR 1=1'}
+        )
+
+
+def test_filter_rejects_key_with_trailing_newline():
+    with pytest.raises(ValueError, match="Invalid filter key"):
+        _validate_filter("user_id\n", "alice")
+
+
 def test_insert_vectors_with_embeddings_missing_data(upstash_instance_with_embeddings):
     vectors = [[0.1, 0.2, 0.3]]
     payloads = [{"name": "vector1"}]  # Missing data field