npm - @kage-core/kage-graph-mcp - Versions diffs - 1.1.38 → 1.2.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/dist/cli.js CHANGED Viewed

@@ -29,6 +29,8 @@ Usage:
   kage hook uninstall --project <dir> [--json]
   kage refresh --project <dir> [--full] [--json]
   kage gc --project <dir> [--dry-run] [--force] [--json]
+  kage compact --project <dir> [--dry-run] [--json]
+  kage verify --project <dir> [--id <packet-id>] [--json]
   kage pr summarize --project <dir> [--json]
   kage pr check --project <dir> [--json]
   kage upgrade [--dry-run]
@@ -74,14 +76,14 @@ Usage:
   kage graph "<query>" --project <dir> [--json]
   kage graph-registry --project <dir> [--json]
   kage embeddings build --project <dir> [--model Xenova/all-MiniLM-L6-v2] [--json]
-  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings]
+  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--max-context-tokens <n>] [--structural-hops <n>]
   kage observe --project <dir> --event <json>
   kage sessions --project <dir> [--json]
   kage replay --project <dir> [--session <id>] [--limit <n>] [--json]
   kage distill --project <dir> --session <id>
-  kage learn --project <dir> --learning <text> [--title <title>] [--type <type>] [--evidence <text>] [--verified-by <text>] [--tags a,b] [--paths a,b]
+  kage learn --project <dir> --learning <text> [--title <title>] [--type <type>] [--evidence <text>] [--verified-by <text>] [--tags a,b] [--paths a,b] [--graph-nodes a,b] [--allow-missing-paths]
   kage feedback --project <dir> --packet <packet-id> --kind helpful|wrong|stale
-  kage capture --project <dir> --title <title> --body <body> [--type <type>] [--summary <summary>] [--tags a,b] [--paths a,b] [--stack a,b]
+  kage capture --project <dir> --title <title> --body <body> [--type <type>] [--summary <summary>] [--tags a,b] [--paths a,b] [--stack a,b] [--graph-nodes a,b] [--allow-missing-paths]
   kage propose --project <dir> --from-diff
   kage review-artifact --project <dir>
   kage promote --project <dir> --public <packet-id>
@@ -404,6 +406,65 @@ async function main() {
         }
         return;
     }
