@kage-core/kage-graph-mcp 1.1.38 → 1.3.0

package/dist/kernel.js

@@ -83,6 +83,9 @@ exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
+exports.kageSuppressedMemory = kageSuppressedMemory;
+exports.verifyCitations = verifyCitations;
+exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
@@ -112,6 +115,8 @@ exports.kageMetrics = kageMetrics;
 exports.auditProject = auditProject;
 exports.memoryInbox = memoryInbox;
 exports.qualityReport = qualityReport;
+exports.benchmarkTrust = benchmarkTrust;
+exports.runDemo = runDemo;
 exports.benchmarkProject = benchmarkProject;
 exports.benchmarkCodingMemoryQuality = benchmarkCodingMemoryQuality;
 exports.benchmarkMemoryScale = benchmarkMemoryScale;
@@ -180,6 +185,27 @@ exports.MEMORY_TYPES = [
     "negative_result",
     "constraint",
 ];
+// Bounded context assembly (PRD Feature 2: "inject only the relevant rule + structural
+// map, dropping the rest"). Opt-in: when a token budget is set, keep the highest-priority
+// sections (preamble + code graph + memory come first in the block) and drop trailing
+// lower-priority sections until the estimate fits. Default (no budget) is unchanged.
+function boundContextBlock(block, budget) {
+    if (!Number.isFinite(budget) || budget <= 0 || estimateTokens(block) <= budget)
+        return block;
+    const parts = block.split(/\n(?=## )/);
+    const kept = [parts[0]];
+    let dropped = 0;
+    for (const section of parts.slice(1)) {
+        if (estimateTokens([...kept, section].join("\n")) <= budget)
+            kept.push(section);
+        else
+            dropped += 1;
+    }
+    const result = kept.join("\n");
+    return dropped
+        ? `${result}\n\n_Context trimmed to ~${budget} tokens; ${dropped} lower-priority section(s) dropped._`
+        : result;
+}
 const graphMemoryCache = new Map();
 exports.SETUP_AGENTS = [
     "codex",
@@ -1119,6 +1145,52 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     }
     return unique(reasons);
 }
+// Classifies stale reasons into severity. "hard" reasons (deprecated status, user
+// reported stale, ttl expired, all citations deleted) mean the memory should be
+// excluded from recall; "soft" reasons (some citations missing, a linked file
+// changed) mean keep-but-flag — the memory may just need review, not suppression.
+function staleSeverity(reasons) {
+    if (!reasons.length)
+        return "none";
+    const hard = reasons.some((reason) => reason.startsWith("packet status is") ||
+        reason.startsWith("user or agent reported") ||
+        reason.startsWith("freshness ttl expired") ||
+        reason.startsWith("all referenced paths are missing"));
+    return hard ? "hard" : "soft";
+}
+// Decides whether a packet should be excluded from the recall payload (PRD Feature 3:
+// "deleted or heavily refactored since the timestamp"). Distinct from staleMemoryReasons:
+// a citation that NEVER existed (no stored fingerprint) is an ungrounded write — guarded
+// at capture time — not recall-time staleness, so it does NOT trigger exclusion here.
+// Returns a reason string when the memory is hard-stale, otherwise null.
+function recallHardStaleReason(projectDir, packet, cache) {
+    if (packet.status === "deprecated" || packet.status === "superseded")
+        return `packet status is ${packet.status}`;
+    const quality = (packet.quality ?? {});
+    if (Number(quality.reports_stale ?? 0) > 0)
+        return "user or agent reported this memory stale";
+    const freshness = (packet.freshness ?? {});
+    const ttlDays = Number(freshness.ttl_days ?? freshness.ttlDays ?? 0);
+    const verifiedAt = Date.parse(String(freshness.last_verified_at ?? packet.updated_at ?? packet.created_at));
+    if (Number.isFinite(ttlDays) && ttlDays > 0 && Number.isFinite(verifiedAt)) {
+        const ageDays = (Date.now() - verifiedAt) / (1000 * 60 * 60 * 24);
+        if (ageDays > ttlDays)
+            return `freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`;
+    }
+    // Only paths that existed at capture get a stored fingerprint; if every one of them is
+    // now gone, the memory's evidence was deleted out from under it.
+    const stored = packetStoredPathFingerprints(packet);
+    if (stored.length) {
+        const deleted = stored.filter((fingerprint) => {
+            const current = memoryPathFingerprint(projectDir, fingerprint.path, cache);
+            return current === null;
+        });
+        if (deleted.length === stored.length) {
+            return `all cited files deleted since capture: ${deleted.slice(0, 4).map((fingerprint) => fingerprint.path).join(", ")}`;
+        }
+    }
+    return null;
+}
 function changedPathsFromStaleReasons(reasons) {
     return unique(reasons.flatMap((reason) => {
         const match = reason.match(/^linked path changed since memory was verified: (.+)$/);
@@ -1523,13 +1595,28 @@ function walkFiles(root, predicate) {
     }
     return out.sort();
 }
+// Tolerant packet read: a single corrupt or merge-conflicted packet (e.g. an
+// unresolved `<<<<<<<` from a teammate's git merge) must not take down all of
+// recall/verify/compact. Skip the bad file with a warning and keep going.
+function tryReadPacket(path) {
+    try {
+        return readJson(path);
+    }
+    catch (error) {
+        process.stderr.write(`kage: skipping unreadable memory packet ${path}: ${error.message}\n`);
+        return null;
+    }
+}
 function loadPacketsFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return [];
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => readJson((0, node_path_1.join)(dir, name)));
+        .flatMap((name) => {
+        const packet = tryReadPacket((0, node_path_1.join)(dir, name));
+        return packet ? [packet] : [];
+    });
 }
 function loadPacketEntriesFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
@@ -1537,9 +1624,10 @@ function loadPacketEntriesFromDir(dir) {
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => {
+        .flatMap((name) => {
         const path = (0, node_path_1.join)(dir, name);
-        return { path, packet: readJson(path) };
+        const packet = tryReadPacket(path);
+        return packet ? [{ path, packet }] : [];
     });
 }
 function loadApprovedPackets(projectDir) {
@@ -5510,6 +5598,127 @@ function gcProject(projectDir, options = {}) {
         total_scanned: packetEntries.length,
     };
 }
+// The memory recall is actively WITHHOLDING from agents right now (hard-stale:
+// cited files deleted, ttl expired, or reported stale). This is the human-facing
+// counterpart to the silent recall-time exclusion — surfaced, never hidden.
+function kageSuppressedMemory(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const cache = new Map();
+    const items = loadApprovedPackets(projectDir)
+        .map((packet) => {
+        const reason = recallHardStaleReason(projectDir, packet, cache);
+        return reason ? { id: packet.id, title: packet.title, type: packet.type, reason, paths: packet.paths } : null;
+    })
+        .filter((entry) => entry !== null);
+    return { schema_version: 1, generated_at: nowIso(), count: items.length, items };
+}
+function verifyCitations(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const targets = options.id ? approved.filter((packet) => packet.id === options.id) : approved;
+    if (options.id && !targets.length) {
+        return { ok: false, project_dir: projectDir, checked: 0, valid: 0, stale: 0, ungrounded: 0, packets: [], errors: [`Approved packet not found: ${options.id}`] };
+    }
+    const cache = new Map();
+    const packets = targets.map((packet) => {
+        const meaningful = packet.paths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+        const missing = meaningful.filter((path) => !pathExistsInRepo(projectDir, path));
+        const reasons = staleMemoryReasons(projectDir, packet, cache);
+        const severity = staleSeverity(reasons);
+        const grounded = packetGroundingWarnings(projectDir, packet, "packet").length === 0;
+        return {
+            id: packet.id,
+            title: packet.title,
+            status: packet.status,
+            paths: packet.paths,
+            missing_paths: missing,
+            grounded,
+            stale: severity !== "none",
+            stale_severity: severity,
+            stale_reasons: reasons,
+        };
+    });
+    return {
+        ok: true,
+        project_dir: projectDir,
+        checked: packets.length,
+        valid: packets.filter((entry) => !entry.stale && entry.grounded).length,
+        stale: packets.filter((entry) => entry.stale).length,
+        ungrounded: packets.filter((entry) => !entry.grounded).length,
+        packets,
+        errors: [],
+    };
+}
+// Deterministic memory consolidation (no hosted LLM — preserves the no-API-key promise):
+//  1. prune dead citations from packets and refresh their path fingerprints,
+//  2. deprecate hard-stale packets (delegating to the same severity rules as recall/gc),
+//  3. surface near-duplicate clusters for an agent to merge via kage_supersede.
+function compactProject(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const dryRun = options.dryRun === true;
+    const entries = loadPacketEntriesFromDir(packetsDir(projectDir));
+    const prunedCitations = [];
+    const deprecated = [];
+    const cache = new Map();
+    for (const { path, packet } of entries) {
+        if (packet.status === "deprecated" || packet.status === "superseded")
+            continue;
+        const hardReason = recallHardStaleReason(projectDir, packet, cache);
+        if (hardReason) {
+            deprecated.push({ id: packet.id, title: packet.title, reason: hardReason });
+            if (!dryRun)
+                writeJson(path, { ...packet, status: "deprecated", updated_at: nowIso() });
+            continue;
+        }
+        const meaningful = packet.paths.filter((p) => meaningfulMemoryPath(p) && !shouldSkipRepoMemoryPath(p));
+        const missing = meaningful.filter((p) => !pathExistsInRepo(projectDir, p));
+        if (missing.length) {
+            const keptPaths = packet.paths.filter((p) => !missing.includes(p));
+            prunedCitations.push({ id: packet.id, title: packet.title, removed_paths: missing });
+            if (!dryRun) {
+                writeJson(path, {
+                    ...packet,
+                    paths: keptPaths,
+                    freshness: {
+                        ...(packet.freshness ?? {}),
+                        path_fingerprints: memoryPathFingerprints(projectDir, keptPaths),
+                        last_verified_at: nowIso(),
+                    },
+                    updated_at: nowIso(),
+                });
+            }
+        }
+    }
+    // Cluster near-duplicate approved packets (report only — merging is an agent decision).
+    const context = memoryQualityContext(projectDir);
+    const approved = context.packets.filter((packet) => packet.status === "approved");
+    const seen = new Set();
+    const clusters = [];
+    for (const packet of approved) {
+        if (seen.has(packet.id))
+            continue;
+        const dupes = duplicateCandidatesWithContext(packet, context, 0.6).filter((dupe) => dupe.status === "approved");
+        if (!dupes.length)
+            continue;
+        const members = [{ id: packet.id, title: packet.title }, ...dupes.map((dupe) => ({ id: dupe.id, title: dupe.title }))];
+        members.forEach((member) => seen.add(member.id));
+        clusters.push({ score: Math.max(...dupes.map((dupe) => dupe.score)), packets: members });
+    }
+    if (!dryRun && (prunedCitations.length || deprecated.length)) {
+        const rebuilt = buildGraphIndexes(projectDir);
+        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetricsShallow(projectDir, rebuilt));
+    }
+    return {
+        ok: true,
+        project_dir: projectDir,
+        dry_run: dryRun,
+        pruned_citations: prunedCitations,
+        deprecated,
+        duplicate_clusters: clusters,
+        total_scanned: entries.length,
+        errors: [],
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");
@@ -6277,7 +6486,23 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         })()
         : recallQueryExpansion(query);
     const terms = expansion.terms;
-    const approvedPackets = loadApprovedPackets(projectDir);
+    const allApprovedPackets = loadApprovedPackets(projectDir);
+    const includeStale = inputs.includeStale === true;
+    const staleFingerprintCache = new Map();
+    const suppressed = [];
+    // Just-in-time staleness gate: hard-stale memory (deleted citations, expired ttl,
+    // reported stale) is excluded from the recall payload so the agent never sees it
+    // as valid. Suppression is recorded (not silent) so `kage verify` can explain it.
+    const approvedPackets = includeStale
+        ? allApprovedPackets
+        : allApprovedPackets.filter((packet) => {
+            const reason = recallHardStaleReason(projectDir, packet, staleFingerprintCache);
+            if (reason) {
+                suppressed.push({ id: packet.id, title: packet.title, reason });
+                return false;
+            }
+            return true;
+        });
     const baseScores = scorePacketsBm25(expansion.baseTerms, approvedPackets);
     const temporalScores = scorePacketsBm25(expansion.temporalTerms, approvedPackets);
     const semanticScores = scorePacketsBm25(expansion.semanticTerms, approvedPackets);
@@ -6335,6 +6560,13 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
     const graphContext = queryGraph(projectDir, query, 5, knowledgeGraph);
     const codeContext = queryCodeGraph(projectDir, query, 5, codeGraph);
     const pinnedContext = renderPinnedRepoContext(readContextSlots(projectDir));
+    // PRD Feature 2: traverse the code graph outward from the recalled memory's files
+    // (the semantic entry point) to assemble a bounded structural blast radius. Opt-in
+    // via inputs.structuralHops so default recall output is unchanged.
+    const structuralHops = inputs.structuralHops ?? 0;
+    const blastRadius = structuralHops > 0
+        ? structuralBlastRadius(codeGraph, unique(scored.flatMap((entry) => entry.packet.paths).filter((path) => meaningfulMemoryPath(path))), structuralHops)
+        : [];
     const lines = [
         `# Kage Context`,
         "",
@@ -6347,6 +6579,9 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ...codeContext.tests.slice(0, 3).map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
         ...(!codeContext.symbols.length && !codeContext.routes.length && !codeContext.tests.length ? codeContext.files.slice(0, 3).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind})`) : []),
         "",
+        ...(blastRadius.length
+            ? [`## Structural Blast Radius (${structuralHops}-hop)`, ...blastRadius.map((path, index) => `${index + 1}. ${path}`), ""]
+            : []),
         scored.length ? "## Relevant Memory" : "No relevant repo memory found.",
         ...scored.flatMap((entry, index) => [
             "",
@@ -6367,11 +6602,16 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         "",
         graphContext.edges.length ? "## Related Graph Facts" : "",
         ...graphContext.edges.slice(0, 5).map((edge, index) => `${index + 1}. ${edge.fact} (evidence: ${edge.evidence.join(", ")})`),
+        ...(suppressed.length
+            ? ["", `_${suppressed.length} stale memory packet(s) excluded from recall. Run kage verify for details._`]
+            : []),
     ];
+    const assembledBlock = lines.join("\n");
     const result = {
         query,
-        context_block: lines.join("\n"),
+        context_block: inputs.maxContextTokens ? boundContextBlock(assembledBlock, inputs.maxContextTokens) : assembledBlock,
         results: scored,
+        suppressed: suppressed.length ? suppressed : undefined,
         explanations: explain
             ? scored.map((entry) => ({
                 packet_id: entry.packet.id,
@@ -6830,6 +7070,45 @@ function codeDependents(graph) {
     }
     return dependents;
 }
+// Bounded N-hop structural traversal from a set of seed files (the files the recalled
+// memory is about) — the PRD's "structural blast radius". Walks both import directions
+// (who-depends-on and what-it-depends-on), excludes the seeds, and ranks by how many
+// files depend on each node. Pure graph traversal; no full-repo scan.
+function structuralBlastRadius(graph, seedPaths, hops, limit = 8) {
+    const seeds = seedPaths.filter(Boolean);
+    if (!seeds.length || hops <= 0)
+        return [];
+    const dependents = codeDependents(graph);
+    const dependencies = new Map();
+    for (const edge of graph.imports) {
+        if (!edge.from_path || !edge.to_path)
+            continue;
+        const list = dependencies.get(edge.from_path) ?? new Set();
+        list.add(edge.to_path);
+        dependencies.set(edge.from_path, list);
+    }
+    const seedSet = new Set(seeds);
+    const visited = new Set();
+    let frontier = new Set(seeds);
+    for (let depth = 0; depth < hops; depth += 1) {
+        const next = new Set();
+        for (const node of frontier) {
+            for (const neighbor of [...(dependents.get(node) ?? []), ...(dependencies.get(node) ?? [])]) {
+                if (seedSet.has(neighbor) || visited.has(neighbor))
+                    continue;
+                visited.add(neighbor);
+                next.add(neighbor);
+            }
+        }
+        frontier = next;
+    }
+    const score = new Map();
+    for (const [path, incoming] of dependents.entries())
+        score.set(path, incoming.size);
+    return [...visited]
+        .sort((a, b) => (score.get(b) ?? 0) - (score.get(a) ?? 0) || a.localeCompare(b))
+        .slice(0, limit);
+}
 function impactSurface(target, dependents, graph) {
     const visited = new Set();
     let frontier = new Set([target]);
@@ -9574,6 +9853,152 @@ function qualityReport(projectDir) {
         packets: rows,
     };
 }
+// The Trust Benchmark measures what retrieval benchmarks cannot: whether the memory
+// system can be TRUSTED — does it refuse to store hallucinated citations, does it
+// withhold memory whose evidence was deleted, and is live repo memory actually grounded.
+// Controlled gates run in an isolated sandbox; the grounding gate runs on the real repo.
+function benchmarkTrust(projectDir) {
+    const runDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "kage-trust-"));
+    const sandbox = (0, node_path_1.join)(runDir, "project");
+    try {
+        ensureMemoryDirs(sandbox);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(sandbox, "src"), { recursive: true });
+        // Gate 1 — Hallucinated-citation rejection: a strict capture whose every cited path
+        // is missing must be rejected. (No competitor validates citations at write time.)
+        const hallucinationAttempts = 8;
+        let rejected = 0;
+        for (let i = 0; i < hallucinationAttempts; i += 1) {
+            const result = capture({
+                projectDir: sandbox,
+                title: `Hallucinated rule ${i}`,
+                body: `Use the helper in src/ghost-${i}.ts for retry handling.`,
+                type: "decision",
+                paths: [`src/ghost-${i}.ts`],
+                strictCitations: true,
+            });
+            if (!result.ok)
+                rejected += 1;
+        }
+        // Gate 2 — Stale-memory exclusion: memory grounded in real files at capture time
+        // must be withheld from recall once those files are deleted (the "deleted since
+        // capture" signal). We only count memories that were recallable BEFORE deletion.
+        const staleAttempts = 8;
+        const recallableBefore = [];
+        for (let i = 0; i < staleAttempts; i += 1) {
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(sandbox, "src", `widget-${i}.ts`), `export const widget${i} = ${i};\n`, "utf8");
+            capture({
+                projectDir: sandbox,
+                title: `Widget ${i} retry invariant`,
+                body: `Widget ${i} retries use idempotency token zeta${i} in src/widget-${i}.ts to avoid duplicate charges.`,
+                type: "decision",
+                paths: [`src/widget-${i}.ts`],
+            });
+        }
+        for (let i = 0; i < staleAttempts; i += 1) {
+            const before = recall(sandbox, `widget ${i} retry idempotency token zeta${i}`, 5, false, { trackAccess: false });
+            recallableBefore[i] = before.results.some((entry) => entry.packet.title === `Widget ${i} retry invariant`);
+        }
+        for (let i = 0; i < staleAttempts; i += 1) {
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(sandbox, "src", `widget-${i}.ts`), { force: true });
+        }
+        let recallableCount = 0;
+        let excludedAfter = 0;
+        for (let i = 0; i < staleAttempts; i += 1) {
+            if (!recallableBefore[i])
+                continue;
+            recallableCount += 1;
+            const after = recall(sandbox, `widget ${i} retry idempotency token zeta${i}`, 5, false, { trackAccess: false });
+            const surfaced = after.results.some((entry) => entry.packet.title === `Widget ${i} retry invariant`);
+            if (!surfaced)
+                excludedAfter += 1;
+        }
+        // Gate 3 — Live grounding: how much of the real repo's approved memory is grounded
+        // (cited files exist) and not stale.
+        const verify = verifyCitations(projectDir);
+        const liveChecked = verify.checked;
+        const grounded = verify.packets.filter((entry) => entry.grounded && !entry.stale).length;
+        const hallucinationRate = percent(rejected, hallucinationAttempts);
+        const staleRate = percent(excludedAfter, recallableCount || staleAttempts);
+        const liveGroundingRate = liveChecked > 0 ? percent(grounded, liveChecked) : 100;
+        const wrongAdvicePrevented = percent(rejected + excludedAfter, hallucinationAttempts + (recallableCount || staleAttempts));
+        const gates = [
+            { name: "hallucinated_citation_rejection", target: 100, actual: hallucinationRate, unit: "percent", pass: hallucinationRate >= 100 },
+            { name: "stale_memory_exclusion", target: 100, actual: staleRate, unit: "percent", pass: staleRate >= 100 },
+            { name: "live_grounding_rate", target: 80, actual: liveGroundingRate, unit: "percent", pass: liveGroundingRate >= 80 },
+        ];
+        const trustScore = Math.round((hallucinationRate + staleRate + liveGroundingRate) / 3);
+        return {
+            schema_version: 1,
+            generated_at: nowIso(),
+            ok: gates.every((gate) => gate.pass),
+            trust_score: trustScore,
+            gates,
+            metrics: {
+                hallucinated_citation_rejection_rate: hallucinationRate,
+                stale_memory_exclusion_rate: staleRate,
+                live_grounding_rate: liveGroundingRate,
+                wrong_advice_prevented_rate: wrongAdvicePrevented,
+            },
+            detail: {
+                hallucination: { attempted: hallucinationAttempts, rejected },
+                staleness: { recallable_before: recallableCount, excluded_after: excludedAfter },
+                live_memory: { checked: liveChecked, grounded, stale: verify.stale },
+            },
+        };
+    }
+    finally {
+        (0, node_fs_1.rmSync)(runDir, { recursive: true, force: true });
+    }
+}
+// `kage demo`: a self-contained 60-second proof of the trust wedge. Seeds a tiny
+// repo with grounded memory, then shows Kage (1) reject a hallucinated citation,
+// (2) withhold a memory whose cited file was deleted, and (3) recall only grounded
+// memory — the three things that make agent memory trustworthy.
+function runDemo(demoDir) {
+    (0, node_fs_1.rmSync)(demoDir, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(demoDir, "src"), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "auth.ts"), "export function validateToken() { return true; }\n", "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "payments.ts"), "export function charge() { return 'ok'; }\n", "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(demoDir, "src", "legacy-retry.ts"), "export function retry() { return 1; }\n", "utf8");
+    ensureMemoryDirs(demoDir);
+    const captured = [];
+    for (const m of [
+        { title: "Auth uses jose, not jsonwebtoken", body: "Validate tokens with jose in src/auth.ts; jsonwebtoken was removed.", paths: ["src/auth.ts"] },
+        { title: "Payments must be idempotent", body: "charge() in src/payments.ts must be idempotent to avoid double charges.", paths: ["src/payments.ts"] },
+        { title: "Legacy retry helper is the fallback", body: "Old retry logic lives in src/legacy-retry.ts and is used as a fallback.", paths: ["src/legacy-retry.ts"] },
+    ]) {
+        const r = capture({ projectDir: demoDir, title: m.title, body: m.body, type: "decision", paths: m.paths });
+        if (r.ok && r.packet)
+            captured.push(r.packet.title);
+    }
+    // (2) delete a cited file → that memory becomes stale and is withheld from recall.
+    (0, node_fs_1.unlinkSync)((0, node_path_1.join)(demoDir, "src", "legacy-retry.ts"));
+    // (1) a hallucinated citation is rejected at write time.
+    const hallucinated = capture({
+        projectDir: demoDir,
+        title: "Use the helper in src/ghost.ts",
+        body: "Retry handling lives in src/ghost.ts.",
+        type: "decision",
+        paths: ["src/ghost.ts"],
+        strictCitations: true,
+    });
+    const rejected = hallucinated.ok ? null : { title: "Use the helper in src/ghost.ts", error: hallucinated.errors[0] ?? "rejected" };
+    // (3) recall surfaces grounded memory; the stale one is withheld.
+    const recall = recallWithVectorScores(demoDir, "auth token payments retry idempotency", 5, false, { trackAccess: false });
+    const recalled = recall.results.map((entry) => entry.packet.title);
+    const withheld = kageSuppressedMemory(demoDir).items.map((item) => ({ title: item.title, reason: item.reason }));
+    const trust = benchmarkTrust(demoDir);
+    return {
+        ok: true,
+        project_dir: demoDir,
+        captured,
+        rejected_hallucination: rejected,
+        recalled,
+        withheld,
+        trust_score: trust.trust_score,
+        viewer_command: `kage viewer --project ${demoDir}`,
+    };
+}
 function benchmarkProject(projectDir, inputs = {}) {
     ensureMemoryDirs(projectDir);
     const built = inputs.codeGraph && inputs.knowledgeGraph ? null : currentOrBuildGraphs(projectDir);
@@ -10453,6 +10878,9 @@ function learn(input) {
         paths: input.paths,
         stack: input.stack,
         context: input.context,
+        allowMissingPaths: input.allowMissingPaths,
+        strictCitations: input.strictCitations,
+        graphNodes: input.graphNodes,
     });
 }
 function capture(input) {
@@ -10468,7 +10896,34 @@ function capture(input) {
             errors: [`Sensitive content blocked: ${unique(scanFindings).join(", ")}`],
         };
     }
