@kage-core/kage-graph-mcp 1.1.2 → 1.1.4

package/README.md

@@ -27,6 +27,7 @@ kage init --project /path/to/repo
 kage policy --project /path/to/repo
 kage doctor --project /path/to/repo
 kage index --project /path/to/repo
+kage refresh --project /path/to/repo
 kage branch --project /path/to/repo
 kage code-graph --project /path/to/repo
 kage code-graph "createApp routes tests" --project /path/to/repo
@@ -45,6 +46,8 @@ kage learn --project /path/to/repo --learning "Decision: use kage_learn for actu
 kage feedback --project /path/to/repo --packet <approved-packet-id> --kind stale
 kage capture --project /path/to/repo --type runbook --title "Webhook tests" --body "Run pnpm test:api -- webhooks."
 kage propose --project /path/to/repo --from-diff
+kage pr summarize --project /path/to/repo
+kage pr check --project /path/to/repo
 kage review-artifact --project /path/to/repo
 kage registry --project /path/to/repo
 kage marketplace --project /path/to/repo
@@ -57,6 +60,7 @@ kage layered-recall "how do I run tests" --project /path/to/repo --org acme --gl
 kage global build --project /path/to/repo --org acme
 kage review --project /path/to/repo
 kage validate --project /path/to/repo
+kage upgrade --dry-run
 ```
 
 `kage init` is the first-run command. It creates `.agent_memory/`, migrates
@@ -121,6 +125,16 @@ and parser coverage, code graph counts, evidence coverage, approved vs pending
 memory, validation status, estimated tokens saved per recall, duplicate
 candidates, average memory quality, and a readiness score.
 
+Use `kage refresh --project <repo>` or the `kage_refresh` MCP tool after
+meaningful file changes. Refresh rebuilds indexes, code graph, memory graph,
+metrics, and stale-memory metadata. Memory is marked stale when status or
+feedback says it is stale, its TTL expires, or grounded paths disappear.
+
+Use `kage pr summarize --project <repo>` / `kage_pr_summarize` before handoff to
+write branch review metadata and repo-local change memory from the git diff.
+Use `kage pr check --project <repo>` / `kage_pr_check` before merge to verify
+validation, graph freshness, stale packets, and memory packet changes.
+
 Review artifacts include memory quality reasons, risks, duplicate candidates,
 and estimated token savings for legacy pending/quarantine packets and promotion
 review.
@@ -185,6 +199,9 @@ Local repo tools:
 - `kage_recall`
 - `kage_code_graph`
 - `kage_metrics`
+- `kage_refresh`
+- `kage_pr_summarize`
+- `kage_pr_check`
 - `kage_quality`
 - `kage_benchmark`
 - `kage_setup_agent`
@@ -267,8 +284,10 @@ Before code changes or repo-specific answers:
 2. Call `kage_recall` with the user task as the query.
 3. Call `kage_graph` with the user task as the query.
 4. Capture reusable learnings with `kage_learn` or `kage_capture`.
-5. Before finishing changed-file tasks, call `kage_propose_from_diff`.
-6. Never publish or promote org/global memory automatically.
+5. After meaningful file changes, call `kage_refresh`.
+6. Before finishing changed-file tasks, call `kage_propose_from_diff` or `kage_pr_summarize`.
+7. Before merge, call `kage_pr_check`.
+8. Never publish or promote org/global memory automatically.
 ```
 
 Run `kage setup verify-agent --agent codex --project <repo>` after setup. The

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
 const promises_1 = require("node:readline/promises");
 const node_process_1 = require("node:process");
 const daemon_js_1 = require("./daemon.js");
@@ -22,6 +23,10 @@ Usage:
   kage daemon status --project <dir> [--json]
   kage daemon doctor --project <dir> [--json]
   kage viewer --project <dir> [--port 3113]
+  kage refresh --project <dir> [--json]
+  kage pr summarize --project <dir> [--json]
+  kage pr check --project <dir> [--json]
+  kage upgrade [--dry-run]
   kage branch --project <dir> [--json]
   kage metrics --project <dir> [--json]
   kage quality --project <dir> [--json]
