@kage-core/kage-graph-mcp 1.1.20 → 1.1.21

package/README.md

@@ -9,7 +9,17 @@ This package exposes two surfaces:
 
 ## Latest Release
 
-`1.1.20` publishes the large-repo indexing pass:
+`1.1.21` publishes the memory-code graph quality pass:
+
+- precise memory-code links now require explicit, non-generic symbol/test
+  mentions instead of broad path-only matches.
+- generated memory symbol/route/test entities no longer carry file path aliases
+  that can collapse stale graph nodes onto code file hubs.
+- the viewer's `Memory <-> Code only` relation shows actual cross-graph links,
+  while path-level memory still appears through capped `affects_code_path`
+  bridge edges.
+
+`1.1.20` published the large-repo indexing pass:
 
 - repeated `kage refresh` calls reuse unchanged code graph artifacts by source
   stat fingerprint, with `kage refresh --full` available for intentional clean
@@ -169,26 +179,44 @@ The graph builder writes evidence-backed graph artifacts under
   and memory type entities.
 - `edges.json`: typed facts such as `contains_memory`, `affects_path`,
   `mentions_tag`, `uses_package`, `documents_command`, and `defines_command`.
-- `graph.json`: the assembled graph with branch, head, and merge-base metadata.
+- `graph.json`: compact graph metadata plus references to the split graph files.
+
+In the viewer, path-level memory such as `affects_path: src` is bridged to a
+small representative set of matching code files at render time. This keeps the
+stored graph compact while still making broad repo memories visibly connected
+to the code graph.
 
 The code graph builder writes source-derived artifacts under
-`.agent_memory/code_graph/`:
-
-- `files.json`: source, test, config, manifest, and doc files, including
-  language and parser metadata.
-- `symbols.json`: functions, classes, constants, and test cases.
-- `imports.json`: local and external import edges.
-- `calls.json`: best-effort call edges between discovered symbols.
-- `routes.json`: best-effort Node/Express/Next route facts.
-- `tests.json`: test-to-symbol/file coverage hints.
-- `packages.json`: package scripts and dependencies.
-- `graph.json`: the assembled code graph.
+`.agent_memory/code_graph/`. `graph.json` is now a compact compatibility
+artifact: it keeps repo state plus calls, routes, tests, and packages inline, and
+references the canonical structural `files.json`, `symbols.json`, and
+`imports.json` instead of duplicating them.
 
 The code graph is multi-language by design. JS/TS/JSX/TSX files use the
 TypeScript compiler API for AST-backed symbols, imports, and call hints. Python,
 Go, Rust, Java, Kotlin, Ruby, PHP, C#, C/C++, and Swift use deterministic generic
 static extractors so every repo gets a useful graph immediately.
 
+For large repos, refresh also writes a complete structural index under
+`.agent_memory/structural/`:
+
+- `files.json`: every supported source/config/doc file, including files the
+  code graph represents as metadata-only because they are too large to parse.
+- `symbols.json`: extracted functions, classes, constants, routes, and tests.
+- `edges.json`: file-to-symbol and file-to-import edges with confidence labels.
+- `manifest.json`: mtime/hash entries, cache hits/misses, ignored files, and
+  deleted-file tracking.
+- `file-cache.json`: packed per-file structural facts keyed by source content
+  hash. Refresh migrates older `.agent_memory/structural/file-cache/*.json`
+  layouts and removes stale per-file cache entries.
+- `report.md`: a compact language/concept coverage report.
+
+This follows the same shape as fast graph indexers such as Graphify: discover
+files, skip generated/vendor paths, use a per-file content cache, parallelize
+extraction on large repos, rebuild only changed files, and keep generated
+structural facts separate from learned memory. Use `.kageignore` for
+repo-specific excludes.
+
 Kage also consumes external industry indexer artifacts when present:
 
 - `.agent_memory/code_index/tree-sitter.json`

package/dist/cli.js

@@ -39,6 +39,7 @@ Usage:
   kage code-graph --project <dir> [--json]
   kage code-graph "<query>" --project <dir> [--json]
   kage code-index --project <dir> [--json]
+  kage structural-index --project <dir> [--json]
   kage graph --project <dir> [--json]
   kage graph --project <dir> --mermaid
   kage graph "<query>" --project <dir> [--json]
@@ -529,6 +530,22 @@ async function main() {
         }
         return;
     }
