@rohirik/openltm-core 2.9.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Shared LTM storage engine — path-agnostic SQLite core used by Claude Code, OpenCode, and Pi adapters",
   "type": "module",
   "main": "./src/index.ts",
@@ -9,7 +9,9 @@
     "./cli": "./src/cli/index.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",

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__/events/crossProcess.test.ts

@@ -14,6 +14,7 @@ import {
   MEMORY_ADDED,
 } from "../../events/index.js";
 import { _resetHonkerForTesting } from "../../lib/honker.js";
+import { resetCapabilitiesForTesting } from "../../extensions.js";
 
 function seedDb(): Database {
   const db = new Database(":memory:");
@@ -25,6 +26,9 @@ describe("cross-process sync — flag + dormant contract (no honker)", () => {
   beforeEach(() => {
     _resetHonkerForTesting();
     delete process.env["LTM_HONKER_EXT"];
+    // Reset cached caps so a prior test's honker=true (vendored binary is
+    // discoverable here) does not leak in — keeps this the dormant contract.
+    resetCapabilitiesForTesting();
   });
   afterEach(() => {
     _resetHonkerForTesting();

package/src/__tests__/events/index.test.ts

@@ -7,11 +7,15 @@
 import { describe, it, expect, beforeEach } from "bun:test";
 import { notifyLtm, startLtmListener, LTM_CHANNEL } from "../../events/index.js";
 import { _resetHonkerForTesting } from "../../lib/honker.js";
+import { resetCapabilitiesForTesting } from "../../extensions.js";
 
 describe("events — dormant path (no honker)", () => {
   beforeEach(() => {
     _resetHonkerForTesting();
     delete process.env["LTM_HONKER_EXT"];
+    // Reset cached caps so a prior test's honker=true (vendored binary is
+    // discoverable here) does not leak in — keeps this the dormant contract.
+    resetCapabilitiesForTesting();
   });
 
   it("exposes the stable channel name", () => {

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/__tests__/queue/index.test.ts

@@ -15,10 +15,15 @@ import {
 } from "../../queue/index.js";
 import { startEmbeddingWorker } from "../../queue/worker.js";
 import { isHonkerAvailable, _resetHonkerForTesting } from "../../lib/honker.js";
+import { resetCapabilitiesForTesting } from "../../extensions.js";
 
 describe("queue — dormant path (no honker)", () => {
   beforeEach(() => {
     _resetHonkerForTesting();
+    // Force the dormant contract: a prior test may have cached caps.honker=true
+    // process-wide (the vendored binary is discoverable here). Reset so
+    // getCapabilities() returns the all-false default and honker stays dormant.
+    resetCapabilitiesForTesting();
   });
 
   it("EMBED_QUEUE has a stable name", () => {

package/src/__tests__/scheduler/index.test.ts

@@ -13,11 +13,15 @@ import {
   DEFAULT_JANITOR_CRON,
 } from "../../scheduler/index.js";
 import { _resetHonkerForTesting } from "../../lib/honker.js";
+import { resetCapabilitiesForTesting } from "../../extensions.js";
 
 describe("scheduler — dormant path (no honker)", () => {
   beforeEach(() => {
     _resetHonkerForTesting();
     delete process.env["LTM_HONKER_EXT"];
+    // Reset cached caps so a prior test's honker=true (vendored binary is
+    // discoverable here) does not leak in — keeps this the dormant contract.
+    resetCapabilitiesForTesting();
   });
 
   it("exposes stable names + default cron", () => {

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];
+}

package/src/db.ts

@@ -6,6 +6,7 @@ import type { Database } from "bun:sqlite";
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { normalizeKey } from "./dedup.js";
+import { normalizeAnchorPaths } from "./anchors.js";
 import { getDb, DB_PATH, configure as configureDb } from "./shared-db.js";
 import { enqueueEmbedding } from "./queue/index.js";
 import { notifyLtm, notifyMemoryAdded } from "./events/index.js";
@@ -51,6 +52,8 @@ export interface Memory {
   workspace_id?: string;
   agent_id?: string;
   decay_score?: number;
+  stale_flagged_at?: string | null;
+  stale_reason?: string | null;
 }
 
 export interface MemoryRelation {
@@ -68,6 +71,8 @@ export interface MemoryWithRelations extends Memory {
   provenance?: import("./dao/types.js").ProvenanceRow[];
   /** Score breakdown + temperature — always populated by recall(). */
   explainer?: import("./recall/explainer.js").RecallExplainer;
+  /** True when a commit touched an anchored file and the memory hasn't been re-confirmed. */
+  stale?: boolean;
 }
 
 export interface LearnInput {
@@ -83,6 +88,8 @@ export interface LearnInput {
   agent_id?: string;
   tags?: string[];
   relate_to?: Array<{ id: number; relationship_type: RelationshipType }>;
+  /** Repo-relative file paths this memory references — anchors for code-change invalidation. */
+  files?: string[];
   /** Skip regenerating docs/memory-long-term.md (use during bulk imports) */
   skipExport?: boolean;
   /** Audit/provenance — all optional; safe to omit from existing callers. */
@@ -145,6 +152,16 @@ function attachTags(db: Database, memoryId: number, tags: string[]): void {
   }
 }
 
+/** Anchor a memory to the repo files it references (merge-safe). */
+function attachFiles(db: Database, memoryId: number, files: string[], projectScope: string | null): void {
+  for (const path of normalizeAnchorPaths(files)) {
+    db.run(
+      `INSERT OR IGNORE INTO memory_files (memory_id, path, project_scope) VALUES (?, ?, ?)`,
+      [memoryId, path, projectScope],
+    );
+  }
+}
+
 /** Fetch tags for a single memory — used in recall() results. */
 function getTagsForMemory(db: Database, memoryId: number): string[] {
   return db.query<{ name: string }, [number]>(
@@ -192,7 +209,7 @@ function getRelationsForMemory(db: Database, memoryId: number): MemoryWithRelati
 }
 
 function enrichMemory(db: Database, mem: Memory): MemoryWithRelations {
-  return { ...mem, tags: getTagsForMemory(db, mem.id), relations: getRelationsForMemory(db, mem.id) };
+  return { ...mem, stale: !!mem.stale_flagged_at, tags: getTagsForMemory(db, mem.id), relations: getRelationsForMemory(db, mem.id) };
 }
 
 // --- Decay / relevance scoring ---
@@ -255,8 +272,14 @@ export function decayMemories(): DecayResult {
   ).all();
 
   const toDeprecate = rows
-    .filter(mem => mem.importance !== 5 && mem.confirm_count < 5)
-    .filter(mem => computeDecayScore(mem) < DEPRECATION_THRESHOLD)
+    .filter(mem => mem.importance !== 5)
+    .filter(mem =>
+      // Code-invalidated memories are decay-eligible regardless of recall
+      // frequency — this is the "high-traffic but stale" case decay can't
+      // otherwise see. Otherwise fall back to the recency/confirm guard.
+      mem.stale_flagged_at != null ||
+      (mem.confirm_count < 5 && computeDecayScore(mem) < DEPRECATION_THRESHOLD)
+    )
     .map(mem => mem.id);
 
   if (toDeprecate.length > 0) {
@@ -270,6 +293,92 @@ export function decayMemories(): DecayResult {
   return { deprecated: toDeprecate.length, scored: rows.length };
 }
 
+export interface FlagStaleResult {
+  flagged: number;
+  ids: number[];
+}
+
+/**
+ * Flag active memories anchored to any of `paths` as stale — the code they
+ * reference changed. Never deletes (audit trail preserved) and never touches
+ * importance=5 (permanent). Matches anchors in the same project scope or global
+ * (NULL-scoped) anchors. Idempotent: re-flagging refreshes stale_flagged_at.
+ */
+export function flagStaleByPaths(
+  paths: string[],
+  opts: { project_scope?: string | null; reason?: string; actor?: string; sessionId?: string } = {},
+): FlagStaleResult {
+  const db = getDb();
+  const norm = normalizeAnchorPaths(paths);
+  if (norm.length === 0) return { flagged: 0, ids: [] };
+
+  const scope = opts.project_scope ?? null;
+  const placeholders = norm.map(() => "?").join(",");
+  const candidates = db
+    .query<{ id: number }, (string | null)[]>(
+      `SELECT DISTINCT m.id
+         FROM memories m
+         JOIN memory_files mf ON mf.memory_id = m.id
+        WHERE m.status = 'active'
+          AND m.importance <> 5
+          AND mf.path IN (${placeholders})
+          AND (mf.project_scope IS ? OR mf.project_scope IS NULL)`,
+    )
+    .all(...norm, scope)
+    .map((r) => r.id);
+
+  const reason = opts.reason ?? "code change";
+  const actor = opts.actor ?? "git-commit";
+
+  for (const id of candidates) {
+    const beforeSnap = snapshotMemory(db, id);
+    db.run(
+      `UPDATE memories SET stale_flagged_at = datetime('now'), stale_reason = ? WHERE id = ?`,
+      [reason, id],
+    );
+    tryAudit(() => {
+      const afterSnap = snapshotMemory(db, id);
+      insertAudit(db, {
+        memory_id: id,
+        op: "update",
+        actor,
+        session_id: opts.sessionId,
+        before_json: beforeSnap ? JSON.stringify(beforeSnap) : null,
+        after_json: afterSnap ? JSON.stringify(afterSnap) : null,
+      });
+    });
+  }
+
+  return { flagged: candidates.length, ids: candidates };
+}
+
+/**
+ * Clear a stale flag — the memory was reviewed and is still valid. Use forget()
+ * instead when the memory is actually wrong. No-op if the memory wasn't flagged.
+ */
+export function revalidate(id: number): { revalidated: boolean } {
+  const db = getDb();
+  const before = snapshotMemory(db, id);
+  const res = db.run(
+    `UPDATE memories SET stale_flagged_at = NULL, stale_reason = NULL
+      WHERE id = ? AND stale_flagged_at IS NOT NULL`,
+    [id],
+  );
+  const revalidated = Number(res.changes ?? 0) > 0;
+  if (revalidated) {
+    tryAudit(() => {
+      insertAudit(db, {
+        memory_id: id,
+        op: "update",
+        actor: "revalidate",
+        before_json: before ? JSON.stringify(before) : null,
+        after_json: JSON.stringify(snapshotMemory(db, id)),
+      });
+    });
+  }
+  return { revalidated };
+}
+
 // Auto-relation detection — called fire-and-forget from learn()
 async function autoDetectRelations(
   newId: number,
@@ -322,10 +431,12 @@ export function learn(input: LearnInput): LearnResult {
     const beforeSnap = snapshotMemory(db, existing.id);
     db.run(
       `UPDATE memories SET confirm_count=confirm_count+1, last_confirmed_at=datetime('now'),
-       confidence=MIN(1.0, confidence+0.05) WHERE id=?`,
+       confidence=MIN(1.0, confidence+0.05),
+       stale_flagged_at=NULL, stale_reason=NULL WHERE id=?`,
       [existing.id]
     );
     if (input.tags) attachTags(db, existing.id, input.tags);
+    if (input.files) attachFiles(db, existing.id, input.files, existing.project_scope ?? input.project_scope ?? null);
     if (input.relate_to) {
       for (const rel of input.relate_to) {
         relate({ source_id: existing.id, target_id: rel.id, relationship_type: rel.relationship_type });
@@ -368,6 +479,7 @@ export function learn(input: LearnInput): LearnResult {
   const newId = Number(result.lastInsertRowid);
 
   if (input.tags) attachTags(db, newId, input.tags);
+  if (input.files) attachFiles(db, newId, input.files, input.project_scope ?? null);
   if (input.relate_to) {
     for (const rel of input.relate_to) {
       relate({ source_id: newId, target_id: rel.id, relationship_type: rel.relationship_type });
@@ -528,7 +640,7 @@ export async function recall(input: RecallInput = {}): Promise<MemoryWithRelatio
     `SELECT id, content, category, importance, confidence, source, project_scope, dedup_key,
             created_at, last_confirmed_at, last_used_at, confirm_count, status,
             first_recalled_at, last_recalled_at, recall_count, superseded_by, superseded_at,
-            workspace_id, agent_id, decay_score
+            workspace_id, agent_id, decay_score, stale_flagged_at, stale_reason
      FROM memories ${where} ${orderBy} LIMIT ${limit}`
   ).all(...params);
 
@@ -549,6 +661,12 @@ export async function recall(input: RecallInput = {}): Promise<MemoryWithRelatio
       .sort((a, b) => b.score - a.score)
       .map(({ m }) => m);
   }
+  // Downrank stale (code-invalidated) memories: stable partition pushes them
+  // after fresh ones at equal relevance — still returned, just demoted.
+  sorted = [
+    ...sorted.filter(m => !m.stale_flagged_at),
+    ...sorted.filter(m => m.stale_flagged_at),
+  ];
   if (sorted.length > 0) {
     const placeholders = sorted.map(() => "?").join(",");
     db.run(

package/src/extensions.ts

@@ -105,8 +105,16 @@ export function ensureCustomSqlite(): boolean {
   const lib = locateSystemSqlite();
   if (!lib) return false;
   try {
-    (Database as unknown as { setCustomSQLite: (p: string) => void }).setCustomSQLite(lib);
+    const DB = Database as unknown as { setCustomSQLite: (p: string) => void };
+    DB.setCustomSQLite(lib);
     _customSqliteApplied = true;
+    // setCustomSQLite is a once-per-process global (Bun throws "SQLite already
+    // loaded" on a second call). honker-bun's open() calls it again on its own
+    // connection and would throw — silently killing the honker handle even
+    // though the extension-enabled SQLite is already active process-wide. Now
+    // that we've loaded it, neutralise further calls so honker-bun (and any
+    // other consumer) no-ops instead of throwing.
+    DB.setCustomSQLite = () => {};
     return true;
   } catch {
     return false;

package/src/index.ts

@@ -10,11 +10,11 @@ export { configureCore, configureDocs } from "./db.js";
 export {
   learn, recall, forget, relate, getSimilarMemories,
   getContextMerge, getContextMergeWithGraph, computeDecayScore,
-  exportMarkdown, exportGraphJson,
+  exportMarkdown, exportGraphJson, flagStaleByPaths, revalidate,
 } from "./db.js";
 export type {
   Memory, MemoryWithRelations, MemoryCategory, RelationshipType, MemoryRelation,
-  LearnInput, LearnResult, RecallInput, DecayResult,
+  LearnInput, LearnResult, RecallInput, DecayResult, FlagStaleResult,
 } from "./db.js";
 
 // Context items
@@ -35,6 +35,7 @@ export { listByProject, upsertGoal, appendProgress, addDecision, addGotcha } fro
 // Utilities
 export { scrubSecrets } from "./secretsScrubber.js";
 export { normalizeKey } from "./dedup.js";
+export { normalizeAnchorPath, normalizeAnchorPaths } from "./anchors.js";
 export { embedText, getLlmConfig, callLlm } from "./embeddings.js";
 
 // Recall utilities

package/src/schema.sql

@@ -63,7 +63,10 @@ CREATE TABLE IF NOT EXISTS memories (
   user_note  TEXT,
   -- Personal relevance signal: 'works' | 'doesnt' | NULL (unrated)
   relevance_signal     TEXT,
-  relevance_signal_at  TEXT
+  relevance_signal_at  TEXT,
+  -- Code-anchored invalidation (migration 023). NULL = not flagged stale.
+  stale_flagged_at     TEXT,
+  stale_reason         TEXT
 );
 
 CREATE INDEX IF NOT EXISTS idx_memories_category   ON memories(category);
@@ -74,6 +77,20 @@ CREATE INDEX IF NOT EXISTS idx_memories_status     ON memories(status);
 CREATE INDEX IF NOT EXISTS idx_memories_last_used  ON memories(last_used_at);
 CREATE INDEX IF NOT EXISTS idx_memories_superseded ON memories(superseded_by);
 CREATE INDEX IF NOT EXISTS idx_memories_recall_count ON memories(recall_count DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_stale ON memories(stale_flagged_at);
+
+-- ============================================================
+-- memory_files: code anchors — files a memory references (migration 023)
+-- A commit touching one of these paths can flag the memory stale.
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memory_files (
+  memory_id     INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  path          TEXT    NOT NULL,
+  project_scope TEXT,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (memory_id, path)
+);
+CREATE INDEX IF NOT EXISTS idx_memory_files_path ON memory_files(path);
 
 -- ============================================================
 -- tags + memory_tags: many-to-many tagging for memories