@@ -296,6 +301,97 @@ async function main() {
         await (0, daemon_js_1.startViewer)(projectArg(args), { port: numberArg(args, "--port", 3113) });
         return;
     }
+    if (command === "refresh") {
+        const result = (0, kernel_js_1.refreshProject)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        console.log(`Refreshed ${result.project_dir}`);
+        console.log(`Packets indexed: ${result.index.packets}`);
+        console.log(`Packet metadata updated: ${result.updated_packets}`);
+        console.log(`Code graph: ${result.code_graph.files} files, ${result.code_graph.symbols} symbols, ${result.code_graph.imports} imports, ${result.code_graph.calls} calls`);
+        console.log(`Memory graph: ${result.memory_graph.entities} entities, ${result.memory_graph.edges} edges, ${result.memory_graph.episodes} episodes`);
+        console.log(`Stale packets: ${result.stale_packets.length}`);
+        for (const packet of result.stale_packets.slice(0, 8)) {
+            console.log(`  - ${packet.title} (${packet.id}): ${packet.reasons.join("; ")}`);
+        }
+        console.log(result.validation.ok ? "Validation: passed" : "Validation: failed");
+        if (result.validation.errors.length)
+            console.log(`Errors:\n${result.validation.errors.map((error) => `  - ${error}`).join("\n")}`);
+        if (result.validation.warnings.length)
+            console.log(`Warnings:\n${result.validation.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+        console.log(`Next actions:\n${result.next_actions.map((action) => `  - ${action}`).join("\n")}`);
+        if (!result.ok)
+            process.exit(2);
+        return;
+    }
+    if (command === "pr") {
+        const action = args[1];
+        if (action === "summarize") {
+            const result = (0, kernel_js_1.prSummarize)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            console.log(`PR summary for ${result.project_dir}`);
+            console.log(`Branch: ${result.branch ?? "(detached)"}`);
+            console.log(`Changed files: ${result.changed_files.join(", ") || "(none)"}`);
+            if (result.diff_memory_packet_id)
+                console.log(`Repo memory: ${result.diff_memory_packet_id}`);
+            if (result.branch_summary_path)
+                console.log(`Branch summary: ${result.branch_summary_path}`);
+            if (result.review_artifact_path)
+                console.log(`Review artifact: ${result.review_artifact_path}`);
+            if (result.warnings.length)
+                console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+            if (result.errors.length)
+                console.log(`Errors:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        if (action === "check") {
+            const result = (0, kernel_js_1.prCheck)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            console.log(`PR memory check for ${result.project_dir}`);
+            console.log(`Branch: ${result.branch ?? "(detached)"}`);
+            console.log(`Changed files: ${result.changed_files.length}`);
+            console.log(`Memory packet changes: ${result.memory_packet_changes.length}`);
+            console.log(`Code graph current: ${result.code_graph_current ? "yes" : "no"}`);
+            console.log(`Memory graph current: ${result.memory_graph_current ? "yes" : "no"}`);
+            console.log(`Stale packets: ${result.stale_packets.length}`);
+            if (result.warnings.length)
+                console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+            if (result.errors.length)
+                console.log(`Errors:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            console.log(`Required actions:\n${result.required_actions.map((action) => `  - ${action}`).join("\n")}`);
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        usage();
+    }
+    if (command === "upgrade") {
+        const commandLine = "npm install -g @kage-core/kage-graph-mcp@latest";
+        if (args.includes("--dry-run")) {
+            console.log(commandLine);
+            return;
+        }
+        console.log(`Running: ${commandLine}`);
+        (0, node_child_process_1.execFileSync)("npm", ["install", "-g", "@kage-core/kage-graph-mcp@latest"], { stdio: "inherit" });
+        console.log("Kage upgraded. Restart Codex or Claude Code so the MCP process reloads the new package.");
+        return;
+    }
     if (command === "graph") {
         const query = firstPositional(args);
         if (query) {

package/dist/index.js

@@ -154,6 +154,39 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_refresh",
+            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file changes and before PR checks.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_pr_summarize",
+            description: "Create a PR/branch memory summary from local git diff metadata and write repo-local change memory. Use when a branch is ready to hand off.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_pr_check",
+            description: "Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_quality",
             description: "Return memory quality metrics: useful memory ratio, duplicate burden, stale/wrong feedback, evidence coverage, path grounding, and review queue size.",
@@ -595,6 +628,27 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_refresh") {
+        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
+    if (name === "kage_pr_summarize") {
+        const result = (0, kernel_js_1.prSummarize)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
+    if (name === "kage_pr_check") {
+        const result = (0, kernel_js_1.prCheck)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
     if (name === "kage_quality") {
         const result = (0, kernel_js_1.qualityReport)(String(args?.project_dir ?? ""));
         return {

package/dist/kernel.js

@@ -66,6 +66,7 @@ exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
+exports.refreshProject = refreshProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.recall = recall;
 exports.queryCodeGraph = queryCodeGraph;
@@ -86,6 +87,8 @@ exports.distillSession = distillSession;
 exports.proposeFromDiff = proposeFromDiff;
 exports.buildBranchOverlay = buildBranchOverlay;
 exports.createReviewArtifact = createReviewArtifact;
+exports.prSummarize = prSummarize;
+exports.prCheck = prCheck;
 exports.exportPublicBundle = exportPublicBundle;
 exports.orgStatus = orgStatus;
 exports.orgUploadPacket = orgUploadPacket;
@@ -177,11 +180,23 @@ Keep captures concise and future-facing. Do not store raw transcripts.
 
 ## End-Of-Task Proposal
 
-Before finishing a task that changed files, call \`kage_propose_from_diff\`.
+After meaningful file changes, call \`kage_refresh\` so indexes, code graph,
+memory graph, metrics, and stale-memory checks are current.
 
-This writes a branch review summary and a repo-local change-memory packet. It
-should capture what changed, why it matters, how to verify it, and what future
-agents should know. Git or PR review is the repo-level review boundary.
+Before finishing a task that changed files, call \`kage_pr_summarize\` or
+\`kage_propose_from_diff\`, then call \`kage_pr_check\`.
+
+\`kage_pr_summarize\` writes a branch review summary and a repo-local
+change-memory packet. \`kage_pr_check\` verifies validation, graph freshness,
+stale packets, and whether repo memory changed with the branch. If the check
+fails, explain the required actions instead of hiding the failure. Git or PR
+review is the repo-level review boundary.
+
+## Package Updates
+
+If the user asks to update Kage, run \`kage upgrade\`, then verify setup with
+\`kage setup verify-agent --agent <agent> --project <repo>\`. Tell the user to
+restart the agent when MCP tools need to reload.
 
 ## Feedback
 
@@ -207,7 +222,9 @@ For normal coding tasks:
 4. \`kage_graph\` for remembered decisions, bugs, workflows, and conventions
 5. Work on the task
 6. \`kage_learn\` for concrete learnings
-7. \`kage_propose_from_diff\` before the final response to create repo-local change memory
+7. \`kage_refresh\` after meaningful file changes
+8. \`kage_pr_summarize\` or \`kage_propose_from_diff\` before the final response to create repo-local change memory
+9. \`kage_pr_check\` before final handoff or merge readiness claims
 
 For quick factual questions, \`kage_recall\` alone is enough. For status or demo requests, call \`kage_metrics\`.
 ${AGENTS_POLICY_END}
@@ -447,12 +464,41 @@ function packetFeedbackScore(packet) {
     const quality = packet.quality;
     return Number(quality.votes_up ?? 0) * 2 - Number(quality.votes_down ?? 0) * 3 - Number(quality.reports_stale ?? 0) * 4;
 }
+function meaningfulMemoryPath(path) {
+    return path !== "root" && path !== "." && !isNoisePath(path);
+}
+function staleMemoryReasons(projectDir, packet) {
+    const reasons = [];
+    const quality = packet.quality;
+    const freshness = packet.freshness;
+    if (packet.status === "deprecated" || packet.status === "superseded") {
+        reasons.push(`packet status is ${packet.status}`);
+    }
+    if (Number(quality.reports_stale ?? 0) > 0) {
+        reasons.push("user or agent reported this memory stale");
+    }
+    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)
+            reasons.push(`freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`);
+    }
+    const paths = packet.paths.filter(meaningfulMemoryPath);
+    const missingPaths = paths.filter((path) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, path)));
+    if (paths.length > 0 && missingPaths.length === paths.length) {
+        reasons.push(`all referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
+    }
+    else if (missingPaths.length > 0) {
+        reasons.push(`some referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
+    }
+    return unique(reasons);
+}
 function classifyPacket(projectDir, packet) {
     const quality = evaluateMemoryQuality(projectDir, packet);
     const score = Number(quality.score);
     const duplicates = quality.duplicate_candidates;
-    const q = packet.quality;
-    if (Number(q.reports_stale ?? 0) > 0 || packet.status === "deprecated" || packet.status === "superseded")
+    if (staleMemoryReasons(projectDir, packet).length)
         return "stale";
     if (duplicates.length)
         return "duplicate";
@@ -522,11 +568,17 @@ function evaluateMemoryQuality(projectDir, packet) {
         score -= 18;
         risks.push("possible duplicate memory");
     }
+    const staleReasons = staleMemoryReasons(projectDir, packet);
+    if (staleReasons.length) {
+        score -= 22;
+        risks.push(...staleReasons);
+    }
     return {
         score: Math.max(0, Math.min(100, score)),
         reasons,
         risks,
         duplicate_candidates: duplicates,
+        stale_reasons: staleReasons,
         estimated_tokens_saved: Math.max(40, estimateTokens(packet.body) * 2),
     };
 }
@@ -769,6 +821,17 @@ function loadPacketsFromDir(dir) {
         .sort()
         .map((name) => readJson((0, node_path_1.join)(dir, name)));
 }
+function loadPacketEntriesFromDir(dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((name) => name.endsWith(".json"))
+        .sort()
+        .map((name) => {
+        const path = (0, node_path_1.join)(dir, name);
+        return { path, packet: readJson(path) };
+    });
+}
 function loadApprovedPackets(projectDir) {
     return loadPacketsFromDir(packetsDir(projectDir)).filter((packet) => packet.status === "approved");
 }
@@ -837,14 +900,15 @@ function isNoisePath(filePath) {
 function parsePorcelainStatus(status) {
     return unique(status
         .split(/\r?\n/)
-        .map((line) => {
-        const raw = line.length > 2 && line[2] === " " ? line.slice(3) : line.slice(2);
-        return raw.trim();
-    })
+        .map(parsePorcelainPath)
         .map((path) => path.replace(/^.* -> /, ""))
         .filter(Boolean)
         .filter((path) => !shouldSkipRepoMemoryPath(path))).sort();
 }
+function parsePorcelainPath(line) {
+    const raw = line.length > 2 && line[2] === " " ? line.slice(3) : line.slice(2);
+    return raw.trim();
+}
 function shouldSkipRepoMemoryPath(relativePath) {
     return isNoisePath(relativePath) || shouldSkipCodePath(relativePath);
 }
@@ -2342,6 +2406,104 @@ function indexProject(projectDir) {
         policyPath: (0, node_path_1.relative)(projectDir, policy.path),
     };
 }
+function staleSuggestedAction(reasons) {
+    if (reasons.some((reason) => reason.includes("status is")))
+        return "mark_stale";
+    if (reasons.some((reason) => reason.includes("missing")))
+        return "update";
+    if (reasons.some((reason) => reason.includes("reported")))
+        return "supersede";
+    return "verify";
+}
+function staleFinding(packet, reasons) {
+    return {
+        id: packet.id,
+        title: packet.title,
+        type: packet.type,
+        status: packet.status,
+        paths: packet.paths,
+        reasons,
+        suggested_action: staleSuggestedAction(reasons),
+    };
+}
+function refreshPacketStaleness(projectDir) {
+    const findings = [];
+    let updated = 0;
+    for (const entry of loadPacketEntriesFromDir(packetsDir(projectDir))) {
+        const reasons = staleMemoryReasons(projectDir, entry.packet);
+        const oldQuality = entry.packet.quality;
+        const oldFreshness = entry.packet.freshness;
+        let nextQuality;
+        if (reasons.length) {
+            const finding = staleFinding(entry.packet, reasons);
+            findings.push(finding);
+            nextQuality = {
+                ...oldQuality,
+                stale: true,
+                stale_reasons: reasons,
+                suggested_action: finding.suggested_action,
+            };
+        }
+        else {
+            const { stale: _stale, stale_reasons: _staleReasons, suggested_action: _suggestedAction, ...rest } = oldQuality;
+            nextQuality = rest;
+        }
+        const nextFreshness = oldFreshness;
+        const changed = JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
+            || JSON.stringify(oldFreshness) !== JSON.stringify(nextFreshness);
+        if (changed) {
+            writeJson(entry.path, {
+                ...entry.packet,
+                freshness: nextFreshness,
+                quality: nextQuality,
+                updated_at: nowIso(),
+            });
+            updated += 1;
+        }
+    }
+    return { findings, updated };
+}
+function refreshProject(projectDir) {
+    const index = indexProject(projectDir);
+    const stale = refreshPacketStaleness(projectDir);
+    const indexes = stale.updated > 0 ? buildIndexes(projectDir).map((path) => (0, node_path_1.relative)(projectDir, path)) : index.indexes;
+    const validation = validateProject(projectDir);
+    const metrics = kageMetrics(projectDir);
+    const nextActions = [];
+    if (stale.findings.length)
+        nextActions.push("Update, verify, or supersede stale repo memories before relying on them.");
+    if (!validation.ok)
+        nextActions.push("Fix validation errors before merging or sharing memory.");
+    if (validation.warnings.length)
+        nextActions.push("Review validation warnings for grounding, indexes, or generated artifacts.");
+    if (!nextActions.length)
+        nextActions.push("Repo memory, code graph, and indexes are current.");
+    return {
+        ok: validation.ok,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        index,
+        validation,
+        metrics,
+        stale_packets: stale.findings,
+        updated_packets: stale.updated,
+        indexes,
+        code_graph: {
+            files: metrics.code_graph.files,
+            symbols: metrics.code_graph.symbols,
+            imports: metrics.code_graph.imports,
+            calls: metrics.code_graph.calls,
+            routes: metrics.code_graph.routes,
+            tests: metrics.code_graph.tests,
+        },
+        memory_graph: {
+            entities: metrics.memory_graph.entities,
+            edges: metrics.memory_graph.edges,
+            episodes: metrics.memory_graph.episodes,
+        },
+        next_actions: nextActions,
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");
@@ -3266,22 +3428,42 @@ Before making code changes or answering implementation questions:
 3. Call kage_code_graph for file, symbol, route, test, or dependency questions.
 4. Call kage_graph for decisions, bugs, workflows, and conventions.
 When you learn something reusable: kage_learn.
-Before finishing a task that changed files: kage_propose_from_diff.
+After meaningful file changes: kage_refresh.
+Before finishing a task that changed files: kage_pr_summarize or kage_propose_from_diff, then kage_pr_check.
 If recalled memory helped: kage_feedback helpful. If wrong or stale: kage_feedback wrong or stale."
 fi
 
 KAGE_MSG="$POLICY" python3 -c "import json,os; print(json.dumps({'systemMessage': os.environ['KAGE_MSG']}))"
+`;
+        const stopHookScript = `#!/usr/bin/env bash
+# Kage Stop hook — best-effort repo memory refresh before Claude Code finishes.
+# Silent if Kage is not initialized in the current project or no git changes exist.
+set -euo pipefail
+
+PAYLOAD="$(cat || true)"
+CWD="$(printf "%s" "$PAYLOAD" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('cwd',''))" 2>/dev/null || echo "")"
+
+[[ -d "$CWD/.agent_memory" ]] || exit 0
+command -v kage >/dev/null 2>&1 || exit 0
+
+if git -C "$CWD" status --porcelain -uall >/dev/null 2>&1 && [[ -n "$(git -C "$CWD" status --porcelain -uall)" ]]; then
+  kage refresh --project "$CWD" --json >/dev/null 2>&1 || true
+  kage pr summarize --project "$CWD" --json >/dev/null 2>&1 || true
+fi
+
+exit 0
 `;
         const settingsPath = (0, node_path_1.join)(home, ".claude", "settings.json");
         const hookEntry = {
             hooks: {
                 SessionStart: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/session-start.sh", timeout: 5 }] }],
+                Stop: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/stop.sh", timeout: 20 }] }],
             },
         };
         setSnippet(path, JSON.stringify({ mcpServers: { kage: server } }, null, 2), [
             "Add the MCP server to ~/.claude.json, then restart Claude Code.",
             "alwaysLoad: true makes Kage tools immediately visible without requiring ToolSearch.",
-            `Also create ${hookDir}/session-start.sh with the hook script and add the SessionStart hook to ~/.claude/settings.json.`,
+            `Also create ${hookDir}/session-start.sh and ${hookDir}/stop.sh with the hook scripts and add SessionStart/Stop hooks to ~/.claude/settings.json.`,
             "Run `kage init --project <repo>` inside each repo to install the ambient memory policy.",
         ], true);
         if (options.write) {
@@ -3289,6 +3471,7 @@ KAGE_MSG="$POLICY" python3 -c "import json,os; print(json.dumps({'systemMessage'
             // Install the ambient session-start hook
             (0, node_fs_1.mkdirSync)(hookDir, { recursive: true });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "session-start.sh"), hookScript, { mode: 0o755 });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "stop.sh"), stopHookScript, { mode: 0o755 });
             upsertJsonSettings(settingsPath, hookEntry);
             result.wrote = true;
         }
@@ -3714,11 +3897,25 @@ function distillSession(projectDir, sessionId) {
 function createDiffChangeMemory(projectDir, summary) {
     const branch = summary.branch ?? "detached";
     const head = summary.head ?? "unknown";
-    const fingerprint = (0, node_crypto_1.createHash)("sha256")
-        .update(`${branch}\n${head}\n${summary.changed_files.join("\n")}\n${summary.diff_stat}`)
-        .digest("hex")
-        .slice(0, 10);
     const title = `Change memory: ${branch}`;
+    // Remove any stale change-memory packets for this branch so propose_from_diff
+    // replaces rather than accumulates. The stable ID (branch-only, no fingerprint)
+    // makes writePacket idempotent going forward; this sweep handles packets that
+    // were written with the old fingerprint-based ID.
+    const stalePrefix = `workflow-${slugify(title)}-`;
+    const stableId = makePacketId(projectDir, "workflow", title);
+    const stableFileName = `${stalePrefix}${(0, node_crypto_1.createHash)("sha256").update(stableId).digest("hex").slice(0, 8)}.json`;
+    try {
+        const existing = (0, node_fs_1.readdirSync)(packetsDir(projectDir)).filter((name) => name.startsWith(stalePrefix) && name !== stableFileName);
+        for (const name of existing) {
+            const stale = (0, node_path_1.join)(packetsDir(projectDir), name);
+            const stalePacket = readJson(stale);
+            if (stalePacket?.type === "workflow" && stalePacket?.title === title) {
+                (0, node_fs_1.unlinkSync)(stale);
+            }
+        }
+    }
+    catch { /* non-fatal */ }
     const verifyCommands = npmScriptCommands(projectDir)
         .filter((command) => /(test|check|lint|build|type|verify)/i.test(command))
         .slice(0, 8);
@@ -3752,7 +3949,7 @@ function createDiffChangeMemory(projectDir, summary) {
     const now = nowIso();
     const packet = {
         schema_version: exports.PACKET_SCHEMA_VERSION,
-        id: makePacketId(projectDir, "workflow", title, fingerprint),
+        id: stableId,
         title,
         summary: `Repo-local context for ${summary.changed_files.length} changed repo path${summary.changed_files.length === 1 ? "" : "s"} on ${branch}.`,
         body,
@@ -3847,7 +4044,7 @@ function proposeFromDiff(projectDir) {
 }
 function buildBranchOverlay(projectDir) {
     ensureMemoryDirs(projectDir);
-    const status = readGit(projectDir, ["status", "--porcelain"]) ?? "";
+    const status = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
     const overlay = {
         schema_version: 1,
         project_dir: projectDir,
@@ -3925,6 +4122,91 @@ function createReviewArtifact(projectDir) {
     (0, node_fs_1.writeFileSync)(path, `${lines.join("\n").trim()}\n`, "utf8");
     return { path, pending: pending.length };
 }
+function graphIsCurrent(projectDir, relativePath, head) {
+    const path = (0, node_path_1.join)(projectDir, relativePath);
+    if (!(0, node_fs_1.existsSync)(path))
+        return false;
+    if (!head)
+        return true;
+    try {
+        const graph = readJson(path);
+        return graph.repo_state?.head === head;
+    }
+    catch {
+        return false;
+    }
+}
+function prSummarize(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const proposal = proposeFromDiff(projectDir);
+    const artifact = createReviewArtifact(projectDir);
+    const validation = validateProject(projectDir);
+    const warnings = [...validation.warnings];
+    if (!proposal.ok)
+        warnings.push(...proposal.errors);
+    return {
+        ok: proposal.ok && validation.ok,
+        project_dir: projectDir,
+        branch: gitBranch(projectDir),
+        head: gitHead(projectDir),
+        changed_files: proposal.changedFiles,
+        diff_memory_packet_id: proposal.packet?.id,
+        diff_memory_packet_path: proposal.packetPath,
+        branch_summary_path: proposal.path,
+        review_artifact_path: artifact.path,
+        validation,
+        errors: validation.errors,
+        warnings,
+    };
+}
+function prCheck(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const overlay = buildBranchOverlay(projectDir);
+    const rawStatus = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
+    const validation = validateProject(projectDir);
+    const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
+        .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
+        .filter((entry) => entry.reasons.length)
+        .map((entry) => staleFinding(entry.packet, entry.reasons));
+    const memoryPacketChanges = unique(rawStatus
+        .split(/\r?\n/)
+        .map(parsePorcelainPath)
+        .map((path) => path.replace(/^.* -> /, ""))
+        .filter((path) => path.startsWith(".agent_memory/packets/") && path.endsWith(".json"))).sort();
+    const codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", overlay.head);
+    const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", overlay.head);
+    const errors = [...validation.errors];
+    const warnings = [...validation.warnings];
+    const requiredActions = [];
+    if (stalePackets.length) {
+        errors.push(`${stalePackets.length} stale memory packet(s) require update, verification, or supersession.`);
+        requiredActions.push("Run kage refresh, then update or supersede stale packets.");
+    }
+    if (!codeGraphCurrent || !memoryGraphCurrent) {
+        errors.push("Generated graph artifacts are missing or not current for this branch head.");
+        requiredActions.push("Run kage refresh --project <dir> before merge.");
+    }
+    if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {
+        warnings.push("No repo memory packet changed for this branch. If durable knowledge was learned, run kage propose --from-diff or kage learn.");
+    }
+    if (!requiredActions.length)
+        requiredActions.push("PR memory and graph checks passed.");
+    return {
+        ok: errors.length === 0,
+        project_dir: projectDir,
+        branch: overlay.branch,
+        head: overlay.head,
+        changed_files: overlay.changed_files,
+        validation,
+        stale_packets: stalePackets,
+        memory_packet_changes: memoryPacketChanges,
+        code_graph_current: codeGraphCurrent,
+        memory_graph_current: memoryGraphCurrent,
+        errors,
+        warnings,
+        required_actions: requiredActions,
+    };
+}
 function exportPublicBundle(projectDir) {
     ensureMemoryDirs(projectDir);
     const candidates = loadPacketsFromDir(publicCandidatesDir(projectDir));

package/package.json

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