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

package/README.md

@@ -9,6 +9,25 @@ This package exposes two surfaces:
 
 ## Latest Release
 
+`1.1.18` publishes the end-to-end performance pass:
+
+- read-only commands reuse current graph artifacts instead of rebuilding them
+  when inputs are fresh.
+- MCP sessions keep an in-process graph cache, so repeated agent calls do not
+  keep reparsing the same graph JSON.
+- `kage refresh` reports lightweight freshness metrics and leaves deep
+  benchmark/quality work to explicit `kage metrics` and `kage benchmark` calls.
+- recall builds graph lookup maps once per query instead of scanning all graph
+  entities and edges for every memory packet.
+- `kage init` remains a packet-only bootstrap path; full graph generation stays
+  with `kage refresh` and `kage index`.
+
+`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 +98,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 +255,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 +431,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

@@ -134,6 +134,7 @@ exports.MEMORY_TYPES = [
     "negative_result",
     "constraint",
 ];
+const graphMemoryCache = new Map();
 exports.SETUP_AGENTS = [
     "codex",
     "claude-code",
@@ -193,8 +194,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 +235,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 +885,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"]);
@@ -1292,6 +1298,11 @@ const CODE_EXTENSIONS = new Set([
     ".hpp",
     ".swift",
 ]);
+const MAX_CODE_FILE_BYTES = positiveIntEnv("KAGE_MAX_CODE_FILE_BYTES", 512 * 1024);
+const MAX_CODE_GRAPH_FILES = positiveIntEnv("KAGE_MAX_CODE_GRAPH_FILES", 2000);
+const MAX_CODE_GRAPH_SYMBOLS = positiveIntEnv("KAGE_MAX_CODE_GRAPH_SYMBOLS", 25000);
+const MAX_CODE_GRAPH_CALLS = positiveIntEnv("KAGE_MAX_CODE_GRAPH_CALLS", 50000);
+const MAX_CODE_GRAPH_CALLS_PER_FILE = positiveIntEnv("KAGE_MAX_CODE_GRAPH_CALLS_PER_FILE", 250);
 const CONFIG_NAMES = new Set([
     "package.json",
     "pyproject.toml",
@@ -1310,6 +1321,10 @@ const CONFIG_NAMES = new Set([
     "vitest.config.js",
     "vitest.config.ts",
 ]);
+function positiveIntEnv(name, fallback) {
+    const value = Number(process.env[name]);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
 function extensionOf(path) {
     const match = path.match(/\.[^.\/]+$/);
     return match ? match[0] : "";
@@ -1317,7 +1332,26 @@ function extensionOf(path) {
 function shouldSkipCodePath(relativePath) {
     return relativePath
         .split("/")
-        .some((part) => [".git", ".agent_memory", "node_modules", "dist", "build", "coverage", ".next", ".turbo"].includes(part));
+        .some((part) => [
+        ".git",
+        ".agent_memory",
+        "node_modules",
+        "vendor",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "dist",
+        "build",
+        "coverage",
+        ".next",
+        ".nuxt",
+        ".output",
+        ".turbo",
+        ".cache",
+        ".parcel-cache",
+        "target",
+        ".gradle",
+    ].includes(part));
 }
 function codeLanguage(path) {
     const extension = extensionOf(path);
@@ -1379,14 +1413,184 @@ function codeFileKind(path) {
         return "doc";
     return "source";
 }
-function listCodeFiles(projectDir) {
-    return walkFiles(projectDir, (absolutePath) => {
+function emptyCodeIndexManifest(projectDir) {
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        repo_key: repoKey(projectDir),
+        generated_at: nowIso(),
+        mode: "quick",
+        limits: {
+            max_file_bytes: MAX_CODE_FILE_BYTES,
+            max_files: MAX_CODE_GRAPH_FILES,
+            max_symbols: MAX_CODE_GRAPH_SYMBOLS,
+            max_calls: MAX_CODE_GRAPH_CALLS,
+            max_calls_per_file: MAX_CODE_GRAPH_CALLS_PER_FILE,
+        },
+        coverage: {
+            indexable_files: 0,
+            indexed_files: 0,
+            deferred_files: 0,
+            ignored_files: 0,
+            coverage_percent: 100,
+            complete: true,
+        },
+        cache: {
+            hits: 0,
+            misses: 0,
+        },
+        deferred_files: [],
+        ignored_summary: {},
+    };
+}
+function codeIndexManifestPath(projectDir) {
+    return (0, node_path_1.join)(codeGraphDir(projectDir), "index-manifest.json");
+}
+function codeIndexSelection(projectDir) {
+    const candidates = [];
+    const deferred = [];
+    const ignoredSummary = {};
+    const ignore = (reason) => {
+        ignoredSummary[reason] = (ignoredSummary[reason] ?? 0) + 1;
+    };
+    const visit = (dir) => {
+        if (!(0, node_fs_1.existsSync)(dir))
+            return;
+        for (const entry of (0, node_fs_1.readdirSync)(dir)) {
+            const absolutePath = (0, node_path_1.join)(dir, entry);
+            const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
+            if (shouldSkipCodePath(rel)) {
+                ignore("generated_vendor_or_cache");
+                continue;
+            }
+            const stats = (0, node_fs_1.statSync)(absolutePath);
+            if (stats.isDirectory()) {
+                visit(absolutePath);
+                continue;
+            }
+            const extension = extensionOf(rel);
+            const indexable = CODE_EXTENSIONS.has(extension) || CONFIG_NAMES.has((0, node_path_1.basename)(rel)) || rel === "README.md";
+            if (!indexable) {
+                ignore("unsupported_file_type");
+                continue;
+            }
+            if (stats.size > MAX_CODE_FILE_BYTES) {
+                deferred.push({ path: rel, size_bytes: stats.size, reason: "over_quick_file_size_limit" });
+                continue;
+            }
+            candidates.push(absolutePath);
+        }
+    };
+    visit(projectDir);
+    const sorted = candidates.sort((a, b) => codeFilePriority(projectDir, a) - codeFilePriority(projectDir, b) || a.localeCompare(b));
+    const indexableFiles = sorted.length + deferred.length;
+    const files = sorted.slice(0, MAX_CODE_GRAPH_FILES);
+    for (const absolutePath of sorted.slice(MAX_CODE_GRAPH_FILES)) {
         const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
-        if (shouldSkipCodePath(rel))
-            return false;
-        const extension = extensionOf(rel);
-        return CODE_EXTENSIONS.has(extension) || CONFIG_NAMES.has((0, node_path_1.basename)(rel)) || rel === "README.md";
-    });
+        deferred.push({ path: rel, size_bytes: (0, node_fs_1.statSync)(absolutePath).size, reason: "over_quick_file_count_limit" });
+    }
+    const manifest = emptyCodeIndexManifest(projectDir);
+    manifest.coverage = {
+        indexable_files: indexableFiles,
+        indexed_files: files.length,
+        deferred_files: deferred.length,
+        ignored_files: Object.values(ignoredSummary).reduce((sum, count) => sum + count, 0),
+        coverage_percent: percent(files.length, indexableFiles),
+        complete: deferred.length === 0,
+    };
+    manifest.deferred_files = deferred.sort((a, b) => a.path.localeCompare(b.path));
+    manifest.ignored_summary = Object.fromEntries(Object.entries(ignoredSummary).sort(([a], [b]) => a.localeCompare(b)));
+    return { files, manifest };
+}
+function writeCodeIndexManifest(projectDir, manifest) {
+    writeJson(codeIndexManifestPath(projectDir), manifest);
+}
+function readCodeIndexManifest(projectDir) {
+    const path = codeIndexManifestPath(projectDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return emptyCodeIndexManifest(projectDir);
+    try {
+        const manifest = readJson(path);
+        if (!manifest.cache)
+            manifest.cache = { hits: 0, misses: 0 };
+        return manifest;
+    }
+    catch {
+        return emptyCodeIndexManifest(projectDir);
+    }
+}
+function listCodeFiles(projectDir) {
+    return codeIndexSelection(projectDir).files;
+}
+function fileFactCacheDir(projectDir) {
+    return (0, node_path_1.join)(codeGraphDir(projectDir), "file-cache");
+}
+function fileFactCachePath(projectDir, rel, hash) {
+    return (0, node_path_1.join)(fileFactCacheDir(projectDir), `${slugify(rel)}-${hash}.json`);
+}
+function readCachedFileFacts(projectDir, rel, hash) {
+    const path = fileFactCachePath(projectDir, rel, hash);
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const cached = readJson(path);
+        if (cached.schema_version !== 1 || cached.path !== rel || cached.hash !== hash)
+            return null;
+        if (!cached.file || !Array.isArray(cached.symbols) || !Array.isArray(cached.imports))
+            return null;
+        return cached;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedFileFacts(projectDir, facts) {
+    ensureDir(fileFactCacheDir(projectDir));
+    writeJson(fileFactCachePath(projectDir, facts.path, facts.hash), facts);
+}
+function buildFileFacts(projectDir, absolutePath, knownFiles) {
+    const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
+    const content = (0, node_fs_1.readFileSync)(absolutePath, "utf8");
+    const fullHash = (0, node_crypto_1.createHash)("sha256").update(content).digest("hex");
+    const cached = readCachedFileFacts(projectDir, rel, fullHash);
+    if (cached)
+        return { facts: cached, content, cacheHit: true };
+    const file = {
+        id: `file:${slugify(rel)}`,
+        path: rel,
+        language: codeLanguage(rel),
+        parser: codeParser(rel),
+        kind: codeFileKind(rel),
+        size_bytes: Buffer.byteLength(content),
+        line_count: content.split(/\r?\n/).length,
+        hash: fullHash.slice(0, 16),
+    };
+    const symbols = [];
+    const imports = [];
+    if (TS_AST_EXTENSIONS.has(extensionOf(rel))) {
+        symbols.push(...extractSymbols(rel, content));
+        imports.push(...extractImports(projectDir, rel, content, knownFiles));
+    }
+    else if (CODE_EXTENSIONS.has(extensionOf(rel))) {
+        symbols.push(...extractGenericSymbols(rel, content));
+        imports.push(...extractGenericImports(projectDir, rel, content, knownFiles));
+    }
+    const facts = { schema_version: 1, path: rel, hash: fullHash, file, symbols, imports };
+    writeCachedFileFacts(projectDir, facts);
+    return { facts, content, cacheHit: false };
+}
+function codeFilePriority(projectDir, absolutePath) {
+    const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
+    const kind = codeFileKind(rel);
+    if (rel === "README.md" || CONFIG_NAMES.has((0, node_path_1.basename)(rel)))
+        return 0;
+    if (kind === "manifest" || kind === "config")
+        return 1;
+    if (kind === "test")
+        return 2;
+    if (TS_AST_EXTENSIONS.has(extensionOf(rel)))
+        return 3;
+    return 4;
 }
 function lineForOffset(text, offset) {
     return text.slice(0, offset).split(/\r?\n/).length;
@@ -1774,6 +1978,8 @@ function extractCalls(path, text, symbols, symbolByName) {
     const sourceFile = sourceFileFor(path, text);
     const calls = [];
     const visit = (node) => {
+        if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
+            return;
         if (!ts.isCallExpression(node)) {
             ts.forEachChild(node, visit);
             return;
@@ -1791,6 +1997,8 @@ function extractCalls(path, text, symbols, symbolByName) {
         const line = lineForNode(sourceFile, node);
         const caller = symbolAtLine(symbols, path, line);
         for (const target of targets.slice(0, 3)) {
+            if (calls.length >= MAX_CODE_GRAPH_CALLS_PER_FILE)
+                break;
             if (target.path === path && target.line === line)
                 continue;
             calls.push({ from_symbol: caller?.id ?? null, to_symbol: target.id, path, line });
@@ -1863,6 +2071,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, absoluteFiles = listCodeFiles(projectDir)) {
+    return graphInputHash([
+        ...fileInputEntries(projectDir, absoluteFiles, "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,39 +2354,37 @@ function buildCodeGraph(projectDir) {
     ensureMemoryDirs(projectDir);
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
+    const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
-    const absoluteFiles = listCodeFiles(projectDir);
+    const selection = codeIndexSelection(projectDir);
+    const absoluteFiles = selection.files;
+    const inputHash = codeGraphInputHash(projectDir, absoluteFiles);
+    writeCodeIndexManifest(projectDir, selection.manifest);
     const knownFiles = new Set(absoluteFiles.map((path) => (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/")));
     const files = [];
     const symbols = [];
     const imports = [];
     const contents = new Map();
+    let cacheHits = 0;
+    let cacheMisses = 0;
     for (const absolutePath of absoluteFiles) {
-        const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
-        const content = (0, node_fs_1.readFileSync)(absolutePath, "utf8");
-        contents.set(rel, content);
-        files.push({
-            id: `file:${slugify(rel)}`,
-            path: rel,
-            language: codeLanguage(rel),
-            parser: codeParser(rel),
-            kind: codeFileKind(rel),
-            size_bytes: Buffer.byteLength(content),
-            line_count: content.split(/\r?\n/).length,
-            hash: (0, node_crypto_1.createHash)("sha256").update(content).digest("hex").slice(0, 16),
-        });
-        if (TS_AST_EXTENSIONS.has(extensionOf(rel))) {
-            symbols.push(...extractSymbols(rel, content));
-            imports.push(...extractImports(projectDir, rel, content, knownFiles));
-        }
-        else if (CODE_EXTENSIONS.has(extensionOf(rel))) {
-            symbols.push(...extractGenericSymbols(rel, content));
-            imports.push(...extractGenericImports(projectDir, rel, content, knownFiles));
-        }
-    }
+        const { facts, content, cacheHit } = buildFileFacts(projectDir, absolutePath, knownFiles);
+        if (cacheHit)
+            cacheHits++;
+        else
+            cacheMisses++;
+        contents.set(facts.path, content);
+        files.push(facts.file);
+        symbols.push(...facts.symbols.slice(0, Math.max(0, MAX_CODE_GRAPH_SYMBOLS - symbols.length)));
+        imports.push(...facts.imports);
+    }
+    selection.manifest.cache = { hits: cacheHits, misses: cacheMisses };
+    writeCodeIndexManifest(projectDir, selection.manifest);
     const externalFacts = loadExternalCodeFacts(projectDir);
     const fileByPath = new Map(files.map((file) => [file.path, file]));
     const addSymbol = (symbol) => {
+        if (symbols.length >= MAX_CODE_GRAPH_SYMBOLS)
+            return;
         if (!fileByPath.has(symbol.path))
             return;
         const file = fileByPath.get(symbol.path);
@@ -2173,13 +2422,17 @@ function buildCodeGraph(projectDir) {
     for (const [rel, content] of contents) {
         if (!TS_AST_EXTENSIONS.has(extensionOf(rel)))
             continue;
+        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);
-        calls.push(...extractCalls(rel, content, symbols, symbolByName));
+        calls.push(...extractCalls(rel, content, fileSymbols, symbolByName).slice(0, Math.max(0, MAX_CODE_GRAPH_CALLS - calls.length)));
         routes.push(...extractRoutes(rel, content, fileSymbols));
         tests.push(...extractTests(rel, content, fileSymbols, fileImports));
     }
     for (const call of externalFacts.calls) {
+        if (calls.length >= MAX_CODE_GRAPH_CALLS)
+            break;
         if (!calls.some((existing) => existing.from_symbol === call.from_symbol && existing.to_symbol === call.to_symbol && existing.path === call.path && existing.line === call.line))
             calls.push(call);
     }
@@ -2188,7 +2441,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)),
@@ -2205,20 +2458,22 @@ function buildCodeGraph(projectDir) {
     writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "tests.json"), graph.tests);
     writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "packages.json"), graph.packages);
     writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "graph.json"), graph);
+    graphMemoryCache.delete((0, node_path_1.resolve)(projectDir));
     return graph;
 }
-function buildKnowledgeGraph(projectDir) {
+function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir)) {
     ensureMemoryDirs(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();
     const episodes = [];
     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 +2795,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)),
@@ -2549,13 +2804,12 @@ function buildKnowledgeGraph(projectDir) {
     writeJson((0, node_path_1.join)(graphDir(projectDir), "entities.json"), graph.entities);
     writeJson((0, node_path_1.join)(graphDir(projectDir), "edges.json"), graph.edges);
     writeJson((0, node_path_1.join)(graphDir(projectDir), "graph.json"), graph);
+    graphMemoryCache.delete((0, node_path_1.resolve)(projectDir));
     return graph;
 }
-function buildIndexes(projectDir) {
+function buildPacketIndexes(projectDir) {
     ensureMemoryDirs(projectDir);
     const packets = loadPacketsFromDir(packetsDir(projectDir)).sort((a, b) => a.id.localeCompare(b.id));
-    const knowledgeGraph = buildKnowledgeGraph(projectDir);
-    const codeGraph = buildCodeGraph(projectDir);
     const byPath = {};
     const byTag = {};
     const byType = {};
@@ -2592,14 +2846,111 @@ function buildIndexes(projectDir) {
         (0, node_path_1.join)(indexesDir(projectDir), "by-path.json"),
         (0, node_path_1.join)(indexesDir(projectDir), "by-tag.json"),
         (0, node_path_1.join)(indexesDir(projectDir), "by-type.json"),
-        (0, node_path_1.join)(indexesDir(projectDir), "graph.json"),
-        (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json"),
     ];
     writeJson(written[0], catalog);
     writeJson(written[1], byPath);
     writeJson(written[2], byTag);
     writeJson(written[3], byType);
-    writeJson(written[4], {
+    return written;
+}
+function readCurrentCodeGraph(projectDir, expectedInputHash) {
+    const path = (0, node_path_1.join)(codeGraphDir(projectDir), "graph.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const graph = readJson(path);
+        const inputHash = expectedInputHash ?? codeGraphInputHash(projectDir, codeIndexSelection(projectDir).files);
+        if (graph.repo_state?.input_hash !== inputHash)
+            return null;
+        return graph;
+    }
+    catch {
+        return null;
+    }
+}
+function readCurrentKnowledgeGraph(projectDir, codeGraph, expectedInputHash) {
+    const path = (0, node_path_1.join)(graphDir(projectDir), "graph.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const graph = readJson(path);
+        const inputHash = expectedInputHash ?? knowledgeGraphInputHash(projectDir, codeGraph.repo_state.input_hash ?? codeGraphInputHash(projectDir));
+        if (graph.repo_state?.input_hash !== inputHash)
+            return null;
+        return graph;
+    }
+    catch {
+        return null;
+    }
+}
+function graphFastFingerprint(projectDir, selection = codeIndexSelection(projectDir)) {
+    const packetPaths = (0, node_fs_1.existsSync)(packetsDir(projectDir))
+        ? (0, node_fs_1.readdirSync)(packetsDir(projectDir))
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => (0, node_path_1.join)(packetsDir(projectDir), name))
+        : [];
+    const paths = [
+        ...selection.files,
+        ...externalIndexFiles(projectDir).map((index) => index.path),
+        ...packetPaths,
+    ];
+    const entries = paths
+        .filter((path) => (0, node_fs_1.existsSync)(path))
+        .map((path) => {
+        const stats = (0, node_fs_1.statSync)(path);
+        return `${projectRelative(projectDir, path)}:${stats.size}:${Math.round(stats.mtimeMs)}`;
+    })
+        .sort();
+    return sha256Hex(entries.join("\n"));
+}
+function readCurrentGraphs(projectDir) {
+    const selection = codeIndexSelection(projectDir);
+    const fingerprint = graphFastFingerprint(projectDir, selection);
+    const cacheKey = (0, node_path_1.resolve)(projectDir);
+    const cached = graphMemoryCache.get(cacheKey);
+    if (cached?.fingerprint === fingerprint) {
+        return { codeGraph: cached.codeGraph, knowledgeGraph: cached.knowledgeGraph };
+    }
+    const codeInputHash = codeGraphInputHash(projectDir, selection.files);
+    const knowledgeInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
+    if (cached?.codeInputHash === codeInputHash && cached.knowledgeInputHash === knowledgeInputHash) {
+        cached.fingerprint = fingerprint;
+        return { codeGraph: cached.codeGraph, knowledgeGraph: cached.knowledgeGraph };
+    }
+    const codeGraph = readCurrentCodeGraph(projectDir, codeInputHash);
+    if (!codeGraph)
+        return null;
+    const knowledgeGraph = readCurrentKnowledgeGraph(projectDir, codeGraph, knowledgeInputHash);
+    if (!knowledgeGraph)
+        return null;
+    graphMemoryCache.set(cacheKey, { fingerprint, codeInputHash, knowledgeInputHash, codeGraph, knowledgeGraph });
+    return { codeGraph, knowledgeGraph };
+}
+function currentOrBuildGraphs(projectDir) {
+    const current = readCurrentGraphs(projectDir);
+    if (current?.codeGraph && current.knowledgeGraph) {
+        return {
+            indexes: [
+                (0, node_path_1.join)(indexesDir(projectDir), "catalog.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "by-path.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "by-tag.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "by-type.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "graph.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json"),
+            ],
+            codeGraph: current.codeGraph,
+            knowledgeGraph: current.knowledgeGraph,
+        };
+    }
+    return buildGraphIndexes(projectDir);
+}
+function buildGraphIndexes(projectDir) {
+    const written = buildPacketIndexes(projectDir);
+    const codeGraph = buildCodeGraph(projectDir);
+    const knowledgeGraph = buildKnowledgeGraph(projectDir, codeGraph);
+    const graphIndexPath = (0, node_path_1.join)(indexesDir(projectDir), "graph.json");
+    const codeGraphIndexPath = (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json");
+    writeJson(graphIndexPath, {
         schema_version: knowledgeGraph.schema_version,
         entities: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(graphDir(projectDir), "entities.json")),
         edges: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(graphDir(projectDir), "edges.json")),
@@ -2608,7 +2959,7 @@ function buildIndexes(projectDir) {
         edge_count: knowledgeGraph.edges.length,
         episode_count: knowledgeGraph.episodes.length,
     });
-    writeJson(written[5], {
+    writeJson(codeGraphIndexPath, {
         schema_version: codeGraph.schema_version,
         files: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "files.json")),
         symbols: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "symbols.json")),
@@ -2624,9 +2975,23 @@ function buildIndexes(projectDir) {
         route_count: codeGraph.routes.length,
         test_count: codeGraph.tests.length,
     });
-    return written;
+    graphMemoryCache.set((0, node_path_1.resolve)(projectDir), {
+        fingerprint: graphFastFingerprint(projectDir),
+        codeInputHash: codeGraph.repo_state.input_hash ?? "",
+        knowledgeInputHash: knowledgeGraph.repo_state.input_hash ?? "",
+        codeGraph,
+        knowledgeGraph,
+    });
+    return {
+        indexes: [...written, graphIndexPath, codeGraphIndexPath],
+        codeGraph,
+        knowledgeGraph,
+    };
+}
+function buildIndexes(projectDir) {
+    return buildGraphIndexes(projectDir).indexes;
 }
-function indexProject(projectDir) {
+function indexProjectDetailed(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const policy = installAgentPolicy(projectDir);
     const migrated = migrateLegacyMarkdown(projectDir);
@@ -2636,15 +3001,23 @@ function indexProject(projectDir) {
     const structure = createRepoStructurePacket(projectDir);
     if (structure)
         upsertGeneratedPacket(projectDir, structure);
-    const indexes = buildIndexes(projectDir);
+    const built = options.graphs === false ? null : buildGraphIndexes(projectDir);
+    const indexes = built?.indexes ?? buildPacketIndexes(projectDir);
     return {
-        projectDir,
-        packets: loadPacketsFromDir(packetsDir(projectDir)).length,
-        migrated,
-        indexes: indexes.map((path) => (0, node_path_1.relative)(projectDir, path)),
-        policyPath: (0, node_path_1.relative)(projectDir, policy.path),
+        result: {
+            projectDir,
+            packets: loadPacketsFromDir(packetsDir(projectDir)).length,
+            migrated,
+            indexes: indexes.map((path) => (0, node_path_1.relative)(projectDir, path)),
+            policyPath: (0, node_path_1.relative)(projectDir, policy.path),
+        },
+        codeGraph: built?.codeGraph,
+        knowledgeGraph: built?.knowledgeGraph,
     };
 }
+function indexProject(projectDir, options = {}) {
+    return indexProjectDetailed(projectDir, options).result;
+}
 function staleSuggestedAction(reasons) {
     if (reasons.some((reason) => reason.includes("status is")))
         return "mark_stale";
@@ -2703,11 +3076,20 @@ function refreshPacketStaleness(projectDir) {
     return { findings, updated };
 }
 function refreshProject(projectDir) {
-    const index = indexProject(projectDir);
+    const detailedIndex = indexProjectDetailed(projectDir);
+    const index = detailedIndex.result;
+    let codeGraph = detailedIndex.codeGraph;
+    let knowledgeGraph = detailedIndex.knowledgeGraph;
     const stale = refreshPacketStaleness(projectDir);
-    const indexes = stale.updated > 0 ? buildIndexes(projectDir).map((path) => (0, node_path_1.relative)(projectDir, path)) : index.indexes;
+    let indexes = index.indexes;
+    if (stale.updated > 0) {
+        const rebuilt = buildGraphIndexes(projectDir);
+        codeGraph = rebuilt.codeGraph;
+        knowledgeGraph = rebuilt.knowledgeGraph;
+        indexes = rebuilt.indexes.map((path) => (0, node_path_1.relative)(projectDir, path));
+    }
     const validation = validateProject(projectDir);
-    const metrics = kageMetrics(projectDir);
+    const metrics = kageMetricsShallow(projectDir, { codeGraph, knowledgeGraph, validation });
     const nextActions = [];
     if (stale.findings.length)
         nextActions.push("Update, verify, or supersede stale repo memories before relying on them.");
@@ -2781,9 +3163,8 @@ function gcProject(projectDir, options = {}) {
         }
     }
     if (!options.dryRun && (deprecated.length || deleted.length)) {
-        buildIndexes(projectDir);
-        buildKnowledgeGraph(projectDir);
-        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetrics(projectDir));
+        const rebuilt = buildGraphIndexes(projectDir);
+        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetricsShallow(projectDir, rebuilt));
     }
     return {
         ok: true,
@@ -3032,11 +3413,29 @@ function recallIntentBoost(queryTerms, packet) {
         score += packet.type === "decision" ? 12 : 0;
     return score;
 }
-function recallBreakdown(projectDir, terms, packet, textScore) {
-    const graph = buildKnowledgeGraph(projectDir);
-    const packetEntityId = graph.entities.find((entity) => entity.type === "memory" && entity.aliases.includes(packet.id))?.id;
+function recallGraphLookup(graph) {
+    const packetEntityByPacketId = new Map();
+    for (const entity of graph.entities) {
+        if (entity.type !== "memory")
+            continue;
+        for (const alias of entity.aliases)
+            packetEntityByPacketId.set(alias, entity.id);
+    }
+    const edgesByEntityId = new Map();
+    for (const edge of graph.edges) {
+        const from = edgesByEntityId.get(edge.from) ?? [];
+        from.push(edge);
+        edgesByEntityId.set(edge.from, from);
+        const to = edgesByEntityId.get(edge.to) ?? [];
+        to.push(edge);
+        edgesByEntityId.set(edge.to, to);
+    }
+    return { packetEntityByPacketId, edgesByEntityId };
+}
+function recallBreakdown(projectDir, terms, packet, textScore, graph = buildKnowledgeGraph(projectDir), lookup = recallGraphLookup(graph)) {
+    const packetEntityId = lookup.packetEntityByPacketId.get(packet.id);
     const rawGraphScore = packetEntityId
-        ? graph.edges.filter((edge) => edge.from === packetEntityId || edge.to === packetEntityId).reduce((sum, edge) => sum + scoreText(terms, edge.fact), 0)
+        ? (lookup.edgesByEntityId.get(packetEntityId) ?? []).reduce((sum, edge) => sum + scoreText(terms, edge.fact), 0)
         : 0;
     const graphScore = Math.min(rawGraphScore * 0.45, textScore > 0 ? textScore * 1.5 + 12 : 8);
     const pathTypeTag = scoreText(terms, `${packet.type} ${packet.tags.join(" ")} ${packet.paths.join(" ")}`, [packet.type, ...packet.tags, ...packet.paths]);
@@ -3048,15 +3447,19 @@ function recallBreakdown(projectDir, terms, packet, textScore) {
     const final = Number((textScore + graphScore + pathTypeTag * 0.8 + intent + vector + freshness + quality + feedback).toFixed(2));
     return { bm25: textScore, text: textScore, graph: Number(graphScore.toFixed(2)), path_type_tag: pathTypeTag, intent, vector, freshness, quality: Number(quality.toFixed(2)), feedback, final };
 }
-function recall(projectDir, query, limit = 5, explain = false) {
-    indexProject(projectDir);
+function recall(projectDir, query, limit = 5, explain = false, inputs = {}) {
+    const current = inputs.codeGraph && inputs.knowledgeGraph ? null : readCurrentGraphs(projectDir);
+    const detailedIndex = inputs.codeGraph && inputs.knowledgeGraph || current ? null : indexProjectDetailed(projectDir);
+    const codeGraph = inputs.codeGraph ?? current?.codeGraph ?? detailedIndex?.codeGraph ?? buildCodeGraph(projectDir);
+    const knowledgeGraph = inputs.knowledgeGraph ?? current?.knowledgeGraph ?? detailedIndex?.knowledgeGraph ?? buildKnowledgeGraph(projectDir, codeGraph);
     const terms = tokenize(query);
     const approvedPackets = loadApprovedPackets(projectDir);
     const lexicalScores = scorePacketsBm25(terms, approvedPackets);
+    const graphLookup = recallGraphLookup(knowledgeGraph);
     const scored = approvedPackets
         .map((packet) => {
         const { score, why } = lexicalScores.get(packet.id) ?? { score: 0, why: [] };
-        const score_breakdown = recallBreakdown(projectDir, terms, packet, score);
+        const score_breakdown = recallBreakdown(projectDir, terms, packet, score, knowledgeGraph, graphLookup);
         const relevance = score + score_breakdown.graph + score_breakdown.path_type_tag + score_breakdown.intent + score_breakdown.vector;
         return { packet, score: score_breakdown.final, relevance, why_matched: why, score_breakdown };
     })
@@ -3082,8 +3485,8 @@ function recall(projectDir, query, limit = 5, explain = false) {
         return true;
     })
         .slice(0, 3);
-    const graphContext = queryGraph(projectDir, query, 5);
-    const codeContext = queryCodeGraph(projectDir, query, 5);
+    const graphContext = queryGraph(projectDir, query, 5, knowledgeGraph);
+    const codeContext = queryCodeGraph(projectDir, query, 5, codeGraph);
     const lines = [
         `# Kage Context`,
         "",
