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

package/dist/cli.js

@@ -12,6 +12,7 @@ function usage() {
 
 Usage:
   kage index --project <dir>
+  kage demo [--project <dir>]
   kage init --project <dir>
   kage policy --project <dir>
   kage doctor --project <dir>
@@ -31,6 +32,7 @@ Usage:
   kage gc --project <dir> [--dry-run] [--force] [--json]
   kage compact --project <dir> [--dry-run] [--json]
   kage verify --project <dir> [--id <packet-id>] [--json]
+  kage suppressed --project <dir> [--json]
   kage pr summarize --project <dir> [--json]
   kage pr check --project <dir> [--json]
   kage upgrade [--dry-run]
@@ -60,6 +62,7 @@ Usage:
   kage inbox --project <dir> [--json]
   kage quality --project <dir> [--json]
   kage benchmark --project <dir> [--json]
+  kage benchmark --trust --project <dir> [--json]
   kage benchmark --memory-quality [--json]
   kage benchmark --scale [--sizes 240,1000,5000] [--json]
   kage benchmark --project <dir> --compare --task <task> [--json]
@@ -176,6 +179,30 @@ async function main() {
         console.log(`Indexes:\n${result.indexes.map((path) => `  - ${path}`).join("\n")}`);
         return;
     }
+    if (command === "demo") {
+        const demoDir = takeArg(args, "--project") ?? `${process.cwd()}/kage-demo`;
+        const result = (0, kernel_js_1.runDemo)(demoDir);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("Kage demo — can you trust your agent's memory?\n");
+        console.log(`Seeded ${result.captured.length} grounded memories in ${result.project_dir}\n`);
+        console.log("1. Hallucinated citation — REJECTED on write:");
+        if (result.rejected_hallucination) {
+            console.log(`   ✗ "${result.rejected_hallucination.title}"`);
+            console.log(`     ${result.rejected_hallucination.error}\n`);
+        }
+        console.log("2. Stale memory (cited file deleted) — WITHHELD from recall:");
+        for (const w of result.withheld)
+            console.log(`   ⊘ ${w.title}\n     ${w.reason}`);
+        console.log("\n3. Recall returns only grounded, current memory:");
+        for (const t of result.recalled)
+            console.log(`   ✓ ${t}`);
+        console.log(`\nTrust score: ${result.trust_score}/100`);
+        console.log(`\nSee it in the viewer:  ${result.viewer_command}`);
+        return;
+    }
     if (command === "init") {
         const result = (0, kernel_js_1.initProject)(projectArg(args));
         console.log(`Initialized Kage memory for ${result.index.projectDir}`);
@@ -465,6 +492,21 @@ async function main() {
         }
         return;
     }
+    if (command === "suppressed") {
+        const result = (0, kernel_js_1.kageSuppressedMemory)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage suppressed memory — ${result.count} packet(s) currently withheld from recall`);
+        for (const item of result.items) {
+            console.log(`  ⊘ ${item.title}`);
+            console.log(`      ${item.reason}`);
+        }
+        if (!result.count)
+            console.log("  (none — all recallable memory is grounded and current)");
+        return;
+    }
     if (command === "refresh") {
         const result = (0, kernel_js_1.refreshProject)(projectArg(args), { full: args.includes("--full") });
         if (args.includes("--json")) {
@@ -1319,6 +1361,24 @@ async function main() {
         return;
     }
     if (command === "benchmark") {
+        if (args.includes("--trust")) {
+            const result = (0, kernel_js_1.benchmarkTrust)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            console.log("Kage Trust Benchmark — can this memory be trusted?");
+            console.log(`Trust score: ${result.trust_score}/100  (${result.ok ? "PASS" : "REVIEW"})`);
+            console.log(`  Hallucinated-citation rejection: ${result.metrics.hallucinated_citation_rejection_rate}%  (${result.detail.hallucination.rejected}/${result.detail.hallucination.attempted})`);
+            console.log(`  Stale-memory exclusion:          ${result.metrics.stale_memory_exclusion_rate}%  (${result.detail.staleness.excluded_after}/${result.detail.staleness.recallable_before})`);
+            console.log(`  Live grounding rate:             ${result.metrics.live_grounding_rate}%  (${result.detail.live_memory.grounded}/${result.detail.live_memory.checked} packets)`);
+            console.log(`  Wrong-advice prevented:          ${result.metrics.wrong_advice_prevented_rate}%`);
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
         if (args.includes("--memory-quality")) {
             const result = (0, kernel_js_1.benchmarkCodingMemoryQuality)({
                 topK: Number(takeArg(args, "--top-k") ?? 10),

package/dist/daemon.js

@@ -573,6 +573,8 @@ async function startViewer(projectDir, options = {}) {
     const timelinePath = (0, node_path_1.join)(reportsDir, "timeline.json");
     const lineagePath = (0, node_path_1.join)(reportsDir, "lineage.json");
     const setupPath = (0, node_path_1.join)(reportsDir, "setup.json");
+    const trustPath = (0, node_path_1.join)(reportsDir, "trust.json");
+    const suppressedPath = (0, node_path_1.join)(reportsDir, "suppressed.json");
     // Pre-generate lightweight JSON reports so the viewer can load them directly.
     try {
         (0, node_fs_1.mkdirSync)(reportsDir, { recursive: true });
@@ -601,11 +603,13 @@ async function startViewer(projectDir, options = {}) {
         (0, node_fs_1.writeFileSync)(timelinePath, JSON.stringify((0, kernel_js_1.kageMemoryTimeline)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(lineagePath, JSON.stringify((0, kernel_js_1.kageMemoryLineage)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(setupPath, JSON.stringify((0, kernel_js_1.setupDoctor)(projectDir), null, 2));
+        (0, node_fs_1.writeFileSync)(trustPath, JSON.stringify((0, kernel_js_1.benchmarkTrust)(projectDir), null, 2));
+        (0, node_fs_1.writeFileSync)(suppressedPath, JSON.stringify((0, kernel_js_1.kageSuppressedMemory)(projectDir), null, 2));
     }
     catch {
         // non-fatal: viewer will show 404 for reports if generation fails
     }
-    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}&quality=${encodeURIComponent(qualityPath)}&benchmark=${encodeURIComponent(benchmarkPath)}&contributors=${encodeURIComponent(contributorsPath)}&profile=${encodeURIComponent(profilePath)}&xray=${encodeURIComponent(xrayPath)}&capabilities=${encodeURIComponent(capabilitiesPath)}&slots=${encodeURIComponent(slotsPath)}&decisions=${encodeURIComponent(decisionsPath)}&risk=${encodeURIComponent(riskPath)}&moduleHealth=${encodeURIComponent(moduleHealthPath)}&graphInsights=${encodeURIComponent(graphInsightsPath)}&workspace=${encodeURIComponent(workspacePath)}&sessions=${encodeURIComponent(sessionsPath)}&replay=${encodeURIComponent(replayPath)}&memoryAccess=${encodeURIComponent(memoryAccessPath)}&memoryAudit=${encodeURIComponent(memoryAuditPath)}&handoff=${encodeURIComponent(handoffPath)}&lifecycle=${encodeURIComponent(lifecyclePath)}&timeline=${encodeURIComponent(timelinePath)}&lineage=${encodeURIComponent(lineagePath)}&setup=${encodeURIComponent(setupPath)}&view=code`;
+    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}&quality=${encodeURIComponent(qualityPath)}&benchmark=${encodeURIComponent(benchmarkPath)}&contributors=${encodeURIComponent(contributorsPath)}&profile=${encodeURIComponent(profilePath)}&xray=${encodeURIComponent(xrayPath)}&capabilities=${encodeURIComponent(capabilitiesPath)}&slots=${encodeURIComponent(slotsPath)}&decisions=${encodeURIComponent(decisionsPath)}&risk=${encodeURIComponent(riskPath)}&moduleHealth=${encodeURIComponent(moduleHealthPath)}&graphInsights=${encodeURIComponent(graphInsightsPath)}&workspace=${encodeURIComponent(workspacePath)}&sessions=${encodeURIComponent(sessionsPath)}&replay=${encodeURIComponent(replayPath)}&memoryAccess=${encodeURIComponent(memoryAccessPath)}&memoryAudit=${encodeURIComponent(memoryAuditPath)}&handoff=${encodeURIComponent(handoffPath)}&lifecycle=${encodeURIComponent(lifecyclePath)}&timeline=${encodeURIComponent(timelinePath)}&lineage=${encodeURIComponent(lineagePath)}&setup=${encodeURIComponent(setupPath)}&trust=${encodeURIComponent(trustPath)}&suppressed=${encodeURIComponent(suppressedPath)}&view=code`;
     const server = (0, node_http_1.createServer)((req, res) => {
         const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
         let filePath = null;

package/dist/index.js

@@ -590,7 +590,7 @@ function listTools() {
                 type: "object",
                 properties: {
                     project_dir: { type: "string" },
-                    mode: { type: "string", enum: ["project", "memory_quality", "memory_scale"] },
+                    mode: { type: "string", enum: ["project", "trust", "memory_quality", "memory_scale"] },
                     sizes: { type: "array", items: { type: "number" } },
                     top_k: { type: "number" },
                 },
@@ -1376,14 +1376,16 @@ async function callTool(name, args) {
     }
     if (name === "kage_benchmark") {
         const mode = String(args?.mode ?? "project");
-        const result = mode === "memory_quality"
-            ? (0, kernel_js_1.benchmarkCodingMemoryQuality)({ topK: Number(args?.top_k ?? 10) })
-            : mode === "memory_scale"
-                ? (0, kernel_js_1.benchmarkMemoryScale)({
-                    sizes: Array.isArray(args?.sizes) ? args.sizes.map(Number) : undefined,
-                    topK: Number(args?.top_k ?? 10),
-                })
-                : (0, kernel_js_1.benchmarkProject)(String(args?.project_dir ?? ""));
+        const result = mode === "trust"
+            ? (0, kernel_js_1.benchmarkTrust)(String(args?.project_dir ?? ""))
+            : mode === "memory_quality"
+                ? (0, kernel_js_1.benchmarkCodingMemoryQuality)({ topK: Number(args?.top_k ?? 10) })
+                : mode === "memory_scale"
+                    ? (0, kernel_js_1.benchmarkMemoryScale)({
+                        sizes: Array.isArray(args?.sizes) ? args.sizes.map(Number) : undefined,
+                        topK: Number(args?.top_k ?? 10),
+                    })
+                    : (0, kernel_js_1.benchmarkProject)(String(args?.project_dir ?? ""));
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
@@ -1692,5 +1694,16 @@ async function main() {
     await server.connect(transport);
 }
 if (require.main === module) {
+    const firstArg = process.argv[2];
+    if (firstArg && !firstArg.startsWith("-")) {
+        // A positional subcommand (demo, init, recall, ...) means the user wants the
+        // kage CLI, not the MCP stdio server. Delegate so a single
+        // `npx @kage-core/kage-graph-mcp <command>` works like the `kage` binary.
+        // MCP clients launch with no args (or flags), which falls through to the server.
+        const { spawnSync } = require("node:child_process");
+        const { join } = require("node:path");
+        const result = spawnSync(process.execPath, [join(__dirname, "cli.js"), ...process.argv.slice(2)], { stdio: "inherit" });
+        process.exit(result.status ?? 0);
+    }
     main().catch(console.error);
 }

package/dist/kernel.js

@@ -83,6 +83,7 @@ exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
+exports.kageSuppressedMemory = kageSuppressedMemory;
 exports.verifyCitations = verifyCitations;
 exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
@@ -114,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;
@@ -5595,8 +5598,20 @@ function gcProject(projectDir, options = {}) {
         total_scanned: packetEntries.length,
     };
 }
-// On-demand citation/freshness check the agent can call before trusting a memory.
-// Pass an id to verify one packet, or omit to audit all approved memory.
+// 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);
@@ -9838,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);
@@ -11150,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)}
 
@@ -11161,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
 
@@ -11197,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), [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [

package/viewer/app.js

@@ -47,7 +47,9 @@
       lifecycle: null,
       timeline: null,
       lineage: null,
-      setup: null
+      setup: null,
+      trust: null,
+      suppressed: null
     },
     pendingPackets: [],
     reviewText: "",
@@ -183,6 +185,8 @@
     edgeCount: document.getElementById("edgeCount"),
     reviewCount: document.getElementById("reviewCount"),
     dashboardStats: document.getElementById("dashboardStats"),
+    trustHero: document.getElementById("trustHero"),
+    suppressionShelf: document.getElementById("suppressionShelf"),
     repoXray: document.getElementById("repoXray"),
     repoXrayStatus: document.getElementById("repoXrayStatus"),
     repoXrayScript: document.getElementById("repoXrayScript"),
@@ -233,8 +237,8 @@
   var PAGE_META = {
     overview: {
       eyebrow: "kage://overview",
-      title: "Repo dashboard",
-      summary: "What is safe to change next, what needs attention, and what is ready to hand off."
+      title: "Repository overview",
+      summary: "Whether this repo's agent memory can be trusted, what needs review, and what's ready to hand off."
     },
     graph: {
       eyebrow: "kage://graph",
@@ -622,6 +626,8 @@
     var timelinePath = params.get("timeline") || params.get("memoryTimeline") || params.get("memory-timeline");
     var lineagePath = params.get("lineage") || params.get("memoryLineage") || params.get("memory-lineage");
     var setupPath = params.get("setup") || params.get("setupDoctor") || params.get("setup-doctor");
+    var trustPath = params.get("trust") || params.get("trustBenchmark") || params.get("trust-benchmark");
+    var suppressedPath = params.get("suppressed") || params.get("suppressedMemory") || params.get("suppressed-memory");
     var inferredRoot = inferMemoryRoot(graphPaths[0] || "");
     if (!inboxPath && inferredRoot) inboxPath = inferredRoot + "/inbox.json";
     if (!reviewPath && inferredRoot) reviewPath = inferredRoot + "/review/memory-review.md";
@@ -648,6 +654,8 @@
       if (!timelinePath) timelinePath = inferredRoot + "/reports/timeline.json";
       if (!lineagePath) lineagePath = inferredRoot + "/reports/lineage.json";
       if (!setupPath) setupPath = inferredRoot + "/reports/setup.json";
+      if (!trustPath) trustPath = inferredRoot + "/reports/trust.json";
+      if (!suppressedPath) suppressedPath = inferredRoot + "/reports/suppressed.json";
     }
     var jobs = [];
     if (metricsPath) jobs.push(fetchJson(metricsPath).then(function (metrics) { state.metrics = metrics; }));
@@ -675,6 +683,8 @@
     if (timelinePath) jobs.push(fetchJson(timelinePath).then(function (report) { state.reports.timeline = report; }).catch(function () { state.reports.timeline = null; }));
     if (lineagePath) jobs.push(fetchJson(lineagePath).then(function (report) { state.reports.lineage = report; }).catch(function () { state.reports.lineage = null; }));
     if (setupPath) jobs.push(fetchJson(setupPath).then(function (report) { state.reports.setup = report; }).catch(function () { state.reports.setup = null; }));
+    if (trustPath) jobs.push(fetchJson(trustPath).then(function (report) { state.reports.trust = report; }).catch(function () { state.reports.trust = null; }));
+    if (suppressedPath) jobs.push(fetchJson(suppressedPath).then(function (report) { state.reports.suppressed = report; }).catch(function () { state.reports.suppressed = null; }));
     if (!graphPaths.length && !jobs.length) {
       loadHostedDefault();
       return;
@@ -723,7 +733,9 @@
       fetchJson("./data/kage/reports/lifecycle.json").catch(function () { return null; }),
       fetchJson("./data/kage/reports/timeline.json").catch(function () { return null; }),
       fetchJson("./data/kage/reports/lineage.json").catch(function () { return null; }),
-      fetchJson("./data/kage/reports/setup.json").catch(function () { return null; })
+      fetchJson("./data/kage/reports/setup.json").catch(function () { return null; }),
+      fetchJson("./data/kage/reports/trust.json").catch(function () { return null; }),
+      fetchJson("./data/kage/reports/suppressed.json").catch(function () { return null; })
     ]).then(function (items) {
       var merged = mergeNormalizedGraphs([normalizeGraph(items[0]), normalizeGraph(items[1])]);
       state.metrics = items[2];
@@ -747,6 +759,8 @@
       state.reports.timeline = items[20];
       state.reports.lineage = items[21];
       state.reports.setup = items[22];
+      state.reports.trust = items[23];
+      state.reports.suppressed = items[24];
       loadNormalizedGraph(merged, "Kage repo graph");
       setAutoLoad("Kage repo graph loaded", true);
     }).catch(function () {
@@ -2983,6 +2997,75 @@
     ].forEach(function (card) { els.debugOverview.appendChild(card); });
   }
 
+  function renderTrustHero(trust) {
+    if (!els.trustHero) return;
+    var metrics = (trust && trust.metrics) || {};
+    var score = trust && typeof trust.trust_score === "number" ? trust.trust_score : null;
+    var status = score == null ? "idle" : (score >= 90 ? "ok" : score >= 70 ? "warn" : "alert");
+    var bars = [
+      ["Hallucinated citations rejected", metrics.hallucinated_citation_rejection_rate],
+      ["Stale memory excluded from recall", metrics.stale_memory_exclusion_rate],
+      ["Live memory grounded to code", metrics.live_grounding_rate]
+    ];
+    var note = score == null
+      ? "Run <code>kage benchmark --trust</code> to score this repo."
+      : (status === "ok"
+        ? "Verified — agents recall only memory that is grounded and current."
+        : "Some memory needs review before agents should trust it.");
+    var barsHtml = bars.map(function (bar) {
+      var raw = bar[1];
+      var has = !(raw === null || raw === undefined || isNaN(raw));
+      var pct = has ? Math.max(0, Math.min(100, Number(raw))) : 0;
+      return '<div class="trust-bar">'
+        + '<span class="trust-bar-label"></span>'
+        + '<span class="trust-bar-track"><i style="width:' + pct + '%"></i></span>'
+        + '<b class="trust-bar-value">' + (has ? pct + "%" : "—") + '</b>'
+        + '</div>';
+    }).join("");
+    els.trustHero.setAttribute("data-status", status);
+    els.trustHero.innerHTML =
+      '<div class="trust-hero-score">'
+      + '<span class="trust-hero-eyebrow">Memory Trust</span>'
+      + '<div class="trust-hero-number"><strong>' + (score == null ? "—" : score) + '</strong><span>/100</span></div>'
+      + '<p class="trust-hero-note">' + note + '</p>'
+      + '</div>'
+      + '<div class="trust-hero-bars">' + barsHtml + '</div>';
+    // Set labels via textContent to avoid any HTML injection from labels.
+    var labelEls = els.trustHero.querySelectorAll(".trust-bar-label");
+    for (var i = 0; i < labelEls.length; i += 1) labelEls[i].textContent = bars[i][0];
+  }
+
+  function renderSuppressionShelf(report) {
+    if (!els.suppressionShelf) return;
+    var items = (report && report.items) || [];
+    if (!items.length) {
+      els.suppressionShelf.innerHTML = "";
+      els.suppressionShelf.hidden = true;
+      return;
+    }
+    els.suppressionShelf.hidden = false;
+    var plural = items.length === 1 ? "memory is" : "memories are";
+    els.suppressionShelf.innerHTML =
+      '<div class="suppression-head">'
+      + '<div><span class="suppression-eyebrow">Withheld from recall</span>'
+      + '<h2>' + items.length + ' ' + plural + ' being withheld from your agents</h2></div>'
+      + '<strong class="suppression-flag">Needs review</strong>'
+      + '</div>'
+      + '<p class="suppression-sub">Recall is hiding these because their cited evidence was deleted or expired. Verify, update, or supersede each before agents should trust them.</p>'
+      + '<div class="suppression-list">'
+      + items.slice(0, 8).map(function () {
+        return '<div class="suppression-item"><span class="suppression-item-title"></span><span class="suppression-item-reason"></span></div>';
+      }).join("")
+      + '</div>'
+      + (items.length > 8 ? '<p class="suppression-more">+ ' + (items.length - 8) + ' more — run <code>kage suppressed</code></p>' : '');
+    var titleEls = els.suppressionShelf.querySelectorAll(".suppression-item-title");
+    var reasonEls = els.suppressionShelf.querySelectorAll(".suppression-item-reason");
+    for (var i = 0; i < titleEls.length; i += 1) {
+      titleEls[i].textContent = items[i].title;
+      reasonEls[i].textContent = items[i].reason;
+    }
+  }
+
   function renderDashboard() {
     if (!els.dashboardStats) return;
     var metrics = state.metrics || {};
@@ -3009,6 +3092,8 @@
     var readiness = handoff || dashboardReadiness(metrics, pendingReview, staleFlags, duplicateFlags, missingContext);
     var memoryCoverage = dashboardMemoryCoverage(reports, memoryCodeEdges, memoryGraph, memoryNodes);
     var riskHealth = riskTargets.length || hotspots ? (riskTargets.length + hotspots) + " checks" : "No flags";
+    renderTrustHero(reports.trust);
+    renderSuppressionShelf(reports.suppressed);
     var statRows = [
       ["Handoff", readiness.label, readiness.detail, readiness.status],
       ["Memory", memoryCoverage.label, memoryCoverage.detail, memoryCoverage.status],
@@ -3547,6 +3632,10 @@
     return state.entities.filter(function (entity) { return entity.type === type; }).length;
   }
 
+  function numOrDash(value) {
+    return (value === null || value === undefined || isNaN(value)) ? "—" : value;
+  }
+
   function formatDashboardValue(value) {
     if (typeof value === "number" && Number.isFinite(value)) return value.toLocaleString();
     return String(value == null ? "n/a" : value);

package/viewer/index.html

@@ -4,7 +4,7 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Kage viewer</title>
-    <link rel="stylesheet" href="./styles.css?v=37">
+    <link rel="stylesheet" href="./styles.css?v=39">
   </head>
   <body>
     <div class="viewer-shell">
@@ -54,16 +54,18 @@
 
         <main class="layout">
       <section class="dashboard-panel" aria-label="Kage repo dashboard">
+        <div id="trustHero" class="trust-hero" aria-label="Memory trust score"></div>
+        <div id="suppressionShelf" class="suppression-shelf" aria-label="Memory withheld from recall" hidden></div>
         <div id="dashboardStats" class="dashboard-stats" aria-label="Repo dashboard stats"></div>
-        <section id="repoXray" class="repo-xray" aria-label="Repo X-Ray">
+        <section id="repoXray" class="repo-xray" aria-label="Repository map">
           <div class="repo-xray-head">
             <div>
-              <span>Repo X-Ray</span>
-              <h2>Show me what you understand</h2>
+              <span>Repository map</span>
+              <h2>What Kage understands about this repo</h2>
             </div>
             <strong id="repoXrayStatus">waiting</strong>
           </div>
-          <p id="repoXrayScript">Kage will map entry points, core files, risk, tests, and memory overlays when the X-Ray report is loaded.</p>
+          <p id="repoXrayScript">Entry points, core modules, change risk, tests, and memory overlays — mapped from the code graph.</p>
           <div id="repoXrayLayers" class="repo-xray-layers"></div>
         </section>
         <div id="dashboardCharts" class="dashboard-charts" aria-label="Repo health charts"></div>
@@ -302,6 +304,6 @@
       </section>
     </div>
 
-    <script src="./app.js?v=50"></script>
+    <script src="./app.js?v=53"></script>
   </body>
 </html>

package/viewer/styles.css

@@ -424,6 +424,103 @@ body.viewer-page-data .graph-panel {
   white-space: nowrap;
 }
 
+.trust-hero {
+  display: grid;
+  grid-template-columns: minmax(170px, 250px) minmax(0, 1fr);
+  gap: 30px;
+  align-items: center;
+  margin-bottom: 18px;
+  padding: 24px 28px;
+  border: 1px solid rgba(65, 255, 143, 0.24);
+  border-radius: 14px;
+  background:
+    radial-gradient(circle at 0 0, rgba(65, 255, 143, 0.12), transparent 380px),
+    linear-gradient(135deg, rgba(8, 17, 13, 0.96), rgba(10, 16, 22, 0.82));
+  box-shadow: var(--shadow);
+}
+.trust-hero[data-status="warn"] { border-color: rgba(255, 209, 102, 0.34); }
+.trust-hero[data-status="alert"] { border-color: rgba(255, 107, 107, 0.38); }
+.trust-hero[data-status="idle"] { border-color: var(--line); }
+.trust-hero-eyebrow {
+  display: block;
+  color: var(--terminal-dim);
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+.trust-hero-number { display: flex; align-items: baseline; gap: 5px; margin-top: 8px; }
+.trust-hero-number strong {
+  font-size: 60px;
+  line-height: 1;
+  color: var(--terminal-strong);
+  text-shadow: 0 0 24px rgba(65, 255, 143, 0.38);
+}
+.trust-hero[data-status="warn"] .trust-hero-number strong { color: var(--warn); text-shadow: 0 0 24px rgba(255, 209, 102, 0.32); }
+.trust-hero[data-status="alert"] .trust-hero-number strong { color: var(--danger); text-shadow: 0 0 24px rgba(255, 107, 107, 0.32); }
+.trust-hero[data-status="idle"] .trust-hero-number strong { color: var(--muted); text-shadow: none; }
+.trust-hero-number span { font-size: 19px; color: var(--muted); }
+.trust-hero-note { margin: 12px 0 0; color: var(--muted); font-size: 12.5px; line-height: 1.45; max-width: 250px; }
+.trust-hero-note code { color: var(--accent); background: var(--accent-soft); padding: 1px 6px; border-radius: 5px; font-size: 11.5px; }
+.trust-hero-bars { display: grid; gap: 15px; }
+.trust-bar {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 52px;
+  grid-template-areas: "label value" "track value";
+  align-items: center;
+  gap: 4px 14px;
+}
+.trust-bar-label { grid-area: label; color: var(--text); font-size: 13px; }
+.trust-bar-track { grid-area: track; height: 8px; border-radius: 999px; background: rgba(215, 249, 223, 0.07); overflow: hidden; }
+.trust-bar-track i { display: block; height: 100%; border-radius: 999px; background: linear-gradient(90deg, var(--brand), var(--accent)); box-shadow: 0 0 12px rgba(65, 255, 143, 0.3); transition: width 0.5s ease; }
+.trust-bar-value { grid-area: value; text-align: right; color: var(--terminal-strong); font-size: 15px; font-weight: 800; }
+@media (max-width: 860px) {
+  .trust-hero { grid-template-columns: 1fr; gap: 20px; }
+  .trust-hero-note { max-width: none; }
+}
+
+.suppression-shelf {
+  margin-bottom: 18px;
+  padding: 20px 24px;
+  border: 1px solid rgba(255, 209, 102, 0.34);
+  border-radius: 14px;
+  background:
+    radial-gradient(circle at 0 0, rgba(255, 209, 102, 0.08), transparent 360px),
+    linear-gradient(135deg, rgba(24, 18, 8, 0.92), rgba(16, 14, 10, 0.82));
+}
+.suppression-shelf[hidden] { display: none; }
+.suppression-head { display: flex; align-items: start; justify-content: space-between; gap: 16px; }
+.suppression-eyebrow { display: block; color: var(--warn); font-size: 11px; font-weight: 800; letter-spacing: 0.14em; text-transform: uppercase; }
+.suppression-head h2 { margin-top: 5px; color: var(--text); text-shadow: none; font-size: 17px; }
+.suppression-flag {
+  flex: none;
+  color: var(--warn);
+  font-size: 11px;
+  font-weight: 800;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  padding: 5px 10px;
+  border: 1px solid rgba(255, 209, 102, 0.4);
+  border-radius: 999px;
+  background: var(--warn-soft);
+}
+.suppression-sub { margin: 8px 0 14px; color: var(--muted); font-size: 12.5px; line-height: 1.45; max-width: 760px; }
+.suppression-list { display: grid; gap: 8px; }
+.suppression-item {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 16px;
+  padding: 11px 14px;
+  border: 1px solid rgba(255, 209, 102, 0.16);
+  border-radius: 9px;
+  background: rgba(8, 17, 13, 0.5);
+}
+.suppression-item-title { color: var(--text); font-size: 13.5px; font-weight: 650; overflow-wrap: anywhere; }
+.suppression-item-reason { color: var(--warn); font-size: 12px; text-align: right; opacity: 0.92; }
+.suppression-more { margin: 12px 0 0; color: var(--muted); font-size: 12px; }
+.suppression-more code { color: var(--accent); background: var(--accent-soft); padding: 1px 5px; border-radius: 5px; }
+
 .dashboard-stats {
   display: grid;
   grid-template-columns: repeat(3, minmax(0, 1fr));
@@ -431,8 +528,8 @@ body.viewer-page-data .graph-panel {
   margin-bottom: 22px;
 }
 .dashboard-stat {
-  min-height: 142px;
-  padding: 22px;
+  min-height: 120px;
+  padding: 20px 22px;
   border: 1px solid rgba(65, 255, 143, 0.12);
   border-radius: 10px;
   background: rgba(8, 17, 13, 0.82);