+    const warnings = [];
+    const meaningfulPaths = (input.paths ?? [])
+        .filter((path) => path && meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(input.projectDir, path));
+    // Citation validation. Strict mode (agent-facing record_memory tools / CLI) rejects a
+    // write whose every cited path is missing — the PRD's "reject if citations don't exist".
+    // The core library stays permissive (warn-only) for programmatic callers and migrations.
+    if (input.strictCitations && meaningfulPaths.length && missingPaths.length === meaningfulPaths.length && !input.allowMissingPaths) {
+        return {
+            ok: false,
+            errors: [
+                `Citation validation failed: none of the referenced paths exist in this repo: ${missingPaths.join(", ")}. ` +
+                    `Fix the paths, or pass allow_missing_paths to record anyway (e.g. for a file you are about to create).`,
+            ],
+            warnings: [],
+        };
+    }
+    if (missingPaths.length) {
+        warnings.push(`Some referenced paths do not exist in this repo: ${missingPaths.join(", ")}`);
+    }
     const createdAt = nowIso();
+    // Agent-asserted links to code-graph nodes (PRD `graph_nodes`): the agent recording the
+    // memory knows which symbol/route/file the rule is about, so let it declare them instead
+    // of relying solely on background derivation.
+    const graphEdges = unique(input.graphNodes ?? [])
+        .map((node) => node.trim())
+        .filter(Boolean)
+        .map((node) => ({ relation: "references_code", to: node, evidence: "agent_capture", created_at: createdAt }));
     const packet = {
         schema_version: exports.PACKET_SCHEMA_VERSION,
         id: makePacketId(input.projectDir, type, input.title, String(Date.now())),
@@ -10510,10 +10965,12 @@ function capture(input) {
         },
         created_at: createdAt,
         updated_at: createdAt,
+        author_branch: gitBranch(input.projectDir),
     };
