nexusmem 0.5.0 → 0.5.2

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 
 // src/cli/index.ts
 import { Command } from "commander";
-import pc18 from "picocolors";
+import pc19 from "picocolors";
 
 // src/config/workspace.ts
 import { existsSync } from "fs";
@@ -726,6 +726,12 @@ function insertDenyListEntry(db, input) {
     createdAt
   };
 }
+function denyListEntryExists(db, projectId, input) {
+  const row = db.prepare(
+    `SELECT 1 FROM deny_list WHERE project_id = ? AND match_type = ? AND pattern = ? AND ignore_case = ? LIMIT 1`
+  ).get(projectId, input.matchType, input.pattern, input.ignoreCase ? 1 : 0);
+  return row !== void 0;
+}
 function matchableText(node) {
   return `${node.title}
 ${node.body}
@@ -748,7 +754,9 @@ function firstMatchingEntry(entries, node) {
 }
 
 // src/cli/commands/forget.ts
+import { readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
 import pc from "picocolors";
+import { z as z2 } from "zod";
 
 // src/store/store.ts
 import Database from "better-sqlite3";
@@ -756,6 +764,21 @@ import { mkdirSync } from "fs";
 import { dirname as dirname3 } from "path";
 import * as sqliteVec from "sqlite-vec";
 
+// src/core/types.ts
+function defaultProvenanceForKind(kind) {
+  switch (kind) {
+    case "git_commit":
+    case "code_diff":
+    case "shell_command":
+      return "observed";
+    case "conversation_turn":
+    case "session_summary":
+    case "doc_section":
+    case "note":
+      return "inferred";
+  }
+}
+
 // src/core/ids.ts
 import { createHash } from "crypto";
 var KEY_SEP = "\0";
@@ -953,12 +976,21 @@ CREATE TABLE tombstones (
 );
 CREATE INDEX idx_tombstones_project ON tombstones (project_id, removed_at DESC);
 `;
+var V6 = `
+ALTER TABLE nodes ADD COLUMN provenance TEXT NOT NULL DEFAULT 'inferred';
+ALTER TABLE nodes ADD COLUMN supersedes TEXT;
+
+UPDATE nodes SET provenance = 'observed' WHERE kind IN ('git_commit', 'code_diff', 'shell_command');
+
+CREATE INDEX idx_nodes_supersedes ON nodes (supersedes) WHERE supersedes IS NOT NULL;
+`;
 var MIGRATIONS = [
   { version: 1, up: (db) => db.exec(V1) },
   { version: 2, up: (db) => db.exec(V2) },
   { version: 3, up: (db) => db.exec(V3) },
   { version: 4, up: (db) => db.exec(V4) },
-  { version: 5, up: (db) => db.exec(V5) }
+  { version: 5, up: (db) => db.exec(V5) },
+  { version: 6, up: (db) => db.exec(V6) }
 ];
 var LATEST_SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
 function currentSchemaVersion(db) {
@@ -1050,11 +1082,12 @@ var MemoryStore = class _MemoryStore {
       "DELETE FROM nodes_vec WHERE rowid = (SELECT rowid FROM nodes WHERE id = ?)"
     );
     const insertNode = this.db.prepare(
-      `INSERT INTO nodes (id, kind, project_id, ts, ts_epoch, source, title, body, signal, meta, created_at)
-       VALUES (@id, @kind, @projectId, @ts, @tsEpoch, @source, @title, @body, @signal, @meta, @now)
+      `INSERT INTO nodes (id, kind, project_id, ts, ts_epoch, source, title, body, signal, meta, provenance, supersedes, created_at)
+       VALUES (@id, @kind, @projectId, @ts, @tsEpoch, @source, @title, @body, @signal, @meta, @provenance, @supersedes, @now)
        ON CONFLICT(id) DO UPDATE SET
          ts = excluded.ts, ts_epoch = excluded.ts_epoch, source = excluded.source,
-         title = excluded.title, body = excluded.body, signal = excluded.signal, meta = excluded.meta`
+         title = excluded.title, body = excluded.body, signal = excluded.signal, meta = excluded.meta,
+         provenance = excluded.provenance`
     );
     const clearFiles = this.db.prepare("DELETE FROM node_files WHERE node_id = ?");
     const insertFile = this.db.prepare(
@@ -1100,6 +1133,8 @@ var MemoryStore = class _MemoryStore {
           body: node.body,
           signal: node.signal,
           meta: JSON.stringify(node.meta),
+          provenance: node.provenance ?? defaultProvenanceForKind(node.kind),
+          supersedes: node.supersedes ?? null,
           now
         });
         clearFiles.run(node.id);
@@ -1186,7 +1221,7 @@ var MemoryStore = class _MemoryStore {
   getNodesByIds(ids) {
     if (ids.length === 0) return [];
     return this.db.prepare(
-      `SELECT id, kind, project_id AS projectId, ts, title, body, signal
+      `SELECT id, kind, project_id AS projectId, ts, title, body, signal, provenance
          FROM nodes WHERE id IN (SELECT value FROM json_each(?))`
     ).all(JSON.stringify(ids));
   }
@@ -1198,7 +1233,7 @@ var MemoryStore = class _MemoryStore {
    */
   listRecentNodes(projectId, limit = 20) {
     return this.db.prepare(
-      `SELECT id, kind, ts, source, title, signal
+      `SELECT id, kind, ts, source, title, signal, provenance
          FROM nodes
          WHERE project_id = ?
          ORDER BY ts_epoch DESC
@@ -1348,6 +1383,59 @@ var MemoryStore = class _MemoryStore {
   listDenyList(projectId) {
     return listDenyListEntries(this.db, projectId);
   }
+  /**
+   * What `importDenyList` with these same entries would do, without writing
+   * anything -- `forget --import`'s dry-run default, same convention as
+   * `previewForget`.
+   */
+  previewImportDenyList(projectId, otherProjectIds, entries) {
+    return entries.map((input) => {
+      validatePattern(input);
+      if (denyListEntryExists(this.db, projectId, input)) {
+        return { matchType: input.matchType, pattern: input.pattern, alreadyPresent: true, wouldRemove: 0 };
+      }
+      const preview = this.previewForget(projectId, otherProjectIds, input);
+      return {
+        matchType: input.matchType,
+        pattern: input.pattern,
+        alreadyPresent: false,
+        wouldRemove: preview.reduce((sum, p) => sum + p.count, 0)
+      };
+    });
+  }
+  /**
+   * Re-apply a previously-exported deny-list against this project.
+   *
+   * This is the fix for `forget`'s per-checkout gap: `deny_list` lives in
+   * `.nexusmem/memory.db`, which is gitignored and never travels with `git
+   * clone`/`git push`, while the things a fresh `sync` re-derives from --
+   * git history and the user-home shell-hook log -- both travel or persist
+   * independently of any one checkout. A fresh clone or a restored backup
+   * starts with an empty deny_list and no memory of what was forgotten. See
+   * docs/forget-mechanism.md.
+   *
+   * Entries already active (same matchType+pattern+ignoreCase) are left
+   * untouched. Every new one goes through `forget` itself, so an imported
+   * value is deleted from this checkout's nodes too, not just blocked going
+   * forward -- exactly what running `nexusmem forget <value>` fresh in this
+   * checkout would have done.
+   */
+  importDenyList(projectId, otherProjectIds, entries) {
+    let imported = 0;
+    let skipped = 0;
+    let removedNodes = 0;
+    for (const input of entries) {
+      validatePattern(input);
+      if (denyListEntryExists(this.db, projectId, input)) {
+        skipped += 1;
+        continue;
+      }
+      const result = this.forget(projectId, otherProjectIds, input);
+      imported += 1;
+      removedNodes += result.removed;
+    }
+    return { imported, skipped, removedNodes };
+  }
   /**
    * Replace this project's entire `file_edges` snapshot in one transaction.
    *
@@ -1433,7 +1521,7 @@ var MemoryStore = class _MemoryStore {
   vectorSearch(projectId, embedding, limit = 20) {
     const overfetch = Math.max(limit * 8, 50);
     return this.db.prepare(
-      `SELECT n.id, n.kind, n.ts, n.title, n.body, n.signal, v.distance AS distance
+      `SELECT n.id, n.kind, n.ts, n.title, n.body, n.signal, n.provenance, v.distance AS distance
          FROM nodes_vec v
          JOIN nodes n ON n.rowid = v.rowid
          WHERE v.embedding MATCH ? AND k = ? AND n.project_id = ?
@@ -1468,7 +1556,7 @@ var MemoryStore = class _MemoryStore {
     const match = toMatchQuery(query);
     if (!match) return [];
     const rows = this.db.prepare(
-      `SELECT n.id, n.kind, n.ts, n.title, n.body, n.signal,
+      `SELECT n.id, n.kind, n.ts, n.title, n.body, n.signal, n.provenance,
                 bm25(nodes_fts, 10.0, 1.0) AS rank
          FROM nodes_fts
          JOIN nodes n ON n.rowid = nodes_fts.rowid
@@ -1478,6 +1566,20 @@ var MemoryStore = class _MemoryStore {
     ).all(match, projectId, limit);
     return rows;
   }
+  /** The project a node belongs to, or null if no node has this id. Used by `mark-stale` to validate both ids. */
+  getNodeProjectId(id) {
+    const row = this.db.prepare("SELECT project_id FROM nodes WHERE id = ?").get(id);
+    return row?.project_id ?? null;
+  }
+  /** Every node id some other node's `supersedes` points at, for one project -- what the ranker should down-weight. */
+  getSupersededIds(projectId) {
+    const rows = this.db.prepare("SELECT DISTINCT supersedes AS id FROM nodes WHERE project_id = ? AND supersedes IS NOT NULL").all(projectId);
+    return new Set(rows.map((r) => r.id));
+  }
+  /** Record that `newNodeId` supersedes `staleNodeId` -- the write behind `nexusmem mark-stale`. Caller validates both ids first. */
+  setSupersedes(newNodeId, staleNodeId) {
+    this.db.prepare("UPDATE nodes SET supersedes = ? WHERE id = ?").run(staleNodeId, newNodeId);
+  }
   /** Escape hatch for tests and future modules. */
   get raw() {
     return this.db;
@@ -1509,6 +1611,17 @@ async function loadContext(cwd) {
 }
 
 // src/cli/commands/forget.ts
+var ExportPayloadSchema = z2.object({
+  version: z2.literal(1),
+  entries: z2.array(
+    z2.object({
+      matchType: z2.enum(["literal", "regex"]),
+      pattern: z2.string(),
+      ignoreCase: z2.boolean(),
+      reason: z2.string().nullable()
+    })
+  )
+});
 async function runForget(opts) {
   const { ws, projectId } = await loadContext(opts.cwd);
   const out = opts.out ?? ((chunk2) => void process.stdout.write(chunk2));
@@ -1532,8 +1645,75 @@ async function runForget(opts) {
       );
       return 0;
     }
+    if (opts.export) {
+      const entries = store.listDenyList(projectId);
+      const payload = {
+        version: 1,
+        entries: entries.map((e) => ({ matchType: e.matchType, pattern: e.pattern, ignoreCase: e.ignoreCase, reason: e.reason }))
+      };
+      await writeFile4(opts.export, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+      out(
+        [
+          `${pc.green("exported")} ${entries.length} deny-list entrie(s) to ${opts.export}`,
+          pc.yellow(
+            "this file contains the raw forgotten value(s) in plaintext -- store it somewhere secure (password manager, encrypted note) and never commit it to git or share it publicly."
+          ),
+          ""
+        ].join("\n")
+      );
+      return 0;
+    }
+    if (opts.import) {
+      let raw;
+      try {
+        raw = await readFile4(opts.import, "utf8");
+      } catch (err) {
+        throw new DenyListError(`could not read ${opts.import}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        throw new DenyListError(`${opts.import} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      const validated = ExportPayloadSchema.safeParse(parsed);
+      if (!validated.success) {
+        throw new DenyListError(
+          `${opts.import} is not a valid deny-list export: ${validated.error.issues.map((i) => i.message).join("; ")}`
+        );
+      }
+      const entries = validated.data.entries;
+      const otherProjectIds2 = store.listOtherProjectIds(projectId);
+      if (!opts.yes) {
+        const preview = store.previewImportDenyList(projectId, otherProjectIds2, entries);
+        const toImport = preview.filter((p) => !p.alreadyPresent);
+        const totalRemove = toImport.reduce((sum, p) => sum + p.wouldRemove, 0);
+        if (toImport.length === 0) {
+          out(`${pc.dim("forget --import")} all ${preview.length} entrie(s) in ${opts.import} are already active -- nothing to do
+`);
+          return 0;
+        }
+        const describe = (p) => `  ${p.matchType === "regex" ? pc.dim("/") + p.pattern + pc.dim("/") : JSON.stringify(p.pattern)}: ${p.wouldRemove} node(s)`;
+        out(
+          [
+            `${pc.yellow("would import")} ${toImport.length} new deny-list entrie(s)${preview.length > toImport.length ? ` (${preview.length - toImport.length} already active)` : ""}, removing ${totalRemove} node(s):`,
+            ...toImport.map(describe),
+            pc.dim("re-run with --yes to permanently deny-list these value(s) and delete matching node(s) -- this cannot be undone"),
+            ""
+          ].join("\n")
+        );
+        return 0;
+      }
+      const result2 = store.importDenyList(projectId, otherProjectIds2, entries);
+      out(
+        `${pc.green("imported")} ${result2.imported} deny-list entrie(s)${result2.skipped > 0 ? ` (${result2.skipped} already active)` : ""}, ${result2.removedNodes} node(s) deleted
+`
+      );
+      return 0;
+    }
     if (!opts.value) {
-      throw new DenyListError("a value is required (or pass --list to see active deny-list entries)");
+      throw new DenyListError("a value is required (or pass --list/--export/--import)");
     }
     const input = {
       matchType: opts.regex ? "regex" : "literal",
@@ -1663,20 +1843,20 @@ import pc4 from "picocolors";
 
 // src/config/registry.ts
 import { existsSync as existsSync2 } from "fs";
-import { mkdir as mkdir4, readFile as readFile4, rename, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, rename, writeFile as writeFile5 } from "fs/promises";
 import { join as join5 } from "path";
-import { z as z2 } from "zod";
-var ENTRY_SCHEMA = z2.object({
-  projectId: z2.string().min(1),
-  root: z2.string().min(1),
-  dbPath: z2.string().min(1),
-  originUrl: z2.string().nullable().default(null),
+import { z as z3 } from "zod";
+var ENTRY_SCHEMA = z3.object({
+  projectId: z3.string().min(1),
+  root: z3.string().min(1),
+  dbPath: z3.string().min(1),
+  originUrl: z3.string().nullable().default(null),
   /** Epoch ms of the last `init`/`sync` that recorded this entry. */
-  lastSeenAt: z2.number().int().nonnegative()
+  lastSeenAt: z3.number().int().nonnegative()
 });
-var REGISTRY_SCHEMA = z2.object({
-  version: z2.literal(1),
-  projects: z2.array(ENTRY_SCHEMA).default([])
+var REGISTRY_SCHEMA = z3.object({
+  version: z3.literal(1),
+  projects: z3.array(ENTRY_SCHEMA).default([])
 });
 function registryPath() {
   return join5(globalWorkspaceDir(), "projects.json");
@@ -1684,7 +1864,7 @@ function registryPath() {
 async function readRegistry() {
   let raw;
   try {
-    raw = await readFile4(registryPath(), "utf8");
+    raw = await readFile5(registryPath(), "utf8");
   } catch {
     return [];
   }
@@ -1724,7 +1904,7 @@ async function writeRegistry(projects) {
   const path = registryPath();
   const tmp = `${path}.${process.pid}.tmp`;
   await mkdir4(globalWorkspaceDir(), { recursive: true });
-  await writeFile4(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
+  await writeFile5(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
 `, "utf8");
   await rename(tmp, path);
 }
@@ -1791,8 +1971,47 @@ async function runInit(opts) {
   return 0;
 }
 
-// src/cli/commands/projects.ts
+// src/cli/commands/mark-stale.ts
 import pc5 from "picocolors";
+var MarkStaleError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MarkStaleError";
+  }
+};
+async function runMarkStale(opts) {
+  const { projectId, ws } = await loadContext(opts.cwd);
+  const out = opts.out ?? ((chunk2) => void process.stdout.write(chunk2));
+  if (opts.nodeId === opts.supersedesId) {
+    throw new MarkStaleError("a node cannot supersede itself");
+  }
+  const store = MemoryStore.open(ws.dbPath);
+  try {
+    const staleProject = store.getNodeProjectId(opts.nodeId);
+    if (staleProject === null) {
+      throw new MarkStaleError(`no node found with id ${opts.nodeId}`);
+    }
+    const supersedingProject = store.getNodeProjectId(opts.supersedesId);
+    if (supersedingProject === null) {
+      throw new MarkStaleError(`no node found with id ${opts.supersedesId}`);
+    }
+    if (staleProject !== projectId || supersedingProject !== projectId) {
+      throw new MarkStaleError("both nodes must belong to the current project");
+    }
+    store.setSupersedes(opts.supersedesId, opts.nodeId);
+    out(
+      `${pc5.green("marked stale")} ${opts.nodeId}
+${pc5.dim("superseded by")} ${opts.supersedesId} -- the old node stays queryable, just ranked lower
+`
+    );
+    return 0;
+  } finally {
+    store.close();
+  }
+}
+
+// src/cli/commands/projects.ts
+import pc6 from "picocolors";
 async function runProjects(opts) {
   const { entries, missing } = await readLiveRegistry();
   const rows = entries.map((entry) => {
@@ -1811,7 +2030,7 @@ async function runProjects(opts) {
   });
   if (opts.prune) {
     const removed = await forgetProjects(missing.map((entry) => entry.projectId));
-    process.stderr.write(`${pc5.yellow("pruned")} ${removed} project(s) whose database is gone
+    process.stderr.write(`${pc6.yellow("pruned")} ${removed} project(s) whose database is gone
 `);
   }
   if (opts.json) {
@@ -1819,28 +2038,28 @@ async function runProjects(opts) {
 `);
     return 0;
   }
-  process.stderr.write(`${pc5.dim("registry")} ${registryPath()}
+  process.stderr.write(`${pc6.dim("registry")} ${registryPath()}
 
 `);
   if (rows.length === 0) {
-    process.stderr.write(`${pc5.yellow("no projects registered")} -- run ${pc5.bold("nexusmem sync")} in a repository
+    process.stderr.write(`${pc6.yellow("no projects registered")} -- run ${pc6.bold("nexusmem sync")} in a repository
 `);
     return 0;
   }
   for (const row of rows) {
     const seen = new Date(row.lastSeenAt).toISOString().slice(0, 16).replace("T", " ");
-    const count = row.nodes === null ? pc5.yellow("unreadable") : `${row.nodes} node(s)`;
-    process.stdout.write(`${pc5.cyan(row.projectId.slice(0, 8))}  ${row.root}
-    ${pc5.dim(`${count}, last seen ${seen}`)}
+    const count = row.nodes === null ? pc6.yellow("unreadable") : `${row.nodes} node(s)`;
+    process.stdout.write(`${pc6.cyan(row.projectId.slice(0, 8))}  ${row.root}
+    ${pc6.dim(`${count}, last seen ${seen}`)}
 `);
   }
   if (!opts.prune && missing.length > 0) {
     process.stderr.write(
       `
-${pc5.yellow(`${missing.length} registered project(s) have no database on disk`)} ${pc5.dim("-- run with --prune to forget them")}
+${pc6.yellow(`${missing.length} registered project(s) have no database on disk`)} ${pc6.dim("-- run with --prune to forget them")}
 `
     );
-    for (const entry of missing) process.stderr.write(`    ${pc5.dim(entry.root)}
+    for (const entry of missing) process.stderr.write(`    ${pc6.dim(entry.root)}
 `);
   }
   return 0;
@@ -1849,7 +2068,7 @@ ${pc5.yellow(`${missing.length} registered project(s) have no database on disk`)
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/mcp/tools.ts
 import { basename as basename3 } from "path";
@@ -2009,6 +2228,7 @@ function packContext(ranked, tokensBudget, opts = {}) {
       score: hit.score,
       summary,
       tokens,
+      provenance: hit.provenance,
       ...hit.project ? { project: hit.project } : {}
     });
     tokensUsed += tokens;
@@ -2021,7 +2241,8 @@ function renderContextBlock(query, result) {
   const lines = [`Relevant history for: ${query}`, ""];
   for (const node of result.nodes) {
     const project = node.project ? `[${node.project}] ` : "";
-    lines.push(`- ${node.ts.slice(0, 10)} ${project}${node.title}`);
+    const provenance = `[${node.provenance}] `;
+    lines.push(`- ${node.ts.slice(0, 10)} ${provenance}${project}${node.title}`);
     if (node.summary && node.summary !== node.title) {
       if (node.kind === "code_diff") {
         for (const line of node.summary.split("\n")) lines.push(`  ${line}`);
@@ -2151,7 +2372,16 @@ function mergeSearchAndVectorHits(bm25Hits, vectorHits) {
   for (const hit of bm25Hits) byId.set(hit.id, hit);
   for (const hit of vectorHits) {
     if (byId.has(hit.id)) continue;
-    byId.set(hit.id, { id: hit.id, kind: hit.kind, ts: hit.ts, title: hit.title, body: hit.body, signal: hit.signal, rank: 0 });
+    byId.set(hit.id, {
+      id: hit.id,
+      kind: hit.kind,
+      ts: hit.ts,
+      title: hit.title,
+      body: hit.body,
+      signal: hit.signal,
+      provenance: hit.provenance,
+      rank: 0
+    });
   }
   return [...byId.values()];
 }
@@ -2162,6 +2392,7 @@ var SIGNAL_FLOOR = 0.2;
 var RECENCY_FLOOR = 0.3;
 var DEFAULT_HALF_LIFE_DAYS = 30;
 var MS_PER_DAY = 864e5;
+var SUPERSEDED_PENALTY = 0.5;
 var MAX_PRIOR_OVERTURN = 2;
 var PRIOR_COUNT = 2;
 var PER_PRIOR_OVERTURN = MAX_PRIOR_OVERTURN ** (1 / PRIOR_COUNT);
@@ -2202,7 +2433,8 @@ function rankHits(hits, opts = {}) {
     const signalWeight = SIGNAL_FLOOR + (1 - SIGNAL_FLOOR) * hit.signal;
     const ageDays = ageDaysOf(hit.ts, now);
     const recencyFactor = RECENCY_FLOOR + (1 - RECENCY_FLOOR) * 2 ** (-ageDays / halfLife);
-    const score = relevance * signalWeight ** SIGNAL_EXPONENT * recencyFactor ** RECENCY_EXPONENT;
+    const rawScore = relevance * signalWeight ** SIGNAL_EXPONENT * recencyFactor ** RECENCY_EXPONENT;
+    const score = opts.supersededIds?.has(hit.id) ? rawScore * SUPERSEDED_PENALTY : rawScore;
     return { ...hit, relevance, signalWeight, ageDays, recencyFactor, score };
   });
   return ranked.sort((a, b) => b.score - a.score);
@@ -2231,6 +2463,7 @@ function pullLinkedResolutions(resolveStore, ranked) {
           title: resolution.title,
           body: resolution.body,
           signal: resolution.signal,
+          provenance: resolution.provenance,
           rank: 0,
           // no bm25/vector rank of its own -- never read again past this point
           relevance: hit.relevance,
@@ -2252,6 +2485,7 @@ async function runCrossProjectQuery(sources, query, opts) {
   const perProject = [];
   let bm25Count = 0;
   let vectorCount = 0;
+  const supersededIds = /* @__PURE__ */ new Set();
   for (const source of sources) {
     const label = (hit) => ({ ...hit, project: source.label });
     const bm25Hits = source.store.search(source.projectId, query, opts.candidates).map(label);
@@ -2264,12 +2498,13 @@ async function runCrossProjectQuery(sources, query, opts) {
       lists.push(vectorHits.map((hit) => ({ ...hit, rank: 0, project: source.label })));
     }
     hits.push(...mergeSearchAndVectorHits(bm25Hits, vectorHits).map(label));
+    for (const id of source.store.getSupersededIds(source.projectId)) supersededIds.add(id);
   }
   const storeByLabel = new Map(sources.map((source) => [source.label, source.store]));
   const relevanceScores = reciprocalRankFusion(lists);
   const ranked = pullLinkedResolutions(
     (hit) => hit.project ? storeByLabel.get(hit.project) : void 0,
-    rankHits(hits, { halfLifeDays: opts.halfLifeDays, relevanceScores })
+    rankHits(hits, { halfLifeDays: opts.halfLifeDays, relevanceScores, supersededIds })
   );
   const packed = packContext(ranked, opts.budget, { query });
   return { bm25Count, vectorCount, hits, packed, perProject };
@@ -2283,9 +2518,10 @@ async function runHybridQuery(store, projectId, query, opts) {
   }
   const hits = vectorHits.length > 0 ? mergeSearchAndVectorHits(bm25Hits, vectorHits) : bm25Hits;
   const relevanceScores = vectorHits.length > 0 ? reciprocalRankFusion([bm25Hits, vectorHits]) : void 0;
+  const supersededIds = store.getSupersededIds(projectId);
   const ranked = pullLinkedResolutions(
     () => store,
-    rankHits(hits, { halfLifeDays: opts.halfLifeDays, relevanceScores })
+    rankHits(hits, { halfLifeDays: opts.halfLifeDays, relevanceScores, supersededIds })
   );
   const packed = packContext(ranked, opts.budget, { query });
   return { bm25Count: bm25Hits.length, vectorCount: vectorHits.length, hits, packed };
@@ -2390,7 +2626,7 @@ var OllamaEmbeddingProvider = class {
 };
 
 // src/cli/commands/sync.ts
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 
 // src/conversation/chunk.ts
 var HEADING_LINE = /^#{1,6}\s+(.+)$/;
@@ -2525,6 +2761,8 @@ function toMemoryNodes(turn, projectId, opts = {}) {
       files: extractMentionedFiles(`${userRedacted.text}
 ${chunk2.text}`),
       signal: scoreConversationTurn(userRedacted.text, chunk2.text),
+      provenance: "inferred",
+      // discourse about what happened, not the event itself
       meta: {
         cwd: turn.cwd,
         source: turn.source,
@@ -2937,6 +3175,7 @@ function toMemoryNode(commit, projectId, opts = {}) {
     body: truncate(bodyParts.join("\n"), maxBody),
     files: keptFiles,
     signal: scoreCommit(commit),
+    provenance: "observed",
     meta: {
       sha: commit.sha,
       shortSha: commit.shortSha,
@@ -3031,6 +3270,7 @@ function toMemoryNodes2(commit, projectId, opts = {}) {
         }
       ],
       signal: scoreFileDiff(commit.subject, file),
+      provenance: "observed",
       meta: {
         sha: commit.sha,
         shortSha: commit.shortSha,
@@ -3094,6 +3334,8 @@ function toMemoryNodes3(file, projectId, opts = {}) {
       body: truncate(chunk2.text, maxBody),
       files: [{ path: file.path, insertions: null, deletions: null, binary: false }],
       signal: scoreDocSection(file.path, chunk2.heading, chunk2.text),
+      provenance: "inferred",
+      // a written claim, and the kind of content most likely to go stale
       meta: {
         path: file.path,
         heading: chunk2.heading,
@@ -3255,6 +3497,8 @@ ${summary.body}`;
     files: extractMentionedFiles(session.turns.map((t) => `${t.userText}
 ${t.assistantText}`).join("\n")),
     signal: scoreSession(session.turns.length),
+    provenance: "inferred",
+    // a model's distillation, not a directly observed event
     meta: {
       sessionKey: session.sessionKey,
       source: session.source,
@@ -3363,6 +3607,7 @@ function toMemoryNode2(entry, projectId, opts = {}) {
     body: renderBody(entry, maxBody),
     files: [],
     signal: scoreShellCommand(entry),
+    provenance: "observed",
     meta: {
       command: entry.command,
       cwd: entry.cwd,
@@ -3378,7 +3623,7 @@ function collectShellHistory(entries, projectId, opts = {}) {
 }
 
 // src/conversation/claude-code-reader.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { basename as basename2 } from "path";
 
 // src/conversation/paths.ts
@@ -3471,14 +3716,14 @@ async function collectClaudeCodeTranscripts(repoRoot) {
   const files = await listTranscriptFiles(repoRoot);
   const turns = [];
   for (const file of files) {
-    const raw = await readFile5(file, "utf8");
+    const raw = await readFile6(file, "utf8");
     turns.push(...parseClaudeCodeTranscript(raw, { sessionId: basename2(file, ".jsonl") }));
   }
   return turns;
 }
 
 // src/docs/read.ts
-import { readFile as readFile6, stat } from "fs/promises";
+import { readFile as readFile7, stat } from "fs/promises";
 import { join as join7 } from "path";
 var DEFAULT_PATHSPECS = ["*.md"];
 async function listDocFiles(repoRoot, opts = {}) {
@@ -3496,7 +3741,7 @@ async function readDocFiles(repoRoot, opts = {}) {
     let content;
     let mtime;
     try {
-      [content, { mtime }] = await Promise.all([readFile6(absPath, "utf8"), stat(absPath)]);
+      [content, { mtime }] = await Promise.all([readFile7(absPath, "utf8"), stat(absPath)]);
     } catch {
       unreadable.push(path);
       continue;
@@ -3508,10 +3753,10 @@ async function readDocFiles(repoRoot, opts = {}) {
 
 // src/shell/detect.ts
 import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile8, stat as stat2 } from "fs/promises";
+import { readFile as readFile9, stat as stat2 } from "fs/promises";
 
 // src/shell/hook-log.ts
-import { appendFile, mkdir as mkdir5, readFile as readFile7 } from "fs/promises";
+import { appendFile, mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 function parseHookLogLine(line) {
   const trimmed = line.trim();
@@ -3536,7 +3781,7 @@ function parseHookLogLine(line) {
 async function readHookLog(path, fromLine) {
   let raw;
   try {
-    raw = await readFile7(path, "utf8");
+    raw = await readFile8(path, "utf8");
   } catch {
     return { entries: [], totalLines: fromLine };
   }
@@ -3670,7 +3915,7 @@ function hookEntryToRaw(e) {
 }
 async function tryReadScrapeSource(path, parse, tailLines) {
   if (!existsSync4(path)) return null;
-  const [raw, stats] = await Promise.all([readFile8(path, "utf8"), stat2(path)]);
+  const [raw, stats] = await Promise.all([readFile9(path, "utf8"), stat2(path)]);
   return parse(raw, stats.mtimeMs, { tailLines });
 }
 async function collectAvailableShellHistory(opts = {}) {
@@ -3824,7 +4069,7 @@ function reconcileProjectId(db, oldProjectId, newProjectId) {
 }
 
 // src/structure/collect.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { join as join8 } from "path";
 
 // src/structure/extract.ts
@@ -3901,7 +4146,7 @@ async function collectFileEdges(repoRoot) {
   for (const path of paths) {
     let content;
     try {
-      content = await readFile9(join8(repoRoot, path), "utf8");
+      content = await readFile10(join8(repoRoot, path), "utf8");
     } catch {
       unreadable.push(path);
       continue;
@@ -4005,25 +4250,25 @@ function addStats(into, from) {
 async function syncGit(store, projectId, opts, repo, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0, denied: 0 };
   if (!repo.head) {
-    log(`${pc6.yellow("git")} skipped -- repository has no commits yet`);
+    log(`${pc7.yellow("git")} skipped -- repository has no commits yet`);
     return { totals, seen: 0 };
   }
   if (!config.sources.git.enabled) {
-    log(`${pc6.dim("git")} disabled in config`);
+    log(`${pc7.dim("git")} disabled in config`);
     return { totals, seen: 0 };
   }
   let cursor = opts.full || opts.rebuild ? null : store.getSyncCursor(projectId, GIT_SOURCE);
   if (cursor && !await isAncestor(repo.root, cursor, repo.head)) {
-    log(`${pc6.yellow("git cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a full walk`);
+    log(`${pc7.yellow("git cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a full walk`);
     cursor = null;
   }
   if (cursor === repo.head) {
-    log(`${pc6.green("git up to date")} at ${repo.head.slice(0, 7)}`);
+    log(`${pc7.green("git up to date")} at ${repo.head.slice(0, 7)}`);
     store.setSyncCursor(projectId, GIT_SOURCE, repo.head);
     return { totals, seen: 0 };
   }
   log(
-    `${pc6.dim("git syncing")} ${repo.branch ?? "HEAD"} ${cursor ? `${cursor.slice(0, 7)}..${repo.head.slice(0, 7)}` : "(full history)"}`
+    `${pc7.dim("git syncing")} ${repo.branch ?? "HEAD"} ${cursor ? `${cursor.slice(0, 7)}..${repo.head.slice(0, 7)}` : "(full history)"}`
   );
   let batch = [];
   let seen = 0;
@@ -4031,7 +4276,7 @@ async function syncGit(store, projectId, opts, repo, config, log) {
     if (batch.length === 0) return;
     addStats(totals, store.upsertNodes(batch));
     batch = [];
-    log(`  ${pc6.dim(`${seen} commits read, ${totals.inserted} new`)}`);
+    log(`  ${pc7.dim(`${seen} commits read, ${totals.inserted} new`)}`);
   };
   const nodes = collectGitCommits(repo.root, projectId, {
     afterCommit: cursor,
@@ -4053,12 +4298,12 @@ async function syncDiffs(store, projectId, opts, repo, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0, denied: 0 };
   if (!repo.head) return { totals, seen: 0 };
   if (!config.sources.diff.enabled) {
-    log(`${pc6.dim("diff")} disabled in config`);
+    log(`${pc7.dim("diff")} disabled in config`);
     return { totals, seen: 0 };
   }
   let cursor = opts.full || opts.rebuild ? null : store.getSyncCursor(projectId, DIFF_SOURCE);
   if (cursor && !await isAncestor(repo.root, cursor, repo.head)) {
-    log(`${pc6.yellow("diff cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a bounded walk`);
+    log(`${pc7.yellow("diff cursor stale")} ${cursor.slice(0, 7)} is not an ancestor of HEAD \u2014 falling back to a bounded walk`);
     cursor = null;
   }
   if (cursor === repo.head) {
@@ -4087,13 +4332,13 @@ async function syncDiffs(store, projectId, opts, repo, config, log) {
   }
   flush();
   store.setSyncCursor(projectId, DIFF_SOURCE, repo.head);
-  log(`  ${pc6.dim(`${DIFF_SOURCE}: ${seen} file diff(s) read`)}`);
+  log(`  ${pc7.dim(`${DIFF_SOURCE}: ${seen} file diff(s) read`)}`);
   return { totals, seen };
 }
 async function syncShell(store, projectId, opts, repoRoot, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0, denied: 0 };
   if (!config.sources.shell.enabled) {
-    log(`${pc6.dim("shell")} disabled in config`);
+    log(`${pc7.dim("shell")} disabled in config`);
     return { totals, seen: 0 };
   }
   const results = await collectAvailableShellHistory({
@@ -4102,7 +4347,7 @@ async function syncShell(store, projectId, opts, repoRoot, config, log) {
     hookCursor: store.getSyncCursor(projectId, "shell:pwsh-hook")
   });
   if (results.length === 0) {
-    log(`${pc6.dim("shell")} no history source found on this machine`);
+    log(`${pc7.dim("shell")} no history source found on this machine`);
     return { totals, seen: 0 };
   }
   let seen = 0;
@@ -4114,7 +4359,7 @@ async function syncShell(store, projectId, opts, repoRoot, config, log) {
       addStats(totals, store.upsertNodes(nodes));
     }
     store.setSyncCursor(projectId, sourceKey, result.cursorAfter ?? `scanned:${result.entries.length}`);
-    log(`  ${pc6.dim(`${sourceKey}: ${nodes.length} entr${nodes.length === 1 ? "y" : "ies"} read`)}`);
+    log(`  ${pc7.dim(`${sourceKey}: ${nodes.length} entr${nodes.length === 1 ? "y" : "ies"} read`)}`);
   }
   return { totals, seen };
 }
@@ -4126,13 +4371,13 @@ function syncConversation(store, projectId, turns, config, log, forceEnabled) {
     return { totals, seen: 0 };
   }
   if (turns.length === 0) {
-    log(`${pc6.dim("conversation")} no transcripts found`);
+    log(`${pc7.dim("conversation")} no transcripts found`);
     return { totals, seen: 0 };
   }
   const nodes = collectConversationTurns(turns, projectId, { maxBodyChars: config.limits.maxBodyChars });
   if (nodes.length > 0) addStats(totals, store.upsertNodes(nodes));
   store.setSyncCursor(projectId, CONVERSATION_SOURCE, `scanned:${nodes.length}`);
-  log(`  ${pc6.dim(`${CONVERSATION_SOURCE}: ${nodes.length} of ${turns.length} exchange(s) kept`)}`);
+  log(`  ${pc7.dim(`${CONVERSATION_SOURCE}: ${nodes.length} of ${turns.length} exchange(s) kept`)}`);
   return { totals, seen: nodes.length };
 }
 var SESSION_SOURCE = "session:claude-code";
@@ -4141,7 +4386,7 @@ async function syncSessions(store, projectId, turns, config, log) {
   const settings = config.sources.session;
   if (!settings.enabled) return { totals, seen: 0 };
   if (turns.length === 0) {
-    log(`${pc6.dim("session")} no transcripts found`);
+    log(`${pc7.dim("session")} no transcripts found`);
     return { totals, seen: 0 };
   }
   const result = await collectSessionSummaries(turns, projectId, new OllamaChatProvider({ model: settings.model }), {
@@ -4153,12 +4398,12 @@ async function syncSessions(store, projectId, turns, config, log) {
       const meta = store.getNodeMeta(makeNodeId(projectId, "session_summary", sessionKey));
       return typeof meta?.contentHash === "string" ? meta.contentHash : null;
     },
-    onProgress: (done, total) => log(`  ${pc6.dim(`session: summarizing ${done}/${total}`)}`)
+    onProgress: (done, total) => log(`  ${pc7.dim(`session: summarizing ${done}/${total}`)}`)
   });
   if (result.nodes.length > 0) addStats(totals, store.upsertNodes(result.nodes));
   if (result.providerUnavailable) {
     log(
-      `${pc6.dim("session")} summarization model unavailable (is Ollama running with \`${settings.model}\` pulled?) -- skipped`
+      `${pc7.dim("session")} summarization model unavailable (is Ollama running with \`${settings.model}\` pulled?) -- skipped`
     );
   } else {
     const parts = [`${result.nodes.length} summarized`];
@@ -4166,7 +4411,7 @@ async function syncSessions(store, projectId, turns, config, log) {
     if (result.deferred > 0) parts.push(`${result.deferred} queued for the next sync`);
     if (result.unsettled > 0) parts.push(`${result.unsettled} still active`);
     if (result.failed > 0) parts.push(`${result.failed} failed`);
-    log(`  ${pc6.dim(`${SESSION_SOURCE}: ${parts.join(", ")}`)}`);
+    log(`  ${pc7.dim(`${SESSION_SOURCE}: ${parts.join(", ")}`)}`);
   }
   store.setSyncCursor(projectId, SESSION_SOURCE, `scanned:${result.nodes.length}`);
   return { totals, seen: result.nodes.length };
@@ -4175,7 +4420,7 @@ var DOCS_SOURCE = "docs";
 async function syncDocs(store, projectId, repoRoot, config, log) {
   const totals = { inserted: 0, updated: 0, unchanged: 0, denied: 0 };
   if (!config.sources.docs.enabled) {
-    log(`${pc6.dim("docs")} disabled in config`);
+    log(`${pc7.dim("docs")} disabled in config`);
     return { totals, seen: 0 };
   }
   const { files, unreadable } = await readDocFiles(repoRoot, { include: config.sources.docs.include });
@@ -4189,23 +4434,23 @@ async function syncDocs(store, projectId, repoRoot, config, log) {
   );
   store.setSyncCursor(projectId, DOCS_SOURCE, `scanned:${nodes.length}`);
   if (files.length === 0 && unreadable.length === 0) {
-    log(`${pc6.dim("docs")} no tracked .md files found`);
+    log(`${pc7.dim("docs")} no tracked .md files found`);
   } else {
-    const prunedPart = pruned > 0 ? `, ${pc6.yellow(`${pruned} stale removed`)}` : "";
+    const prunedPart = pruned > 0 ? `, ${pc7.yellow(`${pruned} stale removed`)}` : "";
     const skippedPart = unreadable.length > 0 ? `, ${unreadable.length} unreadable (kept)` : "";
-    log(`  ${pc6.dim(`${DOCS_SOURCE}: ${nodes.length} section(s) from ${files.length} file(s)`)}${prunedPart}${pc6.dim(skippedPart)}`);
+    log(`  ${pc7.dim(`${DOCS_SOURCE}: ${nodes.length} section(s) from ${files.length} file(s)`)}${prunedPart}${pc7.dim(skippedPart)}`);
   }
   return { totals, seen: nodes.length };
 }
 async function syncStructure(store, projectId, repoRoot, config, log) {
   if (!config.sources.structure.enabled) {
-    log(`${pc6.dim("structure")} disabled in config`);
+    log(`${pc7.dim("structure")} disabled in config`);
     return { edges: 0, filesScanned: 0 };
   }
   const { edges, filesScanned, unreadable } = await collectFileEdges(repoRoot);
   store.replaceFileEdges(projectId, edges);
   const skippedPart = unreadable.length > 0 ? `, ${unreadable.length} unreadable (skipped)` : "";
-  log(`  ${pc6.dim(`structure: ${edges.length} edge(s) from ${filesScanned} file(s)`)}${pc6.dim(skippedPart)}`);
+  log(`  ${pc7.dim(`structure: ${edges.length} edge(s) from ${filesScanned} file(s)`)}${pc7.dim(skippedPart)}`);
   return { edges: edges.length, filesScanned };
 }
 var STALE_SHELL_SOURCES = ["shell:pwsh", "shell:bash", "shell:zsh"];
@@ -4222,15 +4467,15 @@ function runPruneSources(store, projectId, otherProjectIds, sources, yes, out) {
   const counts = sources.flatMap((source) => scopeIds.map((id) => ({ source, id, count: store.countSourceNodes(id, source) })));
   const total = counts.reduce((sum, c) => sum + c.count, 0);
   if (total === 0) {
-    out(`${pc6.dim("prune-source")} no node(s) match ${sources.join(", ")} -- nothing to do
+    out(`${pc7.dim("prune-source")} no node(s) match ${sources.join(", ")} -- nothing to do
 `);
     return 0;
   }
-  const describe = (c) => `  ${pc6.dim(c.source)}${c.id !== projectId ? pc6.dim(` (prior identity ${c.id.slice(0, 8)})`) : ""}: ${c.count} node(s)`;
+  const describe = (c) => `  ${pc7.dim(c.source)}${c.id !== projectId ? pc7.dim(` (prior identity ${c.id.slice(0, 8)})`) : ""}: ${c.count} node(s)`;
   if (!yes) {
     const lines = counts.filter((c) => c.count > 0).map(describe);
     out(
-      [`${pc6.yellow("would remove")} ${total} node(s):`, ...lines, pc6.dim("re-run with --yes to actually delete these -- this cannot be undone"), ""].join(
+      [`${pc7.yellow("would remove")} ${total} node(s):`, ...lines, pc7.dim("re-run with --yes to actually delete these -- this cannot be undone"), ""].join(
         "\n"
       )
     );
@@ -4239,7 +4484,7 @@ function runPruneSources(store, projectId, otherProjectIds, sources, yes, out) {
   let removed = 0;
   for (const { source, id } of counts) removed += store.pruneSourceNodes(id, source, []);
   const identityPart = otherProjectIds.length > 0 ? `, ${scopeIds.length} project identit${scopeIds.length === 1 ? "y" : "ies"}` : "";
-  out(`${pc6.green("pruned")} ${removed} node(s) across ${sources.length} source(s)${identityPart}
+  out(`${pc7.green("pruned")} ${removed} node(s) across ${sources.length} source(s)${identityPart}
 `);
   return 0;
 }
@@ -4256,7 +4501,7 @@ async function runSync(opts) {
     store.upsertProject({ id: projectId, root: repo.root, originUrl: repo.originUrl });
     if (opts.rebuild) {
       const removed = store.clearProject(projectId);
-      log(`${pc6.dim("rebuild")} dropped ${removed} existing node(s)`);
+      log(`${pc7.dim("rebuild")} dropped ${removed} existing node(s)`);
     }
     const staleProjectIds = store.listOtherProjectIds(projectId);
     for (const staleId of staleProjectIds) {
@@ -4270,7 +4515,7 @@ async function runSync(opts) {
       ].filter((part) => part !== null);
       if (parts.length > 0) {
         log(
-          `${pc6.yellow("reconciled")} previous project identity ${pc6.dim(staleId)} (remote URL likely changed): ${parts.join(", ")}`
+          `${pc7.yellow("reconciled")} previous project identity ${pc7.dim(staleId)} (remote URL likely changed): ${parts.join(", ")}`
         );
       }
     }
@@ -4300,26 +4545,26 @@ async function runSync(opts) {
       let lastLogged = 0;
       const result = await embedPendingNodes(store, new OllamaEmbeddingProvider(), projectId, {
         maxNodes: opts.embedLimit,
-        onInvalidated: (count) => log(`${pc6.yellow("vector")} embedding model changed -- dropped ${count} vector(s), re-embedding from scratch`),
+        onInvalidated: (count) => log(`${pc7.yellow("vector")} embedding model changed -- dropped ${count} vector(s), re-embedding from scratch`),
         onProgress: (attempted, total) => {
           if (total < PROGRESS_THRESHOLD || attempted - lastLogged < PROGRESS_EVERY) return;
           lastLogged = attempted;
-          log(`  ${pc6.dim(`vector: ${attempted}/${total} embedded`)}`);
+          log(`  ${pc7.dim(`vector: ${attempted}/${total} embedded`)}`);
         }
       });
       if (result.embedded > 0) {
-        const skippedPart = result.skipped > 0 ? pc6.dim(`, ${result.skipped} skipped`) : "";
-        const remainingPart = result.remaining > 0 ? pc6.yellow(`, ${result.remaining} still pending`) : "";
-        embedLine = `  ${pc6.dim(`vector: ${result.embedded} node(s) embedded`)}${skippedPart}${remainingPart}
+        const skippedPart = result.skipped > 0 ? pc7.dim(`, ${result.skipped} skipped`) : "";
+        const remainingPart = result.remaining > 0 ? pc7.yellow(`, ${result.remaining} still pending`) : "";
+        embedLine = `  ${pc7.dim(`vector: ${result.embedded} node(s) embedded`)}${skippedPart}${remainingPart}
 `;
       } else if (result.providerUnavailable) {
-        log(`${pc6.dim("vector")} embedding provider unavailable (is Ollama running with nomic-embed-text pulled?) -- BM25-only for now`);
+        log(`${pc7.dim("vector")} embedding provider unavailable (is Ollama running with nomic-embed-text pulled?) -- BM25-only for now`);
       }
     }
     let linkLine = "";
     if (opts.linkFailures) {
       const linkStats = correlateFailures(store, projectId);
-      linkLine = `  ${pc6.dim(`chains: ${linkStats.failuresExamined} failure(s) examined, ${linkStats.linkedByRetry} linked by retry, ${linkStats.linkedByDiscussion} by discussion`)}
+      linkLine = `  ${pc7.dim(`chains: ${linkStats.failuresExamined} failure(s) examined, ${linkStats.linkedByRetry} linked by retry, ${linkStats.linkedByDiscussion} by discussion`)}
 `;
     }
     store.markSynced(projectId);
@@ -4337,12 +4582,12 @@ async function runSync(opts) {
     const docsPart = config.sources.docs.enabled ? `, ${docs.seen} doc section(s)` : "";
     const diffPart = config.sources.diff.enabled ? `, ${diffs.seen} file diff(s)` : "";
     const structurePart = config.sources.structure.enabled ? `, ${structure.edges} import edge(s)` : "";
-    const deniedPart = totals.denied > 0 ? `  ${pc6.red(`-${totals.denied} denied`)}` : "";
+    const deniedPart = totals.denied > 0 ? `  ${pc7.red(`-${totals.denied} denied`)}` : "";
     out(
       [
-        `${pc6.green("synced")} ${git2.seen} commit(s)${diffPart}, ${shell.seen} shell entr${shell.seen === 1 ? "y" : "ies"}${conversationPart}${sessionPart}${docsPart}${structurePart} in ${elapsed}s`,
-        `  ${pc6.green(`+${totals.inserted} new`)}  ${pc6.yellow(`~${totals.updated} updated`)}  ${pc6.dim(`=${totals.unchanged} unchanged`)}${deniedPart}`,
-        `  ${pc6.dim(`${stats.total} node(s) total across ${stats.distinctFiles} file path(s)`)}`,
+        `${pc7.green("synced")} ${git2.seen} commit(s)${diffPart}, ${shell.seen} shell entr${shell.seen === 1 ? "y" : "ies"}${conversationPart}${sessionPart}${docsPart}${structurePart} in ${elapsed}s`,
+        `  ${pc7.green(`+${totals.inserted} new`)}  ${pc7.yellow(`~${totals.updated} updated`)}  ${pc7.dim(`=${totals.unchanged} unchanged`)}${deniedPart}`,
+        `  ${pc7.dim(`${stats.total} node(s) total across ${stats.distinctFiles} file path(s)`)}`,
         ""
       ].join("\n") + embedLine + linkLine
     );
@@ -4453,10 +4698,10 @@ function createServer() {
       title: "Search remembered project history",
       description: "Search a NexusMem-tracked repository's remembered history: git commits, code diffs (the patch of each changed file), shell commands, tracked markdown docs, and (if enabled) conversation transcripts and per-session summaries. Returns a token-budgeted, ranked context block -- not raw search results.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        query: z3.string().describe("Free-text question or search terms"),
-        budget: z3.number().int().positive().optional().describe("Max tokens in the returned context block. Default 2000."),
-        allProjects: z3.boolean().optional().describe(
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        query: z4.string().describe("Free-text question or search terms"),
+        budget: z4.number().int().positive().optional().describe("Max tokens in the returned context block. Default 2000."),
+        allProjects: z4.boolean().optional().describe(
           "Search every repository NexusMem has been run in on this machine, not just projectRoot. Use when the answer may live in a different project (a pattern solved elsewhere, a tool that failed the same way before). Each result is tagged with its repository."
         )
       }
@@ -4483,10 +4728,10 @@ function createServer() {
       title: "Sync remembered history",
       description: "Ingest new git, diff, shell, docs and (if enabled) conversation history for a NexusMem-tracked repository into its local database. Pass pruneSource or pruneStaleShell instead to delete a dead source's nodes (e.g. the pre-hook shell scrape) rather than syncing -- dry-run unless yes is also true, since this is an irreversible full wipe of that source.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        pruneSource: z3.string().optional().describe('Delete every node from this exact source (e.g. "shell:pwsh") instead of syncing'),
-        pruneStaleShell: z3.boolean().optional().describe("Shortcut for pruneSource on shell:pwsh, shell:bash and shell:zsh at once -- the dead pre-hook scrape sources"),
-        yes: z3.boolean().optional().describe("Confirms the delete. Without it, pruneSource/pruneStaleShell only report the matching count.")
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        pruneSource: z4.string().optional().describe('Delete every node from this exact source (e.g. "shell:pwsh") instead of syncing'),
+        pruneStaleShell: z4.boolean().optional().describe("Shortcut for pruneSource on shell:pwsh, shell:bash and shell:zsh at once -- the dead pre-hook scrape sources"),
+        yes: z4.boolean().optional().describe("Confirms the delete. Without it, pruneSource/pruneStaleShell only report the matching count.")
       }
     },
     async ({ projectRoot, pruneSource, pruneStaleShell, yes }) => {
@@ -4500,7 +4745,7 @@ function createServer() {
       title: "Show what is remembered",
       description: "Report how many nodes NexusMem currently remembers for a repository, broken down by kind and source.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root")
+        projectRoot: z4.string().describe("Absolute path to the repository root")
       }
     },
     async ({ projectRoot }) => {
@@ -4517,8 +4762,8 @@ function createServer() {
       title: "List recently remembered items",
       description: "List the most recently remembered items for a NexusMem-tracked repository -- git commits, code diffs, shell commands, tracked docs, and (if enabled) conversation transcripts and session summaries -- newest first. Chronological, not relevance-ranked: use search_memory instead for a specific question.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        limit: z3.number().int().positive().optional().describe("Max items to return, newest first. Default 20.")
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        limit: z4.number().int().positive().optional().describe("Max items to return, newest first. Default 20.")
       }
     },
     async ({ projectRoot, limit }) => {
@@ -4538,7 +4783,7 @@ async function runMcpServer() {
 }
 
 // src/cli/commands/precheck.ts
-import pc7 from "picocolors";
+import pc8 from "picocolors";
 
 // src/correlate/precheck.ts
 var DEFAULT_RECENT_DAYS = 30;
@@ -4595,7 +4840,7 @@ async function runPrecheck(opts) {
   const { repo, ws, projectId } = await loadContext(opts.cwd);
   const targetFiles = opts.files ?? (opts.working ? await workingTreeFiles(repo.root) : await stagedFiles(repo.root));
   if (targetFiles.length === 0) {
-    if (!opts.quiet) out(`${pc7.dim("precheck")} no files to check
+    if (!opts.quiet) out(`${pc8.dim("precheck")} no files to check
 `);
     return 0;
   }
@@ -4608,45 +4853,45 @@ async function runPrecheck(opts) {
   }
   const flagged = risks.filter((r) => r.unresolvedFailures.length > 0 || r.commitsRecent >= HIGH_CHURN_THRESHOLD);
   if (flagged.length === 0) {
-    if (!opts.quiet) out(`${pc7.green("precheck")} no warnings \u2014 looking good
+    if (!opts.quiet) out(`${pc8.green("precheck")} no warnings \u2014 looking good
 `);
     return 0;
   }
   out(`
-${pc7.bold("nexusmem precheck")}
-${pc7.dim("-".repeat(40))}
+${pc8.bold("nexusmem precheck")}
+${pc8.dim("-".repeat(40))}
 
 `);
   for (const risk of flagged) {
-    out(`  ${pc7.bold(risk.path)}
+    out(`  ${pc8.bold(risk.path)}
 `);
     if (risk.unresolvedFailures.length > 0) {
-      out(`    ${pc7.yellow("WARN")}  What already failed here (${risk.unresolvedFailures.length} unresolved):
+      out(`    ${pc8.yellow("WARN")}  What already failed here (${risk.unresolvedFailures.length} unresolved):
 `);
       for (const f of risk.unresolvedFailures.slice(0, 3)) {
-        out(`           ${pc7.dim(`${f.ts.slice(0, 10)}  ${f.command.slice(0, 90)}`)}
+        out(`           ${pc8.dim(`${f.ts.slice(0, 10)}  ${f.command.slice(0, 90)}`)}
 `);
       }
       if (risk.unresolvedFailures.length > 3) {
-        out(`           ${pc7.dim(`... and ${risk.unresolvedFailures.length - 3} more`)}
+        out(`           ${pc8.dim(`... and ${risk.unresolvedFailures.length - 3} more`)}
 `);
       }
     }
     if (risk.commitsRecent >= HIGH_CHURN_THRESHOLD) {
-      out(`    ${pc7.yellow("WARN")}  high churn: ${risk.commitsRecent} commits touched this file recently
+      out(`    ${pc8.yellow("WARN")}  high churn: ${risk.commitsRecent} commits touched this file recently
 `);
     }
     out("\n");
   }
   const failureCount = flagged.filter((r) => r.unresolvedFailures.length > 0).length;
-  out(`${pc7.dim(`${flagged.length} file(s) flagged, ${failureCount} with unresolved failures.`)}
+  out(`${pc8.dim(`${flagged.length} file(s) flagged, ${failureCount} with unresolved failures.`)}
 `);
   if (opts.strict && failureCount > 0) return 1;
   return 0;
 }
 
 // src/cli/commands/query.ts
-import pc8 from "picocolors";
+import pc9 from "picocolors";
 async function runQuery(opts) {
   const { repo, ws, projectId } = await loadContext(opts.cwd);
   const opened = opts.allProjects ? await openAllProjectSources({ projectId, root: repo.root, dbPath: ws.dbPath }) : null;
@@ -4668,15 +4913,15 @@ async function runQuery(opts) {
     const { bm25Count, vectorCount, hits, packed } = result;
     if (opened && !opts.json) {
       const searched = opened.sources.map((s) => s.label).join(", ");
-      process.stderr.write(`${pc8.dim("scope  ")} ${opened.sources.length} project(s): ${searched}
+      process.stderr.write(`${pc9.dim("scope  ")} ${opened.sources.length} project(s): ${searched}
 `);
       for (const { entry } of opened.unreadable) {
-        process.stderr.write(`${pc8.yellow("unreadable")} ${entry.root} -- skipped
+        process.stderr.write(`${pc9.yellow("unreadable")} ${entry.root} -- skipped
 `);
       }
       if (opened.missing.length > 0) {
         process.stderr.write(
-          `${pc8.dim("skipped")} ${opened.missing.length} registered project(s) whose database is not on disk ${pc8.dim("(nexusmem projects --prune to forget them)")}
+          `${pc9.dim("skipped")} ${opened.missing.length} registered project(s) whose database is not on disk ${pc9.dim("(nexusmem projects --prune to forget them)")}
 `
         );
       }
@@ -4706,15 +4951,15 @@ async function runQuery(opts) {
       return 0;
     }
     if (matched === 0) {
-      process.stderr.write(`${pc8.yellow("no matches")} for "${opts.query}"
+      process.stderr.write(`${pc9.yellow("no matches")} for "${opts.query}"
 `);
       return 0;
     }
     process.stderr.write(
       [
-        `${pc8.dim("matched")} ${bm25Count} bm25${vectorCount > 0 ? ` + ${vectorCount} vector` : ""}, packed ${pc8.bold(String(packed.nodes.length))} into budget`,
-        `${pc8.dim("tokens ")} ${packed.tokensUsed}/${packed.tokensBudget}` + (packed.droppedForBudget ? pc8.dim(`  (${packed.droppedForBudget} dropped for budget)`) : "") + (packed.droppedForDiversity ? pc8.dim(`  (${packed.droppedForDiversity} dropped for diversity)`) : ""),
-        rawTokens > 0 ? `${pc8.dim("vs raw ")} ${rawTokens} tokens if these same matches were sent unpacked  ${packerEfficiency >= 0 ? pc8.green(`(${(packerEfficiency * 100).toFixed(0)}% packer efficiency)`) : pc8.yellow(`(${(-packerEfficiency * 100).toFixed(0)}% larger -- overhead dominates on small result sets)`)}` : "",
+        `${pc9.dim("matched")} ${bm25Count} bm25${vectorCount > 0 ? ` + ${vectorCount} vector` : ""}, packed ${pc9.bold(String(packed.nodes.length))} into budget`,
+        `${pc9.dim("tokens ")} ${packed.tokensUsed}/${packed.tokensBudget}` + (packed.droppedForBudget ? pc9.dim(`  (${packed.droppedForBudget} dropped for budget)`) : "") + (packed.droppedForDiversity ? pc9.dim(`  (${packed.droppedForDiversity} dropped for diversity)`) : ""),
+        rawTokens > 0 ? `${pc9.dim("vs raw ")} ${rawTokens} tokens if these same matches were sent unpacked  ${packerEfficiency >= 0 ? pc9.green(`(${(packerEfficiency * 100).toFixed(0)}% packer efficiency)`) : pc9.yellow(`(${(-packerEfficiency * 100).toFixed(0)}% larger -- overhead dominates on small result sets)`)}` : "",
         ""
       ].filter(Boolean).join("\n")
     );
@@ -4728,10 +4973,10 @@ async function runQuery(opts) {
 }
 
 // src/cli/commands/scan-conversation.ts
-import pc10 from "picocolors";
+import pc11 from "picocolors";
 
 // src/cli/format.ts
-import pc9 from "picocolors";
+import pc10 from "picocolors";
 var GIT_SIGNAL_BANDS = { high: 0.7, medium: 0.45 };
 var SHELL_SIGNAL_BANDS = { high: 0.6, medium: 0.4 };
 var CONVERSATION_SIGNAL_BANDS = { high: 0.55, medium: 0.35 };
@@ -4743,9 +4988,9 @@ function signalBand(signal, bands) {
   return "low";
 }
 var BAND_COLOR = {
-  high: pc9.green,
-  medium: pc9.yellow,
-  low: pc9.dim
+  high: pc10.green,
+  medium: pc10.yellow,
+  low: pc10.dim
 };
 function formatSignal(signal, bands) {
   return BAND_COLOR[signalBand(signal, bands)](signal.toFixed(2));
@@ -4758,9 +5003,9 @@ async function runScanConversation(opts) {
   const files = await listTranscriptFiles(repo.root);
   if (!opts.json) {
     process.stderr.write(
-      files.length ? `${pc10.dim("transcripts")} ${files.length} file(s) in ${claudeProjectTranscriptDir(repo.root)}
+      files.length ? `${pc11.dim("transcripts")} ${files.length} file(s) in ${claudeProjectTranscriptDir(repo.root)}
 
-` : `${pc10.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
+` : `${pc11.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
 `
     );
   }
@@ -4777,7 +5022,7 @@ async function runScanConversation(opts) {
   const approxTotal = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
   process.stderr.write(
     `
-${pc10.bold(String(nodes.length))} of ${turns.length} exchange(s) above threshold  ${pc10.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}` + (redactedTotal > 0 ? `  ${pc10.yellow(`${redactedTotal} secret-like value(s) redacted`)}` : "") + "\n"
+${pc11.bold(String(nodes.length))} of ${turns.length} exchange(s) above threshold  ${pc11.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}` + (redactedTotal > 0 ? `  ${pc11.yellow(`${redactedTotal} secret-like value(s) redacted`)}` : "") + "\n"
   );
   return 0;
 }
@@ -4786,20 +5031,20 @@ function formatNode(node) {
 }
 
 // src/cli/commands/scan-diff.ts
-import pc12 from "picocolors";
+import pc13 from "picocolors";
 
 // src/cli/commands/scan-git.ts
-import pc11 from "picocolors";
+import pc12 from "picocolors";
 async function runScanGit(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   if (!opts.json) {
     process.stderr.write(
       [
-        `${pc11.dim("repo   ")} ${repo.root}`,
-        `${pc11.dim("branch ")} ${repo.branch ?? pc11.yellow("(detached)")}`,
-        `${pc11.dim("origin ")} ${repo.originUrl ?? pc11.dim("(none)")}`,
-        `${pc11.dim("project")} ${pc11.cyan(projectId)}`,
+        `${pc12.dim("repo   ")} ${repo.root}`,
+        `${pc12.dim("branch ")} ${repo.branch ?? pc12.yellow("(detached)")}`,
+        `${pc12.dim("origin ")} ${repo.originUrl ?? pc12.dim("(none)")}`,
+        `${pc12.dim("project")} ${pc12.cyan(projectId)}`,
         ""
       ].join("\n")
     );
@@ -4833,14 +5078,14 @@ function formatNode2(node) {
   const churn = `+${node.meta.insertions ?? 0}/-${node.meta.deletions ?? 0}`;
   return [
     formatSignal(node.signal, GIT_SIGNAL_BANDS),
-    pc11.dim(date),
-    pc11.magenta(sha),
+    pc12.dim(date),
+    pc12.magenta(sha),
     node.title,
-    pc11.dim(`(${files} file${files === 1 ? "" : "s"}, ${churn})`)
+    pc12.dim(`(${files} file${files === 1 ? "" : "s"}, ${churn})`)
   ].join(" ");
 }
 function summarize2(nodes) {
-  if (nodes.length === 0) return pc11.yellow("no commits matched");
+  if (nodes.length === 0) return pc12.yellow("no commits matched");
   const timestamps = nodes.map((n) => n.ts).sort();
   const avgSignal = nodes.reduce((n, x) => n + x.signal, 0) / nodes.length;
   const totalTokens = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
@@ -4850,7 +5095,7 @@ function summarize2(nodes) {
   }
   const hottest = [...fileHits.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([path, count]) => `    ${String(count).padStart(3)}x ${path}`);
   return [
-    `${pc11.bold(String(nodes.length))} nodes  ${pc11.dim(`${timestamps[0]?.slice(0, 10)} .. ${timestamps.at(-1)?.slice(0, 10)}`)}`,
+    `${pc12.bold(String(nodes.length))} nodes  ${pc12.dim(`${timestamps[0]?.slice(0, 10)} .. ${timestamps.at(-1)?.slice(0, 10)}`)}`,
     `  avg signal ${avgSignal.toFixed(3)}   ~${totalTokens.toLocaleString()} tokens if sent raw`,
     hottest.length ? `  hottest files:
 ${hottest.join("\n")}` : ""
@@ -4865,9 +5110,9 @@ async function runScanDiff(opts) {
   if (!opts.json) {
     process.stderr.write(
       [
-        `${pc12.dim("repo   ")} ${repo.root}`,
-        `${pc12.dim("branch ")} ${repo.branch ?? pc12.yellow("(detached)")}`,
-        `${pc12.dim("project")} ${pc12.cyan(projectId)}`,
+        `${pc13.dim("repo   ")} ${repo.root}`,
+        `${pc13.dim("branch ")} ${repo.branch ?? pc13.yellow("(detached)")}`,
+        `${pc13.dim("project")} ${pc13.cyan(projectId)}`,
         ""
       ].join("\n")
     );
@@ -4897,28 +5142,28 @@ function formatNode3(node) {
   const churn = `+${node.meta.insertions ?? 0}/-${node.meta.deletions ?? 0}`;
   return [
     formatSignal(node.signal, DIFF_SIGNAL_BANDS),
-    pc12.dim(node.ts.slice(0, 10)),
-    pc12.magenta(sha),
+    pc13.dim(node.ts.slice(0, 10)),
+    pc13.magenta(sha),
     String(node.meta.path ?? ""),
-    pc12.dim(`(${churn}, ${node.meta.hunkCount ?? 0} hunk(s))`)
+    pc13.dim(`(${churn}, ${node.meta.hunkCount ?? 0} hunk(s))`)
   ].join(" ");
 }
 
 // src/cli/commands/scan-docs.ts
-import pc13 from "picocolors";
+import pc14 from "picocolors";
 async function runScanDocs(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const { files, unreadable } = await readDocFiles(repo.root);
   if (!opts.json) {
     process.stderr.write(
-      files.length ? `${pc13.dim("tracked .md files")} ${files.map((f) => f.path).join(", ")}
+      files.length ? `${pc14.dim("tracked .md files")} ${files.map((f) => f.path).join(", ")}
 
-` : `${pc13.yellow("no tracked .md files found")}
+` : `${pc14.yellow("no tracked .md files found")}
 `
     );
     if (unreadable.length > 0) {
-      process.stderr.write(`${pc13.yellow("unreadable")} ${unreadable.join(", ")}
+      process.stderr.write(`${pc14.yellow("unreadable")} ${unreadable.join(", ")}
 
 `);
     }
@@ -4934,7 +5179,7 @@ async function runScanDocs(opts) {
   const approxTotal = nodes.reduce((n, x) => n + approxTokens(x.body), 0);
   process.stderr.write(
     `
-${pc13.bold(String(nodes.length))} section(s) from ${files.length} file(s) above threshold  ${pc13.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
+${pc14.bold(String(nodes.length))} section(s) from ${files.length} file(s) above threshold  ${pc14.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
 `
   );
   return 0;
@@ -4944,13 +5189,13 @@ function formatNode4(node) {
 }
 
 // src/cli/commands/scan-session.ts
-import pc14 from "picocolors";
+import pc15 from "picocolors";
 async function runScanSession(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const turns = await collectClaudeCodeTranscripts(repo.root);
   if (turns.length === 0) {
-    process.stderr.write(`${pc14.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
+    process.stderr.write(`${pc15.yellow("no transcripts found")} at ${claudeProjectTranscriptDir(repo.root)}
 `);
     return 0;
   }
@@ -4958,7 +5203,7 @@ async function runScanSession(opts) {
   const settled = selectSettledSessions(sessions, opts.settleMinutes);
   if (!opts.json) {
     process.stderr.write(
-      `${pc14.dim("sessions")} ${sessions.length} found, ${settled.length} settled (quiet ${opts.settleMinutes}m+)
+      `${pc15.dim("sessions")} ${sessions.length} found, ${settled.length} settled (quiet ${opts.settleMinutes}m+)
 
 `
     );
@@ -4984,7 +5229,7 @@ async function runScanSession(opts) {
     }
     for (const preview of previews) {
       process.stdout.write(
-        `${pc14.bold(preview.sessionKey)}  ${preview.startedAt.slice(0, 16).replace("T", " ")}  ${preview.includedTurns}/${preview.turns} turn(s), ${preview.promptChars} chars
+        `${pc15.bold(preview.sessionKey)}  ${preview.startedAt.slice(0, 16).replace("T", " ")}  ${preview.includedTurns}/${preview.turns} turn(s), ${preview.promptChars} chars
 ${preview.prompt}
 
 `
@@ -4996,7 +5241,7 @@ ${preview.prompt}
     settleMinutes: opts.settleMinutes,
     maxSessions: opts.maxSessions,
     onProgress: (done, total) => {
-      if (!opts.json) process.stderr.write(`  ${pc14.dim(`summarizing ${done}/${total}`)}
+      if (!opts.json) process.stderr.write(`  ${pc15.dim(`summarizing ${done}/${total}`)}
 `);
     }
   });
@@ -5006,21 +5251,21 @@ ${preview.prompt}
     return 0;
   }
   for (const node of result.nodes) {
-    process.stdout.write(`${pc14.bold(node.title)}
-${pc14.dim(node.ts.slice(0, 16).replace("T", " "))}
+    process.stdout.write(`${pc15.bold(node.title)}
+${pc15.dim(node.ts.slice(0, 16).replace("T", " "))}
 ${node.body}
 
 `);
   }
   if (result.providerUnavailable) {
     process.stderr.write(
-      `${pc14.yellow("model unavailable")} -- is Ollama running with \`${opts.model}\` pulled? (\`ollama pull ${opts.model}\`)
+      `${pc15.yellow("model unavailable")} -- is Ollama running with \`${opts.model}\` pulled? (\`ollama pull ${opts.model}\`)
 `
     );
     return 0;
   }
   process.stderr.write(
-    `${pc14.bold(String(result.nodes.length))} summarized` + (result.failed > 0 ? `, ${pc14.yellow(`${result.failed} failed`)}` : "") + ` ${pc14.dim(`(model ${opts.model})`)}
+    `${pc15.bold(String(result.nodes.length))} summarized` + (result.failed > 0 ? `, ${pc15.yellow(`${result.failed} failed`)}` : "") + ` ${pc15.dim(`(model ${opts.model})`)}
 `
   );
   return 0;
@@ -5028,16 +5273,16 @@ ${node.body}
 var SCAN_SESSION_DEFAULT_MODEL = DEFAULT_SLM_MODEL;
 
 // src/cli/commands/scan-shell.ts
-import pc15 from "picocolors";
+import pc16 from "picocolors";
 async function runScanShell(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const projectId = makeProjectId({ root: repo.root, originUrl: repo.originUrl });
   const results = await collectAvailableShellHistory({ tailLines: opts.tailLines, repoRoot: repo.root });
   if (!opts.json) {
     process.stderr.write(
-      results.length ? `${pc15.dim("sources found")} ${results.map((r) => r.name).join(", ")}
+      results.length ? `${pc16.dim("sources found")} ${results.map((r) => r.name).join(", ")}
 
-` : `${pc15.yellow("no shell history source found on this machine")}
+` : `${pc16.yellow("no shell history source found on this machine")}
 `
     );
   }
@@ -5046,7 +5291,7 @@ async function runScanShell(opts) {
     const nodes = collectShellHistory(result.entries, projectId).filter((n) => n.signal >= opts.minSignal);
     allNodes.push(...nodes);
     if (!opts.json) {
-      process.stdout.write(`${pc15.bold(`shell:${result.name}`)} ${pc15.dim(`(${nodes.length} of ${result.entries.length} above threshold)`)}
+      process.stdout.write(`${pc16.bold(`shell:${result.name}`)} ${pc16.dim(`(${nodes.length} of ${result.entries.length} above threshold)`)}
 `);
       for (const node of nodes) process.stdout.write(`${formatNode5(node)}
 `);
@@ -5059,19 +5304,19 @@ async function runScanShell(opts) {
     return 0;
   }
   const approxTotal = allNodes.reduce((n, x) => n + approxTokens(x.body), 0);
-  process.stderr.write(`${pc15.bold(String(allNodes.length))} node(s) total  ${pc15.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
+  process.stderr.write(`${pc16.bold(String(allNodes.length))} node(s) total  ${pc16.dim(`~${approxTotal.toLocaleString()} tokens if sent raw`)}
 `);
   return 0;
 }
 function formatNode5(node) {
-  const approx = node.meta.tsApprox ? pc15.dim("~") : " ";
+  const approx = node.meta.tsApprox ? pc16.dim("~") : " ";
   const exit = node.meta.exitCode;
-  const exitLabel = typeof exit === "number" && exit !== 0 ? pc15.red(`exit ${exit}`) : "";
+  const exitLabel = typeof exit === "number" && exit !== 0 ? pc16.red(`exit ${exit}`) : "";
   return [formatSignal(node.signal, SHELL_SIGNAL_BANDS), approx + node.ts.slice(0, 16).replace("T", " "), node.title, exitLabel].filter(Boolean).join(" ");
 }
 
 // src/cli/commands/scan-structure.ts
-import pc16 from "picocolors";
+import pc17 from "picocolors";
 async function runScanStructure(opts) {
   const repo = await readRepoInfo(opts.cwd);
   const { edges, filesScanned, unreadable } = await collectFileEdges(repo.root);
@@ -5081,17 +5326,17 @@ async function runScanStructure(opts) {
     return 0;
   }
   if (unreadable.length > 0) {
-    process.stderr.write(`${pc16.yellow("unreadable")} ${unreadable.join(", ")}
+    process.stderr.write(`${pc17.yellow("unreadable")} ${unreadable.join(", ")}
 
 `);
   }
   for (const edge of edges) {
-    process.stdout.write(`${edge.fromPath} ${pc16.dim("->")} ${edge.toPath}
+    process.stdout.write(`${edge.fromPath} ${pc17.dim("->")} ${edge.toPath}
 `);
   }
   process.stderr.write(
     `
-${pc16.bold(String(edges.length))} edge(s) from ${filesScanned} tracked .ts/.tsx/.js/.jsx file(s)
+${pc17.bold(String(edges.length))} edge(s) from ${filesScanned} tracked .ts/.tsx/.js/.jsx file(s)
 `
   );
   return 0;
@@ -5099,7 +5344,7 @@ ${pc16.bold(String(edges.length))} edge(s) from ${filesScanned} tracked .ts/.tsx
 
 // src/cli/commands/status.ts
 import { statSync } from "fs";
-import pc17 from "picocolors";
+import pc18 from "picocolors";
 function humanBytes(bytes) {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -5127,32 +5372,32 @@ async function runStatus(opts) {
     const structure = store.fileEdgeStats(projectId);
     const dbBytes = fileSize(ws.dbPath) + fileSize(`${ws.dbPath}-wal`);
     const kinds = Object.entries(stats.byKind).sort((a, b) => b[1] - a[1]).map(([kind, n]) => `    ${String(n).padStart(6)}  ${kind}`);
-    const staleProjectWarning = otherProjectIds.length ? `${pc17.yellow("stale   ")} ${otherProjectIds.length} prior project ${otherProjectIds.length === 1 ? "identity holds" : "identities hold"} ${otherProjectNodes} node(s) \u2014 run ${pc17.bold(
+    const staleProjectWarning = otherProjectIds.length ? `${pc18.yellow("stale   ")} ${otherProjectIds.length} prior project ${otherProjectIds.length === 1 ? "identity holds" : "identities hold"} ${otherProjectNodes} node(s) \u2014 run ${pc18.bold(
       "nexusmem sync --prune-source <name>"
     )} to remove stale source data` : "";
     out(
       [
-        `${pc17.dim("repo    ")} ${repo.root}`,
-        `${pc17.dim("branch  ")} ${repo.branch ?? pc17.yellow("(detached)")}`,
-        `${pc17.dim("project ")} ${pc17.cyan(projectId)}`,
-        `${pc17.dim("schema  ")} v${schema}${schema === LATEST_SCHEMA_VERSION ? "" : pc17.yellow(` (latest is v${LATEST_SCHEMA_VERSION})`)}`,
-        `${pc17.dim("database")} ${ws.dbPath} ${pc17.dim(`(${humanBytes(dbBytes)})`)}`,
+        `${pc18.dim("repo    ")} ${repo.root}`,
+        `${pc18.dim("branch  ")} ${repo.branch ?? pc18.yellow("(detached)")}`,
+        `${pc18.dim("project ")} ${pc18.cyan(projectId)}`,
+        `${pc18.dim("schema  ")} v${schema}${schema === LATEST_SCHEMA_VERSION ? "" : pc18.yellow(` (latest is v${LATEST_SCHEMA_VERSION})`)}`,
+        `${pc18.dim("database")} ${ws.dbPath} ${pc18.dim(`(${humanBytes(dbBytes)})`)}`,
         staleProjectWarning,
         "",
-        `${pc17.bold(String(stats.total))} node(s)${stats.total ? ` ${pc17.dim(`${stats.oldest?.slice(0, 10)} .. ${stats.newest?.slice(0, 10)}`)}` : ""}`,
+        `${pc18.bold(String(stats.total))} node(s)${stats.total ? ` ${pc18.dim(`${stats.oldest?.slice(0, 10)} .. ${stats.newest?.slice(0, 10)}`)}` : ""}`,
         ...kinds,
-        stats.total ? `    ${pc17.dim(`${stats.distinctFiles} distinct file path(s)`)}` : "",
+        stats.total ? `    ${pc18.dim(`${stats.distinctFiles} distinct file path(s)`)}` : "",
         "",
-        sources.length ? pc17.dim("sources") : pc17.yellow("no sources synced yet"),
+        sources.length ? pc18.dim("sources") : pc18.yellow("no sources synced yet"),
         ...sources.map((s) => {
           const when = s.lastRunAt ? new Date(s.lastRunAt).toISOString().slice(0, 16).replace("T", " ") : "never";
           const cursorLabel = s.source === "git" ? s.cursor?.slice(0, 7) ?? "-" : s.cursor ?? "-";
-          return `    ${s.source.padEnd(14)} ${pc17.dim(`last run ${when}`)}  ${pc17.dim(`cursor ${cursorLabel}`)}`;
+          return `    ${s.source.padEnd(14)} ${pc18.dim(`last run ${when}`)}  ${pc18.dim(`cursor ${cursorLabel}`)}`;
         }),
-        gitCursor && gitCursor !== repo.head ? `${pc17.yellow("git behind HEAD")} \u2014 run ${pc17.bold("nexusmem sync")}` : "",
+        gitCursor && gitCursor !== repo.head ? `${pc18.yellow("git behind HEAD")} \u2014 run ${pc18.bold("nexusmem sync")}` : "",
         "",
-        chains.failuresTotal ? `${pc17.dim("chains  ")} ${pc17.bold(String(chains.resolvedTotal))}/${chains.failuresTotal} failure(s) resolved ${pc17.dim(`(${chains.resolvedByRetry} retry, ${chains.resolvedByDiscussion} discussion)`)}${chains.resolvedTotal < chains.failuresTotal ? ` \u2014 run ${pc17.bold("nexusmem sync --link-failures")} to link more` : ""}` : "",
-        structure.edges ? `${pc17.dim("structure")} ${pc17.bold(String(structure.edges))} import edge(s) across ${structure.files} file(s)` : ""
+        chains.failuresTotal ? `${pc18.dim("chains  ")} ${pc18.bold(String(chains.resolvedTotal))}/${chains.failuresTotal} failure(s) resolved ${pc18.dim(`(${chains.resolvedByRetry} retry, ${chains.resolvedByDiscussion} discussion)`)}${chains.resolvedTotal < chains.failuresTotal ? ` \u2014 run ${pc18.bold("nexusmem sync --link-failures")} to link more` : ""}` : "",
+        structure.edges ? `${pc18.dim("structure")} ${pc18.bold(String(structure.edges))} import edge(s) across ${structure.files} file(s)` : ""
       ].filter((line) => line !== "").join("\n").concat("\n")
     );
     return 0;
@@ -5167,7 +5412,7 @@ function isExpected(err) {
   // the user fixes, not stack traces they debug.
   err instanceof GitSpawnError || // Survived every retry, so git is genuinely unstable on this machine
   // (antivirus, a bad install). Actionable, and not our stack to print.
-  err instanceof GitCrashError || err instanceof ConfigError || err instanceof ProfileNotFoundError || err instanceof ForeignGitHookError || err instanceof DenyListError;
+  err instanceof GitCrashError || err instanceof ConfigError || err instanceof ProfileNotFoundError || err instanceof ForeignGitHookError || err instanceof DenyListError || err instanceof MarkStaleError;
 }
 function guard(run) {
   return async () => {
@@ -5175,7 +5420,7 @@ function guard(run) {
       process.exitCode = await run();
     } catch (err) {
       if (isExpected(err)) {
-        process.stderr.write(`${pc18.red("error")} ${err.message}
+        process.stderr.write(`${pc19.red("error")} ${err.message}
 `);
         process.exitCode = 1;
         return;
@@ -5254,7 +5499,7 @@ program.command("query").description("Search remembered history and print a toke
 );
 program.command("forget").description(
   "Permanently deny-list a value: deletes matching nodes now and blocks it from ever being re-ingested (irreversible)"
-).argument("[value]", "exact text to forget (see --regex); omit with --list").option("-C, --cwd <path>", "repository path", process.cwd()).option("--regex", "treat <value> as a regular expression instead of a literal substring", false).option("--ignore-case", "case-insensitive match", false).option("--reason <text>", "free-text note stored with the deny-list entry").option("--list", "list active deny-list entries instead of forgetting a new value", false).option("--yes", "confirm the irreversible delete + deny-list write", false).action(
+).argument("[value]", "exact text to forget (see --regex); omit with --list").option("-C, --cwd <path>", "repository path", process.cwd()).option("--regex", "treat <value> as a regular expression instead of a literal substring", false).option("--ignore-case", "case-insensitive match", false).option("--reason <text>", "free-text note stored with the deny-list entry").option("--list", "list active deny-list entries instead of forgetting a new value", false).option("--export <path>", "write this project's deny-list to a JSON file, for --import in another checkout").option("--import <path>", "re-apply a deny-list JSON file (from --export) against this project").option("--yes", "confirm the irreversible delete + deny-list write", false).action(
   (value, options) => guard(
     () => runForget({
       cwd: options.cwd,
@@ -5263,10 +5508,17 @@ program.command("forget").description(
       ignoreCase: options.ignoreCase,
       reason: options.reason,
       list: options.list,
+      export: options.export,
+      import: options.import,
       yes: options.yes
     })
   )()
 );
+program.command("mark-stale").description(
+  "Mark a node as superseded by another -- the ranker down-weights it (never deletes it) so its replacement usually outranks it"
+).argument("<nodeId>", "id of the node to mark stale").requiredOption("--supersedes <newNodeId>", "id of the node that supersedes it").option("-C, --cwd <path>", "repository path", process.cwd()).action(
+  (nodeId, options) => guard(() => runMarkStale({ cwd: options.cwd, nodeId, supersedesId: options.supersedes }))()
+);
 program.command("projects").description("List the repositories `query --all-projects` would search").option("--prune", "forget registered projects whose database is no longer on disk", false).option("--json", "emit the registry as JSON on stdout", false).action((options) => guard(() => runProjects({ prune: options.prune, json: options.json }))());
 program.command("scan-git").description("Preview the MemoryNodes git history would produce (writes nothing)").option("-C, --cwd <path>", "repository path", process.cwd()).option("--since <date>", "only commits newer than this git date expression, e.g. 90.days.ago").option("-n, --limit <count>", "stop after N commits", (v) => Number.parseInt(v, 10)).option("--no-merges", "skip merge commits").option("--min-signal <score>", "drop nodes below this signal", (v) => Number.parseFloat(v), 0).option("--json", "emit MemoryNodes as JSON on stdout", false).action(
   (options) => guard(
@@ -5327,7 +5579,7 @@ program.command("scan-structure").description("Preview the JS/TS import-graph ed
 program.command("mcp").description("Start the MCP server (stdio transport) for Claude Desktop, Cursor, Windsurf, etc.").action(() => guard(() => runMcpServer().then(() => 0))());
 program.parseAsync(process.argv).catch((err) => {
   const message = err instanceof Error ? err.message : String(err);
-  process.stderr.write(`${pc18.red("error")} ${message}
+  process.stderr.write(`${pc19.red("error")} ${message}
 `);
   process.exitCode = 1;
 });