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

package/README.md

@@ -9,18 +9,16 @@ 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.20` publishes 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
+  rebuilds.
+- `kage code-index` prefers SCIP via `scip-typescript` plus the `scip` CLI when
+  those tools are installed, then falls back to Kage's built-in LSP-compatible
+  symbol index.
+- read-only commands and MCP sessions reuse current graph artifacts instead of
+  rebuilding them when inputs are fresh.
 
 `1.1.17` publishes content-based graph freshness:
 
@@ -116,6 +114,7 @@ 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 refresh --project /path/to/repo --full
 kage branch --project /path/to/repo
 kage code-index --project /path/to/repo
 kage code-graph --project /path/to/repo
@@ -206,11 +205,13 @@ generic extraction in metrics and file parser coverage. This keeps installation
 light while allowing teams to plug in the strongest indexer available for their
 language stack.
 
-`kage code-index --project <repo>` writes `.agent_memory/code_index/lsp-symbols.json`
-in an LSP document-symbol-compatible shape using Kage's local parser. The CI,
+`kage code-index --project <repo>` now tries the best external indexer first for
+the common JS/TS case: if `scip-typescript` and the `scip` CLI are on the repo or
+shell path, it writes `.agent_memory/code_index/scip.json` from the generated
+SCIP index. If those tools are unavailable, it writes
+`.agent_memory/code_index/lsp-symbols.json` using Kage's local parser. The CI,
 PR, and sync workflows run it before refresh so the code graph has a committed
-precise-index slot while teams can still replace or augment it with SCIP/LSIF
-artifacts from their preferred toolchain.
+precise-index slot without making first-run setup depend on external binaries.
 
 The memory graph follows the same product direction as temporal context graph
 systems such as Graphiti: immutable ingestion episodes, derived entities and
@@ -258,7 +259,9 @@ Use `kage refresh --project <repo>` or the `kage_refresh` MCP tool after
 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.
+and empty/same-tree commits do not need another refresh. Use `--full` or
+`kage_refresh` with `full: true` only when you intentionally want to bypass
+unchanged-graph reuse and rebuild the code graph from scratch.
 
 Use `kage gc --project <repo> --dry-run` to preview stale packet cleanup.
 `kage gc --project <repo>` marks stale repo packets deprecated, rebuilds

package/dist/cli.js

@@ -24,7 +24,7 @@ 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 refresh --project <dir> [--full] [--json]
   kage gc --project <dir> [--dry-run] [--force] [--json]
   kage pr summarize --project <dir> [--json]
   kage pr check --project <dir> [--json]
@@ -335,7 +335,7 @@ async function main() {
         return;
     }
     if (command === "refresh") {
-        const result = (0, kernel_js_1.refreshProject)(projectArg(args));
+        const result = (0, kernel_js_1.refreshProject)(projectArg(args), { full: args.includes("--full") });
         if (args.includes("--json")) {
             console.log(JSON.stringify(result, null, 2));
             if (!result.ok)
@@ -506,7 +506,7 @@ async function main() {
         return;
     }
     if (command === "code-index") {
-        const result = (0, kernel_js_1.writeLspSymbolIndex)(projectArg(args));
+        const result = (0, kernel_js_1.writeCodeIndex)(projectArg(args));
         if (args.includes("--json")) {
             console.log(JSON.stringify(result, null, 2));
             return;
@@ -516,6 +516,11 @@ async function main() {
         console.log(`Path: ${result.path}`);
         console.log(`Documents: ${result.documents}`);
         console.log(`Symbols: ${result.symbols}`);
+        if (result.warnings.length) {
+            console.log("\nWarnings:");
+            for (const warning of result.warnings)
+                console.log(`  - ${warning}`);
+        }
         if (result.errors.length) {
             console.log("\nErrors:");
             for (const error of result.errors)

package/dist/index.js

@@ -153,6 +153,7 @@ function listTools() {
                 type: "object",
                 properties: {
                     project_dir: { type: "string" },
+                    full: { type: "boolean", description: "Force a full code graph rebuild instead of reusing unchanged graph artifacts." },
                 },
                 required: ["project_dir"],
             },
@@ -173,7 +174,7 @@ function listTools() {
         },
         {
             name: "kage_code_index",
-            description: "Write .agent_memory/code_index/lsp-symbols.json, an LSP-compatible symbol artifact consumed by the code graph for higher parser coverage.",
+            description: "Write external code index artifacts consumed by the code graph. Prefers SCIP when scip-typescript and scip are installed, then falls back to the built-in LSP-compatible symbol index.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -725,7 +726,7 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_code_index") {
-        const result = (0, kernel_js_1.writeLspSymbolIndex)(String(args?.project_dir ?? ""));
+        const result = (0, kernel_js_1.writeCodeIndex)(String(args?.project_dir ?? ""));
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             isError: !result.ok,
@@ -752,7 +753,7 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_refresh") {
-        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""));
+        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""), { full: Boolean(args?.full) });
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             isError: !result.ok,

package/dist/kernel.js

@@ -64,6 +64,7 @@ exports.ensureMemoryDirs = ensureMemoryDirs;
 exports.loadApprovedPackets = loadApprovedPackets;
 exports.loadPendingPackets = loadPendingPackets;
 exports.writeLspSymbolIndex = writeLspSymbolIndex;
+exports.writeCodeIndex = writeCodeIndex;
 exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
@@ -1522,6 +1523,36 @@ function readCodeIndexManifest(projectDir) {
 function listCodeFiles(projectDir) {
     return codeIndexSelection(projectDir).files;
 }
+function codeGraphStatFingerprint(projectDir, absoluteFiles) {
+    const entries = [
+        ...absoluteFiles,
+        ...externalIndexFiles(projectDir).map((index) => index.path),
+        ...["package.json", "requirements.txt", "go.mod", "Cargo.toml"]
+            .map((path) => (0, node_path_1.join)(projectDir, path))
+            .filter((path) => (0, node_fs_1.existsSync)(path)),
+    ]
+        .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 readCachedCodeGraph(projectDir, fingerprint) {
+    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);
+        if (readCodeIndexManifest(projectDir).fingerprint !== fingerprint)
+            return null;
+        return graph;
+    }
+    catch {
+        return null;
+    }
+}
 function fileFactCacheDir(projectDir) {
     return (0, node_path_1.join)(codeGraphDir(projectDir), "file-cache");
 }
@@ -2147,6 +2178,8 @@ function externalSymbol(projectDir, parser, input) {
 }
 function parseKageExternalIndex(projectDir, parser, path) {
     const raw = readJson(path);
+    if (Array.isArray(raw.documents))
+        return parseScipJsonObject(projectDir, raw);
     const symbols = Array.isArray(raw.symbols)
         ? raw.symbols.flatMap((item) => isRecord(item) ? [externalSymbol(projectDir, parser, item)].filter(Boolean) : [])
         : [];
@@ -2178,6 +2211,62 @@ function parseKageExternalIndex(projectDir, parser, path) {
         : [];
     return { symbols, imports, calls };
 }
+function scipSymbolName(symbol) {
+    const local = symbol.trim().split(/\s+/).at(-1) ?? symbol;
+    const segment = local.split(/[\/#.`:]/).filter(Boolean).at(-1) ?? local;
+    return segment.replace(/\(\)?$/, "").replace(/\.$/, "") || symbol;
+}
+function scipRangeLine(input) {
+    if (Array.isArray(input) && typeof input[0] === "number")
+        return Math.max(1, input[0] + 1);
+    if (isRecord(input) && isRecord(input.start) && typeof input.start.line === "number")
+        return Math.max(1, input.start.line + 1);
+    return 1;
+}
+function parseScipJsonObject(projectDir, raw) {
+    const symbols = [];
+    const calls = [];
+    const symbolInfo = new Map();
+    const docs = Array.isArray(raw.documents) ? raw.documents : [];
+    for (const doc of docs) {
+        if (!isRecord(doc))
+            continue;
+        const rel = String(doc.relativePath ?? doc.relative_path ?? doc.path ?? doc.uri ?? "").replace(/^file:\/\//, "").replace(/\\/g, "/");
+        if (!rel)
+            continue;
+        for (const item of Array.isArray(doc.symbols) ? doc.symbols : []) {
+            if (isRecord(item) && typeof item.symbol === "string")
+                symbolInfo.set(item.symbol, item);
+        }
+        for (const occurrence of Array.isArray(doc.occurrences) ? doc.occurrences : []) {
+            if (!isRecord(occurrence) || typeof occurrence.symbol !== "string")
+                continue;
+            const role = Number(occurrence.symbolRoles ?? occurrence.symbol_roles ?? 0);
+            const line = scipRangeLine(occurrence.range);
+            const name = scipSymbolName(occurrence.symbol);
+            if (!name || name === "local")
+                continue;
+            if ((role & 1) === 1) {
+                const info = symbolInfo.get(occurrence.symbol) ?? {};
+                const detail = Array.isArray(info.documentation) ? info.documentation.map(String).find(Boolean) : undefined;
+                const symbol = externalSymbol(projectDir, "scip", {
+                    path: rel,
+                    name,
+                    kind: occurrence.syntaxKind ?? occurrence.syntax_kind ?? info.kind,
+                    line,
+                    signature: detail ?? name,
+                    exported: !occurrence.symbol.startsWith("local "),
+                });
+                if (symbol && !symbols.some((candidate) => candidate.id === symbol.id))
+                    symbols.push(symbol);
+            }
+            else {
+                calls.push({ from_symbol: null, to_symbol: name, path: rel, line });
+            }
+        }
+    }
+    return { symbols, imports: [], calls };
+}
 function parseLspDocumentSymbols(projectDir, path) {
     const raw = readJson(path);
     const docs = Array.isArray(raw) ? raw : isRecord(raw) && Array.isArray(raw.documents) ? raw.documents : [];
@@ -2250,9 +2339,119 @@ function writeLspSymbolIndex(projectDir) {
         parser: "lsp",
         documents: documents.length,
         symbols: symbolCount,
+        warnings: [],
         errors,
     };
 }
+function executableOnPath(projectDir, command) {
+    const local = (0, node_path_1.join)(projectDir, "node_modules", ".bin", command);
+    if ((0, node_fs_1.existsSync)(local))
+        return local;
+    const localCmd = `${local}.cmd`;
+    if ((0, node_fs_1.existsSync)(localCmd))
+        return localCmd;
+    for (const entry of (process.env.PATH ?? "").split(node_path_1.delimiter).filter(Boolean)) {
+        const candidate = (0, node_path_1.join)(entry, command);
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+        const cmdCandidate = `${candidate}.cmd`;
+        if ((0, node_fs_1.existsSync)(cmdCandidate))
+            return cmdCandidate;
+    }
+    return null;
+}
+function hasTypeScriptCode(projectDir) {
+    return listCodeFiles(projectDir).some((path) => TS_AST_EXTENSIONS.has(extensionOf(path)));
+}
+function scipCliJson(scipCli, scipPath, projectDir) {
+    try {
+        return (0, node_child_process_1.execFileSync)(scipCli, ["print", "--json", scipPath], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch {
+        return (0, node_child_process_1.execFileSync)(scipCli, ["print", scipPath, "--json"], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+}
+function writeScipTypescriptIndex(projectDir) {
+    if (!hasTypeScriptCode(projectDir))
+        return null;
+    const scipTypescript = executableOnPath(projectDir, "scip-typescript");
+    if (!scipTypescript)
+        return null;
+    const scipCli = executableOnPath(projectDir, "scip");
+    const outDir = (0, node_path_1.join)(memoryRoot(projectDir), "code_index");
+    ensureDir(outDir);
+    const scipPath = (0, node_path_1.join)(outDir, "index.scip");
+    const outPath = (0, node_path_1.join)(outDir, "scip.json");
+    const warnings = [];
+    const errors = [];
+    try {
+        const args = ["index"];
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, "tsconfig.json")))
+            args.push("--infer-tsconfig");
+        (0, node_child_process_1.execFileSync)(scipTypescript, args, { cwd: projectDir, stdio: ["ignore", "pipe", "pipe"] });
+        const generatedScipPath = (0, node_path_1.join)(projectDir, "index.scip");
+        if ((0, node_fs_1.existsSync)(generatedScipPath))
+            (0, node_fs_1.renameSync)(generatedScipPath, scipPath);
+        if (!(0, node_fs_1.existsSync)(scipPath))
+            throw new Error("scip-typescript completed but did not write index.scip");
+    }
+    catch (error) {
+        errors.push(`scip-typescript failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, project_dir: projectDir, path: scipPath, parser: "scip", documents: 0, symbols: 0, warnings, errors };
+    }
+    if (!scipCli) {
+        warnings.push("scip-typescript wrote index.scip, but the scip CLI is not installed so Kage could not convert it into graph facts.");
+        return { ok: false, project_dir: projectDir, path: scipPath, parser: "scip", documents: 0, symbols: 0, warnings, errors };
+    }
+    try {
+        const raw = JSON.parse(scipCliJson(scipCli, scipPath, projectDir));
+        const facts = parseScipJsonObject(projectDir, raw);
+        writeJson(outPath, {
+            schema_version: 1,
+            generator: "scip-typescript",
+            generated_at: nowIso(),
+            source_artifact: (0, node_path_1.relative)(projectDir, scipPath).replace(/\\/g, "/"),
+            symbols: facts.symbols,
+            imports: facts.imports,
+            calls: facts.calls,
+        });
+        return {
+            ok: true,
+            project_dir: projectDir,
+            path: outPath,
+            parser: "scip",
+            documents: Array.isArray(raw.documents) ? raw.documents.length : 0,
+            symbols: facts.symbols.length,
+            warnings,
+            errors,
+        };
+    }
+    catch (error) {
+        errors.push(`scip conversion failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false, project_dir: projectDir, path: scipPath, parser: "scip", documents: 0, symbols: 0, warnings, errors };
+    }
+}
+function writeCodeIndex(projectDir) {
+    const scip = writeScipTypescriptIndex(projectDir);
+    if (scip?.ok)
+        return scip;
+    const lsp = writeLspSymbolIndex(projectDir);
+    return {
+        ...lsp,
+        warnings: [
+            ...(scip ? [...scip.warnings, ...scip.errors] : ["scip-typescript not found; used built-in LSP-compatible fallback."]),
+            ...lsp.warnings,
+        ],
+    };
+}
 function parseLsif(projectDir, path) {
     const docs = new Map();
     const ranges = new Map();
@@ -2350,7 +2549,7 @@ function extractPackages(projectDir) {
     }
     return packages.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
 }
-function buildCodeGraph(projectDir) {
+function buildCodeGraph(projectDir, options = {}) {
     ensureMemoryDirs(projectDir);
     const branch = gitBranch(projectDir);
     const head = gitHead(projectDir);
@@ -2358,7 +2557,16 @@ function buildCodeGraph(projectDir) {
     const mergeBase = gitMergeBase(projectDir);
     const selection = codeIndexSelection(projectDir);
     const absoluteFiles = selection.files;
+    const fingerprint = codeGraphStatFingerprint(projectDir, absoluteFiles);
+    const cachedGraph = options.force ? null : readCachedCodeGraph(projectDir, fingerprint);
+    if (cachedGraph) {
+        selection.manifest.cache = { hits: absoluteFiles.length, misses: 0 };
+        selection.manifest.fingerprint = fingerprint;
+        writeCodeIndexManifest(projectDir, selection.manifest);
+        return cachedGraph;
+    }
     const inputHash = codeGraphInputHash(projectDir, absoluteFiles);
+    selection.manifest.fingerprint = fingerprint;
     writeCodeIndexManifest(projectDir, selection.manifest);
     const knownFiles = new Set(absoluteFiles.map((path) => (0, node_path_1.relative)(projectDir, path).replace(/\\/g, "/")));
     const files = [];
@@ -2944,9 +3152,9 @@ function currentOrBuildGraphs(projectDir) {
     }
     return buildGraphIndexes(projectDir);
 }
-function buildGraphIndexes(projectDir) {
+function buildGraphIndexes(projectDir, options = {}) {
     const written = buildPacketIndexes(projectDir);
-    const codeGraph = buildCodeGraph(projectDir);
+    const codeGraph = buildCodeGraph(projectDir, { force: options.forceCodeGraph });
     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");
@@ -3001,7 +3209,7 @@ function indexProjectDetailed(projectDir, options = {}) {
     const structure = createRepoStructurePacket(projectDir);
     if (structure)
         upsertGeneratedPacket(projectDir, structure);
-    const built = options.graphs === false ? null : buildGraphIndexes(projectDir);
+    const built = options.graphs === false ? null : buildGraphIndexes(projectDir, { forceCodeGraph: options.full });
     const indexes = built?.indexes ?? buildPacketIndexes(projectDir);
     return {
         result: {
@@ -3075,15 +3283,15 @@ function refreshPacketStaleness(projectDir) {
     }
     return { findings, updated };
 }
-function refreshProject(projectDir) {
-    const detailedIndex = indexProjectDetailed(projectDir);
+function refreshProject(projectDir, options = {}) {
+    const detailedIndex = indexProjectDetailed(projectDir, { full: options.full });
     const index = detailedIndex.result;
     let codeGraph = detailedIndex.codeGraph;
     let knowledgeGraph = detailedIndex.knowledgeGraph;
     const stale = refreshPacketStaleness(projectDir);
     let indexes = index.indexes;
     if (stale.updated > 0) {
-        const rebuilt = buildGraphIndexes(projectDir);
+        const rebuilt = buildGraphIndexes(projectDir, { forceCodeGraph: options.full });
         codeGraph = rebuilt.codeGraph;
         knowledgeGraph = rebuilt.knowledgeGraph;
         indexes = rebuilt.indexes.map((path) => (0, node_path_1.relative)(projectDir, path));

package/package.json

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