+    packet.edges = graphEdges;
     const validation = validatePacket(packet);
     if (!validation.ok)
-        return { ok: false, errors: validation.errors };
+        return { ok: false, errors: validation.errors, warnings };
     packet.quality = {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
@@ -10525,7 +10982,7 @@ function capture(input) {
         path: (0, node_path_1.relative)(input.projectDir, path),
         source_kind: packet.source_refs[0]?.kind ?? "explicit_capture",
     });
-    return { ok: true, packet, path, errors: [] };
+    return { ok: true, packet, path, errors: [], warnings };
 }
 function createPublicCandidate(projectDir, id) {
     ensureMemoryDirs(projectDir);
@@ -10854,6 +11311,10 @@ elif event_name == "PreCompact":
     payload = {"type": "session_end", "summary": "Claude Code is compacting context; distill durable observations before compaction."}
 elif event_name == "SessionEnd":
     payload = {"type": "session_end", "summary": "Claude Code session ended; distill durable observations for teammate handoff."}
+elif event_name == "SubagentStop":
+    payload = {"type": "session_end", "summary": "Subagent finished; distill durable observations from the subagent run."}
+elif event_name == "PreToolUse":
+    payload = {"type": "tool_use", "tool": tool, "path": path, "command": command, "summary": "About to run: " + compact(command or tool or d, 200)}
 else:
     payload = {"type": "tool_use", "tool": tool, "path": path, "command": command, "summary": compact(d, 320), "text": compact(d)}
 
@@ -10865,7 +11326,7 @@ if [[ -n "$OBSERVATION" ]]; then
   kage observe --project "$CWD" --event "$OBSERVATION" --json >/dev/null 2>&1 || true
 fi
 
-if [[ "$EVENT" == "PreCompact" || "$EVENT" == "SessionEnd" ]]; then
+if [[ "$EVENT" == "PreCompact" || "$EVENT" == "SessionEnd" || "$EVENT" == "SubagentStop" ]]; then
   kage distill --project "$CWD" --session "$SESSION" --json >/dev/null 2>&1 || true
 fi
 
@@ -10901,11 +11362,13 @@ exit 0
             hooks: {
                 SessionStart: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/session-start.sh", timeout: 5 }] }],
                 UserPromptSubmit: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 12 }] }],
