@rohirik/openltm-core 2.10.0 → 2.11.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.10.0",
+  "version": "2.11.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;
+}

package/src/mcp/server.ts

@@ -0,0 +1,449 @@
+/**
+ * mcp/server.ts — LTM MCP Server (STDIO transport), packaged.
+ *
+ * The full MCP server lives here so any MCP-capable host can run it via
+ * `bunx @rohirik/openltm-core mcp-serve` — not only the Claude Code plugin.
+ * The plugin's repo-root src/mcp-server.ts is a thin wrapper around this
+ * module that injects config from the plugin's config file.
+ *
+ * IMPORTANT: Never use console.log() — STDIO transport uses stdout for protocol.
+ */
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { learn, recall, relate, forget, revalidate, getContextMerge, type Memory } from "../db.js";
+import { getDb } from "../shared-db.js";
+import { queryAudit } from "../dao/provenanceAudit.js";
+import { getItems } from "../context.js";
+import { traverseGraph, buildReasoningContext } from "../graph.js";
+import { categorise } from "../recall/categorise.js";
+
+// ─── Options ─────────────────────────────────────────────────────────────────
+
+export interface McpServerOptions {
+  /** Host hook: return false to disable the server (e.g. config mcp.enabled=false). Default: enabled. */
+  isEnabled?: () => Promise<boolean>;
+  /** Host hook: confidence threshold for auto-categorisation (default 0.6). */
+  categoriseThreshold?: () => Promise<number>;
+}
+
+// Embedding excluded at the SQL query level — strip() is now a no-op passthrough kept for call-site compatibility.
+function strip(obj: unknown): unknown { return obj; }
+
+/** Compact formatter — strips verbose fields and truncates content to keep MCP responses small. */
+function compact(memories: unknown[]): unknown[] {
+  const MAX_CONTENT = 300;
+  return memories.map(m => {
+    const mem = m as Record<string, unknown>;
+    const content = typeof mem.content === "string" && mem.content.length > MAX_CONTENT
+      ? mem.content.slice(0, MAX_CONTENT) + "…"
+      : mem.content;
+    const relations = Array.isArray(mem.relations) && mem.relations.length > 0
+      ? { relations: mem.relations.map((r: Record<string, unknown>) => ({ id: (r.memory as Record<string, unknown>)?.id, type: r.relationship_type, dir: r.direction })) }
+      : {};
+    const exp = mem.explainer as Record<string, unknown> | undefined;
+    const score = exp
+      ? { temperature: exp.temperature, score: typeof exp.totalScore === "number" ? Math.round(exp.totalScore * 100) / 100 : undefined }
+      : {};
+    return { id: mem.id, content, category: mem.category, importance: mem.importance, tags: mem.tags, project_scope: mem.project_scope, ...score, ...relations };
+  });
+}
+
+// ─── Server factory ──────────────────────────────────────────────────────────
+
+/** Build the LTM MCP server with all tools, resources, and prompts registered. */
+export function buildMcpServer(options: McpServerOptions = {}): McpServer {
+  const server = new McpServer(
+    { name: "openltm", version: "1.0.0" },
+    {},
+  );
+
+  // ─── Tools ─────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "recall",
+    "Surface prior decisions, gotchas, and patterns before a non-trivial task, or when starting work in an unfamiliar area. Ranks long-term memories by query, category, project scope, or tags. Skip for trivial one-liners.",
+    {
+      query: z.string().optional().describe("Full-text search query"),
+      project: z.string().optional().describe("Filter by project scope"),
+      limit: z.number().int().min(1).max(50).optional().describe("Max results (default 10)"),
+      category: z.enum(["preference", "architecture", "gotcha", "pattern", "workflow", "constraint"]).optional(),
+      verbose: z.boolean().optional().describe("Return full memory objects (default false)"),
+      since: z.string().optional().describe("Filter: memories after this ISO date"),
+      until: z.string().optional().describe("Filter: memories before this ISO date"),
+      sort_by: z.enum(["relevance", "created", "last_recalled", "recall_count"]).optional().describe("Sort results by"),
+      workspace_id: z.string().optional().describe("Filter by workspace"),
+      agent_id: z.string().optional().describe("Filter by agent"),
+      includeProvenance: z.boolean().optional().default(false).describe("Attach provenance chain to each result (off by default)"),
+    },
+    async ({ query, project, limit, category, verbose, since, until, sort_by, includeProvenance }) => {
+      const results = await recall({ query, project, limit, category, since, until, sort_by, includeProvenance });
+      const payload = verbose ? strip(results) : compact(strip(results) as unknown[]);
+      return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+    },
+  );
+
+  server.tool(
+    "learn",
+    "Store or reinforce a memory after discovering a non-obvious pattern, gotcha, or architectural decision worth keeping across sessions. Skip facts already derivable from the code or git history. Always pass a concise title (the title param explains how).",
+    {
+      content: z.string().describe("The insight, pattern, or decision to store"),
+      title: z.string().max(60).optional().describe("Short noun-phrase label (≤60 chars) — e.g. 'Repository pattern for all DAO layers'. Always provide it; you generate it inline, no extra LLM call needed."),
+      category: z.enum(["preference", "architecture", "gotcha", "pattern", "workflow", "constraint"]).optional().describe("Category (auto-detected when omitted)"),
+      importance: z.number().int().min(1).max(5).optional().describe("Importance 1-5 (default 3, 5=never decays)"),
+      tags: z.array(z.string()).optional().describe("Tags for categorization"),
+      files: z.array(z.string()).optional().describe("Repo-relative file paths this memory references — anchors so a commit touching them flags the memory stale"),
+      project: z.string().optional().describe("Scope to a specific project"),
+      workspace_id: z.string().optional().describe("Workspace for this memory"),
+      agent_id: z.string().optional().describe("Agent ID for this memory"),
+    },
+    async ({ content, title, category, importance, tags, files, project, workspace_id, agent_id }) => {
+      let resolvedCategory = category;
+      let categoriseSource: string | undefined;
+
+      if (!resolvedCategory) {
+        try {
+          const threshold = await (options.categoriseThreshold?.() ?? Promise.resolve(0.6));
+          const result = await categorise(content, threshold);
+          resolvedCategory = result.category;
+          categoriseSource = result.source;
+        } catch {
+          resolvedCategory = "pattern";
+        }
+      }
+
+      const result = learn({
+        content,
+        title,
+        category: resolvedCategory,
+        importance,
+        tags,
+        files,
+        project_scope: project,
+        workspace_id,
+        agent_id,
+        actor: "mcp:ltm_learn",
+      });
+
+      try {
+        server.server.notification({
+          method: "notifications/message",
+          params: { level: "info", logger: "ltm", data: `memory_stored: id=${result.id} category=${resolvedCategory}${categoriseSource ? ` (auto:${categoriseSource})` : ""} importance=${importance ?? 3} action=${result.action}` },
+        });
+      } catch { /* notifications not supported by this client — ignore */ }
+
+      return { content: [{ type: "text", text: JSON.stringify({ ...result, category: resolvedCategory, categoriseSource }) }] };
+    },
+  );
+
+  server.tool(
+    "relate",
+    "Link two memories with a typed relationship when they connect — e.g. a decision caused a gotcha, or a pattern applies to an architecture.",
+    {
+      source_id: z.number().int(),
+      target_id: z.number().int(),
+      relationship_type: z.enum(["supports", "contradicts", "refines", "depends_on", "related_to", "supersedes"]),
+    },
+    async ({ source_id, target_id, relationship_type }) => {
+      relate({ source_id, target_id, relationship_type });
+      return { content: [{ type: "text", text: JSON.stringify({ ok: true }) }] };
+    },
+  );
+
+  server.tool(
+    "forget",
+    "Delete a memory by ID when it is wrong, outdated, or the user requests removal. Cascades to its relations.",
+    {
+      id: z.number().int(),
+      reason: z.string().optional().describe("Why this memory is being removed"),
+    },
+    async ({ id, reason }) => {
+      forget({ id, reason, actor: "mcp:ltm_forget" });
+      return { content: [{ type: "text", text: JSON.stringify({ ok: true, id, reason }) }] };
+    },
+  );
+
+  server.tool(
+    "revalidate",
+    "Clear a memory's stale flag after reviewing it — the code changed but this memory is still correct. Use forget instead when the memory is actually wrong.",
+    {
+      id: z.number().int().describe("Memory ID to revalidate"),
+    },
+    async ({ id }) => {
+      const result = revalidate(id);
+      return { content: [{ type: "text", text: JSON.stringify({ id, ...result }) }] };
+    },
+  );
+
+  server.tool(
+    "admin_audit",
+    "Query the memory audit log. Returns a list of audit events (insert, update, forget, redact, etc.) with before/after snapshots. Use for tracing who wrote or deleted a memory.",
+    {
+      memory_id: z.number().int().optional().describe("Filter to a specific memory ID"),
+      op: z.enum(["insert","update","forget","deprecate","supersede","redact","restore","archive"]).optional().describe("Filter by operation type"),
+      session_id: z.string().optional().describe("Filter by session that triggered the op"),
+      since: z.string().optional().describe("ISO date — only events after this time"),
+      limit: z.number().int().min(1).max(200).optional().default(50).describe("Max rows (default 50)"),
+      verbose: z.boolean().optional().default(false).describe("Include full before/after JSON snapshots"),
+    },
+    async ({ memory_id, op, session_id, since, limit, verbose }) => {
+      const db = getDb();
+      const rows = queryAudit(db, { memoryId: memory_id, op, sessionId: session_id, since, limit });
+      const payload = verbose ? rows : rows.map(r => ({
+        id: r.id, memory_id: r.memory_id, op: r.op, actor: r.actor,
+        session_id: r.session_id, created_at: r.created_at,
+        before_preview: r.before_json ? r.before_json.slice(0, 120) : null,
+        after_preview: r.after_json ? r.after_json.slice(0, 120) : null,
+      }));
+      return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+    },
+  );
+
+  server.tool(
+    "context",
+    "Restore project goals, decisions, and gotchas at session start or when switching projects. Returns merged context (globals + project-scoped memories).",
+    {
+      project: z.string().describe("Project name from registry"),
+    },
+    async ({ project }) => {
+      const result = getContextMerge(project);
+      return { content: [{ type: "text", text: JSON.stringify(strip(result)) }] };
+    },
+  );
+
+  server.tool(
+    "graph",
+    "Traverse the memory graph from seed nodes when exploring connections between memories or tracing decision chains. Builds a reasoning context from the traversal.",
+    {
+      memory_ids: z.array(z.number().int()).min(1).describe("Starting memory IDs for traversal"),
+      depth: z.number().int().min(1).max(4).optional().describe("Traversal depth (default 2)"),
+    },
+    async ({ memory_ids, depth = 2 }) => {
+      const results = await Promise.allSettled(
+        memory_ids.map((id) => traverseGraph(id, depth, false)),
+      );
+
+      const blocks: string[] = [];
+      let totalNodes = 0;
+      let totalEdges = 0;
+
+      for (const r of results) {
+        if (r.status === "fulfilled") {
+          const block = buildReasoningContext(r.value);
+          totalNodes += r.value.chain.length;
+          totalEdges += r.value.reinforcements.length + r.value.conflicts.length;
+          if (block) blocks.push(block);
+        }
+      }
+
+      try {
+        server.server.notification({
+          method: "notifications/message",
+          params: { level: "info", logger: "ltm", data: `graph_traversal: nodes=${totalNodes} edges=${totalEdges} depth=${depth}` },
+        });
+      } catch { /* notifications not supported by this client — ignore */ }
+
+      return { content: [{ type: "text", text: blocks.join("\n\n") || "No reasoning context found." }] };
+    },
+  );
+
+  server.tool(
+    "context_items",
+    "List specific context types — goals, decisions, progress, or gotchas — for a project. Returns structured context items.",
+    {
+      project: z.string().describe("Project name from registry"),
+      type: z.enum(["goal", "decision", "progress", "gotcha"]).optional(),
+    },
+    async ({ project, type }) => {
+      const items = getItems(project, type);
+      return { content: [{ type: "text", text: JSON.stringify(items) }] };
+    },
+  );
+
+  // ─── Resources ─────────────────────────────────────────────────────────────
+
+  server.resource(
+    "memory://globals",
+    "memory://globals",
+    { description: "All importance=5 global memories (never decay)" },
+    async () => {
+      const db = getDb();
+      const rows = db.query<Memory, []>(
+        `SELECT * FROM memories WHERE importance = 5 AND project_scope IS NULL AND status = 'active' ORDER BY created_at DESC`,
+      ).all();
+      return { contents: [{ uri: "memory://globals", text: JSON.stringify(strip(rows)), mimeType: "application/json" }] };
+    },
+  );
+
+  server.resource(
+    "memory://recent",
+    "memory://recent",
+    { description: "Last 20 memories across all projects" },
+    async () => {
+      const db = getDb();
+      const rows = db.query<Memory, []>(
+        `SELECT * FROM memories WHERE status = 'active' ORDER BY created_at DESC LIMIT 20`,
+      ).all();
+      return { contents: [{ uri: "memory://recent", text: JSON.stringify(strip(rows)), mimeType: "application/json" }] };
+    },
+  );
+
+  server.resource(
+    "memory://tags",
+    "memory://tags",
+    { description: "All unique tags with usage counts" },
+    async () => {
+      const db = getDb();
+      const rows = db.query<{ name: string; count: number }, []>(
+        `SELECT t.name, COUNT(mt.memory_id) as count FROM tags t
+         JOIN memory_tags mt ON t.id = mt.tag_id
+         GROUP BY t.id ORDER BY count DESC`,
+      ).all();
+      return { contents: [{ uri: "memory://tags", text: JSON.stringify(strip(rows)), mimeType: "application/json" }] };
+    },
+  );
+
+  const projectTemplate = new ResourceTemplate("memory://project/{name}", { list: undefined });
+  server.resource(
+    "memory://project/{name}",
+    projectTemplate,
+    { description: "All active memories scoped to a specific project" },
+    async (uri, { name }) => {
+      const projectName = (Array.isArray(name) ? name[0] : name) ?? "";
+      const db = getDb();
+      const rows = db.query<Memory, [string]>(
+        `SELECT * FROM memories WHERE project_scope = ? AND status = 'active' ORDER BY importance DESC, created_at DESC`,
+      ).all(projectName);
+      return {
+        contents: [{
+          uri: uri.href,
+          text: JSON.stringify(strip(rows), null, 2),
+          mimeType: "application/json",
+        }],
+      };
+    },
+  );
+
+  // ─── Prompts ───────────────────────────────────────────────────────────────
+
+  server.prompt(
+    "recall_before_task",
+    "Before starting a task, recall relevant memories and past decisions",
+    { topic: z.string().describe("The topic or task you are about to work on") },
+    ({ topic }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Before starting work on "${topic}", use the recall tool to search for relevant memories, past decisions, and gotchas related to this topic. Summarize what you find and note any decisions that should be followed.`,
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "learn_after_session",
+    "Extract learnable patterns and insights from a session summary",
+    { summary: z.string().describe("Summary of the session or work done") },
+    ({ summary }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Extract learnable patterns, gotchas, and architectural decisions from this session summary. For each insight, use learn to store it with the appropriate category and importance.\n\nSession summary:\n${summary}`,
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "graph_reason",
+    "Use graph traversal to reason about a question using connected memories",
+    { question: z.string().describe("The question or topic to reason about") },
+    ({ question }) => ({
+      messages: [{
+        role: "user",
+        content: {
+          type: "text",
+          text: `Use recall to find memories related to "${question}", then use graph on the top result IDs to traverse connected memories. Synthesize the chain of reasoning, conflicts, and reinforcements into a coherent answer.`,
+        },
+      }],
+    }),
+  );
+
+  server.prompt(
+    "learn_after_decision",
+    "Store an architectural decision or key choice in long-term memory with full context",
+    {
+      decision: z.string().describe("The architectural decision or key choice that was made"),
+      rationale: z.string().describe("Why this decision was made"),
+      project: z.string().optional().describe("Project this decision belongs to"),
+    },
+    ({ decision, rationale, project }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `We just made an architectural decision that should be preserved for future sessions. Store it using learn.\n\nDecision: ${decision}\nRationale: ${rationale}${project ? `\nProject: ${project}` : ""}\n\nStore with category=architecture, importance=4, and include the rationale in the content so future recall explains the "why".`,
+          },
+        },
+        {
+          role: "assistant",
+          content: {
+            type: "text",
+            text: `I'll store this decision now using learn with category=architecture and importance=4 so it persists across sessions and surfaces in future context loads.`,
+          },
+        },
+      ],
+    }),
+  );
+
+  server.prompt(
+    "context_before_work",
+    "Get full project context before starting work — combines context and recall for a complete picture",
+    {
+      project: z.string().describe("Project name from the LTM registry"),
+      topic: z.string().describe("What you are about to work on"),
+    },
+    ({ project, topic }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Before starting work on "${topic}" in project "${project}", gather full context:\n\n1. Call context(project="${project}") to load goals, decisions, and gotchas.\n2. Call recall(query="${topic}", project="${project}") to surface relevant past patterns.\n3. Synthesize: list any active decisions, known gotchas, or prior work that affects this task.`,
+          },
+        },
+        {
+          role: "assistant",
+          content: {
+            type: "text",
+            text: `I'll call context and recall now, then synthesize the relevant context before proceeding with "${topic}".`,
+          },
+        },
+      ],
+    }),
+  );
+
+  return server;
+}
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+/** Connect the LTM MCP server to stdio. Resolves once the transport is up. */
+export async function startMcpServer(options: McpServerOptions = {}): Promise<void> {
+  process.on("unhandledRejection", (err) => {
+    process.stderr.write(`[ltm-mcp] Unhandled rejection: ${err}\n`);
+  });
+
+  if (options.isEnabled && !(await options.isEnabled())) {
+    process.stderr.write("[ltm-mcp] mcp.enabled=false — server disabled\n");
+    process.exit(0);
+  }
+
+  const server = buildMcpServer(options);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[ltm-mcp] LTM MCP server running on stdio\n");
+}