@rohirik/openltm-core 2.9.1 → 2.11.0

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.9.1",
+  "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"
+    "ltm": "src/cli/bin.ts",
+    "openltm": "src/cli/bin.ts",
+    "openltm-core": "src/cli/bin.ts"
   },
   "repository": {
     "type": "git",
@@ -29,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__/codeAnchors.test.ts

@@ -0,0 +1,246 @@
+/**
+ * codeAnchors.test.ts — Phase 2: path normaliser + anchor-on-learn.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { normalizeAnchorPath, normalizeAnchorPaths } from "../anchors.js";
+import { _setDbForTesting } from "../shared-db.js";
+import { learn, flagStaleByPaths, revalidate, recall, decayMemories } from "../db.js";
+import { getMigrationFiles, parseMigration } from "../migrations.js";
+
+// Full schema = schema.sql baseline + every migration `up` (later columns like
+// created_by come from migrations). Apply ups directly to skip runPendingMigrations'
+// real-DB backup/retention side-effects; tolerate dup-column on already-in-schema.sql.
+async function freshDb(): Promise<Database> {
+  const db = new Database(":memory:");
+  db.exec("PRAGMA foreign_keys=ON;");
+  db.exec(readFileSync(join(import.meta.dir, "..", "schema.sql"), "utf8"));
+  for (const f of await getMigrationFiles()) {
+    const { up } = parseMigration(f.content);
+    if (!up) continue;
+    try {
+      db.exec(up);
+    } catch (e) {
+      if (!/duplicate column|already exists/i.test(String(e))) throw e;
+    }
+  }
+  return db;
+}
+
+function anchorPaths(db: Database, memoryId: number): string[] {
+  return db
+    .query<{ path: string }, [number]>(
+      "SELECT path FROM memory_files WHERE memory_id=? ORDER BY path",
+    )
+    .all(memoryId)
+    .map((r) => r.path);
+}
+
+describe("normalizeAnchorPath (AC7)", () => {
+  it("strips ./ and leading slashes, normalises backslashes", () => {
+    expect(normalizeAnchorPath("./src/a.ts")).toBe("src/a.ts");
+    expect(normalizeAnchorPath("src\\b.ts")).toBe("src/b.ts");
+    expect(normalizeAnchorPath("/src/c.ts")).toBe("src/c.ts");
+    expect(normalizeAnchorPath("  src/d.ts  ")).toBe("src/d.ts");
+  });
+
+  it("makes absolute paths under repoRoot relative", () => {
+    expect(normalizeAnchorPath("/repo/root/src/e.ts", "/repo/root")).toBe("src/e.ts");
+    expect(normalizeAnchorPath("/repo/root/", "/repo/root")).toBe("");
+  });
+
+  it("de-duplicates and drops empties", () => {
+    expect(normalizeAnchorPaths(["./a.ts", "a.ts", "", "  ", "b.ts"])).toEqual(["a.ts", "b.ts"]);
+  });
+});
+
+describe("anchor-on-learn", () => {
+  let db: Database;
+  beforeEach(async () => {
+    db = await freshDb();
+    _setDbForTesting(db);
+  });
+
+  it("stores normalised anchors scoped to the project (AC5, AC7)", () => {
+    const r = learn({
+      content: "auth uses JWT verified in middleware layer",
+      category: "architecture",
+      project_scope: "proj",
+      files: ["./src/auth.ts", "src\\auth.ts", "src/jwt.ts"],
+      skipExport: true,
+    });
+    expect(anchorPaths(db, r.id)).toEqual(["src/auth.ts", "src/jwt.ts"]);
+    const scope = db
+      .query<{ project_scope: string }, [number]>(
+        "SELECT project_scope FROM memory_files WHERE memory_id=? LIMIT 1",
+      )
+      .get(r.id);
+    expect(scope?.project_scope).toBe("proj");
+  });
+
+  it("omitting files writes no anchors (AC6)", () => {
+    const r = learn({ content: "a memory with no file anchors at all", category: "pattern", skipExport: true });
+    expect(anchorPaths(db, r.id)).toEqual([]);
+  });
+
+  it("reinforce merges new anchors without duplicates (AC8)", () => {
+    const a = learn({
+      content: "shared memory body for reinforcement",
+      category: "gotcha",
+      project_scope: "p",
+      files: ["src/a.ts"],
+      skipExport: true,
+    });
+    const b = learn({
+      content: "shared memory body for reinforcement",
+      category: "gotcha",
+      project_scope: "p",
+      files: ["src/a.ts", "src/b.ts"],
+      skipExport: true,
+    });
+    expect(b.action).toBe("reinforced");
+    expect(b.id).toBe(a.id);
+    expect(anchorPaths(db, a.id)).toEqual(["src/a.ts", "src/b.ts"]);
+  });
+});
+
+describe("flagStaleByPaths (invalidate-on-commit)", () => {
+  let db: Database;
+  beforeEach(async () => {
+    db = await freshDb();
+    _setDbForTesting(db);
+  });
+
+  function staleAt(id: number): string | null {
+    return (
+      db
+        .query<{ stale_flagged_at: string | null }, [number]>(
+          "SELECT stale_flagged_at FROM memories WHERE id=?",
+        )
+        .get(id)?.stale_flagged_at ?? null
+    );
+  }
+
+  it("flags a memory anchored to a changed path + records reason and audit (AC10)", () => {
+    const m = learn({
+      content: "auth verified via jwt in the middleware layer",
+      category: "architecture",
+      project_scope: "p",
+      files: ["src/auth.ts"],
+      skipExport: true,
+    });
+    const res = flagStaleByPaths(["src/auth.ts"], { project_scope: "p", reason: "commit abc" });
+    expect(res.flagged).toBe(1);
+    expect(res.ids).toContain(m.id);
+    expect(staleAt(m.id)).not.toBeNull();
+    const row = db
+      .query<{ stale_reason: string }, [number]>("SELECT stale_reason FROM memories WHERE id=?")
+      .get(m.id);
+    expect(row?.stale_reason).toBe("commit abc");
+    const audit = db
+      .query<{ n: number }, [number]>(
+        "SELECT count(*) n FROM memory_audit WHERE memory_id=? AND op='update'",
+      )
+      .get(m.id);
+    expect(audit?.n ?? 0).toBeGreaterThanOrEqual(1);
+  });
+
+  it("never flags importance=5 memories (AC12)", () => {
+    const m = learn({
+      content: "permanent architectural rule never decays",
+      category: "architecture",
+      importance: 5,
+      project_scope: "p",
+      files: ["src/auth.ts"],
+      skipExport: true,
+    });
+    const res = flagStaleByPaths(["src/auth.ts"], { project_scope: "p" });
+    expect(res.flagged).toBe(0);
+    expect(staleAt(m.id)).toBeNull();
+  });
+
+  it("returns flagged:0 when no memory is anchored to the path (AC14)", () => {
+    learn({ content: "anchored to a different file entirely", category: "pattern", project_scope: "p", files: ["src/other.ts"], skipExport: true });
+    expect(flagStaleByPaths(["src/unrelated.ts"], { project_scope: "p" }).flagged).toBe(0);
+  });
+
+  it("normalises commit paths (./ , backslash) before matching", () => {
+    const m = learn({ content: "path normalisation parity check body", category: "gotcha", project_scope: "p", files: ["src/n.ts"], skipExport: true });
+    expect(flagStaleByPaths(["./src/n.ts"], { project_scope: "p" }).ids).toContain(m.id);
+  });
+
+  it("flags global (null-scope) anchors regardless of commit scope", () => {
+    const m = learn({ content: "global anchor not scoped to a project", category: "pattern", files: ["src/g.ts"], skipExport: true });
+    expect(flagStaleByPaths(["src/g.ts"], { project_scope: "someproj" }).ids).toContain(m.id);
+  });
+});
+
+describe("stale-aware recall + decay + revalidate", () => {
+  let db: Database;
+  beforeEach(async () => {
+    db = await freshDb();
+    _setDbForTesting(db);
+  });
+
+  function staleAt(id: number): string | null {
+    return (
+      db
+        .query<{ stale_flagged_at: string | null }, [number]>(
+          "SELECT stale_flagged_at FROM memories WHERE id=?",
+        )
+        .get(id)?.stale_flagged_at ?? null
+    );
+  }
+  function statusOf(id: number): string {
+    return (
+      db.query<{ status: string }, [number]>("SELECT status FROM memories WHERE id=?").get(id)
+        ?.status ?? ""
+    );
+  }
+
+  it("recall marks stale + downranks but still returns it (AC15)", async () => {
+    const fresh = learn({ content: "alpha keyword fresh memory body", category: "pattern", project_scope: "p", files: ["src/x.ts"], skipExport: true });
+    const stale = learn({ content: "alpha keyword stale memory body", category: "pattern", project_scope: "p", files: ["src/y.ts"], skipExport: true });
+    flagStaleByPaths(["src/y.ts"], { project_scope: "p" });
+
+    const res = await recall({ query: "alpha keyword", limit: 10 });
+    const ids = res.map((r) => r.id);
+    expect(ids).toContain(fresh.id);
+    expect(ids).toContain(stale.id);
+    expect(res.find((r) => r.id === stale.id)?.stale).toBe(true);
+    expect(res.find((r) => r.id === fresh.id)?.stale).toBe(false);
+    expect(ids.indexOf(fresh.id)).toBeLessThan(ids.indexOf(stale.id));
+  });
+
+  it("decay deprecates a flagged memory but never importance:5 or unflagged-fresh (AC16)", () => {
+    const flagged = learn({ content: "beta flagged should decay now", category: "pattern", project_scope: "p", files: ["src/a.ts"], skipExport: true });
+    const permanent = learn({ content: "beta permanent rule stays", category: "architecture", importance: 5, project_scope: "p", files: ["src/a.ts"], skipExport: true });
+    const freshUnflagged = learn({ content: "beta fresh untouched stays", category: "pattern", project_scope: "p", files: ["src/b.ts"], skipExport: true });
+
+    flagStaleByPaths(["src/a.ts"], { project_scope: "p" }); // flags `flagged`; skips imp5 `permanent`
+    decayMemories();
+
+    expect(statusOf(flagged.id)).toBe("deprecated");
+    expect(statusOf(permanent.id)).toBe("active");
+    expect(statusOf(freshUnflagged.id)).toBe("active");
+  });
+
+  it("reinforce (re-learn same content) clears the stale flag (AC17)", () => {
+    const m = learn({ content: "gamma reconfirm body text", category: "gotcha", project_scope: "p", files: ["src/a.ts"], skipExport: true });
+    flagStaleByPaths(["src/a.ts"], { project_scope: "p" });
+    expect(staleAt(m.id)).not.toBeNull();
+    const again = learn({ content: "gamma reconfirm body text", category: "gotcha", project_scope: "p", skipExport: true });
+    expect(again.id).toBe(m.id);
+    expect(staleAt(m.id)).toBeNull();
+  });
+
+  it("revalidate clears the flag and is a no-op when not flagged (AC18)", () => {
+    const m = learn({ content: "delta revalidate body text", category: "pattern", project_scope: "p", files: ["src/a.ts"], skipExport: true });
+    flagStaleByPaths(["src/a.ts"], { project_scope: "p" });
+    expect(revalidate(m.id).revalidated).toBe(true);
+    expect(staleAt(m.id)).toBeNull();
+    expect(revalidate(m.id).revalidated).toBe(false);
+  });
+});

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/__tests__/migrations/023_memory_files.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { getMigrationFiles, parseMigration } from "../../migrations.js";
+
+async function migration023() {
+  const files = await getMigrationFiles();
+  const f = files.find((m) => m.version === 23 && m.name === "memory_files");
+  if (!f) throw new Error("migration 023_memory_files.sql not found");
+  return parseMigration(f.content);
+}
+
+// Minimal pre-021 memories table (the upgrade path only needs the FK target).
+function baseMemories(db: Database) {
+  db.exec(
+    "CREATE TABLE memories (id INTEGER PRIMARY KEY AUTOINCREMENT, importance INTEGER NOT NULL DEFAULT 3);",
+  );
+}
+
+function colNames(db: Database, table: string): string[] {
+  return db
+    .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+    .all()
+    .map((c) => c.name);
+}
+
+describe("migration 021 — memory_files + staleness columns", () => {
+  it("UP creates memory_files and adds stale columns (AC1, AC2)", async () => {
+    const db = new Database(":memory:");
+    db.exec("PRAGMA foreign_keys=ON;");
+    baseMemories(db);
+
+    const { up } = await migration023();
+    expect(up).toBeTruthy();
+    db.exec(up!);
+
+    const tbl = db
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='memory_files'",
+      )
+      .get();
+    expect(tbl?.name).toBe("memory_files");
+
+    const cols = colNames(db, "memories");
+    expect(cols).toContain("stale_flagged_at");
+    expect(cols).toContain("stale_reason");
+
+    // Anchor row inserts and ON DELETE CASCADE wipes it with the parent.
+    db.exec("INSERT INTO memories (id, importance) VALUES (1, 3);");
+    db.exec("INSERT INTO memory_files (memory_id, path, project_scope) VALUES (1, 'src/a.ts', 'demo');");
+    expect(
+      db.query<{ n: number }, []>("SELECT count(*) n FROM memory_files").get()?.n,
+    ).toBe(1);
+    db.exec("DELETE FROM memories WHERE id=1;");
+    expect(
+      db.query<{ n: number }, []>("SELECT count(*) n FROM memory_files").get()?.n,
+    ).toBe(0);
+  });
+
+  it("DOWN reverses cleanly and re-UP works (AC3 idempotent roundtrip)", async () => {
+    const db = new Database(":memory:");
+    baseMemories(db);
+    const { up, down } = await migration023();
+    expect(down).toBeTruthy();
+
+    db.exec(up!);
+    db.exec(down!);
+
+    expect(
+      db
+        .query("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_files'")
+        .get(),
+    ).toBeNull();
+    expect(colNames(db, "memories")).not.toContain("stale_flagged_at");
+
+    // Re-applying after a clean DOWN must succeed.
+    db.exec(up!);
+    expect(
+      db
+        .query("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_files'")
+        .get(),
+    ).toBeTruthy();
+  });
+});

package/src/anchors.ts

@@ -0,0 +1,39 @@
+/**
+ * anchors.ts — file-path normalisation for code-anchored memory invalidation.
+ *
+ * Both sides of the feature MUST normalise identically or flagging silently misses:
+ *   - learn() stores anchors a memory references (agent may pass absolute paths)
+ *   - the post-commit hook flags memories anchored to files `git diff-tree
+ *     --name-only` reports (always repo-relative, forward-slash, no leading ./)
+ *
+ * This module is the single source of truth for that normalisation. Output mirrors
+ * git's repo-relative path form so anchors and changed-file lists compare exactly.
+ */
+
+/**
+ * Normalise one path to the repo-relative, forward-slash form git emits.
+ * When `repoRoot` is given, an absolute path under it is made relative.
+ */
+export function normalizeAnchorPath(path: string, repoRoot?: string): string {
+  let s = path.trim().replace(/\\/g, "/");
+  if (!s) return "";
+  if (repoRoot) {
+    const root = repoRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (root && (s === root || s.startsWith(`${root}/`))) {
+      s = s.slice(root.length + 1);
+    }
+  }
+  // Strip leading "./" and any leading slashes — git paths are repo-relative.
+  s = s.replace(/^(\.\/)+/, "").replace(/^\/+/, "");
+  return s;
+}
+
+/** Normalise + de-duplicate a list of anchor paths, dropping empties. */
+export function normalizeAnchorPaths(paths: string[], repoRoot?: string): string[] {
+  const seen = new Set<string>();
+  for (const p of paths) {
+    const n = normalizeAnchorPath(p, repoRoot);
+    if (n) seen.add(n);
+  }
+  return [...seen];
+}