+    if (command === "structural-index") {
+        const result = (0, kernel_js_1.buildStructuralIndex)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage Structural Index: ${result.manifest.project_dir}`);
+        console.log(`Files: ${result.files.length}`);
+        console.log(`Symbols: ${result.symbols.length}`);
+        console.log(`Edges: ${result.edges.length}`);
+        console.log(`Metadata-only files: ${result.manifest.files.metadata_only}`);
+        console.log(`Cache: ${result.manifest.cache.hits} hits, ${result.manifest.cache.misses} misses`);
+        console.log(`Workers: ${result.manifest.worker_count}`);
+        console.log(`Path: .agent_memory/structural`);
+        return;
+    }
     if (command === "branch") {
         const result = (0, kernel_js_1.buildBranchOverlay)(projectArg(args));
         if (args.includes("--json"))
@@ -562,6 +579,13 @@ async function main() {
         console.log(`  Indexer coverage: ${result.code_graph.indexer_coverage_percent}%`);
         console.log(`  Languages: ${Object.entries(result.code_graph.languages).map(([name, count]) => `${name}=${count}`).join(", ") || "(none)"}`);
         console.log(`  Parsers: ${Object.entries(result.code_graph.parsers).map(([name, count]) => `${name}=${count}`).join(", ") || "(none)"}`);
+        console.log("\nStructural index:");
+        console.log(`  Files: ${result.structural_index.files}`);
+        console.log(`  Symbols: ${result.structural_index.symbols}`);
+        console.log(`  Edges: ${result.structural_index.edges}`);
+        console.log(`  Metadata-only files: ${result.structural_index.metadata_only_files}`);
+        console.log(`  Workers: ${result.structural_index.worker_count}`);
+        console.log(`  Cache: ${result.structural_index.cache_hits} hits, ${result.structural_index.cache_misses} misses`);
         console.log("\nMemory graph:");
         console.log(`  Approved packets: ${result.memory_graph.approved_packets}`);
         console.log(`  Pending packets: ${result.memory_graph.pending_packets}`);
@@ -604,7 +628,7 @@ async function main() {
         console.log(`Memory inbox: ${result.checks.memory_inbox.approved_packets} approved, ${result.checks.memory_inbox.pending_packets} pending, ${result.checks.memory_inbox.stale_packets} stale`);
         console.log(`Structured memory: ${result.checks.structured_memory.structured_packets}/${result.checks.structured_memory.total_packets} (${result.checks.structured_memory.coverage_percent}%)`);
         console.log(`Code graph precision: ${result.checks.code_graph.precise_files}/${result.checks.code_graph.files} precise (${result.checks.code_graph.precise_coverage_percent}%), ${result.checks.code_graph.ast_files} AST, ${result.checks.code_graph.fallback_files} fallback`);
-        console.log(`Memory-code graph edges: ${result.checks.graph_links.memory_code_edges}`);
+        console.log(`Memory-code graph edges: ${result.checks.graph_links.memory_code_edges} (${result.checks.graph_links.precise_memory_code_edges} precise, ${result.checks.graph_links.path_memory_code_edges} path)`);
         if (result.recommendations.length) {
             console.log("\nRecommendations:");
             for (const recommendation of result.recommendations)

package/dist/daemon.js

@@ -249,12 +249,15 @@ async function startViewer(projectDir, options = {}) {
     catch {
         // non-fatal: viewer will show 404 for reports if generation fails
     }
-    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}`;
+    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}&view=code`;
     const server = (0, node_http_1.createServer)((req, res) => {
         const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
         let filePath = null;
         if (requestUrl.pathname === "/" || requestUrl.pathname === "/viewer") {
-            filePath = (0, node_path_1.join)(viewerDir, "index.html");
+            const viewerSearch = requestUrl.search || new URL(url).search;
+            res.writeHead(302, { location: `/viewer/index.html${viewerSearch}` });
+            res.end();
+            return;
         }
         else if (requestUrl.pathname.startsWith("/viewer/")) {
             filePath = (0, node_path_1.join)(viewerDir, (0, node_path_1.normalize)(requestUrl.pathname.replace(/^\/viewer\//, "")));

package/dist/index.js

@@ -183,6 +183,17 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_structural_index",
+            description: "Build the complete cache-backed structural index for large repos. This covers all supported source/config/doc files and writes .agent_memory/structural artifacts separate from learned memory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_metrics",
             description: "Return concise Kage adoption and quality metrics: code graph counts, language/parser coverage, memory graph evidence coverage, pending/approved packets, validation state, and readiness score.",
@@ -732,6 +743,12 @@ async function callTool(name, args) {
             isError: !result.ok,
         };
     }
+    if (name === "kage_structural_index") {
+        const result = (0, kernel_js_1.buildStructuralIndex)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_metrics") {
         const result = (0, kernel_js_1.kageMetrics)(String(args?.project_dir ?? ""));
         return {