feat: add official mem0 CLI (Python & TypeScript) (#4575)

cli/node/tests/branding.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for branding utilities.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  BRAND_COLOR,
+  SUCCESS_COLOR,
+  ERROR_COLOR,
+  TAGLINE,
+  LOGO_MINI,
+  printSuccess,
+  printError,
+  printWarning,
+  printInfo,
+  printScope,
+} from "../src/branding.js";
+
+let output: string;
+let errOutput: string;
+const originalLog = console.log;
+const originalError = console.error;
+
+beforeEach(() => {
+  output = "";
+  errOutput = "";
+  console.log = (...args: unknown[]) => {
+    output += args.map(String).join(" ") + "\n";
+  };
+  console.error = (...args: unknown[]) => {
+    errOutput += args.map(String).join(" ") + "\n";
+  };
+});
+
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+describe("branding constants", () => {
+  it("has correct brand color", () => {
+    expect(BRAND_COLOR).toBe("#8b5cf6");
+  });
+
+  it("has correct tagline", () => {
+    expect(TAGLINE).toBe("The Memory Layer for AI Agents");
+  });
+
+  it("has correct logo mini", () => {
+    expect(LOGO_MINI).toBe("◆ mem0");
+  });
+});
+
+describe("printSuccess", () => {
+  it("prints success message", () => {
+    printSuccess("Operation completed");
+    expect(output).toContain("Operation completed");
+  });
+});
+
+describe("printError", () => {
+  it("prints error message to stderr", () => {
+    printError("Something failed");
+    expect(errOutput).toContain("Something failed");
+  });
+
+  it("prints hint when provided to stderr", () => {
+    printError("Failed", "Try again");
+    expect(errOutput).toContain("Try again");
+  });
+});
+
+describe("printWarning", () => {
+  it("prints warning message to stderr", () => {
+    printWarning("Be careful");
+    expect(errOutput).toContain("Be careful");
+  });
+});
+
+describe("printInfo", () => {
+  it("prints info message", () => {
+    printInfo("Important note");
+    expect(output).toContain("Important note");
+  });
+});
+
+describe("printScope", () => {
+  it("prints scope when IDs present", () => {
+    printScope({ user_id: "alice", agent_id: "bot" });
+    expect(output).toContain("alice");
+    expect(output).toContain("bot");
+  });
+
+  it("prints nothing when no IDs", () => {
+    printScope({});
+    expect(output).toBe("");
+  });
+});

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

