@rohirik/openltm-core 2.10.0 → 2.12.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Shared LTM storage engine — path-agnostic SQLite core used by Claude Code, OpenCode, and Pi adapters",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./cli": "./src/cli/index.ts"
+    "./cli": "./src/cli/index.ts",
+    "./mcp": "./src/mcp/server.ts"
   },
   "bin": {
     "ltm": "src/cli/bin.ts",
@@ -31,8 +32,10 @@
   "dependencies": {
     "@clack/prompts": "^1.3.0",
     "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "bun-types": "^1.0.0",
-    "sqlite-vec": "0.1.9"
+    "sqlite-vec": "0.1.9",
+    "zod": "^4.3.6"
   },
   "optionalDependencies": {
     "@russellthehippo/honker-bun": "^0.2.2"

package/src/__tests__/cli/memory.test.ts

@@ -0,0 +1,186 @@
+/**
+ * memory.test.ts — unit tests for packages/openltm-core/src/cli/memory.ts
+ *
+ * RED phase: written before implementation. Defines the contract for the
+ * `ltm memory <learn|recall|forget|relate|context>` CLI surface that gives
+ * headless/CLI agents a direct path to LTM without the agent TUI.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { Database } from "bun:sqlite";
+
+// ── Arg parsing (pure) ────────────────────────────────────────────────────────
+
+describe("cli/memory — parseMemoryArgs", () => {
+  it("parses learn with all flags", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs([
+      "learn",
+      "--text", "Use WAL mode for SQLite",
+      "--title", "SQLite WAL",
+      "--category", "pattern",
+      "--importance", "4",
+      "--project", "homelab",
+      "--tags", "sqlite,db",
+      "--json",
+    ]);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.command).toBe("learn");
+    expect(parsed.options["text"]).toBe("Use WAL mode for SQLite");
+    expect(parsed.options["title"]).toBe("SQLite WAL");
+    expect(parsed.options["category"]).toBe("pattern");
+    expect(parsed.options["importance"]).toBe(4);
+    expect(parsed.options["project"]).toBe("homelab");
+    expect(parsed.options["tags"]).toEqual(["sqlite", "db"]);
+    expect(parsed.json).toBe(true);
+  });
+
+  it("learn without --text is a usage error", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["learn", "--category", "pattern"]);
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.error).toContain("--text");
+  });
+
+  it("learn rejects invalid category", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["learn", "--text", "x", "--category", "bogus"]);
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.error).toContain("category");
+  });
+
+  it("learn rejects importance outside 1-5", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["learn", "--text", "x", "--importance", "9"]);
+    expect(parsed.ok).toBe(false);
+    if (parsed.ok) return;
+    expect(parsed.error).toContain("importance");
+  });
+
+  it("parses recall with query/limit/project", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["recall", "--query", "docker", "--limit", "5", "--project", "homelab"]);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.command).toBe("recall");
+    expect(parsed.options["query"]).toBe("docker");
+    expect(parsed.options["limit"]).toBe(5);
+  });
+
+  it("forget requires numeric --id", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    expect(parseMemoryArgs(["forget"]).ok).toBe(false);
+    expect(parseMemoryArgs(["forget", "--id", "abc"]).ok).toBe(false);
+    const parsed = parseMemoryArgs(["forget", "--id", "12", "--reason", "stale"]);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.options["id"]).toBe(12);
+  });
+
+  it("relate requires --from --to --type with valid relationship", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    expect(parseMemoryArgs(["relate", "--from", "1"]).ok).toBe(false);
+    expect(parseMemoryArgs(["relate", "--from", "1", "--to", "2", "--type", "nope"]).ok).toBe(false);
+    const parsed = parseMemoryArgs(["relate", "--from", "1", "--to", "2", "--type", "supports"]);
+    expect(parsed.ok).toBe(true);
+  });
+
+  it("context requires --project", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    expect(parseMemoryArgs(["context"]).ok).toBe(false);
+    expect(parseMemoryArgs(["context", "--project", "homelab"]).ok).toBe(true);
+  });
+
+  it("unknown memory subcommand is a usage error", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["destroy-everything"]);
+    expect(parsed.ok).toBe(false);
+  });
+
+  it("no subcommand is a usage error", async () => {
+    const { parseMemoryArgs } = await import("../../cli/memory.js");
+    expect(parseMemoryArgs([]).ok).toBe(false);
+  });
+});
+
+// ── Round-trip against temp DB ────────────────────────────────────────────────
+
+describe("cli/memory — runMemoryCommand round-trip", () => {
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), "ltm-cli-test-"));
+    const dbPath = join(dir, "test.db");
+    const { initDb, _setDbForTesting } = await import("../../shared-db.js");
+    const db = await initDb({ dbPath });
+    _setDbForTesting(db as Database);
+  });
+
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("learn then recall returns the stored memory", async () => {
+    const { parseMemoryArgs, runMemoryCommand } = await import("../../cli/memory.js");
+    const learnParsed = parseMemoryArgs([
+      "learn", "--text", "CLI round trip memory about traefik routing", "--category", "gotcha", "--json",
+    ]);
+    expect(learnParsed.ok).toBe(true);
+    if (!learnParsed.ok) return;
+    const learnRes = await runMemoryCommand(learnParsed);
+    expect(learnRes.exitCode).toBe(0);
+    const learnOut = JSON.parse(learnRes.output);
+    expect(typeof learnOut.id).toBe("number");
+    expect(["created", "reinforced"]).toContain(learnOut.action);
+
+    const recallParsed = parseMemoryArgs(["recall", "--query", "traefik routing", "--json"]);
+    expect(recallParsed.ok).toBe(true);
+    if (!recallParsed.ok) return;
+    const recallRes = await runMemoryCommand(recallParsed);
+    expect(recallRes.exitCode).toBe(0);
+    const rows = JSON.parse(recallRes.output);
+    expect(Array.isArray(rows)).toBe(true);
+    expect(rows.some((r: { id: number }) => r.id === learnOut.id)).toBe(true);
+  });
+
+  it("forget removes the memory", async () => {
+    const { parseMemoryArgs, runMemoryCommand } = await import("../../cli/memory.js");
+    const learnParsed = parseMemoryArgs(["learn", "--text", "Temporary memory to forget immediately", "--category", "pattern", "--json"]);
+    if (!learnParsed.ok) throw new Error("parse failed");
+    const learnRes = await runMemoryCommand(learnParsed);
+    const { id } = JSON.parse(learnRes.output);
+
+    const forgetParsed = parseMemoryArgs(["forget", "--id", String(id), "--reason", "test", "--json"]);
+    if (!forgetParsed.ok) throw new Error("parse failed");
+    const forgetRes = await runMemoryCommand(forgetParsed);
+    expect(forgetRes.exitCode).toBe(0);
+    expect(JSON.parse(forgetRes.output).ok).toBe(true);
+  });
+
+  it("relate links two memories", async () => {
+    const { parseMemoryArgs, runMemoryCommand } = await import("../../cli/memory.js");
+    const a = JSON.parse((await runMemoryCommand(parseMemoryArgs(["learn", "--text", "Memory A for relate test", "--category", "pattern", "--json"]) as never)).output);
+    const b = JSON.parse((await runMemoryCommand(parseMemoryArgs(["learn", "--text", "Memory B for relate test", "--category", "pattern", "--json"]) as never)).output);
+    const parsed = parseMemoryArgs(["relate", "--from", String(a.id), "--to", String(b.id), "--type", "related_to", "--json"]);
+    if (!parsed.ok) throw new Error("parse failed");
+    const res = await runMemoryCommand(parsed);
+    expect(res.exitCode).toBe(0);
+    expect(JSON.parse(res.output).ok).toBe(true);
+  });
+
+  it("context returns globals and scoped arrays", async () => {
+    const { parseMemoryArgs, runMemoryCommand } = await import("../../cli/memory.js");
+    const parsed = parseMemoryArgs(["context", "--project", "ltm-cli-test", "--json"]);
+    if (!parsed.ok) throw new Error("parse failed");
+    const res = await runMemoryCommand(parsed);
+    expect(res.exitCode).toBe(0);
+    const out = JSON.parse(res.output);
+    expect(Array.isArray(out.globals)).toBe(true);
+    expect(Array.isArray(out.scoped)).toBe(true);
+  });
+});

package/src/__tests__/mcp-server.test.ts

@@ -0,0 +1,39 @@
+/**
+ * mcp-server.test.ts — smoke tests for packages/openltm-core/src/mcp/server.ts
+ *
+ * The full stdio handshake is covered by manual smoke tests; here we assert the
+ * module loads, the factory builds a connectable server, and the tool surface
+ * matches the documented contract.
+ */
+import { describe, it, expect } from "bun:test";
+
+describe("mcp/server — buildMcpServer", () => {
+  it("exports buildMcpServer and startMcpServer", async () => {
+    const mod = await import("../mcp/server.js");
+    expect(typeof mod.buildMcpServer).toBe("function");
+    expect(typeof mod.startMcpServer).toBe("function");
+  });
+
+  it("builds a server exposing the documented tool set", async () => {
+    const { buildMcpServer } = await import("../mcp/server.js");
+    const server = buildMcpServer();
+    expect(typeof server.connect).toBe("function");
+    // McpServer keeps registered tools in a private map — assert via the
+    // public-ish _registeredTools record the SDK maintains.
+    const tools = (server as unknown as { _registeredTools: Record<string, unknown> })._registeredTools;
+    const names = Object.keys(tools);
+    for (const expected of ["recall", "learn", "relate", "forget", "revalidate", "admin_audit", "context", "graph", "context_items"]) {
+      expect(names).toContain(expected);
+    }
+  });
+
+  it("accepts host config hooks without invoking them at build time", async () => {
+    const { buildMcpServer } = await import("../mcp/server.js");
+    let called = false;
+    buildMcpServer({
+      isEnabled: async () => { called = true; return true; },
+      categoriseThreshold: async () => { called = true; return 0.6; },
+    });
+    expect(called).toBe(false);
+  });
+});

package/src/cli/bin.ts

@@ -14,6 +14,7 @@
  */
 import { runInstallCli } from "./install.js";
 import { runHook } from "./hook.js";
+import { runMemoryCli } from "./memory.js";
 
 function printHelp(): void {
   process.stdout.write(
@@ -29,8 +30,10 @@ function printHelp(): void {
       "    --help, -h      Show this help",
       "",
       "  Sub-commands:",
+      "    memory <cmd>          Read/write memories from the shell (learn, recall,",
+      "                          forget, relate, context) — run 'memory --help'",
       "    hook --name <event>   Lifecycle hook stub (for Claude Code hook wiring)",
-      "    mcp-serve             Start the LTM MCP server",
+      "    mcp-serve             Start the LTM MCP server (stdio)",
       "",
       "  If no target flags are given, agents are auto-detected.",
       "",
@@ -46,6 +49,12 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  // Sub-command: memory (learn | recall | forget | relate | context)
+  if (argv[0] === "memory") {
+    const exitCode = await runMemoryCli(argv.slice(1));
+    process.exit(exitCode);
+  }
+
   // Sub-command: hook
   if (argv[0] === "hook") {
     const nameIdx = argv.indexOf("--name");
@@ -58,12 +67,19 @@ async function main(): Promise<void> {
     return;
   }
 
-  // Sub-command: mcp-serve (stub — full implementation deferred)
+  // Sub-command: mcp-serve — run the LTM MCP server on stdio
   if (argv[0] === "mcp-serve") {
-    process.stderr.write(
-      "  ltm mcp-serve: not yet implemented — install the Claude Code plugin for MCP server support\n",
-    );
-    process.exit(0);
+    const { startMcpServer } = await import("../mcp/server.js");
+    await startMcpServer();
+    return; // keep the process alive — transport owns the event loop
+  }
+
+  // Unknown positional sub-command: print help + exit 1. Never fall through
+  // to the install wizard (e.g. `ltm memry learn ...` must not start installing).
+  if (argv[0] && !argv[0].startsWith("--")) {
+    process.stderr.write(`  ltm: unknown sub-command '${argv[0]}'\n`);
+    printHelp();
+    process.exit(1);
   }
 
   // Parse installer flags

package/src/cli/memory.ts

@@ -0,0 +1,305 @@
+/**
+ * cli/memory.ts — `ltm memory <learn|recall|forget|relate|context>` subcommands.
+ *
+ * Gives headless/CLI agents (OpenCode CLI, scripts, cron jobs) a direct path
+ * to LTM without the agent TUI, slash commands, or a running MCP server:
+ *
+ *   bunx @rohirik/openltm-core memory learn --text "..." --category gotcha
+ *   bunx @rohirik/openltm-core memory recall --query "docker rate limit" --json
+ *
+ * DB path resolution follows paths.ts: LTM_DB_PATH > CLAUDE_PLUGIN_DATA > dev
+ * fallback. All writes route through db.ts learn() and therefore through
+ * scrubSecrets — the CLI is not a secret-leak bypass.
+ *
+ * Exit codes: 0 success · 1 usage error · 2 runtime/DB error.
+ */
+import { learn, recall, forget, relate, getContextMerge, type MemoryCategory } from "../db.js";
+import { waitForInit } from "../shared-db.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type MemoryCommand = "learn" | "recall" | "forget" | "relate" | "context";
+
+export interface ParsedMemoryArgs {
+  ok: true;
+  command: MemoryCommand;
+  options: Record<string, string | number | string[] | undefined>;
+  json: boolean;
+}
+
+export interface MemoryArgsError {
+  ok: false;
+  error: string;
+}
+
+export interface MemoryCommandResult {
+  exitCode: number;
+  output: string;
+}
+
+const CATEGORIES: readonly string[] = ["preference", "architecture", "gotcha", "pattern", "workflow", "constraint"];
+const RELATIONSHIP_TYPES: readonly string[] = ["supports", "contradicts", "refines", "depends_on", "related_to", "supersedes"];
+
+// ── Parsing ───────────────────────────────────────────────────────────────────
+
+/** Scan argv for `--flag value` pairs and bare `--flag` booleans. */
+function scanFlags(argv: string[]): Record<string, string | true> {
+  const flags: Record<string, string | true> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg?.startsWith("--")) continue;
+    const name = arg.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      flags[name] = next;
+      i++;
+    } else {
+      flags[name] = true;
+    }
+  }
+  return flags;
+}
+
+function asInt(value: string | true | undefined): number | undefined {
+  if (typeof value !== "string") return undefined;
+  const n = Number.parseInt(value, 10);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+function asList(value: string | true | undefined): string[] | undefined {
+  if (typeof value !== "string") return undefined;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+/**
+ * parseMemoryArgs — pure parser for `memory` subcommand argv (without the
+ * leading "memory"). Returns a typed parse result; never exits the process.
+ */
+export function parseMemoryArgs(argv: string[]): ParsedMemoryArgs | MemoryArgsError {
+  const command = argv[0];
+  if (!command || command.startsWith("--")) {
+    return { ok: false, error: "missing subcommand — expected one of: learn, recall, forget, relate, context" };
+  }
+
+  const flags = scanFlags(argv.slice(1));
+  const json = flags["json"] === true;
+
+  switch (command) {
+    case "learn": {
+      const text = typeof flags["text"] === "string" ? flags["text"] : undefined;
+      if (!text) return { ok: false, error: "learn: --text <content> is required" };
+      const category = typeof flags["category"] === "string" ? flags["category"] : undefined;
+      if (category && !CATEGORIES.includes(category)) {
+        return { ok: false, error: `learn: invalid category '${category}' — expected one of: ${CATEGORIES.join(", ")}` };
+      }
+      const importance = asInt(flags["importance"]);
+      if (flags["importance"] !== undefined && (importance === undefined || importance < 1 || importance > 5)) {
+        return { ok: false, error: "learn: --importance must be an integer 1-5" };
+      }
+      return {
+        ok: true,
+        command: "learn",
+        json,
+        options: {
+          text,
+          title: typeof flags["title"] === "string" ? flags["title"] : undefined,
+          category,
+          importance,
+          project: typeof flags["project"] === "string" ? flags["project"] : undefined,
+          tags: asList(flags["tags"]),
+          files: asList(flags["files"]),
+        },
+      };
+    }
+
+    case "recall": {
+      const limit = asInt(flags["limit"]);
+      if (flags["limit"] !== undefined && (limit === undefined || limit < 1)) {
+        return { ok: false, error: "recall: --limit must be a positive integer" };
+      }
+      const category = typeof flags["category"] === "string" ? flags["category"] : undefined;
+      if (category && !CATEGORIES.includes(category)) {
+        return { ok: false, error: `recall: invalid category '${category}' — expected one of: ${CATEGORIES.join(", ")}` };
+      }
+      return {
+        ok: true,
+        command: "recall",
+        json,
+        options: {
+          query: typeof flags["query"] === "string" ? flags["query"] : undefined,
+          category,
+          project: typeof flags["project"] === "string" ? flags["project"] : undefined,
+          limit,
+          tags: asList(flags["tags"]),
+        },
+      };
+    }
+
+    case "forget": {
+      const id = asInt(flags["id"]);
+      if (id === undefined) return { ok: false, error: "forget: --id <number> is required" };
+      return {
+        ok: true,
+        command: "forget",
+        json,
+        options: { id, reason: typeof flags["reason"] === "string" ? flags["reason"] : undefined },
+      };
+    }
+
+    case "relate": {
+      const from = asInt(flags["from"]);
+      const to = asInt(flags["to"]);
+      const type = typeof flags["type"] === "string" ? flags["type"] : undefined;
+      if (from === undefined || to === undefined) {
+        return { ok: false, error: "relate: --from <id> and --to <id> are required" };
+      }
+      if (!type || !RELATIONSHIP_TYPES.includes(type)) {
+        return { ok: false, error: `relate: --type must be one of: ${RELATIONSHIP_TYPES.join(", ")}` };
+      }
+      return { ok: true, command: "relate", json, options: { from, to, type } };
+    }
+
+    case "context": {
+      const project = typeof flags["project"] === "string" ? flags["project"] : undefined;
+      if (!project) return { ok: false, error: "context: --project <name> is required" };
+      return { ok: true, command: "context", json, options: { project } };
+    }
+
+    default:
+      return { ok: false, error: `unknown memory subcommand '${command}' — expected one of: learn, recall, forget, relate, context` };
+  }
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+/**
+ * runMemoryCommand — execute a parsed memory command against the LTM DB.
+ * Returns output text + exit code; never writes to stdout/stderr or exits
+ * (the bin entrypoint handles I/O), so it is directly unit-testable.
+ */
+export async function runMemoryCommand(parsed: ParsedMemoryArgs): Promise<MemoryCommandResult> {
+  try {
+    await waitForInit();
+    const o = parsed.options;
+
+    switch (parsed.command) {
+      case "learn": {
+        const result = learn({
+          content: o["text"] as string,
+          title: o["title"] as string | undefined,
+          category: (o["category"] as MemoryCategory | undefined) ?? "pattern",
+          importance: o["importance"] as number | undefined,
+          project_scope: o["project"] as string | undefined,
+          tags: o["tags"] as string[] | undefined,
+          files: o["files"] as string[] | undefined,
+          actor: "cli:ltm_memory",
+        });
+        const payload = { ...result, category: (o["category"] as string | undefined) ?? "pattern" };
+        return {
+          exitCode: 0,
+          output: parsed.json
+            ? JSON.stringify(payload)
+            : `  ${payload.action === "created" ? "Stored" : "Reinforced"} memory #${payload.id} (category: ${payload.category}, confirms: ${payload.confirm_count})`,
+        };
+      }
+
+      case "recall": {
+        const results = await recall({
+          query: o["query"] as string | undefined,
+          category: o["category"] as MemoryCategory | undefined,
+          project: o["project"] as string | undefined,
+          limit: o["limit"] as number | undefined,
+          tags: o["tags"] as string[] | undefined,
+        });
+        if (parsed.json) {
+          const compact = results.map((m) => ({
+            id: m.id, title: m.title, content: m.content, category: m.category,
+            importance: m.importance, project_scope: m.project_scope,
+          }));
+          return { exitCode: 0, output: JSON.stringify(compact) };
+        }
+        if (results.length === 0) return { exitCode: 0, output: "  No memories found." };
+        const lines = results.map(
+          (m) => `  #${m.id} [${m.category}/${m.importance}]${m.project_scope ? ` (${m.project_scope})` : ""} ${m.title ?? m.content.slice(0, 60)}`,
+        );
+        return { exitCode: 0, output: lines.join("\n") };
+      }
+
+      case "forget": {
+        forget({ id: o["id"] as number, reason: o["reason"] as string | undefined, actor: "cli:ltm_memory" });
+        return {
+          exitCode: 0,
+          output: parsed.json ? JSON.stringify({ ok: true, id: o["id"] }) : `  Forgot memory #${o["id"]}`,
+        };
+      }
+
+      case "relate": {
+        relate({ source_id: o["from"] as number, target_id: o["to"] as number, relationship_type: o["type"] as string });
+        return {
+          exitCode: 0,
+          output: parsed.json ? JSON.stringify({ ok: true }) : `  Related #${o["from"]} -[${o["type"]}]-> #${o["to"]}`,
+        };
+      }
+
+      case "context": {
+        const result = getContextMerge(o["project"] as string);
+        if (parsed.json) return { exitCode: 0, output: JSON.stringify(result) };
+        const fmt = (m: { id: number; content: string }) => `  #${m.id} ${m.content.slice(0, 80)}`;
+        return {
+          exitCode: 0,
+          output: [
+            `  Globals (${result.globals.length}):`,
+            ...result.globals.map(fmt),
+            `  Scoped to ${o["project"]} (${result.scoped.length}):`,
+            ...result.scoped.map(fmt),
+          ].join("\n"),
+        };
+      }
+    }
+  } catch (err) {
+    return { exitCode: 2, output: `  ltm memory ${parsed.command}: ${String(err)}` };
+  }
+}
+
+// ── Entrypoint glue ───────────────────────────────────────────────────────────
+
+export function printMemoryHelp(): string {
+  return [
+    "",
+    "  ltm memory <command> [options]",
+    "",
+    "  Commands:",
+    "    learn    --text <content> [--title <t>] [--category <c>] [--importance 1-5]",
+    "             [--project <scope>] [--tags a,b] [--files f1,f2] [--json]",
+    "    recall   [--query <q>] [--category <c>] [--project <scope>] [--limit N]",
+    "             [--tags a,b] [--json]",
+    "    forget   --id <n> [--reason <r>] [--json]",
+    "    relate   --from <id> --to <id> --type <rel> [--json]",
+    "    context  --project <name> [--json]",
+    "",
+    `    categories: ${CATEGORIES.join(", ")}`,
+    `    relations:  ${RELATIONSHIP_TYPES.join(", ")}`,
+    "",
+    "  DB path: LTM_DB_PATH env var overrides the default plugin data location.",
+    "",
+  ].join("\n");
+}
+
+/** runMemoryCli — top-level handler invoked by bin.ts. Handles I/O + exit code. */
+export async function runMemoryCli(argv: string[]): Promise<number> {
+  if (argv[0] === "--help" || argv[0] === "-h" || argv.length === 0) {
+    process.stdout.write(printMemoryHelp());
+    return argv.length === 0 ? 1 : 0;
+  }
+  const parsed = parseMemoryArgs(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`  ltm memory: ${parsed.error}\n`);
+    process.stderr.write(printMemoryHelp());
+    return 1;
+  }
+  const result = await runMemoryCommand(parsed);
+  const stream = result.exitCode === 0 ? process.stdout : process.stderr;
+  stream.write(result.output + "\n");
+  return result.exitCode;
+}