@mem0/cli 0.1.0

package/src/output.ts

@@ -0,0 +1,230 @@
+/**
+ * Output formatting for mem0 CLI — text, JSON, table, quiet modes.
+ */
+
+import Table from "cli-table3";
+import boxen from "boxen";
+import { colors, sym } from "./branding.js";
+
+const { brand, accent, success, error: errorColor, dim } = colors;
+
+function formatDate(dtStr?: string): string | undefined {
+  if (!dtStr) return undefined;
+  try {
+    const dt = new Date(dtStr.replace("Z", "+00:00"));
+    return dt.toISOString().slice(0, 10);
+  } catch {
+    return dtStr?.slice(0, 10);
+  }
+}
+
+export function formatMemoriesText(
+  memories: Record<string, unknown>[],
+  title = "memories",
+): void {
+  const count = memories.length;
+  console.log(`\n${brand(`Found ${count} ${title}:`)}\n`);
+
+  for (let i = 0; i < memories.length; i++) {
+    const mem = memories[i];
+    const memoryText = (mem.memory ?? mem.text ?? "") as string;
+    const memId = ((mem.id as string) ?? "").slice(0, 8);
+    const score = mem.score as number | undefined;
+    const created = formatDate(mem.created_at as string | undefined);
+    let category: string | undefined;
+    const cats = mem.categories;
+    if (Array.isArray(cats)) {
+      category = cats[0] as string | undefined;
+    }
+
+    console.log(`  ${i + 1}. ${memoryText}`);
+
+    const details: string[] = [];
+    if (score !== undefined) details.push(`Score: ${score.toFixed(2)}`);
+    if (memId) details.push(`ID: ${memId}`);
+    if (created) details.push(`Created: ${created}`);
+    if (category) details.push(`Category: ${category}`);
+
+    if (details.length > 0) {
+      console.log(`     ${dim(details.join(" · "))}`);
+    }
+    console.log();
+  }
+}
+
+export function formatMemoriesTable(memories: Record<string, unknown>[]): void {
+  const table = new Table({
+    head: [accent("ID"), accent("Memory"), accent("Category"), accent("Created")],
+    colWidths: [12, 52, 16, 14],
+    wordWrap: true,
+    style: { head: [], border: [] },
+  });
+
+  for (const mem of memories) {
+    const memId = ((mem.id as string) ?? "").slice(0, 8);
+    let memoryText = (mem.memory ?? mem.text ?? "") as string;
+    if (memoryText.length > 60) {
+      memoryText = memoryText.slice(0, 57) + "...";
+    }
+    const categories = mem.categories;
+    const cat =
+      Array.isArray(categories) && categories.length > 0
+        ? (categories[0] as string)
+        : "—";
+    const created = formatDate(mem.created_at as string | undefined) ?? "—";
+    table.push([dim(memId), memoryText, cat, created]);
+  }
+
+  console.log();
+  console.log(table.toString());
+  console.log();
+}
+
+export function formatJson(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export function formatSingleMemory(
+  mem: Record<string, unknown>,
+  output = "text",
+): void {
+  if (output === "json") {
+    formatJson(mem);
+    return;
+  }
+
+  const memoryText = (mem.memory ?? mem.text ?? "") as string;
+  const memId = (mem.id ?? "") as string;
+
+  const lines: string[] = [];
+  lines.push(`  ${memoryText}`);
+  lines.push("");
+
+  if (memId) lines.push(`  ${dim("ID:")}         ${memId}`);
+  const created = formatDate(mem.created_at as string | undefined);
+  if (created) lines.push(`  ${dim("Created:")}    ${created}`);
+  const updated = formatDate(mem.updated_at as string | undefined);
+  if (updated) lines.push(`  ${dim("Updated:")}    ${updated}`);
+  const meta = mem.metadata;
+  if (meta) lines.push(`  ${dim("Metadata:")}   ${JSON.stringify(meta)}`);
+  const categories = mem.categories;
+  if (categories) {
+    const catStr = Array.isArray(categories) ? categories.join(", ") : String(categories);
+    lines.push(`  ${dim("Categories:")} ${catStr}`);
+  }
+
+  const content = lines.join("\n");
+  console.log();
+  console.log(
+    boxen(content, {
+      title: brand("Memory"),
+      titleAlignment: "left",
+      borderColor: "magenta",
+      padding: 1,
+    }),
+  );
+  console.log();
+}
+
+export function formatAddResult(
+  result: Record<string, unknown> | Record<string, unknown>[],
+  output = "text",
+): void {
+  if (output === "json") {
+    formatJson(result);
+    return;
+  }
+  if (output === "quiet") return;
+
+  const results: Record<string, unknown>[] = Array.isArray(result)
+    ? result
+    : ((result.results as Record<string, unknown>[]) ?? [result]);
+
+  if (!results.length) {
+    console.log(`  ${dim("No memories extracted.")}`);
+    return;
+  }
+
+  console.log();
+  for (const r of results) {
+    // Detect async PENDING response
+    if (r.status === "PENDING") {
+      const eventId = ((r.event_id as string) ?? "").slice(0, 8);
+      const icon = accent(sym("⧗", "..."));
+      const parts = [`  ${icon} ${dim("Queued".padEnd(10))}`, "Processing in background"];
+      if (eventId) parts.push(dim(`(event ${eventId})`));
+      console.log(parts.join("  "));
+      continue;
+    }
+
+    const event = (r.event ?? "ADD") as string;
+    const memory = (r.memory ?? r.text ?? r.content ?? r.data ?? "") as string;
+    const memId = ((r.id as string) ?? (r.memory_id as string) ?? "").slice(0, 8);
+
+    let icon: string;
+    let label: string;
+    if (event === "ADD") {
+      icon = success("+");
+      label = "Added";
+    } else if (event === "UPDATE") {
+      icon = accent("~");
+      label = "Updated";
+    } else if (event === "DELETE") {
+      icon = errorColor("-");
+      label = "Deleted";
+    } else if (event === "NOOP") {
+      icon = dim("·");
+      label = "No change";
+    } else {
+      icon = dim("?");
+      label = event;
+    }
+
+    const parts = [`  ${icon} ${dim(label.padEnd(10))}`];
+    if (memory) parts.push(memory);
+    if (memId) parts.push(dim(`(${memId})`));
+    console.log(parts.join("  "));
+  }
+  console.log();
+}
+
+export function formatJsonEnvelope(opts: {
+  command: string;
+  data: unknown;
+  durationMs?: number;
+  scope?: Record<string, string | undefined>;
+  count?: number;
+  status?: string;
+  error?: string;
+}): void {
+  const envelope: Record<string, unknown> = {
+    status: opts.status ?? "success",
+    command: opts.command,
+  };
+  if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+  if (opts.scope !== undefined) envelope.scope = opts.scope;
+  if (opts.count !== undefined) envelope.count = opts.count;
+  if (opts.error) envelope.error = opts.error;
+  envelope.data = opts.data;
+  console.log(JSON.stringify(envelope, null, 2));
+}
+
+export function printResultSummary(opts: {
+  count: number;
+  durationSecs?: number;
+  page?: number;
+  scopeIds?: Record<string, string | undefined>;
+}): void {
+  const parts = [`${opts.count} result${opts.count !== 1 ? "s" : ""}`];
+  if (opts.page !== undefined) parts.push(`page ${opts.page}`);
+  if (opts.scopeIds) {
+    const scopeParts = Object.entries(opts.scopeIds)
+      .filter(([, v]) => v)
+      .map(([k, v]) => `${k.replace(/_/g, " ")}=${v}`);
+    if (scopeParts.length > 0) parts.push(scopeParts.join(", "));
+  }
+  if (opts.durationSecs !== undefined) parts.push(`${opts.durationSecs.toFixed(2)}s`);
+
+  console.log(`  ${dim(parts.join(" · "))}`);
+  console.log();
+}

package/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("");
+  });
+});

package/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 });
+  });
+});

package/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");
+  });
+});