@kage-core/kage-graph-mcp 2.3.3 → 2.5.0

package/dist/cli.js

@@ -114,6 +114,7 @@ Usage:
   kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--docs] [--max-context-tokens <n>] [--structural-hops <n>]
   kage docs-search "<query>" --project <dir> [--limit <n>] [--json]   search this repo's own committed docs (README, docs/**, *.md)
   kage file-context --project <dir> --path <file> [--json]
+  kage prompt-context --project <dir> --query "<task>" [--json]   recall + savings receipt for an ambient prompt hook
   kage observe --project <dir> --event <json>
   kage sessions --project <dir> [--json]
   kage replay --project <dir> [--session <id>] [--limit <n>] [--json]
@@ -314,9 +315,22 @@ async function main() {
             console.log("  npx -y kage-graph-mcp scan --project /path/to/repo");
             process.exit(2);
         }
+        // scan is read-only by promise ("nothing generated"): if the repo has no Kage memory
+        // yet — e.g. a one-off scan of a repo you don't own — don't leave a .agent_memory/
+        // tree behind. Remove what the graph build created, but only if it wasn't there before.
+        const hadMemory = (0, node_fs_1.existsSync)((0, node_path_1.join)(scanTarget, ".agent_memory"));
+        const cleanupScanArtifacts = () => {
+            if (hadMemory)
+                return;
+            try {
+                (0, node_fs_1.rmSync)((0, node_path_1.join)(scanTarget, ".agent_memory"), { recursive: true, force: true });
+            }
+            catch { }
+        };
         const result = (0, kernel_js_1.truthReport)(scanTarget);
         if (args.includes("--json")) {
             console.log(JSON.stringify(result, null, 2));
+            cleanupScanArtifacts();
             return;
         }
         if (args.includes("--scorecard")) {
@@ -329,6 +343,7 @@ async function main() {
             console.log(`Scorecard written to ${outPath}`);
             console.log("Share it: embed the SVG in a README, screenshot it, or post it.\n");
             console.log((0, kernel_js_1.truthScorecardMarkdown)(result));
+            cleanupScanArtifacts();
             return;
         }
         console.log(`Kage Truth Report — ${result.project_dir}`);
@@ -381,6 +396,7 @@ async function main() {
         console.log(result.findings.length ? "Fix the void:" : "Next:");
         for (const action of result.next_actions)
             console.log(`  ${action}`);
+        cleanupScanArtifacts();
         return;
     }
     if (command === "demo") {
@@ -1388,6 +1404,29 @@ async function main() {
         // No verified packets cite this file: print nothing so hooks can gate on empty output.
         return;
     }
+    if (command === "prompt-context") {
+        // Top-of-task recall for an ambient UserPromptSubmit hook: recall on the user's prompt
+        // and emit the memory PLUS a one-line savings receipt (what was recalled + tokens saved).
+        // Silent when nothing relevant is found, so hooks can gate on empty output.
+        const query = takeArg(args, "--query") ?? firstPositional(args);
+        if (!query)
+            usage();
+        const result = (0, kernel_js_1.recall)(projectArg(args), query, 5, false, {});
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (!result.results.length)
+            return;
+        let out = result.context_block;
+        if (result.value_receipt) {
+            const r = result.value_receipt;
+            const plural = result.results.length === 1 ? "y" : "ies";
+            out += `\n\n_↳ Kage recalled ${result.results.length} verified memor${plural} · ~${(0, kernel_js_1.formatTokenCount)(r.tokens_saved)} tokens saved this recall · ${r.stale_withheld} stale withheld._`;
+        }
+        console.log(out);
+        return;
+    }
     if (command === "memory-access") {
         const result = (0, kernel_js_1.kageMemoryAccess)(projectArg(args));
         if (args.includes("--json")) {

package/dist/index.js

@@ -114,6 +114,7 @@ function listTools() {
             // separate deferred schemas. Cuts session start from 4 schema loads to 1.
             name: "kage_context",
             description: "Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task; it answers caller/usage questions from the code graph too, so you rarely need a separate graph tool.",
+            annotations: { title: "Recall verified memory and query the code/knowledge graph", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -218,10 +219,11 @@ function listTools() {
         {
             name: "kage_risk",
             description: "Assess modification risk for files using Kage's code graph plus local git history: dependents, impact surface, churn, ownership, co-change partners, and test gaps. Use before editing hotspot or shared files.",
+            annotations: { title: "Assess file modification risk", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     targets: { type: "array", items: { type: "string" }, description: "File paths to assess" },
                     changed_files: { type: "array", items: { type: "string" }, description: "Optional PR/branch changed files. If targets is omitted, these are assessed." },
                 },
@@ -231,10 +233,11 @@ function listTools() {
         {
             name: "kage_dependency_path",
             description: "Find how two files are connected in Kage's source-derived code graph. Reports direct dependency direction, reverse impact direction, or undirected graph connection.",
+            annotations: { title: "Trace the dependency path between two files", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     from: { type: "string", description: "Source file path or unique suffix" },
                     to: { type: "string", description: "Target file path or unique suffix" },
                 },
@@ -353,6 +356,7 @@ function listTools() {
         {
             name: "kage_decisions",
             description: "Summarize the repo's 'why' memory at a glance: the decisions, gotchas, runbooks, conventions, and code explanations Kage has captured, plus which high-traffic code paths still have no decision memory. Use it to brief yourself on a repo before changing it, or to audit where institutional knowledge is thin or going stale. Read-only: returns grouped entries with titles, types, cited file paths, and call-outs for weak, stale, or undocumented hot paths. Does not modify any memory.",
+            annotations: { title: "Summarize the repo's decision memory", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -386,12 +390,13 @@ function listTools() {
         {
             name: "kage_docs_search",
             description: "Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.",
+            annotations: { title: "Search the repo's own committed docs", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    query: { type: "string" },
-                    project_dir: { type: "string" },
-                    limit: { type: "number" },
+                    query: { type: "string", description: "Search terms to match against the repo's documentation." },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    limit: { type: "number", description: "Max ranked doc hits to return (default 5)." },
                 },
                 required: ["query", "project_dir"],
             },
@@ -489,10 +494,11 @@ function listTools() {
         {
             name: "kage_refresh",
             description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file/content changes before PR checks; push-only or same-tree commits do not need another refresh. On non-default git branches metadata-only packet rewrites are skipped (quiet refresh) to avoid merge conflicts; pass force to persist them anyway.",
+            annotations: { title: "Rebuild Kage indexes and graphs", readOnlyHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                     force: { type: "boolean", description: "Persist packet metadata rewrites even on a non-default branch" },
                 },
                 required: ["project_dir"],
@@ -521,10 +527,11 @@ function listTools() {
         {
             name: "kage_pr_check",
             description: "Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge. Leads with a human summary of team memories invalidated by the current change — relay it to the developer.",
+            annotations: { title: "Check memory readiness for merge", readOnlyHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
                 },
                 required: ["project_dir"],
             },
@@ -613,6 +620,7 @@ function listTools() {
         {
             name: "kage_supersede",
             description: "Replace one repo-local memory packet with a newer one that corrects or obsoletes it. Marks the old packet superseded, links it to the replacement, and writes bidirectional lineage edges so the history stays traceable. Use this instead of deleting when new knowledge updates an old fact, or to resolve a contradiction surfaced by kage_conflicts. Mutates both packets on disk: the superseded packet is withheld from recall but kept for lineage.",
+            annotations: { title: "Supersede a memory packet with a newer one", readOnlyHint: false, destructiveHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -638,12 +646,13 @@ function listTools() {
         {
             name: "kage_skills",
             description: "Codify durable, verified repo memory (runbooks, workflows, actionable decisions) into git-native SKILL.md files under .claude/skills/ that every teammate's agent auto-loads. Only grounded, non-stale packets become skills. Pass dry_run to preview without writing. dir overrides the output directory.",
+            annotations: { title: "Codify verified memory into agent skills", readOnlyHint: false, idempotentHint: true },
             inputSchema: {
                 type: "object",
                 properties: {
-                    project_dir: { type: "string" },
-                    dry_run: { type: "boolean" },
-                    dir: { type: "string" },
+                    project_dir: { type: "string", description: "Absolute path to the repository root." },
+                    dry_run: { type: "boolean", description: "Preview which skills would be written without creating any files." },
+                    dir: { type: "string", description: "Override the output directory (default .claude/skills/)." },
                 },
                 required: ["project_dir"],
             },
@@ -736,6 +745,7 @@ function listTools() {
         {
             name: "kage_learn",
             description: "Capture a durable, reusable learning from the current session as a verified repo-local memory packet (committed under .agent_memory/, shared with the team via git). Use it the moment you discover something a future session should know: a decision and its rationale, a bug's root cause and fix, a convention, or a setup step. Prefer it over diff-based proposals when you already know what was learned. The write is rejected if every cited path is missing from the repo (set allow_missing_paths for a file you are about to create), and secrets/PII are scanned out before writing. Returns the new packet id plus any contradiction warnings against existing memory.",
+            annotations: { title: "Capture a verified learning to repo memory", readOnlyHint: false },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -873,6 +883,7 @@ function listTools() {
         {
             name: "kage_feedback",
             description: "Record how useful a recalled repo-local memory packet was, which tunes Kage's trust and future recall. 'helpful' reinforces the packet, 'wrong' flags it as disputed, and 'stale' marks it for re-verification and withholds it from recall until refreshed. Use it right after a recalled packet helped you, misled you, or no longer matched the code. Mutates the packet's quality signals on disk.",
+            annotations: { title: "Rate a recalled memory packet", readOnlyHint: false },
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1050,10 +1061,11 @@ async function callTool(name, args) {
         const validationText = validation.ok
             ? "Memory healthy."
             : `Warnings: ${validation.warnings.join("; ")}`;
-        // recall (memory + code graph + knowledge graph combined)
+        // recall already includes the code graph + knowledge-graph facts (its "## Related Graph
+        // Facts" section). We deliberately do NOT query the graph a second time here: doing so
+        // emitted a near-duplicate dump of the same edges which, with no size cap, blew
+        // kage_context past 270k chars and overflowed the response.
         const recallResult = (0, kernel_js_1.recall)(projectDir, query, limit, false);
-        // graph facts on top of recall
-        const graphResult = (0, kernel_js_1.queryGraph)(projectDir, query, 5);
         const explicitTargets = [...arrayArg(args?.targets), ...filePathHints(query)];
         const changedFiles = arrayArg(args?.changed_files);
         const riskResult = explicitTargets.length || changedFiles.length ? (0, kernel_js_1.kageRisk)(projectDir, explicitTargets, changedFiles) : null;
@@ -1076,23 +1088,27 @@ async function callTool(name, args) {
         const learningLedger = typeof args?.session_id === "string" && args.session_id.trim()
             ? (0, kernel_js_1.kageSessionLearningLedger)(projectDir, { sessionId: args.session_id, limit: 20 })
             : null;
-        const sections = [
+        const body = [
             recallResult.context_block,
             teammateBrief.context_block,
             learningLedger ? learningLedger.context_block : "",
-            graphResult.context_block ? `\n## Graph Facts\n${graphResult.context_block}` : "",
             riskResult ? riskContextBlock(riskResult) : "",
             dependencyResult ? `\n## Dependency Path\n${dependencyResult.summary}${dependencyResult.path.length ? `\nPath: ${dependencyResult.path.join(" -> ")}` : ""}` : "",
             reconciliation.unresolved_count ? `\n## Memory Reconciliation\n${reconciliation.agent_instruction}` : "",
             `\n_${validationText}_`,
-            // Visible receipt: surface what the harness saved today so agents relay it.
-            (() => {
-                const gains = (0, kernel_js_1.valueSummary)(projectDir).today;
-                return `\n\nGains: ~${(0, kernel_js_1.formatTokenCount)(gains.tokens_saved)} tokens saved this session · stale memories withheld: ${gains.stale_withheld}`;
-            })(),
         ].filter(Boolean).join("");
-        return {
-            content: [{ type: "text", text: sections }],
+        // Visible receipt: surface what the harness saved today so agents relay it. Kept
+        // outside the size cap so it always survives.
+        const gains = (0, kernel_js_1.valueSummary)(projectDir).today;
+        const gainsLine = `\n\nGains: ~${(0, kernel_js_1.formatTokenCount)(gains.tokens_saved)} tokens saved this session · stale memories withheld: ${gains.stale_withheld}`;
+        // Backstop: per-field clamping + graph dedup keep this compact in practice, but never
+        // let a pathological repo overflow the MCP response again. ~24k chars ≈ 6k tokens.
+        const MAX_CONTEXT_CHARS = 24000;
+        const cappedBody = body.length > MAX_CONTEXT_CHARS
+            ? `${body.slice(0, MAX_CONTEXT_CHARS)}\n\n_…kage_context truncated to keep the response within limits; narrow your query for more specific memory._`
+            : body;
+        return {
+            content: [{ type: "text", text: `${cappedBody}${gainsLine}` }],
         };
     }
     if (name === "kage_recall") {

package/dist/kernel.js

@@ -3202,6 +3202,14 @@ const MAX_CODE_GRAPH_CALLS_PER_FILE = positiveIntEnv("KAGE_MAX_CODE_GRAPH_CALLS_
 const MAX_STRUCTURAL_EXTRACT_FILE_BYTES = positiveIntEnv("KAGE_MAX_STRUCTURAL_EXTRACT_FILE_BYTES", MAX_CODE_FILE_BYTES);
 const MAX_STRUCTURAL_WORKERS = positiveIntEnv("KAGE_STRUCTURAL_WORKERS", Math.max(1, Math.min(8, (0, node_os_1.availableParallelism)() - 1)));
 const MIN_STRUCTURAL_PARALLEL_FILES = positiveIntEnv("KAGE_STRUCTURAL_PARALLEL_MIN_FILES", 64);
+// Hard ceiling on indexable files a single scan will parse, so a very large monorepo
+// degrades to a bounded sample instead of an unbounded (and effectively quadratic) parse.
+// The skipped count is recorded in the scan's ignoredSummary as "exceeded_file_cap".
+const MAX_SCAN_FILES = positiveIntEnv("KAGE_MAX_SCAN_FILES", 25000);
+// Bound the single full-history git-log pass in truthReport to the most recent N commits.
+// Covers virtually every repo fully while preventing an unbounded log + buffer on a
+// deep-history monorepo (Linux/Chromium-class).
+const TRUTH_REPORT_MAX_COMMITS = positiveIntEnv("KAGE_SCAN_MAX_COMMITS", 8000);
 const CONFIG_NAMES = new Set([
     "package.json",
     "pyproject.toml",
@@ -3724,6 +3732,10 @@ function scanStructuralFiles(projectDir) {
                 ignore("unsupported_file_type");
                 continue;
             }
+            if (files.length >= MAX_SCAN_FILES) {
+                ignore("exceeded_file_cap");
+                continue;
+            }
             files.push(absolutePath);
         }
     };
@@ -3736,11 +3748,27 @@ function scanStructuralFiles(projectDir) {
 function countBufferLines(buffer) {
     if (buffer.length === 0)
         return 0;
-    let lines = 1;
+    // Count newline bytes (matches `wc -l` for newline-terminated files) and add one for a
+    // final line without a trailing newline, so the count is not inflated by +1.
+    let lines = 0;
     for (const byte of buffer) {
         if (byte === 10)
             lines += 1;
     }
+    if (buffer[buffer.length - 1] !== 10)
+        lines += 1;
+    return lines;
+}
+function countTextLines(text) {
+    if (text.length === 0)
+        return 0;
+    let lines = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            lines += 1;
+    }
+    if (text.charCodeAt(text.length - 1) !== 10)
+        lines += 1;
     return lines;
 }
 function structuralConcepts(rel, symbols) {
@@ -4011,7 +4039,7 @@ function buildStructuralFile(projectDir, absolutePath, knownFiles, prior) {
         language,
         kind: codeFileKind(rel),
         size_bytes: stats.size,
-        line_count: content ? content.split(/\r?\n/).length : countBufferLines(buffer ?? (0, node_fs_1.readFileSync)(absolutePath)),
+        line_count: content ? countTextLines(content) : countBufferLines(buffer ?? (0, node_fs_1.readFileSync)(absolutePath)),
         hash: hash.slice(0, 16),
         mtime_ms: stats.mtimeMs,
         extraction: entry.extraction,
@@ -5786,11 +5814,15 @@ function buildCodeGraph(projectDir, options = {}) {
         if (file)
             file.parser = strongerParser(file.parser, symbol.parser);
     }
+    const symbolById = new Map();
+    for (const symbol of symbols)
+        if (!symbolById.has(symbol.id))
+            symbolById.set(symbol.id, symbol);
     const addSymbol = (symbol) => {
         if (!fileByPath.has(symbol.path))
             return;
         const file = fileByPath.get(symbol.path);
-        const existing = symbols.find((candidate) => candidate.id === symbol.id);
+        const existing = symbolById.get(symbol.id);
         if (existing) {
             existing.parser = strongerParser(existing.parser, symbol.parser);
             if (file)
@@ -5800,6 +5832,7 @@ function buildCodeGraph(projectDir, options = {}) {
         if (file)
             file.parser = strongerParser(file.parser, symbol.parser);
         symbols.push(symbol);
+        symbolById.set(symbol.id, symbol);
     };
     for (const symbol of externalFacts.symbols)
         addSymbol(symbol);
@@ -5818,14 +5851,29 @@ function buildCodeGraph(projectDir, options = {}) {
         list.push(symbol);
         symbolByName.set(symbol.name, list);
     }
+    // Index symbols and imports by file once, so the per-file loop below is an O(1) lookup
+    // instead of an O(files × symbols) / O(files × imports) scan over the global arrays —
+    // the dominant cost on large monorepos.
+    const symbolsByPath = new Map();
+    for (const symbol of symbols) {
+        const list = symbolsByPath.get(symbol.path) ?? [];
+        list.push(symbol);
+        symbolsByPath.set(symbol.path, list);
+    }
+    const importsByFromPath = new Map();
+    for (const item of imports) {
+        const list = importsByFromPath.get(item.from_path) ?? [];
+        list.push(item);
+        importsByFromPath.set(item.from_path, list);
+    }
     const calls = [];
     const routes = [];
     const tests = [];
     for (const [rel, content] of contents) {
         if (calls.length >= MAX_CODE_GRAPH_CALLS)
             break;
-        const fileSymbols = symbols.filter((symbol) => symbol.path === rel);
-        const fileImports = imports.filter((item) => item.from_path === rel);
+        const fileSymbols = symbolsByPath.get(rel) ?? [];
+        const fileImports = importsByFromPath.get(rel) ?? [];
         const importedNames = new Map();
         for (const item of fileImports) {
             for (const importedName of item.imported) {
@@ -6950,6 +6998,15 @@ function gcProject(projectDir, options = {}) {
             skipped.push({ id: packet.id, title: packet.title, reason: "already deprecated" });
             continue;
         }
+        // Serialized transcript / tool-output / file-content dumps carry no durable knowledge
+        // and bloat recall + the graph. Always delete them (deprecating would leave the blob on
+        // disk) — this also reclaims legacy dumps written before the capture-time guard existed.
+        if (isSerializedDumpTitle(packet.title) || isSerializedDumpBody(packet.body)) {
+            if (!options.dryRun)
+                (0, node_fs_1.unlinkSync)(path);
+            deleted.push({ id: packet.id, title: packet.title });
+            continue;
+        }
         const reasons = staleMemoryReasons(projectDir, packet);
         if (!reasons.length) {
             skipped.push({ id: packet.id, title: packet.title, reason: "healthy" });
@@ -7820,7 +7877,12 @@ function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0
     const vector = Number(vectorScore.toFixed(2));
     const usage = Number(usageScore.toFixed(2));
     const pathTypeTagWeight = packet.type === "reference" ? 0.2 : 0.8;
-    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + usage + freshness + quality + feedback).toFixed(2));
+    // Popularity (usage) must only AMPLIFY genuine relevance, never float a packet that has no
+    // lexical/semantic/graph/intent match to the top — that is what produced confident
+    // off-domain junk (a hot packet ranked #1 for a query it shared no terms with).
+    const coreRelevance = textScore + graphScore + intent + vector;
+    const effectiveUsage = coreRelevance > 0 ? usage : 0;
+    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + effectiveUsage + freshness + quality + feedback).toFixed(2));
     return {
         bm25: textScore,
         text: textScore,
@@ -7872,6 +7934,50 @@ function diversifyRecallEntries(entries, limit, maxPerSource = 3) {
     }
     return selected.slice(0, limit);
 }
+// Raw transcript / serialized tool-output packets are capture noise, not knowledge. Keep
+// them out of recall so they can never outrank real memory. This is the recall-side safety
+// net; the durable fixes are a capture-time guard and pruning the existing ones (`kage prune`).
+function isSerializedDumpTitle(title) {
+    const t = (title ?? "").trimStart();
+    return /^(workflow|runbook)\s*:?\s*[{[]/i.test(t)
+        || t.startsWith('{"')
+        || /^<(task-notification|div|svg|html)\b/i.test(t)
+        || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title);
+}
+// Durable-learning size ceiling. A memory packet body is a distilled insight, not a
+// document; anything past this is almost certainly a raw transcript, file-content, or
+// tool-output dump. Env-overridable for unusual repos.
+const MAX_PACKET_BODY_CHARS = positiveIntEnv("KAGE_MAX_PACKET_BODY_CHARS", 16000);
+// Body-level counterpart to isSerializedDumpTitle: catches raw transcript, serialized
+// tool-output, or file-content dumps that arrive as a packet/edge body even when the
+// title was massaged into something innocuous (e.g. a shell-prompt paste). The byte cap
+// alone catches the rest — a 300KB "learning" is never knowledge.
+function isSerializedDumpBody(body) {
+    const t = (body ?? "").trimStart();
+    if (!t)
+        return false;
+    if (t.length > MAX_PACKET_BODY_CHARS)
+        return true;
+    return isSerializedDumpTitle(t)
+        || /<task-notification\b|<tool-use-id\b|"hookSpecificOutput"|"isImage"\s*:|"noOutputExpected"\s*:|"interrupted"\s*:\s*(true|false)/i.test(t.slice(0, 4000));
+}
+// Collapse whitespace and hard-cap a value rendered inline in a context block, so one
+// oversized field (e.g. a graph fact whose body is a raw transcript) can never blow up
+// the assembled output — the 270k-char overflow that motivated this guard.
+function clampInline(text, max = 280) {
+    const oneLine = (text ?? "").replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, max)}… [+${oneLine.length - max} chars truncated]`;
+}
+// Like clampInline but preserves newlines — for multi-line blocks (git diff stats, packet
+// bodies shown in diagnostics) where line structure carries meaning.
+function clampBlock(text, max) {
+    const t = (text ?? "").trim();
+    if (t.length <= max)
+        return t;
+    return `${t.slice(0, max)}\n… [+${t.length - max} chars truncated]`;
+}
 function recallWithVectorScores(projectDir, query, limit = 5, explain = false, inputs = {}, externalVectorScores) {
     const current = inputs.codeGraph && inputs.knowledgeGraph ? null : readCurrentGraphs(projectDir);
     const detailedIndex = inputs.codeGraph && inputs.knowledgeGraph || current ? null : indexProjectDetailed(projectDir);
@@ -7940,7 +8046,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ];
         return { packet, score: score_breakdown.final, relevance, why_matched: unique(why).slice(0, 12), score_breakdown };
     })
-        .filter((entry) => entry.relevance > 0)
+        .filter((entry) => entry.relevance > 0 && !isSerializedDumpTitle(entry.packet.title))
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title));
     const scored = diversifyRecallEntries(rankedScored, limit)
         .map(({ relevance, ...entry }) => entry);
@@ -8018,7 +8124,7 @@ 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(", ")})`),
+        ...graphContext.edges.slice(0, 5).map((edge, index) => `${index + 1}. ${clampInline(edge.fact)} (evidence: ${clampInline(edge.evidence.join(", "), 200)})`),
         ...(suppressed.length
             ? [
                 "",
@@ -9133,6 +9239,13 @@ function kageCleanupCandidates(projectDir) {
 }
 const TRUTH_REPORT_MAX_FINDINGS = 16;
 const TRUTH_REPORT_AI_ERA_DAYS = 120;
+// A same-name, same-signature symbol spread across more than this many directories is a
+// framework/language convention (e.g. Go's per-package addKnownTypes / AddToScheme), not
+// copy-paste worth surfacing. Real, actionable duplication is a handful of sites.
+const TRUTH_DUPLICATE_MAX_DIRS = 8;
+// A directory whose last segment is an API version (v1, v2, v1beta1, v2alpha3, ...). The
+// same type redefined across sibling version packages is API versioning, not duplication.
+const TRUTH_VERSION_DIR = /(^|\/)v\d+((alpha|beta)\d+)?$/i;
 // Symbol names too generic to mean "two teams built the same thing".
 const TRUTH_COMMON_SYMBOL_NAMES = new Set([
     "main", "init", "run", "setup", "start", "stop", "open", "close", "create", "destroy",
@@ -9146,10 +9259,24 @@ const TRUTH_DUPLICATE_NAME_DENYLIST = new Set([
     "decorator", "wrapper", "inner", "callback", "wrapped", "fn", "cb", "noop",
     "predicate", "comparator", "getter", "setter", "factory", "visit",
 ]);
+// Machine-generated code (protobuf, conversion/deepcopy codegen, mocks, minified bundles)
+// is not where a human's undocumented knowledge lives — flagging it as a hotspot, duplicate,
+// or ghost export is pure noise. Detected by the conventional names generators emit.
+function isGeneratedPath(path) {
+    const p = path.toLowerCase();
+    return /(^|[/._-])(zz_generated|generated|autogen|codegen)[._-]/.test(p)
+        || /(^|\/)(generated|__generated__)\//.test(p)
+        || /\.pb\.(go|cc|h|ts|js|py|rb|dart|swift)$/.test(p)
+        || /[._](pb2|pb2_grpc)\.py$/.test(p)
+        || /\.(gen|g|freezed)\.[^.]+$/.test(p)
+        || /(^|\/)(mock_[^/]*|wire_gen)\.[^.]+$/.test(p)
+        || /\.min\.(js|css)$/.test(p);
+}
 function truthExcludedPath(path) {
     return /(^|\/)(tests?|__tests__|specs?|examples?|fixtures?|benchmarks?|mocks?|__mocks__|vendor|node_modules|dist|build)\//i.test(path)
         || /\.(test|spec)\.[^.]+$/i.test(path)
-        || /(^|\/)test[^/]*\.[^.]+$/i.test(path);
+        || /(^|\/)test[^/]*\.[^.]+$/i.test(path)
+        || isGeneratedPath(path);
 }
 const TRUTH_DOC_PATH_EXTENSIONS = "ts|tsx|js|jsx|mjs|cjs|json|md|yml|yaml|toml|py|rb|go|rs|java|kt|sh|bash|css|scss|html|sql|proto|graphql|c|h|cpp|hpp|cs|txt";
 function truthDocPathCandidates(line) {
@@ -9167,6 +9294,117 @@ function truthDocPathCandidates(line) {
         && !candidate.includes("node_modules")
         && !candidate.startsWith(".agent_memory"));
 }
+const TRUTH_DECL_KEYWORDS = new Set([
+    "function", "func", "fn", "def", "class", "struct", "trait", "interface",
+    "type", "enum", "const", "let", "var", "impl", "module", "object",
+]);
+// Render "<path>:<line>  <kind> <signature>" without doubling the declaration keyword.
+// The captured signature often already declares the construct ("export function abort(...)",
+// "pub fn abort(...)", "class Foo"), so blindly prefixing the kind yields
+// "function export function abort". Only add the kind when the signature carries no
+// leading declaration keyword of its own.
+function truthSymbolEvidence(path, line, kind, signature) {
+    const sig = signature.slice(0, 80).trim();
+    const leadTokens = sig.toLowerCase().split(/[^a-z]+/, 4);
+    const selfDescribing = leadTokens.some((tok) => TRUTH_DECL_KEYWORDS.has(tok))
+        || sig.toLowerCase().startsWith(`${kind.toLowerCase()} `);
+    return `${path}:${line}  ${selfDescribing ? sig : `${kind} ${sig}`}`;
+}
+// Real test coverage beats the import-reachability heuristic. When a standard coverage
+// report exists we read measured line coverage; KAGE_COVERAGE_MIN (default 0.5) is the
+// fraction below which a hot file counts as under-tested.
+const COVERAGE_TESTED_MIN = (() => {
+    const raw = Number(process.env.KAGE_COVERAGE_MIN);
+    return Number.isFinite(raw) && raw > 0 && raw <= 1 ? raw : 0.5;
+})();
+function parseLcovCoverage(text) {
+    const map = new Map();
+    let file = null;
+    let hit = 0;
+    let total = 0;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith("SF:")) {
+            file = line.slice(3).trim();
+            hit = 0;
+            total = 0;
+        }
+        else if (line.startsWith("DA:")) {
+            const count = Number(line.slice(3).split(",")[1] ?? 0) || 0;
+            total += 1;
+            if (count > 0)
+                hit += 1;
+        }
+        else if (line.startsWith("LH:")) {
+            hit = Number(line.slice(3)) || hit;
+        }
+        else if (line.startsWith("LF:")) {
+            total = Number(line.slice(3)) || total;
+        }
+        else if (line === "end_of_record" && file) {
+            map.set(file, { hit, total });
+            file = null;
+        }
+    }
+    return map;
+}
+function parseIstanbulCoverage(text) {
+    const map = new Map();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        return map;
+    }
+    for (const [key, entry] of Object.entries(json)) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const counts = Object.values(entry.s ?? {});
+        if (!counts.length)
+            continue;
+        const hit = counts.filter((value) => Number(value) > 0).length;
+        map.set(entry.path ?? key, { hit, total: counts.length });
+    }
+    return map;
+}
+function readCoverageReport(projectDir) {
+    const candidates = ["coverage/lcov.info", "lcov.info", "coverage/coverage-final.json", "coverage-final.json"];
+    const root = projectDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    for (const rel of candidates) {
+        const abs = (0, node_path_1.join)(projectDir, rel);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        const text = safeReadText(abs);
+        if (!text)
+            continue;
+        const parsed = rel.endsWith(".info") ? parseLcovCoverage(text) : parseIstanbulCoverage(text);
+        if (!parsed.size)
+            continue;
+        const byPath = new Map();
+        for (const [rawPath, value] of parsed) {
+            let p = rawPath.replace(/\\/g, "/");
+            if (p.startsWith(`${root}/`))
+                p = p.slice(root.length + 1);
+            p = p.replace(/^\.\//, "").replace(/^\/+/, "");
+            byPath.set(p, value);
+        }
+        return { source: rel, byPath, entries: [...byPath.entries()] };
+    }
+    return null;
+}
+// Coverage paths can carry an absolute or CI-machine prefix; fall back to suffix match.
+function coverageFor(report, path) {
+    const direct = report.byPath.get(path);
+    if (direct)
+        return direct;
+    const suffix = `/${path}`;
+    for (const [key, value] of report.entries) {
+        if (key.endsWith(suffix) || path.endsWith(`/${key}`))
+            return value;
+    }
+    return null;
+}
 function truthReport(projectDir) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const warnings = [];
@@ -9183,12 +9421,13 @@ function truthReport(projectDir) {
     const fileCommits = new Map();
     const fileNewestEpoch = new Map();
     if (hasGit) {
-        const raw = readGit(projectDir, ["log", "--no-renames", "--format=__KAGE_SCAN__%x1f%ae%x1f%ct", "--name-only"]) ?? "";
+        const raw = readGit(projectDir, ["log", `--max-count=${TRUTH_REPORT_MAX_COMMITS}`, "--no-renames", "--format=__KAGE_SCAN__%x1f%ae%x1f%ct", "--name-only"]) ?? "";
         // Resolve the repo->project prefix once; gitPathToProjectRelative spawns git per call,
         // which is far too slow for a full-history name-only walk.
         const projectPrefix = readGit(projectDir, ["rev-parse", "--show-prefix"])?.replace(/\\/g, "/").replace(/\/+$/, "") ?? "";
         let author = "";
         let epoch = 0;
+        let commitsSeen = 0;
         for (const rawLine of raw.split(/\r?\n/)) {
             const line = rawLine.trim();
             if (!line)
@@ -9197,6 +9436,7 @@ function truthReport(projectDir) {
                 const parts = line.split("\x1f");
                 author = (parts[1] ?? "").toLowerCase();
                 epoch = Number(parts[2] ?? 0) || 0;
+                commitsSeen += 1;
                 continue;
             }
             if (!author)
@@ -9213,6 +9453,9 @@ function truthReport(projectDir) {
             if (!fileNewestEpoch.has(path))
                 fileNewestEpoch.set(path, epoch);
         }
+        if (commitsSeen >= TRUTH_REPORT_MAX_COMMITS) {
+            warnings.push(`Git history is large; churn, bus-factor, and recency are computed from the most recent ${TRUTH_REPORT_MAX_COMMITS} commits.`);
+        }
     }
     // Centrality: import + call edges touching the file.
     const centrality = new Map();
@@ -9255,6 +9498,12 @@ function truthReport(projectDir) {
         const paths = new Set(members.map((member) => member.path));
         if (dirs.size < 2 || paths.size < 2)
             continue;
+        if (dirs.size > TRUTH_DUPLICATE_MAX_DIRS)
+            continue;
+        // Skip the same symbol redefined across sibling API-version packages (v1/v1beta1/...).
+        const versionedCount = members.filter((member) => TRUTH_VERSION_DIR.test((0, node_path_1.dirname)(member.path))).length;
+        if (versionedCount >= 2 && members.length - versionedCount <= 1)
+            continue;
         const signatureCounts = new Map();
         for (const member of members) {
             const normalized = member.signature.replace(/\s+/g, "");
@@ -9271,7 +9520,7 @@ function truthReport(projectDir) {
             kind: "duplicate_cluster",
             title: `${members[0].name} — ${paths.size} implementations across ${dirs.size} directories${recent ? " [recently changed]" : ""}`,
             detail: "Same name and near-identical signature in unrelated directories — likely parallel implementations of the same idea, worth a look.",
-            evidence: members.slice(0, 5).map((member) => `${member.path}:${member.line}  ${member.kind} ${member.signature.slice(0, 80)}`),
+            evidence: members.slice(0, 5).map((member) => truthSymbolEvidence(member.path, member.line, member.kind, member.signature)),
             surprise: Math.min(100, 45 + paths.size * 8 + (signatureMatch ? 15 : 0) + (recent ? 20 : 0)),
         });
     }
@@ -9325,7 +9574,7 @@ function truthReport(projectDir) {
                 kind: "ghost_export",
                 title: `${symbol.name} — exported, never called`,
                 detail: "No call edge, no import, and the name appears in no other file. Dead code, or knowledge nobody wired in.",
-                evidence: [`${symbol.path}:${symbol.line}  ${symbol.kind} ${symbol.signature.slice(0, 80)}`],
+                evidence: [truthSymbolEvidence(symbol.path, symbol.line, symbol.kind, symbol.signature)],
                 surprise: Math.min(100, 35 + Math.min(30, fileCentrality)),
             }];
     });
@@ -9445,8 +9694,9 @@ function truthReport(projectDir) {
                 testedPaths.add(edge.to_path);
         }
     }
+    const coverage = readCoverageReport(projectDir);
     const untestedFindings = [];
-    if (hasTests) {
+    if (hasTests || coverage) {
         for (const file of sourceFiles) {
             if (isEntrypointLike(file.path))
                 continue;
@@ -9456,7 +9706,26 @@ function truthReport(projectDir) {
                 continue;
             if (hasGit && commits < 2)
                 continue;
-            if (testedPaths.has(file.path))
+            // Prefer measured line coverage when the file is in the report; only fall back to
+            // the import-reachability heuristic for files the report doesn't cover.
+            if (coverage) {
+                const cov = coverageFor(coverage, file.path);
+                if (cov && cov.total > 0) {
+                    const pct = cov.hit / cov.total;
+                    if (pct >= COVERAGE_TESTED_MIN)
+                        continue;
+                    const pctLabel = Math.round(pct * 100);
+                    untestedFindings.push({
+                        kind: "untested_hot",
+                        title: `${file.path} — undertested hot path`,
+                        detail: `Only ${pctLabel}% line coverage (${cov.hit}/${cov.total} lines, measured from ${coverage.source}) on a file ${fileCentrality} other(s) depend on${commits ? `, changed ${commits} time(s)` : ""}. Thinly-covered hub files are where regressions hide.`,
+                        evidence: [`${file.path}:1  ${pctLabel}% line coverage (${cov.hit}/${cov.total} lines), centrality ${fileCentrality}`],
+                        surprise: Math.min(100, 30 + Math.min(45, fileCentrality * 3) + (hasGit ? Math.min(15, commits) : 0) + Math.round((1 - pct) * 12)),
+                    });
+                    continue;
+                }
+            }
+            if (!hasTests || testedPaths.has(file.path))
                 continue;
             untestedFindings.push({
                 kind: "untested_hot",
@@ -9467,6 +9736,12 @@ function truthReport(projectDir) {
             });
         }
     }
+    if (coverage) {
+        warnings.push(`Test coverage measured from ${coverage.source} (${coverage.byPath.size} files); files outside it fall back to static test-import heuristics.`);
+    }
+    else if (untestedFindings.length) {
+        warnings.push(`Untested findings are heuristic (no coverage report found): they flag hot files no test imports directly, not measured line coverage. Generate coverage/lcov.info for exact results.`);
+    }
     untestedFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
     // 1f. Complexity hotspots: very large source files many things depend on —
     // where knowledge concentrates and onboarding stalls.
@@ -9624,6 +9899,13 @@ function truthReport(projectDir) {
         ...(docLines.length ? [[docLieFindings.length, `${docLieFindings.length} doc lie${docLieFindings.length === 1 ? "" : "s"}`]] : []),
     ];
     const headlineParts = headlineCandidates.filter(([count]) => count > 0).map(([, label]) => label);
+    // If the file-count ceiling kicked in, say so plainly — a silent "scanned 25,000 files"
+    // on a 60k-file monorepo reads as "covered everything" when it didn't.
+    const cappedFiles = readCodeIndexManifest(projectDir).ignored_summary?.["exceeded_file_cap"] ?? 0;
+    if (cappedFiles > 0) {
+        const totalIndexable = graph.files.length + cappedFiles;
+        warnings.push(`Large repo: scanned ${graph.files.length.toLocaleString()} of ${totalIndexable.toLocaleString()} indexable files (capped). Set KAGE_MAX_SCAN_FILES higher to scan more.`);
+    }
     return {
         schema_version: 1,
         project_dir: projectDir,
@@ -11868,7 +12150,9 @@ function queryGraph(projectDir, query, limit = 10, graph) {
         const temporalPenalty = edge.invalidated_at ? -4 : 0;
         return { edge, score: textScore + graphScore + evidenceScore + temporalPenalty };
     })
-        .filter((entry) => entry.score > 0)
+        // Serialized transcript / tool-output / file-content dumps are capture noise, not
+        // facts. Keep them out of the graph context so one raw edge can't dominate the output.
+        .filter((entry) => entry.score > 0 && !isSerializedDumpBody(entry.edge.fact))
         .sort((a, b) => b.score - a.score || a.edge.fact.localeCompare(b.edge.fact))
         .slice(0, limit)
         .map((entry) => entry.edge);
@@ -11880,7 +12164,8 @@ function queryGraph(projectDir, query, limit = 10, graph) {
         `Query: ${query}`,
         "",
         edges.length ? "## Facts" : "No related graph facts found.",
-        ...edges.map((edge, index) => `${index + 1}. ${edge.fact}\n   Relation: ${edge.relation}\n   Evidence: ${edge.evidence.join(", ")}`),
+        // Clamp every field: a fact is a one-liner, never a document.
+        ...edges.map((edge, index) => `${index + 1}. ${clampInline(edge.fact)}\n   Relation: ${clampInline(edge.relation, 80)}\n   Evidence: ${clampInline(edge.evidence.join(", "), 200)}`),
     ];
     return {
         query,
@@ -13366,6 +13651,18 @@ function capture(input) {
     if (!exports.MEMORY_TYPES.includes(type)) {
         return { ok: false, errors: [`Invalid memory type: ${type}`] };
     }
+    // Reject raw transcript / serialized tool-output / file-content dumps at the source.
+    // This fires on EVERY capture path, not just strictCitations: the auto-distill /
+    // observation pipeline (distillSession) calls capture()/learn() without strictCitations,
+    // which is exactly how the 300KB dumps got in and then bloated recall and the graph.
+    // Title OR body trips it — a massaged title (e.g. a shell-prompt paste) won't sneak a
+    // dump past the title check. Recall + graph filtering is the safety net; this is the gate.
+    if (isSerializedDumpTitle(input.title) || isSerializedDumpBody(input.body)) {
+        return {
+            ok: false,
+            errors: ["Capture blocked: this looks like a raw transcript, serialized tool output, or file-content dump, not a durable learning. Summarize the insight in a short, human-readable title and a concise body."],
+        };
+    }
     const scanFindings = scanSensitiveText([input.title, input.summary ?? "", input.body].join("\n"));
     if (scanFindings.length) {
         return {
@@ -13880,14 +14177,7 @@ except Exception:
 print((d.get("prompt") or d.get("user_prompt") or d.get("message") or "")[:1000])
 ' 2>/dev/null || echo "")"
   if [[ -n "$QUERY" ]]; then
-    CONTEXT="$(kage recall "$QUERY" --project "$CWD" --json 2>/dev/null | python3 -c 'import json, sys
-try:
-    d = json.load(sys.stdin)
-except Exception:
-    d = {}
-text = d.get("context_block") or ""
-print(text[:6000] if d.get("results") else "")
-' 2>/dev/null || true)"
+    CONTEXT="$(kage prompt-context --project "$CWD" --query "$QUERY" 2>/dev/null || true)"
     if [[ -n "$CONTEXT" ]]; then
       KAGE_CONTEXT="$CONTEXT" python3 -c 'import json, os
 print(json.dumps({"additionalContext": os.environ.get("KAGE_CONTEXT", "")}))
@@ -14276,6 +14566,18 @@ function observe(projectDir, event) {
         summary: event.summary === undefined ? undefined : stripPrivateSpans(event.summary),
         command: event.command === undefined ? undefined : stripPrivateSpans(event.command),
     };
+    // Cap free-text fields so a giant pasted command or tool-output dump can't bloat the
+    // observation log (and the resume digest distilled from it). The gist is enough for
+    // distillation; the full payload is not durable memory.
+    const capObservationField = (value, max) => value === undefined ? undefined
+        : value.length > max ? `${value.slice(0, max).trimEnd()}… [+${value.length - max} chars truncated]`
+            : value;
+    event = {
+        ...event,
+        command: capObservationField(event.command, 600),
+        summary: capObservationField(event.summary, 600),
+        text: capObservationField(event.text, 4000),
+    };
     const allowed = ["session_start", "user_prompt", "tool_use", "tool_result", "file_change", "command_result", "test_result", "session_end"];
     if (!allowed.includes(event.type))
         return { ok: false, stored: false, duplicate: false, errors: [`Invalid observation type: ${event.type}`] };
@@ -14453,6 +14755,9 @@ function reusableFileObservation(event) {
     const text = `${event.summary ?? ""}\n${event.text ?? ""}`.trim();
     if (!text)
         return "";
+    // A captured file diff / file content blob is not a learning — skip it outright.
+    if (isSerializedDumpBody(text))
+        return "";
     const lower = text.toLowerCase();
     const generic = [
         "file changed",
@@ -14493,7 +14798,7 @@ function reusableFileObservation(event) {
         "bug",
         "test",
     ];
-    return durableSignals.some((signal) => lower.includes(signal)) ? text : "";
+    return durableSignals.some((signal) => lower.includes(signal)) ? clampInline(text, 1200) : "";
 }
 function normalizeCommandText(command) {
     return command.trim().replace(/\s+/g, " ").replace(/[).,;]+$/, "");
@@ -14513,6 +14818,9 @@ function reusableCommandObservation(event, knownCommands) {
     if (!command)
         return null;
     const summary = `${event.summary ?? ""}\n${event.text ?? ""}`.trim();
+    // A raw stdout/stderr dump is not a reusable command learning — skip it.
+    if (isSerializedDumpBody(summary))
+        return null;
     const lower = summary.toLowerCase();
     const known = knownCommands.has(command);
     const commandLooksUseful = /^(npm|pnpm|yarn|bun|npx|node|vitest|jest|pytest|cargo|go test|make|uv|ruff|mypy|tsc)\b/.test(command);
@@ -14542,13 +14850,16 @@ function reusableCommandObservation(event, knownCommands) {
         return null;
     if (!known && !hasDurableSignal && !hasSpecialArgs && event.exit_code === 0)
         return null;
-    const learning = summary || `Use ${command}.`;
+    const learning = clampInline(summary, 1200) || `Use ${command}.`;
     return { command, learning };
 }
 function reusablePromptObservation(event) {
     const text = `${event.summary ?? ""}\n${event.text ?? ""}`.trim();
     if (!text)
         return "";
+    // A pasted transcript / tool-notification block is not an intent learning — skip it.
+    if (isSerializedDumpBody(text))
+        return "";
     const lower = text.toLowerCase();
     const durableSignals = [
         "remember",
@@ -15166,11 +15477,16 @@ function kageResume(projectDir) {
                 block.push(...candidate);
         });
     }
+    // Lead the SessionStart injection with the team's pinned, always-on repo memory (the
+    // curated high-signal facts), not just the recent-timeline digest — parity with recall's
+    // context block, so a new session starts already holding the key knowledge, not only a
+    // usage policy.
+    const pinnedBlock = renderPinnedRepoContext(readContextSlots(projectDir));
     return {
         schema_version: 1,
         project_dir: projectDir,
         generated_at: nowIso(),
-        has_content: hasContent,
+        has_content: hasContent || Boolean(pinnedBlock),
         last_session: lastSession,
         last_change_memory: lastChangeMemory,
         pending_auto_distilled: pendingAutoDistilled,
@@ -15178,7 +15494,7 @@ function kageResume(projectDir) {
         ...(pendingAutoDistilled ? { review_command: `kage review --project ${projectDir}` } : {}),
         reconciliation: { unresolved_count: reconciliation.unresolved_count, items: reconciliationItems },
         recent_memory: recentMemory,
-        context_block: block.join("\n"),
+        context_block: [pinnedBlock, block.join("\n")].filter((part) => part && part.trim()).join("\n\n"),
     };
 }
 function createDiffChangeMemory(projectDir, summary) {
@@ -15220,7 +15536,9 @@ function createDiffChangeMemory(projectDir, summary) {
         "",
         "Diff summary:",
         "```text",
-        summary.diff_stat.trim(),
+        // Clamp the diff stat: a huge diff would otherwise produce a dump-sized change-memory
+        // body. This path builds the packet directly (not via capture()), so bound it here.
+        clampBlock(summary.diff_stat, 4000),
         "```",
         "",
         "How to verify:",
@@ -15895,7 +16213,8 @@ function recallFromPackets(query, packets, limit, label) {
             "",
             packet.summary,
             "",
-            packet.body,
+            // Diagnostic sample only — clamp the body so an oversized packet can't bloat output.
+            clampBlock(packet.body, 1500),
         ].join("\n");
     });
     return {
@@ -17093,6 +17412,15 @@ function capturePersonal(input) {
     if (!exports.MEMORY_TYPES.includes(type)) {
         return { ok: false, errors: [`Invalid memory type: ${type}`] };
     }
+    // Same dump guard as repo capture(): a raw transcript / tool-output / file-content dump
+    // is never a durable learning, and personal memory syncs to a remote, so junk here is
+    // worse, not better.
+    if (isSerializedDumpTitle(input.title) || isSerializedDumpBody(input.body)) {
+        return {
+            ok: false,
+            errors: ["Capture blocked: this looks like a raw transcript, serialized tool output, or file-content dump, not a durable learning. Summarize the insight in a short, human-readable title and a concise body."],
+        };
+    }
     // Personal memory syncs to a remote, so the secret scan matters MORE here, not less.
     const scanFindings = scanSensitiveText([input.title, input.summary ?? "", input.body].join("\n"));
     if (scanFindings.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.3.3",
+  "version": "2.5.0",
   "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,8 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "ts-node index.ts",
-    "test": "npm run build && node --test dist/**/*.test.js"
+    "test": "npm run build && node --test dist/**/*.test.js && npm run test:dogfood",
+    "test:dogfood": "node --test ../evals/agent-trajectory/replay.test.mjs"
   },
   "keywords": [
     "mcp",