+                PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PostToolUseFailure: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PreCompact: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
                 Stop: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/stop.sh", timeout: 20 }] }],
                 SessionEnd: [{ hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
+                SubagentStop: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 20 }] }],
             },
         };
         setSnippet(path, JSON.stringify({ mcpServers: { kage: server } }, null, 2), [
@@ -12110,12 +12573,65 @@ function regexpEscape(value) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\"'\"'")}'`;
 }
-function gitHookPath(projectDir) {
-    const raw = readGit(projectDir, ["rev-parse", "--git-path", "hooks/post-commit"]);
+function gitHookPath(projectDir, hookName = "post-commit") {
+    const raw = readGit(projectDir, ["rev-parse", "--git-path", `hooks/${hookName}`]);
     if (!raw)
         return null;
     return (0, node_path_1.resolve)(projectDir, raw);
 }
+// Hooks that fire after history changes underfoot (git pull / merge / checkout):
+// re-index repo memory so newly pulled teammate packets are immediately recallable.
+const KAGE_SYNC_HOOKS = ["post-merge", "post-checkout"];
+function kageSyncHookBlock(projectDir) {
+    const project = shellQuote((0, node_path_1.resolve)(projectDir));
+    return [
+        KAGE_POST_COMMIT_HOOK_START,
+        "# Kage sync hook: re-index repo memory after pull/merge/checkout.",
+        "# Set KAGE_SKIP_HOOK=1 to bypass, or KAGE_BIN=/path/to/kage to override.",
+        "if [ \"${KAGE_SKIP_HOOK:-0}\" != \"1\" ]; then",
+        "  KAGE_BIN=\"${KAGE_BIN:-kage}\"",
+        "  if command -v \"$KAGE_BIN\" >/dev/null 2>&1; then",
+        "    (",
+        `      "$KAGE_BIN" index --project ${project} --json >/dev/null 2>&1 || true`,
+        "    ) &",
+        "  fi",
+        "fi",
+        KAGE_POST_COMMIT_HOOK_END,
+    ].join("\n");
+}
+function installSyncHooks(projectDir) {
+    const installed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        ensureDir((0, node_path_1.dirname)(hookPath));
+        const existing = safeReadText(hookPath) ?? "";
+        const base = stripKageHookBlock(existing);
+        const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
+        const next = `${prefix}\n\n${kageSyncHookBlock(projectDir)}\n`;
+        if (existing !== next)
+            (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        installed.push(hookPath);
+    }
+    return installed;
+}
+function uninstallSyncHooks(projectDir) {
+    const removed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        const existing = safeReadText(hookPath) ?? "";
+        if (!hasKageHookBlock(existing))
+            continue;
+        (0, node_fs_1.writeFileSync)(hookPath, stripKageHookBlock(existing), "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        removed.push(hookPath);
+    }
+    return removed;
+}
 function hasKageHookBlock(content) {
     return content.includes(KAGE_POST_COMMIT_HOOK_START) && content.includes(KAGE_POST_COMMIT_HOOK_END);
 }
@@ -12191,20 +12707,24 @@ function kageHookInstall(projectDir) {
     const base = stripKageHookBlock(existing);
     const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
     const next = `${prefix}\n\n${kagePostCommitHookBlock(projectDir)}\n`;
-    const changed = existing !== next;
-    if (changed)
+    const commitChanged = existing !== next;
+    if (commitChanged)
         (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const syncHooks = installSyncHooks(projectDir);
     return {
         ok: true,
         action: "install",
         project_dir: projectDir,
         hook_path: hookPath,
         installed: true,
-        changed,
-        message: changed ? "Installed Kage post-commit hook." : "Kage post-commit hook is already current.",
+        changed: commitChanged,
+        message: commitChanged
+            ? "Installed Kage post-commit hook and pull/merge sync hooks."
+            : "Kage post-commit and sync hooks are already current.",
         errors: [],
         warnings: [],
+        additional_hooks: syncHooks,
     };
 }
 function kageHookUninstall(projectDir) {
@@ -12240,6 +12760,7 @@ function kageHookUninstall(projectDir) {
     const next = stripKageHookBlock(existing);
     (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const removedSyncHooks = uninstallSyncHooks(projectDir);
     return {
         ok: true,
         action: "uninstall",
@@ -12247,9 +12768,10 @@ function kageHookUninstall(projectDir) {
         hook_path: hookPath,
         installed: false,
         changed: true,
-        message: "Removed Kage post-commit hook.",
+        message: "Removed Kage post-commit and sync hooks.",
         errors: [],
         warnings: [],
+        additional_hooks: removedSyncHooks,
     };
 }
 function exportPublicBundle(projectDir) {