The Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.
Python agentic-memoryagentic-memory-systemagentsaiai-agentschatgptgenaillmlong-term-memorymemorymemory-managementpythonragstate-management
feat(cli): Platform option parity across Python and Node CLIs (MEM-5893) (#6696)
Kartikc90bdbdce078
diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.ymlindex 8c8278aa6..eaf00275c 100644--- a/.github/workflows/ci-gate.yml+++ b/.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.ymlsecrets: 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 Pluginneeds: changes@@ -173,6 +186,7 @@ jobs:- cli-python- cli-node- openclaw+ - mem0-plugin- opencode-plugin- pi-agent-plugin- n8n-nodes-mem0diff --git a/.github/workflows/mem0-plugin-checks.yml b/.github/workflows/mem0-plugin-checks.ymlnew file mode 100644index 000000000..87eda7ada--- /dev/null+++ b/.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 -qdiff --git a/AGENTS.md b/AGENTS.mdindex ae9889730..384a92c0b 100644--- a/AGENTS.md+++ b/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 |diff --git a/cli/cli-spec.json b/cli/cli-spec.jsonindex 437bb8e46..c8cecad3a 100644--- a/cli/cli-spec.json+++ b/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" },diff --git a/cli/node/src/backend/base.ts b/cli/node/src/backend/base.tsindex be1a0ce1f..d66a3519d 100644--- a/cli/node/src/backend/base.ts+++ b/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(diff --git a/cli/node/src/backend/platform.ts b/cli/node/src/backend/platform.tsindex 0819bf3cb..f53b5dddc 100644--- a/cli/node/src/backend/platform.ts+++ b/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");diff --git a/cli/node/src/commands/memory.ts b/cli/node/src/commands/memory.tsindex 3b7b67b4f..3f5e5e621 100644--- a/cli/node/src/commands/memory.ts+++ b/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 {+ customCats = JSON.parse(opts.customCategories);+ } catch {+ printError("Invalid JSON in --custom-categories.");+ process.exit(1);+ }+ }++ let schema: Record<string, unknown> | undefined;+ if (opts.structuredDataSchema) {try {- cats = JSON.parse(opts.categories);+ schema = JSON.parse(opts.structuredDataSchema);} catch {- cats = opts.categories.split(",").map((c) => c.trim());+ 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));diff --git a/cli/node/src/index.ts b/cli/node/src/index.tsindex b038fb171..dfe46910f 100644--- a/cli/node/src/index.ts+++ b/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 @@ programkeyword: 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 @@ programcategory: 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 @@ programconst 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 @@ programoutput,dryRun: opts.dryRun,force: opts.force,+ deleteLinked: opts.deleteLinked,});return;}diff --git a/cli/node/src/output.ts b/cli/node/src/output.tsindex fa14849e7..84dffb1fe 100644--- a/cli/node/src/output.ts+++ b/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":diff --git a/cli/node/src/state.ts b/cli/node/src/state.tsindex 724068925..03ace9a4b 100644--- a/cli/node/src/state.ts+++ b/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;+ }+}diff --git a/cli/node/tests/commands.test.ts b/cli/node/tests/commands.test.tsindex 4cd43d1be..02789f056 100644--- a/cli/node/tests/commands.test.ts+++ b/cli/node/tests/commands.test.ts@@ -2,11 +2,11 @@* Tests for CLI commands using mock backend.*/-import { describe, it, expect, vi, beforeEach } from "vitest";import { Command } from "commander";-import { createMockBackend } from "./setup.js";+import { beforeEach, describe, expect, it, vi } from "vitest";import type { Backend } from "../src/backend/base.js";import { setAgentMode } from "../src/state.js";+import { createMockBackend } from "./setup.js";let mockBackend: Backend;@@ -17,450 +17,657 @@ const originalLog = console.log;const originalError = console.error;beforeEach(() => {- mockBackend = createMockBackend();- output = "";- errOutput = "";- console.log = (...args: unknown[]) => {- output += args.map(String).join(" ") + "\n";- };- console.error = (...args: unknown[]) => {- errOutput += args.map(String).join(" ") + "\n";- };+ mockBackend = createMockBackend();+ output = "";+ errOutput = "";+ console.log = (...args: unknown[]) => {+ output += args.map(String).join(" ") + "\n";+ };+ console.error = (...args: unknown[]) => {+ errOutput += args.map(String).join(" ") + "\n";+ };});// Restore after each testimport { afterEach } from "vitest";afterEach(() => {- console.log = originalLog;- console.error = originalError;- setAgentMode(false);+ console.log = originalLog;+ console.error = originalError;+ setAgentMode(false);});describe("cmdAdd", () => {- it("adds text memory", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "I prefer dark mode", {- userId: "alice",- immutable: false,- output: "text",- });- expect(mockBackend.add).toHaveBeenCalledOnce();- });-- it("adds from messages JSON", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, undefined, {- userId: "alice",- messages: JSON.stringify([{ role: "user", content: "I love Python" }]),- immutable: false,- output: "text",- });- expect(mockBackend.add).toHaveBeenCalledOnce();- });-- it("outputs json format", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test", {- userId: "alice",- immutable: false,- output: "json",- });- expect(output).toContain("results");- });-- it("quiet mode produces no memory content", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test", {- userId: "alice",- immutable: false,- output: "quiet",- });- expect(output).not.toContain("dark mode");- });+ it("adds text memory", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "I prefer dark mode", {+ userId: "alice",+ immutable: false,+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledOnce();+ });++ it("adds from messages JSON", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, undefined, {+ userId: "alice",+ messages: JSON.stringify([{ role: "user", content: "I love Python" }]),+ immutable: false,+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledOnce();+ });++ it("outputs json format", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ output: "json",+ });+ expect(output).toContain("results");+ });++ it("quiet mode produces no memory content", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ output: "quiet",+ });+ expect(output).not.toContain("dark mode");+ });});describe("cmdAdd forwards --no-infer (regression for #5261)", () => {- it("forwards infer: false when --no-infer is set", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- // `infer: false` is the shape Commander produces for `--no-infer`.- await cmdAdd(mockBackend, "store me verbatim", {- userId: "alice",- immutable: false,- infer: false,- output: "text",- });- expect(mockBackend.add).toHaveBeenCalledWith(- "store me verbatim",- undefined,- expect.objectContaining({ infer: false }),- );- });-- it("forwards infer: true by default (flag absent)", async () => {- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "infer me", {- userId: "alice",- immutable: false,- output: "text",- });- expect(mockBackend.add).toHaveBeenCalledWith(- "infer me",- undefined,- expect.objectContaining({ infer: true }),- );- });-- it("Commander stores --no-infer as opts.infer, not opts.noInfer", () => {- // Pins the assumption the fix relies on: Commander's `--no-X` option- // populates the positive camelCase key (`infer`), never `noInfer`.- const withFlag = new Command();- withFlag.option("--no-infer", "Skip inference, store raw.").action(() => {});- withFlag.parse(["--no-infer"], { from: "user" });- expect(withFlag.opts().infer).toBe(false);- expect(withFlag.opts().noInfer).toBeUndefined();-- const withoutFlag = new Command();- withoutFlag.option("--no-infer", "Skip inference, store raw.").action(() => {});- withoutFlag.parse([], { from: "user" });- expect(withoutFlag.opts().infer).toBe(true);- });+ it("forwards infer: false when --no-infer is set", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "store me verbatim", {+ userId: "alice",+ immutable: false,+ infer: false,+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledWith(+ "store me verbatim",+ undefined,+ expect.objectContaining({ infer: false }),+ );+ });++ it("forwards infer: true by default (flag absent)", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "infer me", {+ userId: "alice",+ immutable: false,+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledWith(+ "infer me",+ undefined,+ expect.objectContaining({ infer: true }),+ );+ });++ it("Commander stores --no-infer as opts.infer, not opts.noInfer", () => {+ const withFlag = new Command();+ withFlag+ .option("--no-infer", "Skip inference, store raw.")+ .action(() => {});+ withFlag.parse(["--no-infer"], { from: "user" });+ expect(withFlag.opts().infer).toBe(false);+ expect(withFlag.opts().noInfer).toBeUndefined();++ const withoutFlag = new Command();+ withoutFlag+ .option("--no-infer", "Skip inference, store raw.")+ .action(() => {});+ withoutFlag.parse([], { from: "user" });+ expect(withoutFlag.opts().infer).toBe(true);+ });+});++describe("cmdAdd forwards MEM-5893 option-parity flags", () => {+ it("forwards customInstructions, customCategories, structuredDataSchema, timestamp", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ customInstructions: "Extract only preferences.",+ customCategories: JSON.stringify([{ prefs: "user preferences" }]),+ structuredDataSchema: JSON.stringify({ type: "object" }),+ timestamp: 1700000000,+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledWith(+ "test",+ undefined,+ expect.objectContaining({+ customInstructions: "Extract only preferences.",+ customCategories: [{ prefs: "user preferences" }],+ structuredDataSchema: { type: "object" },+ timestamp: 1700000000,+ }),+ );+ });++ it("regression: metadata, expires, and customCategories reach the backend together", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ metadata: JSON.stringify({ source: "test" }),+ expires: "2099-01-01",+ customCategories: JSON.stringify([{ prefs: "user preferences" }]),+ output: "text",+ });+ expect(mockBackend.add).toHaveBeenCalledWith(+ "test",+ undefined,+ expect.objectContaining({+ metadata: { source: "test" },+ expires: "2099-01-01",+ customCategories: [{ prefs: "user preferences" }],+ }),+ );+ });+});++describe("cmdAdd rejects invalid input before calling the backend (MEM-5893)", () => {+ function mockProcessExit() {+ return vi.spyOn(process, "exit").mockImplementation(((code?: number) => {+ throw new Error(`process.exit:${code}`);+ }) as never);+ }++ it("rejects --categories with a message pointing to --custom-categories", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ const exitSpy = mockProcessExit();++ await expect(+ cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ categories: "prefs",+ output: "text",+ }),+ ).rejects.toThrow("process.exit:1");++ expect(errOutput).toContain("--custom-categories");+ expect(mockBackend.add).not.toHaveBeenCalled();+ exitSpy.mockRestore();+ });++ it("rejects invalid JSON in --custom-categories", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ const exitSpy = mockProcessExit();++ await expect(+ cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ customCategories: "not-json",+ output: "text",+ }),+ ).rejects.toThrow("process.exit:1");++ expect(errOutput).toContain("--custom-categories");+ expect(mockBackend.add).not.toHaveBeenCalled();+ exitSpy.mockRestore();+ });++ it("rejects invalid JSON in --structured-data-schema", async () => {+ const { cmdAdd } = await import("../src/commands/memory.js");+ const exitSpy = mockProcessExit();++ await expect(+ cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ structuredDataSchema: "not-json",+ output: "text",+ }),+ ).rejects.toThrow("process.exit:1");++ expect(errOutput).toContain("--structured-data-schema");+ expect(mockBackend.add).not.toHaveBeenCalled();+ exitSpy.mockRestore();+ });});describe("cmdAdd deduplicates PENDING", () => {- const DUPLICATE_PENDING = {- results: [- { status: "PENDING", event_id: "evt-dup" },- { status: "PENDING", event_id: "evt-dup" },- ],- };-- it("text shows one pending block", async () => {- (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test", {- userId: "alice",- immutable: false,- output: "text",- });- expect(output.match(/Queued/g)?.length).toBe(1);- });-- it("json shows one pending entry", async () => {- (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test", {- userId: "alice",- immutable: false,- output: "json",- });- const data = JSON.parse(output);- const pending = data.results.filter((r: Record<string, unknown>) => r.status === "PENDING");- expect(pending).toHaveLength(1);- });-- it("agent shows one pending entry", async () => {- (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(DUPLICATE_PENDING);- setAgentMode(true);- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test", {- userId: "alice",- immutable: false,- output: "agent",- });- const data = JSON.parse(output);- expect(data.count).toBe(1);- expect(data.data).toHaveLength(1);- });+ const DUPLICATE_PENDING = {+ results: [+ { status: "PENDING", event_id: "evt-dup" },+ { status: "PENDING", event_id: "evt-dup" },+ ],+ };++ it("text shows one pending block", async () => {+ (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(+ DUPLICATE_PENDING,+ );+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ output: "text",+ });+ expect(output.match(/Queued/g)?.length).toBe(1);+ });++ it("json shows one pending entry", async () => {+ (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(+ DUPLICATE_PENDING,+ );+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ output: "json",+ });+ const data = JSON.parse(output);+ const pending = data.results.filter(+ (r: Record<string, unknown>) => r.status === "PENDING",+ );+ expect(pending).toHaveLength(1);+ });++ it("agent shows one pending entry", async () => {+ (mockBackend.add as ReturnType<typeof vi.fn>).mockResolvedValue(+ DUPLICATE_PENDING,+ );+ setAgentMode(true);+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test", {+ userId: "alice",+ immutable: false,+ output: "agent",+ });+ const data = JSON.parse(output);+ expect(data.count).toBe(1);+ expect(data.data).toHaveLength(1);+ });});describe("cmdSearch", () => {- it("searches and shows results in text mode", async () => {- const { cmdSearch } = await import("../src/commands/memory.js");- await cmdSearch(mockBackend, "preferences", {- userId: "alice",- topK: 10,- threshold: 0.3,- rerank: false,- keyword: false,-- output: "text",- });- expect(output).toContain("Found 2");- });-- it("outputs json format", async () => {- const { cmdSearch } = await import("../src/commands/memory.js");- await cmdSearch(mockBackend, "preferences", {- userId: "alice",- topK: 10,- threshold: 0.3,- rerank: false,- keyword: false,-- output: "json",- });- expect(output).toContain("memory");- });-- it("shows no results message", async () => {- (mockBackend.search as ReturnType<typeof vi.fn>).mockResolvedValue([]);- const { cmdSearch } = await import("../src/commands/memory.js");- await cmdSearch(mockBackend, "nonexistent", {- userId: "alice",- topK: 10,- threshold: 0.3,- rerank: false,- keyword: false,-- output: "text",- });- expect(errOutput).toContain("No memories found");- });+ it("searches and shows results in text mode", async () => {+ const { cmdSearch } = await import("../src/commands/memory.js");+ await cmdSearch(mockBackend, "preferences", {+ userId: "alice",+ topK: 10,+ threshold: 0.3,+ rerank: false,+ keyword: false,++ output: "text",+ });+ expect(output).toContain("Found 2");+ });++ it("outputs json format", async () => {+ const { cmdSearch } = await import("../src/commands/memory.js");+ await cmdSearch(mockBackend, "preferences", {+ userId: "alice",+ topK: 10,+ threshold: 0.3,+ rerank: false,+ keyword: false,++ output: "json",+ });+ expect(output).toContain("memory");+ });++ it("shows no results message", async () => {+ (mockBackend.search as ReturnType<typeof vi.fn>).mockResolvedValue([]);+ const { cmdSearch } = await import("../src/commands/memory.js");+ await cmdSearch(mockBackend, "nonexistent", {+ userId: "alice",+ topK: 10,+ threshold: 0.3,+ rerank: false,+ keyword: false,++ output: "text",+ });+ expect(errOutput).toContain("No memories found");+ });++ it("forwards showExpired, referenceDate, latestOnly (MEM-5893)", async () => {+ const { cmdSearch } = await import("../src/commands/memory.js");+ await cmdSearch(mockBackend, "preferences", {+ userId: "alice",+ topK: 10,+ threshold: 0.3,+ rerank: false,+ keyword: false,+ showExpired: true,+ referenceDate: "2024-01-01",+ latestOnly: true,+ output: "text",+ });+ expect(mockBackend.search).toHaveBeenCalledWith(+ "preferences",+ expect.objectContaining({+ showExpired: true,+ referenceDate: "2024-01-01",+ latestOnly: true,+ }),+ );+ });});describe("cmdGet", () => {- it("gets memory in text mode", async () => {- const { cmdGet } = await import("../src/commands/memory.js");- await cmdGet(mockBackend, "abc-123-def-456", { output: "text" });- expect(output).toContain("dark mode");- });-- it("gets memory in json mode", async () => {- const { cmdGet } = await import("../src/commands/memory.js");- await cmdGet(mockBackend, "abc-123-def-456", { output: "json" });- expect(output).toContain("memory");- });+ it("gets memory in text mode", async () => {+ const { cmdGet } = await import("../src/commands/memory.js");+ await cmdGet(mockBackend, "abc-123-def-456", { output: "text" });+ expect(output).toContain("dark mode");+ });++ it("gets memory in json mode", async () => {+ const { cmdGet } = await import("../src/commands/memory.js");+ await cmdGet(mockBackend, "abc-123-def-456", { output: "json" });+ expect(output).toContain("memory");+ });});describe("cmdList", () => {- it("lists in table mode", async () => {- const { cmdList } = await import("../src/commands/memory.js");- await cmdList(mockBackend, {- userId: "alice",- page: 1,- pageSize: 100,-- output: "table",- });- expect(output).toContain("dark mode");- });-- it("shows empty message", async () => {- (mockBackend.listMemories as ReturnType<typeof vi.fn>).mockResolvedValue([]);- const { cmdList } = await import("../src/commands/memory.js");- await cmdList(mockBackend, {- userId: "alice",- page: 1,- pageSize: 100,-- output: "text",- });- expect(errOutput).toContain("No memories found");- });+ it("lists in table mode", async () => {+ const { cmdList } = await import("../src/commands/memory.js");+ await cmdList(mockBackend, {+ userId: "alice",+ page: 1,+ pageSize: 100,++ output: "table",+ });+ expect(output).toContain("dark mode");+ });++ it("shows empty message", async () => {+ (mockBackend.listMemories as ReturnType<typeof vi.fn>).mockResolvedValue(+ [],+ );+ const { cmdList } = await import("../src/commands/memory.js");+ await cmdList(mockBackend, {+ userId: "alice",+ page: 1,+ pageSize: 100,++ output: "text",+ });+ expect(errOutput).toContain("No memories found");+ });++ it("forwards showExpired and latestOnly (MEM-5893)", async () => {+ const { cmdList } = await import("../src/commands/memory.js");+ await cmdList(mockBackend, {+ userId: "alice",+ page: 1,+ pageSize: 100,+ showExpired: true,+ latestOnly: true,+ output: "text",+ });+ expect(mockBackend.listMemories).toHaveBeenCalledWith(+ expect.objectContaining({ showExpired: true, latestOnly: true }),+ );+ });});describe("cmdUpdate", () => {- it("updates memory", async () => {- const { cmdUpdate } = await import("../src/commands/memory.js");- await cmdUpdate(mockBackend, "abc-123", "New text", { output: "text" });- expect(output.toLowerCase()).toContain("updated");- });+ it("updates memory", async () => {+ const { cmdUpdate } = await import("../src/commands/memory.js");+ await cmdUpdate(mockBackend, "abc-123", "New text", { output: "text" });+ expect(output.toLowerCase()).toContain("updated");+ });++ it("forwards expires and timestamp (MEM-5893)", async () => {+ const { cmdUpdate } = await import("../src/commands/memory.js");+ await cmdUpdate(mockBackend, "abc-123", "New text", {+ expires: "2099-01-01",+ timestamp: 1700000000,+ output: "text",+ });+ expect(mockBackend.update).toHaveBeenCalledWith(+ "abc-123",+ "New text",+ undefined,+ expect.objectContaining({+ expirationDate: "2099-01-01",+ timestamp: 1700000000,+ }),+ );+ });});describe("cmdDelete", () => {- it("deletes memory", async () => {- const { cmdDelete } = await import("../src/commands/memory.js");- await cmdDelete(mockBackend, "abc-123", { output: "text" });- expect(output.toLowerCase()).toContain("deleted");- });+ it("deletes memory", async () => {+ const { cmdDelete } = await import("../src/commands/memory.js");+ await cmdDelete(mockBackend, "abc-123", { output: "text" });+ expect(output.toLowerCase()).toContain("deleted");+ });++ it("forwards deleteLinked (MEM-5893)", async () => {+ const { cmdDelete } = await import("../src/commands/memory.js");+ await cmdDelete(mockBackend, "abc-123", {+ deleteLinked: true,+ output: "text",+ });+ expect(mockBackend.delete).toHaveBeenCalledWith(+ "abc-123",+ expect.objectContaining({ deleteLinked: true }),+ );+ });});describe("cmdDeleteAll", () => {- it("deletes all with force", async () => {- const { cmdDeleteAll } = await import("../src/commands/memory.js");- await cmdDeleteAll(mockBackend, {- force: true,- userId: "alice",- output: "text",- });- expect(output.toLowerCase()).toContain("deleted");- });+ it("deletes all with force", async () => {+ const { cmdDeleteAll } = await import("../src/commands/memory.js");+ await cmdDeleteAll(mockBackend, {+ force: true,+ userId: "alice",+ output: "text",+ });+ expect(output.toLowerCase()).toContain("deleted");+ });});-describe("cmdEntitiesList", () => {- it("lists users in table mode", async () => {- const { cmdEntitiesList } = await import("../src/commands/entities.js");- await cmdEntitiesList(mockBackend, "users", { output: "table" });- expect(output).toContain("alice");- });-- it("lists in json mode", async () => {- const { cmdEntitiesList } = await import("../src/commands/entities.js");- await cmdEntitiesList(mockBackend, "users", { output: "json" });- expect(output).toContain("alice");- });+ it("lists users in table mode", async () => {+ const { cmdEntitiesList } = await import("../src/commands/entities.js");+ await cmdEntitiesList(mockBackend, "users", { output: "table" });+ expect(output).toContain("alice");+ });++ it("lists in json mode", async () => {+ const { cmdEntitiesList } = await import("../src/commands/entities.js");+ await cmdEntitiesList(mockBackend, "users", { output: "json" });+ expect(output).toContain("alice");+ });});describe("cmdEventList", () => {- it("lists events in table mode", async () => {- const { cmdEventList } = await import("../src/commands/events.js");- await cmdEventList(mockBackend, { output: "table" });- expect(output).toContain("evt-abc-");- expect(output).toContain("ADD");- expect(output).toContain("SUCCEEDED");- });-- it("lists events in json mode", async () => {- const { cmdEventList } = await import("../src/commands/events.js");- await cmdEventList(mockBackend, { output: "json" });- expect(output).toContain("evt-abc-123-def-456");- expect(output).toContain("evt-def-456-ghi-789");- });-- it("shows empty message when no events", async () => {- (mockBackend.listEvents as ReturnType<typeof vi.fn>).mockResolvedValueOnce([]);- const { cmdEventList } = await import("../src/commands/events.js");- await cmdEventList(mockBackend, { output: "table" });- expect((output + errOutput).toLowerCase()).toContain("no events");- });+ it("lists events in table mode", async () => {+ const { cmdEventList } = await import("../src/commands/events.js");+ await cmdEventList(mockBackend, { output: "table" });+ expect(output).toContain("evt-abc-");+ expect(output).toContain("ADD");+ expect(output).toContain("SUCCEEDED");+ });++ it("lists events in json mode", async () => {+ const { cmdEventList } = await import("../src/commands/events.js");+ await cmdEventList(mockBackend, { output: "json" });+ expect(output).toContain("evt-abc-123-def-456");+ expect(output).toContain("evt-def-456-ghi-789");+ });++ it("shows empty message when no events", async () => {+ (mockBackend.listEvents as ReturnType<typeof vi.fn>).mockResolvedValueOnce(+ [],+ );+ const { cmdEventList } = await import("../src/commands/events.js");+ await cmdEventList(mockBackend, { output: "table" });+ expect((output + errOutput).toLowerCase()).toContain("no events");+ });});describe("cmdEventStatus", () => {- it("shows event details in text mode", async () => {- const { cmdEventStatus } = await import("../src/commands/events.js");- await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "text" });- expect(output).toContain("evt-abc-123-def-456");- expect(output).toContain("SUCCEEDED");- });-- it("shows event details in json mode", async () => {- const { cmdEventStatus } = await import("../src/commands/events.js");- await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "json" });- expect(output).toContain("evt-abc-123-def-456");- expect(output).toContain("ADD");- });+ it("shows event details in text mode", async () => {+ const { cmdEventStatus } = await import("../src/commands/events.js");+ await cmdEventStatus(mockBackend, "evt-abc-123-def-456", {+ output: "text",+ });+ expect(output).toContain("evt-abc-123-def-456");+ expect(output).toContain("SUCCEEDED");+ });++ it("shows event details in json mode", async () => {+ const { cmdEventStatus } = await import("../src/commands/events.js");+ await cmdEventStatus(mockBackend, "evt-abc-123-def-456", {+ output: "json",+ });+ expect(output).toContain("evt-abc-123-def-456");+ expect(output).toContain("ADD");+ });});describe("agent mode", () => {- it("cmdAdd outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdAdd } = await import("../src/commands/memory.js");- await cmdAdd(mockBackend, "test preference", {- userId: "alice",- immutable: false,- output: "agent",- });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("add");- expect(parsed.data).toBeDefined();- expect(parsed.scope).toMatchObject({ user_id: "alice" });- expect(Object.keys(parsed.data[0]).sort()).toEqual(["event", "id", "memory"].sort());- });-- it("cmdSearch outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdSearch } = await import("../src/commands/memory.js");- await cmdSearch(mockBackend, "preferences", {- userId: "alice",- topK: 10,- threshold: 0.3,- rerank: false,- keyword: false,-- output: "agent",- });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("search");- expect(Array.isArray(parsed.data)).toBe(true);- expect(parsed.count).toBe(2);- const keys = Object.keys(parsed.data[0]);- expect(keys).toContain("id");- expect(keys).toContain("memory");- expect(keys).toContain("score");- expect(keys).toContain("created_at");- expect(keys).toContain("categories");- expect(keys).not.toContain("user_id");- expect(keys).not.toContain("agent_id");- });-- it("cmdList outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdList } = await import("../src/commands/memory.js");- await cmdList(mockBackend, {- userId: "alice",- page: 1,- pageSize: 100,-- output: "agent",- });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("list");- expect(Array.isArray(parsed.data)).toBe(true);- expect(parsed.count).toBe(2);- expect(Object.keys(parsed.data[0]).sort()).toEqual(["categories", "created_at", "id", "memory"]);- });-- it("cmdGet outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdGet } = await import("../src/commands/memory.js");- await cmdGet(mockBackend, "abc-123-def-456", { output: "agent" });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("get");- expect(parsed.data).toBeDefined();- expect(parsed.data).toMatchObject({ id: "abc-123-def-456" });- expect(Object.keys(parsed.data)).not.toContain("user_id");- });-- it("cmdUpdate outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdUpdate } = await import("../src/commands/memory.js");- await cmdUpdate(mockBackend, "abc-123", "Updated text", { output: "agent" });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("update");- expect(parsed.data).toBeDefined();- });-- it("cmdDelete outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdDelete } = await import("../src/commands/memory.js");- await cmdDelete(mockBackend, "abc-123", { output: "agent" });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("delete");- expect(parsed.data).toBeDefined();- });-- it("cmdEventList outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdEventList } = await import("../src/commands/events.js");- await cmdEventList(mockBackend, { output: "agent" });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("event list");- expect(Array.isArray(parsed.data)).toBe(true);- expect(parsed.count).toBe(2);- expect(Object.keys(parsed.data[0]).sort()).toEqual(- ["created_at", "event_type", "id", "latency", "status"],- );- expect(Object.keys(parsed.data[0])).not.toContain("updated_at");- });-- it("cmdEventStatus outputs JSON envelope", async () => {- setAgentMode(true);- const { cmdEventStatus } = await import("../src/commands/events.js");- await cmdEventStatus(mockBackend, "evt-abc-123-def-456", { output: "agent" });- const parsed = JSON.parse(output.trim());- expect(parsed.status).toBe("success");- expect(parsed.command).toBe("event status");- expect(parsed.data).toBeDefined();- expect(parsed.data).toMatchObject({ id: "evt-abc-123-def-456" });- expect(parsed.data.results[0]).toHaveProperty("memory");- expect(parsed.data.results[0]).not.toHaveProperty("data");- });+ it("cmdAdd outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdAdd } = await import("../src/commands/memory.js");+ await cmdAdd(mockBackend, "test preference", {+ userId: "alice",+ immutable: false,+ output: "agent",+ });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("add");+ expect(parsed.data).toBeDefined();+ expect(parsed.scope).toMatchObject({ user_id: "alice" });+ expect(Object.keys(parsed.data[0]).sort()).toEqual(+ ["event", "id", "memory"].sort(),+ );+ });++ it("cmdSearch outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdSearch } = await import("../src/commands/memory.js");+ await cmdSearch(mockBackend, "preferences", {+ userId: "alice",+ topK: 10,+ threshold: 0.3,+ rerank: false,+ keyword: false,++ output: "agent",+ });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("search");+ expect(Array.isArray(parsed.data)).toBe(true);+ expect(parsed.count).toBe(2);+ const keys = Object.keys(parsed.data[0]);+ expect(keys).toContain("id");+ expect(keys).toContain("memory");+ expect(keys).toContain("score");+ expect(keys).toContain("created_at");+ expect(keys).toContain("categories");+ expect(keys).not.toContain("user_id");+ expect(keys).not.toContain("agent_id");+ });++ it("cmdList outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdList } = await import("../src/commands/memory.js");+ await cmdList(mockBackend, {+ userId: "alice",+ page: 1,+ pageSize: 100,++ output: "agent",+ });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("list");+ expect(Array.isArray(parsed.data)).toBe(true);+ expect(parsed.count).toBe(2);+ expect(Object.keys(parsed.data[0]).sort()).toEqual([+ "categories",+ "created_at",+ "id",+ "memory",+ ]);+ });++ it("cmdGet outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdGet } = await import("../src/commands/memory.js");+ await cmdGet(mockBackend, "abc-123-def-456", { output: "agent" });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("get");+ expect(parsed.data).toBeDefined();+ expect(parsed.data).toMatchObject({ id: "abc-123-def-456" });+ expect(Object.keys(parsed.data)).not.toContain("user_id");+ });++ it("cmdUpdate outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdUpdate } = await import("../src/commands/memory.js");+ await cmdUpdate(mockBackend, "abc-123", "Updated text", {+ output: "agent",+ });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("update");+ expect(parsed.data).toBeDefined();+ });++ it("cmdDelete outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdDelete } = await import("../src/commands/memory.js");+ await cmdDelete(mockBackend, "abc-123", { output: "agent" });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("delete");+ expect(parsed.data).toBeDefined();+ });++ it("cmdEventList outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdEventList } = await import("../src/commands/events.js");+ await cmdEventList(mockBackend, { output: "agent" });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("event list");+ expect(Array.isArray(parsed.data)).toBe(true);+ expect(parsed.count).toBe(2);+ expect(Object.keys(parsed.data[0]).sort()).toEqual([+ "created_at",+ "event_type",+ "id",+ "latency",+ "status",+ ]);+ expect(Object.keys(parsed.data[0])).not.toContain("updated_at");+ });++ it("cmdEventStatus outputs JSON envelope", async () => {+ setAgentMode(true);+ const { cmdEventStatus } = await import("../src/commands/events.js");+ await cmdEventStatus(mockBackend, "evt-abc-123-def-456", {+ output: "agent",+ });+ const parsed = JSON.parse(output.trim());+ expect(parsed.status).toBe("success");+ expect(parsed.command).toBe("event status");+ expect(parsed.data).toBeDefined();+ expect(parsed.data).toMatchObject({ id: "evt-abc-123-def-456" });+ expect(parsed.data.results[0]).toHaveProperty("memory");+ expect(parsed.data.results[0]).not.toHaveProperty("data");+ });});diff --git a/cli/node/tests/option-parity.test.ts b/cli/node/tests/option-parity.test.tsnew file mode 100644index 000000000..72f46a5f2--- /dev/null+++ b/cli/node/tests/option-parity.test.ts@@ -0,0 +1,133 @@+/**+ * 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>> = {};++const ADD_MAPPING: Record<string, string[]> = {+ messages: ["--messages", "--file", "text"],+ user_id: ["--user-id"],+ agent_id: ["--agent-id"],+ run_id: ["--run-id"],+ metadata: ["--metadata"],+ expiration_date: ["--expires"],+ custom_instructions: ["--custom-instructions"],+ custom_categories: ["--custom-categories"],+ infer: ["--no-infer"],+};++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"],+};++const LIST_MAPPING: Record<string, string[]> = {+ filters: [+ "--user-id",+ "--agent-id",+ "--run-id",+ "--category",+ "--after",+ "--before",+ ],+ show_expired: ["--show-expired"],+};++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);+ }+ });+ }+});diff --git a/cli/node/tests/platform-backend.test.ts b/cli/node/tests/platform-backend.test.tsindex cb577a638..62c71305a 100644--- a/cli/node/tests/platform-backend.test.ts+++ b/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]);-- 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);- });-- 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" } });- });-- 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("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",+ });++ 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",+ });++ 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",+ );+ });+});++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();-- 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",- ]);- });-- 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");-- 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/",- ]);- });+ 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");++ 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();++ 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/",+ ]);+ });});diff --git a/cli/python/src/mem0_cli/app.py b/cli/python/src/mem0_cli/app.pyindex 850bfa0cd..9eb4f58ef 100644--- a/cli/python/src/mem0_cli/app.py+++ b/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_deletebackend = _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.",diff --git a/cli/python/src/mem0_cli/backend/base.py b/cli/python/src/mem0_cli/backend/base.pyindex 183e0bfa1..e5788b056 100644--- a/cli/python/src/mem0_cli/backend/base.py+++ b/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]: ...@abstractmethoddef 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: ...@abstractmethoddiff --git a/cli/python/src/mem0_cli/backend/platform.py b/cli/python/src/mem0_cli/backend/platform.pyindex 1df3deadd..083c804e6 100644--- a/cli/python/src/mem0_cli/backend/platform.py+++ b/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"] = Falseif 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"] = timestamppayload["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"] = Trueif 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"] = Truepayload["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"] = Truepayload["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"] = contentif metadata:payload["metadata"] = metadata+ if expiration_date:+ payload["expiration_date"] = expiration_date+ if timestamp is not None:+ payload["timestamp"] = timestamppayload["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_idreturn 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")diff --git a/cli/python/src/mem0_cli/commands/memory.py b/cli/python/src/mem0_cli/commands/memory.pyindex 7e9ace6e4..315cde280 100644--- a/cli/python/src/mem0_cli/commands/memory.py+++ b/cli/python/src/mem0_cli/commands/memory.py@@ -4,9 +4,11 @@ from __future__ import annotationsimport jsonimport os+import reimport stat as _stat_modimport sysimport time as _time+from datetime import datefrom pathlib import Pathimport 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 = Nonecontent = 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(",")]-- # Validate --expires- if expires:- import re+ print_error(err_console, "Invalid JSON in --custom-categories.")+ raise typer.Exit(1) from None- 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+ 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- if date.fromisoformat(expires) <= date.today():- print_error(err_console, "--expires date must be in the future.")- raise typer.Exit(1)+ if expires:+ _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 Nonediff --git a/cli/python/src/mem0_cli/output.py b/cli/python/src/mem0_cli/output.pyindex 8aad44bbb..dc1524d33 100644--- a/cli/python/src/mem0_cli/output.py+++ b/cli/python/src/mem0_cli/output.py@@ -262,16 +262,32 @@ def sanitize_agent_data(command: str, data: Any) -> Any:return resultif 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 datadiff --git a/cli/python/tests/test_commands.py b/cli/python/tests/test_commands.pyindex 4fd6a0c39..ad900f605 100644--- a/cli/python/tests/test_commands.py+++ b/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):diff --git a/cli/python/tests/test_option_parity.py b/cli/python/tests/test_option_parity.pynew file mode 100644index 000000000..191cb32f4--- /dev/null+++ b/cli/python/tests/test_option_parity.py@@ -0,0 +1,78 @@+"""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] = {}++ADD_MAPPING: dict[str, list[str]] = {+ "messages": ["messages", "file", "text"],+ "user_id": ["user_id"],+ "agent_id": ["agent_id"],+ "run_id": ["run_id"],+ "metadata": ["metadata"],+ "expiration_date": ["expires"],+ "custom_instructions": ["custom_instructions"],+ "custom_categories": ["custom_categories"],+ "infer": ["no_infer"],+}++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"],+}++LIST_MAPPING: dict[str, list[str]] = {+ "filters": ["user_id", "agent_id", "run_id", "category", "after", "before"],+ "show_expired": ["show_expired"],+}+++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")diff --git a/cli/python/tests/test_platform_backend_options.py b/cli/python/tests/test_platform_backend_options.pynew file mode 100644index 000000000..9559864d2--- /dev/null+++ b/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.kwargsdiff --git a/docs/platform/cli.mdx b/docs/platform/cli.mdxindex 399216632..f2547997d 100644--- a/docs/platform/cli.mdx+++ b/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 |diff --git a/integrations/mem0-plugin/scripts/load_settings.py b/integrations/mem0-plugin/scripts/load_settings.pyindex 58a53b569..139d180c6 100644--- a/integrations/mem0-plugin/scripts/load_settings.py+++ b/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 sysif 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()))diff --git a/integrations/mem0-plugin/tests/conftest.py b/integrations/mem0-plugin/tests/conftest.pyindex ab3eb809c..a170017f5 100644--- a/integrations/mem0-plugin/tests/conftest.py+++ b/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()diff --git a/integrations/mem0-plugin/tests/test_load_settings.py b/integrations/mem0-plugin/tests/test_load_settings.pynew file mode 100644index 000000000..0f3216256--- /dev/null+++ b/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+++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() == []++[email protected]("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 seconddiff --git a/mem0-ts/src/client/mem0.types.ts b/mem0-ts/src/client/mem0.types.tsindex d4f54b53f..b66d4a444 100644--- a/mem0-ts/src/client/mem0.types.ts+++ b/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 {diff --git a/mem0-ts/src/client/tests/memoryClient.search.test.ts b/mem0-ts/src/client/tests/memoryClient.search.test.tsindex 9b36babe3..021187867 100644--- a/mem0-ts/src/client/tests/memoryClient.search.test.ts+++ b/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/", {diff --git a/mem0/client/types.py b/mem0/client/types.pyindex 62df27629..527bc2fc6 100644--- a/mem0/client/types.py+++ b/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):diff --git a/tests/test_client.py b/tests/test_client.pyindex 8aa554763..aa8c16ce5 100644--- a/tests/test_client.py+++ b/tests/test_client.py@@ -8,6 +8,8 @@ import httpximport pytestimport requests+from mem0.client.types import GetAllMemoryOptions, SearchMemoryOptions+@pytest.fixturedef 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."""