@@ -3151,8 +3554,8 @@ function scoreText(terms, text, boosts = []) {
         score += 3;
     return score;
 }
-function queryCodeGraph(projectDir, query, limit = 10) {
-    const graph = buildCodeGraph(projectDir);
+function queryCodeGraph(projectDir, query, limit = 10, graph) {
+    graph = graph ?? readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const terms = tokenize(query);
     const files = graph.files
         .map((file) => ({ file, score: scoreText(terms, `${file.path} ${file.kind} ${file.language} ${file.parser}`, [file.path, file.language]) }))
@@ -3216,8 +3619,8 @@ function queryCodeGraph(projectDir, query, limit = 10) {
     ];
     return { query, context_block: lines.join("\n"), files, symbols, imports: imports.map((entry) => entry.item), calls, routes, tests };
 }
-function queryGraph(projectDir, query, limit = 10) {
-    const graph = buildKnowledgeGraph(projectDir);
+function queryGraph(projectDir, query, limit = 10, graph) {
+    graph = graph ?? readCurrentGraphs(projectDir)?.knowledgeGraph ?? buildKnowledgeGraph(projectDir);
     const terms = tokenize(query);
     const entityScores = new Map();
     for (const entity of graph.entities) {
@@ -3263,7 +3666,7 @@ function mermaidLabel(value) {
     return value.replace(/["\n\r]/g, " ").slice(0, 80);
 }
 function graphMermaid(projectDir, limit = 40) {
-    const graph = buildKnowledgeGraph(projectDir);
+    const graph = readCurrentGraphs(projectDir)?.knowledgeGraph ?? buildKnowledgeGraph(projectDir);
     const selectedEdges = graph.edges.slice(0, limit);
     const selectedEntityIds = new Set(selectedEdges.flatMap((edge) => [edge.from, edge.to]));
     const selectedEntities = graph.entities.filter((entity) => selectedEntityIds.has(entity.id));
@@ -3287,17 +3690,19 @@ function percent(numerator, denominator) {
 }
 function kageMetrics(projectDir) {
     ensureMemoryDirs(projectDir);
-    const codeGraph = buildCodeGraph(projectDir);
-    const knowledgeGraph = buildKnowledgeGraph(projectDir);
+    const built = currentOrBuildGraphs(projectDir);
+    const codeGraph = built.codeGraph;
+    const knowledgeGraph = built.knowledgeGraph;
     const validation = validateProject(projectDir);
     const approvedPackets = loadPacketsFromDir(packetsDir(projectDir)).length;
     const pendingPackets = loadPacketsFromDir(pendingDir(projectDir)).length;
     const evidenceBackedEdges = knowledgeGraph.edges.filter((edge) => edge.evidence.length > 0).length;
     const policyPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const policyInstalled = (0, node_fs_1.existsSync)(policyPath) && (0, node_fs_1.readFileSync)(policyPath, "utf8").includes(AGENTS_POLICY_MARKER);
+    const indexManifest = readCodeIndexManifest(projectDir);
     const sourceFiles = codeGraph.files.filter((file) => file.kind === "source" || file.kind === "test");
     const indexedSourceFiles = sourceFiles.filter((file) => file.parser !== "metadata");
-    const coverage = percent(indexedSourceFiles.length, sourceFiles.length);
+    const coverage = indexManifest.coverage.indexable_files > 0 ? indexManifest.coverage.coverage_percent : percent(indexedSourceFiles.length, sourceFiles.length);
     const allPackets = [...loadPacketsFromDir(packetsDir(projectDir)), ...loadPacketsFromDir(pendingDir(projectDir))];
     const qualityScores = allPackets
         .map((packet) => Number(packet.quality.score ?? evaluateMemoryQuality(projectDir, packet).score))
@@ -3319,7 +3724,7 @@ function kageMetrics(projectDir) {
         (validation.ok ? 5 : -20) -
         validation.warnings.length * 2)));
     const quality = qualityReport(projectDir);
-    const benchmark = benchmarkProject(projectDir);
+    const benchmark = benchmarkProject(projectDir, { codeGraph, knowledgeGraph });
     return {
         schema_version: 1,
         project_dir: projectDir,
@@ -3337,6 +3742,13 @@ function kageMetrics(projectDir) {
             parsers: countBy(codeGraph.files, (file) => file.parser),
             source_symbols_by_parser: countBy(codeGraph.symbols, (symbol) => symbol.parser),
             indexer_coverage_percent: coverage,
+            index_status: indexManifest.coverage.complete ? "complete" : "partial",
+            indexable_files: indexManifest.coverage.indexable_files || sourceFiles.length,
+            indexed_files: indexManifest.coverage.indexed_files || indexedSourceFiles.length,
+            deferred_files: indexManifest.coverage.deferred_files,
+            ignored_files: indexManifest.coverage.ignored_files,
+            cache_hits: indexManifest.cache.hits,
+            cache_misses: indexManifest.cache.misses,
         },
         memory_graph: {
             approved_packets: approvedPackets,
@@ -3379,8 +3791,9 @@ function auditProject(projectDir) {
     ensureMemoryDirs(projectDir);
     const validation = validateProject(projectDir);
     const quality = qualityReport(projectDir);
-    const codeGraph = buildCodeGraph(projectDir);
-    const knowledgeGraph = buildKnowledgeGraph(projectDir);
+    const built = currentOrBuildGraphs(projectDir);
+    const codeGraph = built.codeGraph;
+    const knowledgeGraph = built.knowledgeGraph;
     const approved = loadApprovedPackets(projectDir);
     const pending = loadPendingPackets(projectDir);
     const structuredPackets = approved.filter(hasStructuredEngineeringContext);
@@ -3629,8 +4042,11 @@ function qualityReport(projectDir) {
         packets: rows,
     };
 }
-function benchmarkProject(projectDir) {
+function benchmarkProject(projectDir, inputs = {}) {
     ensureMemoryDirs(projectDir);
+    const built = inputs.codeGraph && inputs.knowledgeGraph ? null : currentOrBuildGraphs(projectDir);
+    const codeGraph = inputs.codeGraph ?? built?.codeGraph;
+    const knowledgeGraph = inputs.knowledgeGraph ?? built?.knowledgeGraph;
     const scenarios = [
         { query: "how do I run tests", expected: "test" },
         { query: "where are routes defined", expected: "route" },
@@ -3638,7 +4054,7 @@ function benchmarkProject(projectDir) {
         { query: "what changed on this branch", expected: "branch" },
         { query: "what gotchas exist", expected: "gotcha" },
     ].map((scenario) => {
-        const result = recall(projectDir, scenario.query, 5, true);
+        const result = recall(projectDir, scenario.query, 5, true, { codeGraph, knowledgeGraph });
         const text = `${result.context_block}\n${result.results.map((entry) => packetText(entry.packet)).join("\n")}`.toLowerCase();
         return {
             query: scenario.query,
@@ -3649,7 +4065,7 @@ function benchmarkProject(projectDir) {
             context_tokens: estimateTokens(result.context_block),
         };
     });
-    const metrics = kageMetricsShallow(projectDir);
+    const metrics = kageMetricsShallow(projectDir, { codeGraph, knowledgeGraph });
     const quality = qualityReport(projectDir);
     const typeCoverage = quality.memory_type_coverage;
     const recallHitRate = percent(scenarios.filter((scenario) => scenario.hit).length, scenarios.length);
@@ -3813,13 +4229,14 @@ function benchmarkTaskComparison(projectDir, task) {
         ],
     };
 }
-function kageMetricsShallow(projectDir) {
-    const codeGraph = buildCodeGraph(projectDir);
-    const knowledgeGraph = buildKnowledgeGraph(projectDir);
-    const validation = validateProject(projectDir);
+function kageMetricsShallow(projectDir, inputs = {}) {
+    const codeGraph = inputs.codeGraph ?? buildCodeGraph(projectDir);
+    const knowledgeGraph = inputs.knowledgeGraph ?? buildKnowledgeGraph(projectDir, codeGraph);
+    const validation = inputs.validation ?? validateProject(projectDir);
+    const indexManifest = readCodeIndexManifest(projectDir);
     const sourceFiles = codeGraph.files.filter((file) => file.kind === "source" || file.kind === "test");
     const indexedSourceFiles = sourceFiles.filter((file) => file.parser !== "metadata");
-    const coverage = percent(indexedSourceFiles.length, sourceFiles.length);
+    const coverage = indexManifest.coverage.indexable_files > 0 ? indexManifest.coverage.coverage_percent : percent(indexedSourceFiles.length, sourceFiles.length);
     const allPackets = [...loadPacketsFromDir(packetsDir(projectDir)), ...loadPacketsFromDir(pendingDir(projectDir))];
     const indexedSourceTokens = Math.ceil(sourceFiles.reduce((sum, file) => sum + file.size_bytes, 0) / 4);
     const memoryTokens = allPackets.reduce((sum, packet) => sum + estimateTokens(packetText(packet)), 0);
@@ -3841,6 +4258,13 @@ function kageMetricsShallow(projectDir) {
             parsers: countBy(codeGraph.files, (file) => file.parser),
             source_symbols_by_parser: countBy(codeGraph.symbols, (symbol) => symbol.parser),
             indexer_coverage_percent: coverage,
+            index_status: indexManifest.coverage.complete ? "complete" : "partial",
+            indexable_files: indexManifest.coverage.indexable_files || sourceFiles.length,
+            indexed_files: indexManifest.coverage.indexed_files || indexedSourceFiles.length,
+            deferred_files: indexManifest.coverage.deferred_files,
+            ignored_files: indexManifest.coverage.ignored_files,
+            cache_hits: indexManifest.cache.hits,
+            cache_misses: indexManifest.cache.misses,
         },
         memory_graph: {
             approved_packets: loadPacketsFromDir(packetsDir(projectDir)).length,
@@ -4239,7 +4663,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 +5387,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 +5436,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 +5448,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 +5458,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/"))) {
@@ -5516,9 +5950,9 @@ function installClaudeSettings(projectDir) {
 function initProject(projectDir) {
     installAgentPolicy(projectDir);
     installClaudeSettings(projectDir);
-    const index = indexProject(projectDir);
+    const index = indexProject(projectDir, { graphs: false });
     const validation = validateProject(projectDir);
-    const sampleRecall = recall(projectDir, "how do I run tests");
+    const sampleRecall = recallFromPackets("how do I run tests", loadApprovedPackets(projectDir), 5, "Repo Memory");
     return { index, validation, sampleRecall };
 }
 function doctorProject(projectDir) {

package/package.json

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

package/viewer/app.js

@@ -112,6 +112,7 @@
   };
 
   var MEMORY_CODE_RELATIONS = new Set(["explains_symbol", "informs_symbol", "fixes_symbol", "applies_to_route", "verified_by_test", "affects_path"]);
+  var INSPECTOR_CONNECTION_LIMIT = 8;
 
   els.graphFile.addEventListener("change", handleFile);
   els.searchInput.addEventListener("input", scheduleRender);
@@ -1373,6 +1374,97 @@
     els.selectionDetails.appendChild(title);
     els.selectionDetails.appendChild(kind);
     els.selectionDetails.appendChild(rows);
+    renderInspectorConnections(item);
+  }
+
+  function renderInspectorConnections(item) {
+    if (state.selected.kind !== "entity") {
+      if (item && isMemoryCodeEdge(item)) {
+        els.selectionDetails.appendChild(detailSection("Memory-Code Link", [
+          connectionText(item, state.entityById.get(item.from), state.entityById.get(item.to))
+        ], 0));
+      }
+      return;
+    }
+
+    var links = memoryCodeConnections(item.id);
+    if (!links.length) return;
+    var rows = links.slice(0, INSPECTOR_CONNECTION_LIMIT).map(function (link) {
+      return connectionText(link.edge, item, link.other);
+    });
+    els.selectionDetails.appendChild(detailSection("Memory-Code Evidence", rows, links.length - rows.length));
+  }
+
+  function memoryCodeConnections(entityId) {
+    return state.edges
+      .filter(function (edge) { return isMemoryCodeEdge(edge) && (edge.from === entityId || edge.to === entityId); })
+      .map(function (edge) {
+        var otherId = edge.from === entityId ? edge.to : edge.from;
+        return { edge: edge, other: state.entityById.get(otherId) };
+      })
+      .filter(function (link) { return Boolean(link.other); })
+      .sort(function (a, b) {
+        return connectionImportance(b) - connectionImportance(a) ||
+          displayName(a.other).localeCompare(displayName(b.other));
+      });
+  }
+
+  function isMemoryCodeEdge(edge) {
+    return Boolean(edge && (edge.memory_code_link || isMemoryCodeRelation(edge.relation)));
+  }
+
+  function connectionImportance(link) {
+    var relation = String(link.edge.relation || "");
+    var score = entityImportance(link.other);
+    if (["fixes_symbol", "verified_by_test"].indexOf(relation) !== -1) score += 36;
+    if (["explains_symbol", "applies_to_route"].indexOf(relation) !== -1) score += 24;
+    if (link.other.graph_kind === "memory") score += 18;
+    return score;
+  }
+
+  function connectionText(edge, selected, other) {
+    var from = state.entityById.get(edge.from);
+    var to = state.entityById.get(edge.to);
+    var peer = other || (selected && selected.id === edge.from ? to : from);
+    var label = peer ? displayName(peer) : displayName(from) + " -> " + displayName(to);
+    var meta = [edge.relation || "related", peer && (peer.graph_kind || peer.type)].filter(Boolean).join(" | ");
+    return {
+      label: label,
+      meta: meta,
+      body: edge.fact || "",
+      edge: edge,
+      entity: peer
+    };
+  }
+
+  function detailSection(title, items, hiddenCount) {
+    var section = document.createElement("section");
+    section.className = "detail-section";
+    var heading = document.createElement("div");
+    heading.className = "detail-section-title";
+    heading.textContent = title;
+    section.appendChild(heading);
+    items.forEach(function (item) {
+      var button = document.createElement("button");
+      button.type = "button";
+      button.className = "detail-link";
+      button.innerHTML = "<span class=\"detail-link-title\"></span><span class=\"detail-link-meta\"></span><span class=\"detail-link-body\"></span>";
+      button.querySelector(".detail-link-title").textContent = item.label;
+      button.querySelector(".detail-link-meta").textContent = item.meta;
+      button.querySelector(".detail-link-body").textContent = item.body;
+      button.addEventListener("click", function () {
+        state.selected = item.entity ? { kind: "entity", id: item.entity.id } : { kind: "edge", id: item.edge.id };
+        render();
+      });
+      section.appendChild(button);
+    });
+    if (hiddenCount > 0) {
+      var more = document.createElement("div");
+      more.className = "detail-more";
+      more.textContent = "+" + hiddenCount + " more connected items hidden to keep the graph readable.";
+      section.appendChild(more);
+    }
+    return section;
   }
 
   function detailRow(label, value) {
@@ -1727,7 +1819,6 @@
     var node = findCanvasNode(world.x, world.y);
     if (!node) return;
     state.selected = { kind: "entity", id: node.id };
-    els.scopeFilter.value = "focus";
     render();
   }
 

package/viewer/index.html

@@ -86,21 +86,14 @@
             <option value="">All relations</option>
           </select>
         </label>
-        <label>
-          <span>Scope</span>
-          <select id="scopeFilter">
-            <option value="signal">High signal</option>
-            <option value="focus">Focus selection</option>
-            <option value="all">Everything</option>
-          </select>
-        </label>
+        <input id="scopeFilter" type="hidden" value="signal">
         <label>
           <span>Max Nodes</span>
           <select id="maxNodes">
             <option value="60">60</option>
             <option value="90" selected>90</option>
             <option value="140">140</option>
-            <option value="9999">All</option>
+            <option value="220">220</option>
           </select>
         </label>
         <label class="toggle-control">

package/viewer/styles.css

@@ -435,6 +435,55 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
 .detail-row { padding: 9px 0; border-top: 1px solid var(--line); }
 .detail-row dt { margin: 0 0 4px; color: var(--terminal-dim); font-size: 11px; font-weight: 760; text-transform: uppercase; }
 .detail-row dd { margin: 0; color: var(--text); overflow-wrap: anywhere; white-space: pre-wrap; }
+.detail-section {
+  margin-top: 12px;
+  padding-top: 12px;
+  border-top: 1px solid var(--line);
+}
+.detail-section-title {
+  margin-bottom: 8px;
+  color: var(--terminal-dim);
+  font-size: 11px;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+.detail-link {
+  width: 100%;
+  display: grid;
+  gap: 4px;
+  min-height: 0;
+  margin-top: 8px;
+  padding: 9px;
+  border-color: rgba(216, 255, 95, 0.28);
+  background: rgba(216, 255, 95, 0.045);
+  color: var(--text);
+  text-align: left;
+  white-space: normal;
+  box-shadow: none;
+}
+.detail-link:hover { background: rgba(216, 255, 95, 0.085); }
+.detail-link-title {
+  color: var(--terminal);
+  font-weight: 820;
+  overflow-wrap: anywhere;
+}
+.detail-link-meta {
+  color: var(--warn);
+  font-size: 10px;
+  font-weight: 760;
+  text-transform: uppercase;
+  overflow-wrap: anywhere;
+}
+.detail-link-body {
+  color: var(--muted);
+  font-size: 11px;
+  overflow-wrap: anywhere;
+}
+.detail-more {
+  margin-top: 9px;
+  color: var(--terminal-dim);
+  font-size: 11px;
+}
 
 .entities-panel { grid-area: entities; }
 .edges-panel { grid-area: edges; }