@kage-core/kage-graph-mcp 1.1.16 → 1.1.17

package/README.md

@@ -9,6 +9,12 @@ This package exposes two surfaces:
 
 ## Latest Release
 
+`1.1.17` publishes content-based graph freshness:
+
+- `kage pr check` now uses graph input hashes, so push-only operations and
+  empty/same-tree commits do not force another refresh while real source,
+  approved-memory, or code-index changes still stale generated graph artifacts.
+
 `1.1.16` fixes the guarded release helper's npm verification step:
 
 - exact-version `npm view` checks now retry with backoff after publish so npm
@@ -79,6 +85,10 @@ The script fetches the current branch and blocks if the remote branch is not an
 ancestor of local `HEAD`, which prevents publishing an npm version from a branch
 that cannot be pushed cleanly.
 
+Do not refresh again just because the branch was pushed. Graph freshness is
+based on source, approved memory, and code-index inputs; empty/same-tree commits
+are accepted by `kage pr check`.
+
 ## CLI
 
 ```bash
@@ -232,9 +242,10 @@ hashes, git state, audit trust, inbox counts, and metrics readiness. CI, PR, and
 sync workflows build it after refresh.
 
 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.
+meaningful file/content 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. Pushes
+and empty/same-tree commits do not need another refresh.
 
 Use `kage gc --project <repo> --dry-run` to preview stale packet cleanup.
 `kage gc --project <repo>` marks stale repo packets deprecated, rebuilds
@@ -407,7 +418,7 @@ Minimum policy:
 Before code changes or repo-specific answers:
 1. Call `kage_context` with `project_dir` and the user task as `query`.
 2. Capture reusable learnings with `kage_learn` or `kage_capture`.
-3. After meaningful file changes, call `kage_refresh`.
+3. After meaningful file/content changes, call `kage_refresh`; skip it for push-only or same-tree commits.
 4. Before finishing changed-file tasks, call `kage_propose_from_diff` or `kage_pr_summarize`.
 5. Before merge, call `kage_pr_check`.
 6. Never publish or promote org/global memory automatically.

package/dist/index.js

@@ -217,7 +217,7 @@ 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 changes and before PR checks.",
+            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.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/kernel.js

@@ -193,8 +193,10 @@ decisions, debugging, explanation, or action. Do not store raw transcripts.
 
 ## End-Of-Task Proposal
 
-After meaningful file changes, call \`kage_refresh\` so indexes, code graph,
-memory graph, metrics, and stale-memory checks are current.
+After meaningful file/content changes, call \`kage_refresh\` so indexes, code
+graph, memory graph, metrics, and stale-memory checks are current. Do not
+refresh solely because a branch was pushed, an empty commit was created, or the
+git commit changed without graph inputs changing.
 
 Before finishing a task that changed files, call \`kage_pr_summarize\` or
 \`kage_propose_from_diff\`, then call \`kage_pr_check\`.
@@ -232,7 +234,7 @@ For normal coding tasks:
 1. \`kage_context\` — validate + recall + code graph + knowledge graph in one call
 2. Work on the task
 3. \`kage_learn\` for concrete learnings
-4. \`kage_refresh\` after meaningful file changes
+4. \`kage_refresh\` after meaningful file/content changes, not after push-only or same-tree commits
 5. \`kage_propose_from_diff\` before the final response to create repo-local change memory
 
 For quick factual questions, \`kage_context\` alone is enough. For status or demo requests, call \`kage_metrics\`.
@@ -882,6 +884,9 @@ function gitBranch(projectDir) {
 function gitHead(projectDir) {
     return readGit(projectDir, ["rev-parse", "HEAD"]);
 }
+function gitTree(projectDir) {
+    return readGit(projectDir, ["rev-parse", "HEAD^{tree}"]);
+}
 function gitMergeBase(projectDir) {
     return readGit(projectDir, ["merge-base", "HEAD", "origin/main"])
         || readGit(projectDir, ["merge-base", "HEAD", "origin/master"]);
@@ -1863,6 +1868,49 @@ function externalIndexFiles(projectDir) {
         { path: (0, node_path_1.join)(projectDir, "dump.lsif"), parser: "lsif", format: "lsif" },
     ];
 }
+function sha256Hex(content) {
+    return (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+function projectRelative(projectDir, path) {
+    return (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/");
+}
+function graphInputHash(entries) {
+    const hash = (0, node_crypto_1.createHash)("sha256");
+    const sorted = entries.slice().sort((a, b) => a.kind.localeCompare(b.kind) || a.path.localeCompare(b.path));
+    for (const entry of sorted) {
+        hash.update(entry.kind);
+        hash.update("\0");
+        hash.update(entry.path);
+        hash.update("\0");
+        hash.update(entry.sha256);
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function fileInputEntries(projectDir, paths, kind) {
+    return paths
+        .filter((path) => (0, node_fs_1.existsSync)(path))
+        .map((path) => ({
+        kind,
+        path: projectRelative(projectDir, path),
+        sha256: sha256Hex((0, node_fs_1.readFileSync)(path)),
+    }));
+}
+function codeGraphInputHash(projectDir) {
+    return graphInputHash([
+        ...fileInputEntries(projectDir, listCodeFiles(projectDir), "code_file"),
+        ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
+    ]);
+}
+function knowledgeGraphInputHash(projectDir, codeInputHash = codeGraphInputHash(projectDir)) {
+    const packetEntries = loadPacketEntriesFromDir(packetsDir(projectDir))
+        .filter((entry) => entry.packet.status === "approved")
+        .map((entry) => entry.path);
+    return graphInputHash([
+        { kind: "code_graph_input", path: ".agent_memory/code_graph/input", sha256: codeInputHash },
+        ...fileInputEntries(projectDir, packetEntries, "approved_packet"),
+    ]);
+}
 function normalizeExternalKind(value) {
     const kind = String(value ?? "").toLowerCase();
     if (["function", "method", "class", "constant", "route", "test"].includes(kind))
@@ -2103,7 +2151,9 @@ function buildCodeGraph(projectDir) {
     ensureMemoryDirs(projectDir);
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
+    const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
+    const inputHash = codeGraphInputHash(projectDir);
     const absoluteFiles = listCodeFiles(projectDir);
     const knownFiles = new Set(absoluteFiles.map((path) => (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/")));
     const files = [];
@@ -2188,7 +2238,7 @@ function buildCodeGraph(projectDir) {
         project_dir: projectDir,
         repo_key: repoKey(projectDir),
         generated_at: nowIso(),
-        repo_state: { branch, head, merge_base: mergeBase },
+        repo_state: { branch, head, merge_base: mergeBase, tree, input_hash: inputHash },
         files: files.sort((a, b) => a.path.localeCompare(b.path)),
         symbols: symbols.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.name.localeCompare(b.name)),
         imports: imports.sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier)),
@@ -2212,6 +2262,7 @@ function buildKnowledgeGraph(projectDir) {
     const packets = loadApprovedPackets(projectDir).sort((a, b) => a.id.localeCompare(b.id));
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
+    const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
     const entities = new Map();
     const edges = new Map();
@@ -2219,6 +2270,7 @@ function buildKnowledgeGraph(projectDir) {
     const repoEntityId = graphEntityId("repo", repoKey(projectDir));
     const generatedFrom = packets.map((packet) => packet.updated_at).sort().at(-1) ?? null;
     const codeGraph = buildCodeGraph(projectDir);
+    const inputHash = knowledgeGraphInputHash(projectDir, codeGraph.repo_state.input_hash ?? codeGraphInputHash(projectDir));
     addEntity(entities, {
         id: repoEntityId,
         type: "repo",
@@ -2540,7 +2592,7 @@ function buildKnowledgeGraph(projectDir) {
         project_dir: projectDir,
         repo_key: repoKey(projectDir),
         generated_from_updated_at: generatedFrom,
-        repo_state: { branch, head, merge_base: mergeBase },
+        repo_state: { branch, head, merge_base: mergeBase, tree, input_hash: inputHash },
         episodes: episodes.sort((a, b) => a.id.localeCompare(b.id)),
         entities: [...entities.values()].sort((a, b) => a.id.localeCompare(b.id)),
         edges: [...edges.values()].sort((a, b) => a.id.localeCompare(b.id)),
@@ -4239,7 +4291,7 @@ Before making code changes or answering implementation questions:
 1. Call kage_context with project_dir and the user task as query.
 2. Use returned memory only when it is relevant, source-backed, and not stale.
 When you learn something reusable: kage_learn.
-After meaningful file changes: kage_refresh.
+After meaningful file/content changes: kage_refresh. Push-only or same-tree commits do not need another 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
@@ -4963,15 +5015,22 @@ 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) {
+function graphIsCurrent(projectDir, relativePath, expected) {
     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;
+        const repoState = graph.repo_state;
+        if (!repoState)
+            return false;
+        if (expected.inputHash && repoState.input_hash)
+            return repoState.input_hash === expected.inputHash;
+        if (expected.tree && repoState.tree)
+            return repoState.tree === expected.tree;
+        if (!expected.head)
+            return true;
+        return repoState.head === expected.head;
     }
     catch {
         return false;
@@ -5005,6 +5064,9 @@ function prCheck(projectDir) {
     const overlay = buildBranchOverlay(projectDir);
     const rawStatus = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
     const validation = validateProject(projectDir);
+    const tree = gitTree(projectDir);
+    const codeInputHash = codeGraphInputHash(projectDir);
+    const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
     const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
         .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
         .filter((entry) => entry.reasons.length)
@@ -5014,8 +5076,8 @@ function prCheck(projectDir) {
         .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 codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", { head: overlay.head, tree, inputHash: codeInputHash });
+    const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", { head: overlay.head, tree, inputHash: memoryInputHash });
     const errors = [...validation.errors];
     const warnings = [...validation.warnings];
     const requiredActions = [];
@@ -5024,7 +5086,7 @@ function prCheck(projectDir) {
         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.");
+        errors.push("Generated graph artifacts are missing or not current for this working tree content.");
         requiredActions.push("Run kage refresh --project <dir> before merge.");
     }
     if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {

package/package.json

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