feat(cli): remove mem0 version subcommand from md files and fix help --json in the Python CLI (#6773)

cli/node/README.md

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

cli/node/development.md

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

cli/node/src/commands/utils.ts

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

cli/node/src/index.ts

@@ -858,8 +858,8 @@ program
 	.addHelpText("after", "\nExamples:\n  $ mem0 help\n  $ mem0 help --json")
 	.action((opts) => {
 		// opts.json is set when `mem0 help --json` is used (subcommand flag).
-		// program.opts().json is set when the root --json global flag was used first.
-		if (opts.json || program.opts().json) {
+		// program.opts().json/.agent is set when a root global flag was used first.
+		if (opts.json || program.opts().json || program.opts().agent) {
 			// Load spec from parent directory
 			const __dirname = path.dirname(fileURLToPath(import.meta.url));
 			const specPath = path.join(__dirname, "..", "..", "cli-spec.json");

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

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

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

@@ -16,18 +16,45 @@ const OPENAPI_PATH = path.join(
 	"openapi.json",
 );
 
-const KNOWN_UNSURFACED: Record<string, Record<string, string>> = {};
+const KNOWN_UNSURFACED: Record<string, Record<string, string>> = {
+	"/v3/memories/add/": {
+		includes: "extraction hint, no CLI flag yet",
+		excludes: "extraction hint, no CLI flag yet",
+		enable_graph: "graph memory toggle, no CLI flag yet",
+		output_format: "response envelope is pinned by the CLI",
+		prompt_profile_id: "no CLI flag yet",
+		temporal_reasoning: "no CLI flag yet",
+		timezone: "no CLI flag yet",
+		observation_datetime: "no CLI flag yet, --timestamp backdates instead",
+		observation_date: "no CLI flag yet, --timestamp backdates instead",
+	},
+	"/v3/memories/search/": {
+		categories: "expressible through --filter",
+		metadata: "expressible through --filter",
+	},
+	"/v3/memories/": {
+		start_date: "covered by --after via filters.created_at.gte",
+		end_date: "covered by --before via filters.created_at.lte",
+		categories: "covered by --category via filters.categories",
+		fields: "no CLI flag yet",
+		keywords: "no CLI flag yet",
+	},
+};
 
 const ADD_MAPPING: Record<string, string[]> = {
 	messages: ["--messages", "--file", "text"],
 	user_id: ["--user-id"],
 	agent_id: ["--agent-id"],
+	app_id: ["--app-id"],
 	run_id: ["--run-id"],
 	metadata: ["--metadata"],
 	expiration_date: ["--expires"],
 	custom_instructions: ["--custom-instructions"],
 	custom_categories: ["--custom-categories"],
 	infer: ["--no-infer"],
+	immutable: ["--immutable"],
+	structured_data_schema: ["--structured-data-schema"],
+	timestamp: ["--timestamp"],
 };
 
 const SEARCH_MAPPING: Record<string, string[]> = {
@@ -38,6 +65,7 @@ const SEARCH_MAPPING: Record<string, string[]> = {
 	threshold: ["--threshold"],
 	rerank: ["--rerank"],
 	reference_date: ["--reference-date"],
+	fields: ["--fields"],
 };
 
 const LIST_MAPPING: Record<string, string[]> = {
@@ -50,6 +78,8 @@ const LIST_MAPPING: Record<string, string[]> = {
 		"--before",
 	],
 	show_expired: ["--show-expired"],
+	page: ["--page"],
+	page_size: ["--page-size"],
 };
 
 function documentedFields(endpoint: string): string[] {