@@ -0,0 +1,156 @@
+/**
+ * Integration tests — invoke CLI as subprocess to test end-to-end.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function run(
+  args: string[],
+  opts: { home?: string; env?: Record<string, string> } = {},
+): { stdout: string; stderr: string; exitCode: number } {
+  const env = { ...process.env };
+  // Strip MEM0_ env vars
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("MEM0_")) delete env[key];
+  }
+  if (opts.home) env.HOME = opts.home;
+  if (opts.env) Object.assign(env, opts.env);
+
+  try {
+    const stdout = execSync(
+      `npx tsx src/index.ts ${args.join(" ")}`,
+      { cwd: path.join(__dirname, ".."), env, encoding: "utf-8", timeout: 15000 },
+    );
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (e: any) {
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+      exitCode: e.status ?? 1,
+    };
+  }
+}
+
+describe("CLI Integration — help and version", () => {
+  it("shows help with --help", () => {
+    const result = run(["--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("mem0");
+    expect(result.stdout).toContain("add");
+    expect(result.stdout).toContain("search");
+  });
+
+  it("shows version with --version", () => {
+    const result = run(["--version"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("0.1.0");
+  });
+
+
+  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("shows add help", () => {
+    const result = run(["add", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("user-id");
+    expect(result.stdout).toContain("messages");
+  });
+
+  it("shows search help", () => {
+    const result = run(["search", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("top-k");
+  });
+
+  it("shows list help", () => {
+    const result = run(["list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("page-size");
+  });
+
+  it("shows delete help with --all, --entity, --project", () => {
+    const result = run(["delete", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--all");
+    expect(result.stdout).toContain("--entity");
+    expect(result.stdout).toContain("--project");
+    expect(result.stdout).toContain("--force");
+    expect(result.stdout.toLowerCase()).toContain("memory");
+  });
+
+  it("delete with no args errors", () => {
+    const result = run(["delete"]);
+    expect(result.exitCode).not.toBe(0);
+    const combined = result.stdout + result.stderr;
+    expect(combined).toContain("--all");
+  });
+
+  it("shows entity list help", () => {
+    const result = run(["entity", "list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.toLowerCase()).toContain("entitytype");
+  });
+
+  it("shows entity delete help", () => {
+    const result = run(["entity", "delete", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--user-id");
+    expect(result.stdout).toContain("--force");
+  });
+
+  it("shows import help", () => {
+    const result = run(["import", "--help"]);
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("add help has --graph flag", () => {
+    const result = run(["add", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+
+  it("search help has --graph flag", () => {
+    const result = run(["search", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+
+  it("list help has --graph flag", () => {
+    const result = run(["list", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--graph");
+  });
+});
+
+describe("CLI Integration — isolated (clean home)", () => {
+  function cleanHome(): string {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+  }
+
+  it("add without API key errors", () => {
+    const home = cleanHome();
+    const result = run(["add", "test", "--user-id", "alice"], { home });
+    expect(result.exitCode).not.toBe(0);
+    const combined = result.stdout + result.stderr;
+    expect(combined.toLowerCase()).toMatch(/api.key|error/i);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  it("config show works with clean home", () => {
+    const home = cleanHome();
+    const result = run(["config", "show"], { home });
+    expect(result.exitCode).toBe(0);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});

cli/node/tests/commands.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for CLI commands using mock backend.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createMockBackend } from "./setup.js";
+import type { Backend } from "../src/backend/base.js";
+
+let mockBackend: Backend;
+
+// Capture console.log and console.error output
+let output: string;
+let errOutput: string;
+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";
+  };
+});
+
+// Restore after each test
+import { afterEach } from "vitest";
+afterEach(() => {
+  console.log = originalLog;
+  console.error = originalError;
+});
+
+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,
+      noInfer: false,
+      enableGraph: 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,
+      noInfer: false,
+      enableGraph: 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,
+      noInfer: false,
+      enableGraph: 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,
+      noInfer: false,
+      enableGraph: false,
+      output: "quiet",
+    });
+    expect(output).not.toContain("dark mode");
+  });
+});
+
+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,
+      enableGraph: 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,
+      enableGraph: 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,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(output).toContain("No memories found");
+  });
+});
+
+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");
+  });
+});
+
+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,
+      enableGraph: false,
+      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,
+      enableGraph: false,
+      output: "text",
+    });
+    expect(output).toContain("No memories found");
+  });
+});
+
+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");
+  });
+});
+
+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");
+  });
+});
+
+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");
+  });
+});
+
+describe("cmdVersion", () => {
+  it("shows version", async () => {
+    const { cmdVersion } = await import("../src/commands/utils.js");
+    cmdVersion();
+    expect(output).toContain("0.1.0");
+  });
+});
+
+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");
+  });
+});

cli/node/tests/config.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for configuration management.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  createDefaultConfig,
+  loadConfig,
+  saveConfig,
+  redactKey,
+  getNestedValue,
+  setNestedValue,
+  CONFIG_DIR,
+  CONFIG_FILE,
+} from "../src/config.js";
+
+// Use a temp directory for config during tests
+let origConfigDir: string;
+let origConfigFile: string;
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+  // Monkey-patch the module-level constants
+  // We'll use env vars and direct file manipulation instead
+  // Clear MEM0_ env vars
+  for (const key of Object.keys(process.env)) {
+    if (key.startsWith("MEM0_")) {
+      delete process.env[key];
+    }
+  }
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("redactKey", () => {
+  it("returns '(not set)' for empty key", () => {
+    expect(redactKey("")).toBe("(not set)");
+  });
+
+  it("redacts short key", () => {
+    expect(redactKey("abc")).toBe("ab***");
+  });
+
+  it("redacts normal key", () => {
+    const result = redactKey("m0-abcdefgh12345678");
+    expect(result).toBe("m0-a...5678");
+    expect(result).not.toContain("abcdefgh");
+  });
+
+  it("redacts exactly 8-char key as short", () => {
+    expect(redactKey("12345678")).toBe("12***");
+  });
+});
+
+describe("createDefaultConfig", () => {
+  it("has correct defaults", () => {
+    const config = createDefaultConfig();
+    expect(config.platform.baseUrl).toBe("https://api.mem0.ai");
+    expect(config.platform.apiKey).toBe("");
+    expect(config.defaults.userId).toBe("");
+    expect(config.defaults.enableGraph).toBe(false);
+  });
+});
+
+describe("getNestedValue", () => {
+  it("gets platform.api_key", () => {
+    const config = createDefaultConfig();
+    config.platform.apiKey = "test-key";
+    expect(getNestedValue(config, "platform.api_key")).toBe("test-key");
+  });
+
+  it("returns undefined for nonexistent key", () => {
+    const config = createDefaultConfig();
+    expect(getNestedValue(config, "nonexistent.key")).toBeUndefined();
+  });
+
+  it("gets defaults.user_id", () => {
+    const config = createDefaultConfig();
+    config.defaults.userId = "alice";
+    expect(getNestedValue(config, "defaults.user_id")).toBe("alice");
+  });
+});
+
+describe("setNestedValue", () => {
+  it("sets platform.api_key", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "platform.api_key", "new-key")).toBe(true);
+    expect(config.platform.apiKey).toBe("new-key");
+  });
+
+  it("returns false for nonexistent key", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "nonexistent.key", "val")).toBe(false);
+  });
+
+  it("sets defaults.user_id", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "defaults.user_id", "bob")).toBe(true);
+    expect(config.defaults.userId).toBe("bob");
+  });
+
+  it("coerces boolean for enable_graph", () => {
+    const config = createDefaultConfig();
+    expect(setNestedValue(config, "defaults.enable_graph", "true")).toBe(true);
+    expect(config.defaults.enableGraph).toBe(true);
+  });
+});

cli/node/tests/output.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for output formatting.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  formatMemoriesText,
+  formatMemoriesTable,
+  formatJson,
+  formatSingleMemory,
+  formatAddResult,
+  printResultSummary,
+} from "../src/output.js";
+
+let output: string;
+const originalLog = console.log;
+
+beforeEach(() => {
+  output = "";
+  console.log = (...args: unknown[]) => {
+    output += args.map(String).join(" ") + "\n";
+  };
+});
+
+afterEach(() => {
+  console.log = originalLog;
+});
+
+const sampleMemories = [
+  {
+    id: "abc-123-def-456",
+    memory: "User prefers dark mode",
+    score: 0.92,
+    created_at: "2026-02-15T10:30:00Z",
+    categories: ["preferences"],
+  },
+  {
+    id: "ghi-789-jkl-012",
+    memory: "User uses vim keybindings",
+    score: 0.78,
+    created_at: "2026-03-01T14:00:00Z",
+    categories: ["tools"],
+  },
+];
+
+describe("formatMemoriesText", () => {
+  it("shows count and memory content", () => {
+    formatMemoriesText(sampleMemories);
+    expect(output).toContain("Found 2");
+    expect(output).toContain("dark mode");
+    expect(output).toContain("vim keybindings");
+  });
+
+  it("shows scores and IDs", () => {
+    formatMemoriesText(sampleMemories);
+    expect(output).toContain("0.92");
+    expect(output).toContain("abc-123-");
+  });
+});
+
+describe("formatMemoriesTable", () => {
+  it("renders a table with memory content", () => {
+    formatMemoriesTable(sampleMemories);
+    expect(output).toContain("dark mode");
+  });
+});
+
+describe("formatJson", () => {
+  it("outputs valid JSON", () => {
+    formatJson({ key: "value" });
+    expect(JSON.parse(output)).toEqual({ key: "value" });
+  });
+});
+
+describe("formatSingleMemory", () => {
+  it("shows memory text in text mode", () => {
+    formatSingleMemory(sampleMemories[0], "text");
+    expect(output).toContain("dark mode");
+  });
+
+  it("outputs JSON in json mode", () => {
+    formatSingleMemory(sampleMemories[0], "json");
+    expect(output).toContain("memory");
+  });
+});
+
+describe("formatAddResult", () => {
+  it("shows ADD event", () => {
+    formatAddResult({
+      results: [{ id: "abc-123", memory: "Test", event: "ADD" }],
+    });
+    expect(output).toContain("Added");
+  });
+
+  it("shows PENDING event", () => {
+    formatAddResult({
+      results: [{ status: "PENDING", event_id: "evt-12345678" }],
+    });
+    expect(output).toContain("Queued");
+  });
+});
+
+describe("printResultSummary", () => {
+  it("shows count and duration", () => {
+    printResultSummary({ count: 5, durationSecs: 1.23 });
+    expect(output).toContain("5 results");
+    expect(output).toContain("1.23s");
+  });
+
+  it("handles singular", () => {
+    printResultSummary({ count: 1 });
+    expect(output).toContain("1 result");
+    expect(output).not.toContain("results");
+  });
+});

cli/node/tests/setup.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared test helpers and mock factories for mem0 CLI tests.
+ */
+
+import { vi } from "vitest";
+import type { Backend } from "../src/backend/base.js";
+
+/** Create a mock backend with all methods stubbed with sensible defaults. */
+export function createMockBackend(): Backend {
+  return {
+    add: vi.fn().mockResolvedValue({
+      results: [
+        {
+          id: "abc-123-def-456",
+          memory: "User prefers dark mode",
+          event: "ADD",
+        },
+      ],
+    }),
+
+    search: vi.fn().mockResolvedValue([
+      {
+        id: "abc-123-def-456",
+        memory: "User prefers dark mode",
+        score: 0.92,
+        created_at: "2026-02-15T10:30:00Z",
+        categories: ["preferences"],
+      },
+      {
+        id: "ghi-789-jkl-012",
+        memory: "User uses vim keybindings",
+        score: 0.78,
+        created_at: "2026-03-01T14:00:00Z",
+        categories: ["tools"],
+      },
+    ]),
+
+    get: vi.fn().mockResolvedValue({
+      id: "abc-123-def-456",
+      memory: "User prefers dark mode",
+      created_at: "2026-02-15T10:30:00Z",
+      updated_at: "2026-02-20T08:00:00Z",
+      metadata: { source: "onboarding" },
+      categories: ["preferences"],
+    }),
+
+    listMemories: vi.fn().mockResolvedValue([
+      {
+        id: "abc-123-def-456",
+        memory: "User prefers dark mode",
+        created_at: "2026-02-15T10:30:00Z",
+        categories: ["preferences"],
+      },
+      {
+        id: "ghi-789-jkl-012",
+        memory: "User uses vim keybindings",
+        created_at: "2026-03-01T14:00:00Z",
+        categories: ["tools"],
+      },
+    ]),
+
+    update: vi.fn().mockResolvedValue({ id: "abc-123-def-456", memory: "Updated memory" }),
+    delete: vi.fn().mockResolvedValue({ status: "deleted" }),
+    status: vi.fn().mockResolvedValue({
+      connected: true,
+      backend: "platform",
+      base_url: "https://api.mem0.ai",
+    }),
+    deleteEntities: vi.fn().mockResolvedValue({ message: "Entity deleted" }),
+    entities: vi.fn().mockResolvedValue([
+      { name: "alice", count: 5 },
+      { name: "bob", count: 3 },
+    ]),
+  };
+}