+    if (command === "compact") {
+        const project = projectArg(args);
+        const dryRun = args.includes("--dry-run");
+        const result = (0, kernel_js_1.compactProject)(project, { dryRun });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const label = dryRun ? " [dry-run]" : "";
+        console.log(`Kage compact${label} — scanned ${result.total_scanned} packets`);
+        if (result.pruned_citations.length) {
+            console.log(`\nPruned dead citations (${result.pruned_citations.length}):`);
+            for (const p of result.pruned_citations)
+                console.log(`  ✂  ${p.title} — removed ${p.removed_paths.join(", ")}`);
+        }
+        if (result.deprecated.length) {
+            console.log(`\nDeprecated stale (${result.deprecated.length}):`);
+            for (const p of result.deprecated)
+                console.log(`  ✗ ${p.title} — ${p.reason}`);
+        }
+        if (result.duplicate_clusters.length) {
+            console.log(`\nDuplicate clusters to merge (${result.duplicate_clusters.length}) — review with kage_compact / kage supersede:`);
+            for (const cluster of result.duplicate_clusters) {
+                console.log(`  ~${cluster.score} similarity:`);
+                for (const member of cluster.packets)
+                    console.log(`     • ${member.title} (${member.id})`);
+            }
+        }
+        if (!result.pruned_citations.length && !result.deprecated.length && !result.duplicate_clusters.length) {
+            console.log("Nothing to compact — memory is clean.");
+        }
+        return;
+    }
+    if (command === "verify") {
+        const project = projectArg(args);
+        const idFlag = args.indexOf("--id");
+        const id = idFlag >= 0 ? args[idFlag + 1] : undefined;
+        const result = (0, kernel_js_1.verifyCitations)(project, { id });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        if (!result.ok) {
+            console.log(`Verification failed:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            process.exit(2);
+        }
+        console.log(`Kage verify — ${result.checked} packet(s): ${result.valid} valid, ${result.stale} stale, ${result.ungrounded} ungrounded`);
+        for (const entry of result.packets.filter((p) => p.stale || !p.grounded)) {
+            const flags = [entry.stale ? `stale:${entry.stale_severity}` : "", entry.grounded ? "" : "ungrounded"].filter(Boolean).join(", ");
+            console.log(`  ⚠ ${entry.title} [${flags}]`);
+            if (entry.missing_paths.length)
+                console.log(`      missing: ${entry.missing_paths.join(", ")}`);
+            for (const reason of entry.stale_reasons)
+                console.log(`      - ${reason}`);
+        }
+        return;
+    }
     if (command === "refresh") {
         const result = (0, kernel_js_1.refreshProject)(projectArg(args), { full: args.includes("--full") });
         if (args.includes("--json")) {
@@ -1377,12 +1438,17 @@ async function main() {
             tags: listArg(takeArg(args, "--tags")),
             paths: listArg(takeArg(args, "--paths")),
             stack: listArg(takeArg(args, "--stack")),
+            graphNodes: listArg(takeArg(args, "--graph-nodes")),
+            allowMissingPaths: args.includes("--allow-missing-paths"),
+            strictCitations: true,
         });
         if (!result.ok) {
             console.error(`Learning capture blocked:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
             process.exit(2);
         }
         console.log(`Captured session learning: ${result.path}`);
+        if (result.warnings?.length)
+            console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
         return;
     }
@@ -1565,9 +1631,11 @@ async function main() {
         const query = firstPositional(args);
         if (!query)
             usage();
+        const maxContextTokens = args.includes("--max-context-tokens") ? numberArg(args, "--max-context-tokens", 0) : undefined;
+        const structuralHops = args.includes("--structural-hops") ? numberArg(args, "--structural-hops", 2) : undefined;
         const result = args.includes("--embeddings")
             ? await (0, kernel_js_1.recallWithEmbeddings)(projectArg(args), query, 5, args.includes("--explain"))
-            : (0, kernel_js_1.recall)(projectArg(args), query, 5, args.includes("--explain"));
+            : (0, kernel_js_1.recall)(projectArg(args), query, 5, args.includes("--explain"), { maxContextTokens, structuralHops });
         if (args.includes("--json"))
             console.log(JSON.stringify(result, null, 2));
         else
@@ -1711,6 +1779,9 @@ async function main() {
             tags: listArg(takeArg(args, "--tags")),
             paths: listArg(takeArg(args, "--paths")),
             stack: listArg(takeArg(args, "--stack")),
+            graphNodes: listArg(takeArg(args, "--graph-nodes")),
+            allowMissingPaths: args.includes("--allow-missing-paths"),
+            strictCitations: true,
         };
         const result = (0, kernel_js_1.capture)(input);
         if (!result.ok) {
@@ -1718,6 +1789,8 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured repo-local packet: ${result.path}`);
+        if (result.warnings?.length)
+            console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
         return;
     }

package/dist/index.js CHANGED Viewed

@@ -152,6 +152,8 @@ function listTools() {
                     explain: { type: "boolean" },
                     embeddings: { type: "boolean" },
                     json: { type: "boolean" },
+                    max_context_tokens: { type: "number" },
+                    structural_hops: { type: "number", description: "If >0, append a bounded N-hop code-graph blast radius seeded from the recalled memory's files." },
                 },
                 required: ["query", "project_dir"],
             },
@@ -668,7 +670,7 @@ function listTools() {
         },
         {
             name: "kage_learn",
-            description: "Capture an actual reusable learning from the current session as repo-local memory. Prefer this over diff proposal when the agent knows what was learned.",
+            description: "Capture an actual reusable learning from the current session as repo-local memory. Prefer this over diff proposal when the agent knows what was learned. Capture is rejected if every referenced path is missing from the repo; set allow_missing_paths to record anyway (e.g. a file you are about to create).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -681,13 +683,15 @@ function listTools() {
                     tags: { type: "array", items: { type: "string" } },
                     paths: { type: "array", items: { type: "string" } },
                     stack: { type: "array", items: { type: "string" } },
+                    graph_nodes: { type: "array", items: { type: "string" } },
+                    allow_missing_paths: { type: "boolean" },
                 },
                 required: ["project_dir", "learning"],
             },
         },
         {
             name: "kage_capture",
-            description: "Create a repo-local Kage memory packet immediately. Org/global promotion still requires explicit human review.",
+            description: "Create a repo-local Kage memory packet immediately. Org/global promotion still requires explicit human review. Capture is rejected if every referenced path is missing from the repo; set allow_missing_paths to record anyway.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -699,10 +703,36 @@ function listTools() {
                     tags: { type: "array", items: { type: "string" } },
                     paths: { type: "array", items: { type: "string" } },
                     stack: { type: "array", items: { type: "string" } },
+                    graph_nodes: { type: "array", items: { type: "string" }, description: "Code-graph node references (symbol/route/file) this memory is about." },
+                    allow_missing_paths: { type: "boolean" },
                 },
                 required: ["project_dir", "title", "body"],
             },
         },
+        {
+            name: "kage_verify_citations",
+            description: "Verify that a memory packet's cited file paths still exist and that the memory is not stale, before trusting it. Pass an id to check one packet, or omit to audit all approved repo memory. Returns grounding and staleness for each.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    id: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_compact",
+            description: "Consolidate repo memory: prune dead citations, deprecate hard-stale packets, and surface near-duplicate clusters to merge (via kage_supersede). Defaults to a dry run; pass dry_run=false to apply pruning/deprecation. Duplicate merging stays an agent decision — no hosted LLM is used.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    dry_run: { type: "boolean" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_observe",
             description: "Store an automatic local observation event from an agent session. Observations are privacy-scanned, deduplicated, and never published automatically.",
@@ -1092,9 +1122,11 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_recall") {
+        const maxContextTokens = typeof args?.max_context_tokens === "number" ? args.max_context_tokens : undefined;
+        const structuralHops = typeof args?.structural_hops === "number" ? args.structural_hops : undefined;
         const result = args?.embeddings
             ? await (0, kernel_js_1.recallWithEmbeddings)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain))
-            : (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain));
+            : (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain), { maxContextTokens, structuralHops });
         return {
             content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : result.context_block }],
         };
@@ -1403,13 +1435,17 @@ async function callTool(name, args) {
             tags: arrayArg(args?.tags),
             paths: arrayArg(args?.paths),
             stack: arrayArg(args?.stack),
+            graphNodes: arrayArg(args?.graph_nodes),
+            allowMissingPaths: Boolean(args?.allow_missing_paths),
+            strictCitations: true,
         });
+        const learnWarnings = result.warnings?.length ? `\nWarnings:\n${result.warnings.map((warning) => `- ${warning}`).join("\n")}` : "";
         return {
             content: [
                 {
                     type: "text",
                     text: result.ok
-                        ? `Captured session learning: ${result.path}\nRepo-local memory is written immediately. Org/global promotion still requires explicit review.`
+                        ? `Captured session learning: ${result.path}\nRepo-local memory is written immediately. Org/global promotion still requires explicit review.${learnWarnings}`
                         : `Learning capture blocked:\n${result.errors.map((error) => `- ${error}`).join("\n")}`,
                 },
             ],
@@ -1426,19 +1462,41 @@ async function callTool(name, args) {
             tags: arrayArg(args?.tags),
             paths: arrayArg(args?.paths),
             stack: arrayArg(args?.stack),
+            graphNodes: arrayArg(args?.graph_nodes),
+            allowMissingPaths: Boolean(args?.allow_missing_paths),
+            strictCitations: true,
         });
+        const captureWarnings = result.warnings?.length ? `\nWarnings:\n${result.warnings.map((warning) => `- ${warning}`).join("\n")}` : "";
         return {
             content: [
                 {
                     type: "text",
                     text: result.ok
-                        ? `Captured repo-local packet: ${result.path}\nOrg/global promotion still requires explicit review.`
+                        ? `Captured repo-local packet: ${result.path}\nOrg/global promotion still requires explicit review.${captureWarnings}`
                         : `Capture blocked:\n${result.errors.map((error) => `- ${error}`).join("\n")}`,
                 },
             ],
             isError: !result.ok,
         };
     }
+    if (name === "kage_verify_citations") {
+        const result = (0, kernel_js_1.verifyCitations)(String(args?.project_dir ?? ""), {
+            id: args?.id ? String(args.id) : undefined,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
+    if (name === "kage_compact") {
+        const result = (0, kernel_js_1.compactProject)(String(args?.project_dir ?? ""), {
+            dryRun: args?.dry_run === undefined ? true : Boolean(args.dry_run),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
     if (name === "kage_observe") {
         const projectDir = String(args?.project_dir ?? "");
         const event = { ...args };

package/dist/kernel.js CHANGED Viewed

@@ -83,6 +83,8 @@ exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
 exports.gcProject = gcProject;
+exports.verifyCitations = verifyCitations;
+exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
@@ -180,6 +182,27 @@ exports.MEMORY_TYPES = [
     "negative_result",
     "constraint",
 ];
+// Bounded context assembly (PRD Feature 2: "inject only the relevant rule + structural
+// map, dropping the rest"). Opt-in: when a token budget is set, keep the highest-priority
+// sections (preamble + code graph + memory come first in the block) and drop trailing
+// lower-priority sections until the estimate fits. Default (no budget) is unchanged.
+function boundContextBlock(block, budget) {
+    if (!Number.isFinite(budget) || budget <= 0 || estimateTokens(block) <= budget)
+        return block;
+    const parts = block.split(/\n(?=## )/);
+    const kept = [parts[0]];
+    let dropped = 0;
+    for (const section of parts.slice(1)) {
+        if (estimateTokens([...kept, section].join("\n")) <= budget)
+            kept.push(section);
+        else
+            dropped += 1;
+    }
+    const result = kept.join("\n");
+    return dropped
+        ? `${result}\n\n_Context trimmed to ~${budget} tokens; ${dropped} lower-priority section(s) dropped._`
+        : result;
+}
 const graphMemoryCache = new Map();
 exports.SETUP_AGENTS = [
     "codex",
@@ -1119,6 +1142,52 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     }
     return unique(reasons);
 }
+// Classifies stale reasons into severity. "hard" reasons (deprecated status, user
+// reported stale, ttl expired, all citations deleted) mean the memory should be
+// excluded from recall; "soft" reasons (some citations missing, a linked file
+// changed) mean keep-but-flag — the memory may just need review, not suppression.
+function staleSeverity(reasons) {
+    if (!reasons.length)
+        return "none";
+    const hard = reasons.some((reason) => reason.startsWith("packet status is") ||
+        reason.startsWith("user or agent reported") ||
+        reason.startsWith("freshness ttl expired") ||
+        reason.startsWith("all referenced paths are missing"));
+    return hard ? "hard" : "soft";
+}
+// Decides whether a packet should be excluded from the recall payload (PRD Feature 3:
+// "deleted or heavily refactored since the timestamp"). Distinct from staleMemoryReasons:
+// a citation that NEVER existed (no stored fingerprint) is an ungrounded write — guarded
+// at capture time — not recall-time staleness, so it does NOT trigger exclusion here.
+// Returns a reason string when the memory is hard-stale, otherwise null.
+function recallHardStaleReason(projectDir, packet, cache) {
+    if (packet.status === "deprecated" || packet.status === "superseded")
+        return `packet status is ${packet.status}`;
+    const quality = (packet.quality ?? {});
+    if (Number(quality.reports_stale ?? 0) > 0)
+        return "user or agent reported this memory stale";
+    const freshness = (packet.freshness ?? {});
+    const ttlDays = Number(freshness.ttl_days ?? freshness.ttlDays ?? 0);
+    const verifiedAt = Date.parse(String(freshness.last_verified_at ?? packet.updated_at ?? packet.created_at));
+    if (Number.isFinite(ttlDays) && ttlDays > 0 && Number.isFinite(verifiedAt)) {
+        const ageDays = (Date.now() - verifiedAt) / (1000 * 60 * 60 * 24);
+        if (ageDays > ttlDays)
+            return `freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`;
+    }
+    // Only paths that existed at capture get a stored fingerprint; if every one of them is
+    // now gone, the memory's evidence was deleted out from under it.
+    const stored = packetStoredPathFingerprints(packet);
+    if (stored.length) {
+        const deleted = stored.filter((fingerprint) => {
+            const current = memoryPathFingerprint(projectDir, fingerprint.path, cache);
+            return current === null;
+        });
+        if (deleted.length === stored.length) {
+            return `all cited files deleted since capture: ${deleted.slice(0, 4).map((fingerprint) => fingerprint.path).join(", ")}`;
+        }
+    }
+    return null;
+}
 function changedPathsFromStaleReasons(reasons) {
     return unique(reasons.flatMap((reason) => {
         const match = reason.match(/^linked path changed since memory was verified: (.+)$/);
@@ -1523,13 +1592,28 @@ function walkFiles(root, predicate) {
     }
     return out.sort();
 }
+// Tolerant packet read: a single corrupt or merge-conflicted packet (e.g. an
+// unresolved `<<<<<<<` from a teammate's git merge) must not take down all of
+// recall/verify/compact. Skip the bad file with a warning and keep going.
+function tryReadPacket(path) {
+    try {
+        return readJson(path);
+    }
+    catch (error) {
+        process.stderr.write(`kage: skipping unreadable memory packet ${path}: ${error.message}\n`);
+        return null;
+    }
+}
 function loadPacketsFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return [];
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => readJson((0, node_path_1.join)(dir, name)));
+        .flatMap((name) => {
+        const packet = tryReadPacket((0, node_path_1.join)(dir, name));
+        return packet ? [packet] : [];
+    });
 }
 function loadPacketEntriesFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
@@ -1537,9 +1621,10 @@ function loadPacketEntriesFromDir(dir) {
     return (0, node_fs_1.readdirSync)(dir)
         .filter((name) => name.endsWith(".json"))
         .sort()
-        .map((name) => {
+        .flatMap((name) => {
         const path = (0, node_path_1.join)(dir, name);
-        return { path, packet: readJson(path) };
+        const packet = tryReadPacket(path);
+        return packet ? [{ path, packet }] : [];
     });
 }
 function loadApprovedPackets(projectDir) {
@@ -5510,6 +5595,115 @@ 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.
+function verifyCitations(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const targets = options.id ? approved.filter((packet) => packet.id === options.id) : approved;
+    if (options.id && !targets.length) {
+        return { ok: false, project_dir: projectDir, checked: 0, valid: 0, stale: 0, ungrounded: 0, packets: [], errors: [`Approved packet not found: ${options.id}`] };
+    }
+    const cache = new Map();
+    const packets = targets.map((packet) => {
+        const meaningful = packet.paths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+        const missing = meaningful.filter((path) => !pathExistsInRepo(projectDir, path));
+        const reasons = staleMemoryReasons(projectDir, packet, cache);
+        const severity = staleSeverity(reasons);
+        const grounded = packetGroundingWarnings(projectDir, packet, "packet").length === 0;
+        return {
+            id: packet.id,
+            title: packet.title,
+            status: packet.status,
+            paths: packet.paths,
+            missing_paths: missing,
+            grounded,
+            stale: severity !== "none",
+            stale_severity: severity,
+            stale_reasons: reasons,
+        };
+    });
+    return {
+        ok: true,
+        project_dir: projectDir,
+        checked: packets.length,
+        valid: packets.filter((entry) => !entry.stale && entry.grounded).length,
+        stale: packets.filter((entry) => entry.stale).length,
+        ungrounded: packets.filter((entry) => !entry.grounded).length,
+        packets,
+        errors: [],
+    };
+}
+// Deterministic memory consolidation (no hosted LLM — preserves the no-API-key promise):
+//  1. prune dead citations from packets and refresh their path fingerprints,
+//  2. deprecate hard-stale packets (delegating to the same severity rules as recall/gc),
+//  3. surface near-duplicate clusters for an agent to merge via kage_supersede.
+function compactProject(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const dryRun = options.dryRun === true;
+    const entries = loadPacketEntriesFromDir(packetsDir(projectDir));
+    const prunedCitations = [];
+    const deprecated = [];
+    const cache = new Map();
+    for (const { path, packet } of entries) {
+        if (packet.status === "deprecated" || packet.status === "superseded")
+            continue;
+        const hardReason = recallHardStaleReason(projectDir, packet, cache);
+        if (hardReason) {
+            deprecated.push({ id: packet.id, title: packet.title, reason: hardReason });
+            if (!dryRun)
+                writeJson(path, { ...packet, status: "deprecated", updated_at: nowIso() });
+            continue;
+        }
+        const meaningful = packet.paths.filter((p) => meaningfulMemoryPath(p) && !shouldSkipRepoMemoryPath(p));
+        const missing = meaningful.filter((p) => !pathExistsInRepo(projectDir, p));
+        if (missing.length) {
+            const keptPaths = packet.paths.filter((p) => !missing.includes(p));
+            prunedCitations.push({ id: packet.id, title: packet.title, removed_paths: missing });
+            if (!dryRun) {
+                writeJson(path, {
+                    ...packet,
+                    paths: keptPaths,
+                    freshness: {
+                        ...(packet.freshness ?? {}),
+                        path_fingerprints: memoryPathFingerprints(projectDir, keptPaths),
+                        last_verified_at: nowIso(),
+                    },
+                    updated_at: nowIso(),
+                });
+            }
+        }
+    }
+    // Cluster near-duplicate approved packets (report only — merging is an agent decision).
+    const context = memoryQualityContext(projectDir);
+    const approved = context.packets.filter((packet) => packet.status === "approved");
+    const seen = new Set();
+    const clusters = [];
+    for (const packet of approved) {
+        if (seen.has(packet.id))
+            continue;
+        const dupes = duplicateCandidatesWithContext(packet, context, 0.6).filter((dupe) => dupe.status === "approved");
+        if (!dupes.length)
+            continue;
+        const members = [{ id: packet.id, title: packet.title }, ...dupes.map((dupe) => ({ id: dupe.id, title: dupe.title }))];
+        members.forEach((member) => seen.add(member.id));
+        clusters.push({ score: Math.max(...dupes.map((dupe) => dupe.score)), packets: members });
+    }
+    if (!dryRun && (prunedCitations.length || deprecated.length)) {
+        const rebuilt = buildGraphIndexes(projectDir);
+        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetricsShallow(projectDir, rebuilt));
+    }
+    return {
+        ok: true,
+        project_dir: projectDir,
+        dry_run: dryRun,
+        pruned_citations: prunedCitations,
+        deprecated,
+        duplicate_clusters: clusters,
+        total_scanned: entries.length,
+        errors: [],
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");
@@ -6277,7 +6471,23 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         })()
         : recallQueryExpansion(query);
     const terms = expansion.terms;
-    const approvedPackets = loadApprovedPackets(projectDir);
+    const allApprovedPackets = loadApprovedPackets(projectDir);
+    const includeStale = inputs.includeStale === true;
+    const staleFingerprintCache = new Map();
+    const suppressed = [];
+    // Just-in-time staleness gate: hard-stale memory (deleted citations, expired ttl,
+    // reported stale) is excluded from the recall payload so the agent never sees it
+    // as valid. Suppression is recorded (not silent) so `kage verify` can explain it.
+    const approvedPackets = includeStale
+        ? allApprovedPackets
+        : allApprovedPackets.filter((packet) => {
+            const reason = recallHardStaleReason(projectDir, packet, staleFingerprintCache);
+            if (reason) {
+                suppressed.push({ id: packet.id, title: packet.title, reason });
+                return false;
+            }
+            return true;
+        });
     const baseScores = scorePacketsBm25(expansion.baseTerms, approvedPackets);
     const temporalScores = scorePacketsBm25(expansion.temporalTerms, approvedPackets);
     const semanticScores = scorePacketsBm25(expansion.semanticTerms, approvedPackets);
@@ -6335,6 +6545,13 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
     const graphContext = queryGraph(projectDir, query, 5, knowledgeGraph);
     const codeContext = queryCodeGraph(projectDir, query, 5, codeGraph);
     const pinnedContext = renderPinnedRepoContext(readContextSlots(projectDir));
+    // PRD Feature 2: traverse the code graph outward from the recalled memory's files
+    // (the semantic entry point) to assemble a bounded structural blast radius. Opt-in
+    // via inputs.structuralHops so default recall output is unchanged.
+    const structuralHops = inputs.structuralHops ?? 0;
+    const blastRadius = structuralHops > 0
+        ? structuralBlastRadius(codeGraph, unique(scored.flatMap((entry) => entry.packet.paths).filter((path) => meaningfulMemoryPath(path))), structuralHops)
+        : [];
     const lines = [
         `# Kage Context`,
         "",
@@ -6347,6 +6564,9 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ...codeContext.tests.slice(0, 3).map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
         ...(!codeContext.symbols.length && !codeContext.routes.length && !codeContext.tests.length ? codeContext.files.slice(0, 3).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind})`) : []),
         "",
+        ...(blastRadius.length
+            ? [`## Structural Blast Radius (${structuralHops}-hop)`, ...blastRadius.map((path, index) => `${index + 1}. ${path}`), ""]
+            : []),
         scored.length ? "## Relevant Memory" : "No relevant repo memory found.",
         ...scored.flatMap((entry, index) => [
             "",
@@ -6367,11 +6587,16 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         "",
         graphContext.edges.length ? "## Related Graph Facts" : "",
         ...graphContext.edges.slice(0, 5).map((edge, index) => `${index + 1}. ${edge.fact} (evidence: ${edge.evidence.join(", ")})`),
+        ...(suppressed.length
+            ? ["", `_${suppressed.length} stale memory packet(s) excluded from recall. Run kage verify for details._`]
+            : []),
     ];
+    const assembledBlock = lines.join("\n");
     const result = {
         query,
-        context_block: lines.join("\n"),
+        context_block: inputs.maxContextTokens ? boundContextBlock(assembledBlock, inputs.maxContextTokens) : assembledBlock,
         results: scored,
+        suppressed: suppressed.length ? suppressed : undefined,
         explanations: explain
             ? scored.map((entry) => ({
                 packet_id: entry.packet.id,
@@ -6830,6 +7055,45 @@ function codeDependents(graph) {
     }
     return dependents;
 }
+// Bounded N-hop structural traversal from a set of seed files (the files the recalled
+// memory is about) — the PRD's "structural blast radius". Walks both import directions
+// (who-depends-on and what-it-depends-on), excludes the seeds, and ranks by how many
+// files depend on each node. Pure graph traversal; no full-repo scan.
+function structuralBlastRadius(graph, seedPaths, hops, limit = 8) {
+    const seeds = seedPaths.filter(Boolean);
+    if (!seeds.length || hops <= 0)
+        return [];
+    const dependents = codeDependents(graph);
+    const dependencies = new Map();
+    for (const edge of graph.imports) {
+        if (!edge.from_path || !edge.to_path)
+            continue;
+        const list = dependencies.get(edge.from_path) ?? new Set();
+        list.add(edge.to_path);
+        dependencies.set(edge.from_path, list);
+    }
+    const seedSet = new Set(seeds);
+    const visited = new Set();
+    let frontier = new Set(seeds);
+    for (let depth = 0; depth < hops; depth += 1) {
+        const next = new Set();
+        for (const node of frontier) {
+            for (const neighbor of [...(dependents.get(node) ?? []), ...(dependencies.get(node) ?? [])]) {
+                if (seedSet.has(neighbor) || visited.has(neighbor))
+                    continue;
+                visited.add(neighbor);
+                next.add(neighbor);
+            }
+        }
+        frontier = next;
+    }
+    const score = new Map();
+    for (const [path, incoming] of dependents.entries())
+        score.set(path, incoming.size);
+    return [...visited]
+        .sort((a, b) => (score.get(b) ?? 0) - (score.get(a) ?? 0) || a.localeCompare(b))
+        .slice(0, limit);
+}
 function impactSurface(target, dependents, graph) {
     const visited = new Set();
     let frontier = new Set([target]);
@@ -10453,6 +10717,9 @@ function learn(input) {
         paths: input.paths,
         stack: input.stack,
         context: input.context,
+        allowMissingPaths: input.allowMissingPaths,
+        strictCitations: input.strictCitations,
+        graphNodes: input.graphNodes,
     });
 }
 function capture(input) {
@@ -10468,7 +10735,34 @@ function capture(input) {
             errors: [`Sensitive content blocked: ${unique(scanFindings).join(", ")}`],
         };
     }
+    const warnings = [];
+    const meaningfulPaths = (input.paths ?? [])
+        .filter((path) => path && meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(input.projectDir, path));
+    // Citation validation. Strict mode (agent-facing record_memory tools / CLI) rejects a
+    // write whose every cited path is missing — the PRD's "reject if citations don't exist".
+    // The core library stays permissive (warn-only) for programmatic callers and migrations.
+    if (input.strictCitations && meaningfulPaths.length && missingPaths.length === meaningfulPaths.length && !input.allowMissingPaths) {
+        return {
+            ok: false,
+            errors: [
+                `Citation validation failed: none of the referenced paths exist in this repo: ${missingPaths.join(", ")}. ` +
+                    `Fix the paths, or pass allow_missing_paths to record anyway (e.g. for a file you are about to create).`,
+            ],
+            warnings: [],
+        };
+    }
+    if (missingPaths.length) {
+        warnings.push(`Some referenced paths do not exist in this repo: ${missingPaths.join(", ")}`);
+    }
     const createdAt = nowIso();
+    // Agent-asserted links to code-graph nodes (PRD `graph_nodes`): the agent recording the
+    // memory knows which symbol/route/file the rule is about, so let it declare them instead
+    // of relying solely on background derivation.
+    const graphEdges = unique(input.graphNodes ?? [])
+        .map((node) => node.trim())
+        .filter(Boolean)
+        .map((node) => ({ relation: "references_code", to: node, evidence: "agent_capture", created_at: createdAt }));
     const packet = {
         schema_version: exports.PACKET_SCHEMA_VERSION,
         id: makePacketId(input.projectDir, type, input.title, String(Date.now())),
@@ -10510,10 +10804,12 @@ function capture(input) {
         },
         created_at: createdAt,
         updated_at: createdAt,
+        author_branch: gitBranch(input.projectDir),
     };
+    packet.edges = graphEdges;
     const validation = validatePacket(packet);
     if (!validation.ok)
-        return { ok: false, errors: validation.errors };
+        return { ok: false, errors: validation.errors, warnings };
     packet.quality = {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
@@ -10525,7 +10821,7 @@ function capture(input) {
         path: (0, node_path_1.relative)(input.projectDir, path),
         source_kind: packet.source_refs[0]?.kind ?? "explicit_capture",
     });
-    return { ok: true, packet, path, errors: [] };
+    return { ok: true, packet, path, errors: [], warnings };
 }
 function createPublicCandidate(projectDir, id) {
     ensureMemoryDirs(projectDir);
@@ -12110,12 +12406,65 @@ function regexpEscape(value) {
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\"'\"'")}'`;
 }
-function gitHookPath(projectDir) {
-    const raw = readGit(projectDir, ["rev-parse", "--git-path", "hooks/post-commit"]);
+function gitHookPath(projectDir, hookName = "post-commit") {
+    const raw = readGit(projectDir, ["rev-parse", "--git-path", `hooks/${hookName}`]);
     if (!raw)
         return null;
     return (0, node_path_1.resolve)(projectDir, raw);
 }
+// Hooks that fire after history changes underfoot (git pull / merge / checkout):
+// re-index repo memory so newly pulled teammate packets are immediately recallable.
+const KAGE_SYNC_HOOKS = ["post-merge", "post-checkout"];
+function kageSyncHookBlock(projectDir) {
+    const project = shellQuote((0, node_path_1.resolve)(projectDir));
+    return [
+        KAGE_POST_COMMIT_HOOK_START,
+        "# Kage sync hook: re-index repo memory after pull/merge/checkout.",
+        "# Set KAGE_SKIP_HOOK=1 to bypass, or KAGE_BIN=/path/to/kage to override.",
+        "if [ \"${KAGE_SKIP_HOOK:-0}\" != \"1\" ]; then",
+        "  KAGE_BIN=\"${KAGE_BIN:-kage}\"",
+        "  if command -v \"$KAGE_BIN\" >/dev/null 2>&1; then",
+        "    (",
+        `      "$KAGE_BIN" index --project ${project} --json >/dev/null 2>&1 || true`,
+        "    ) &",
+        "  fi",
+        "fi",
+        KAGE_POST_COMMIT_HOOK_END,
+    ].join("\n");
+}
+function installSyncHooks(projectDir) {
+    const installed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        ensureDir((0, node_path_1.dirname)(hookPath));
+        const existing = safeReadText(hookPath) ?? "";
+        const base = stripKageHookBlock(existing);
+        const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
+        const next = `${prefix}\n\n${kageSyncHookBlock(projectDir)}\n`;
+        if (existing !== next)
+            (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        installed.push(hookPath);
+    }
+    return installed;
+}
+function uninstallSyncHooks(projectDir) {
+    const removed = [];
+    for (const hookName of KAGE_SYNC_HOOKS) {
+        const hookPath = gitHookPath(projectDir, hookName);
+        if (!hookPath)
+            continue;
+        const existing = safeReadText(hookPath) ?? "";
+        if (!hasKageHookBlock(existing))
+            continue;
+        (0, node_fs_1.writeFileSync)(hookPath, stripKageHookBlock(existing), "utf8");
+        (0, node_fs_1.chmodSync)(hookPath, 0o755);
+        removed.push(hookPath);
+    }
+    return removed;
+}
 function hasKageHookBlock(content) {
     return content.includes(KAGE_POST_COMMIT_HOOK_START) && content.includes(KAGE_POST_COMMIT_HOOK_END);
 }
@@ -12191,20 +12540,24 @@ function kageHookInstall(projectDir) {
     const base = stripKageHookBlock(existing);
     const prefix = base.trim() ? base.trimEnd() : "#!/bin/sh";
     const next = `${prefix}\n\n${kagePostCommitHookBlock(projectDir)}\n`;
-    const changed = existing !== next;
-    if (changed)
+    const commitChanged = existing !== next;
+    if (commitChanged)
         (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const syncHooks = installSyncHooks(projectDir);
     return {
         ok: true,
         action: "install",
         project_dir: projectDir,
         hook_path: hookPath,
         installed: true,
-        changed,
-        message: changed ? "Installed Kage post-commit hook." : "Kage post-commit hook is already current.",
+        changed: commitChanged,
+        message: commitChanged
+            ? "Installed Kage post-commit hook and pull/merge sync hooks."
+            : "Kage post-commit and sync hooks are already current.",
         errors: [],
         warnings: [],
+        additional_hooks: syncHooks,
     };
 }
 function kageHookUninstall(projectDir) {
@@ -12240,6 +12593,7 @@ function kageHookUninstall(projectDir) {
     const next = stripKageHookBlock(existing);
     (0, node_fs_1.writeFileSync)(hookPath, next, "utf8");
     (0, node_fs_1.chmodSync)(hookPath, 0o755);
+    const removedSyncHooks = uninstallSyncHooks(projectDir);
     return {
         ok: true,
         action: "uninstall",
@@ -12247,9 +12601,10 @@ function kageHookUninstall(projectDir) {
         hook_path: hookPath,
         installed: false,
         changed: true,
-        message: "Removed Kage post-commit hook.",
+        message: "Removed Kage post-commit and sync hooks.",
         errors: [],
         warnings: [],
+        additional_hooks: removedSyncHooks,
     };
 }
 function exportPublicBundle(projectDir) {

package/package.json CHANGED Viewed

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