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

package/dist/kernel.js

@@ -42,6 +42,7 @@ exports.indexesDir = indexesDir;
 exports.graphDir = graphDir;
 exports.graphRegistryDir = graphRegistryDir;
 exports.codeGraphDir = codeGraphDir;
+exports.structuralIndexDir = structuralIndexDir;
 exports.branchesDir = branchesDir;
 exports.reviewDir = reviewDir;
 exports.publicBundleDir = publicBundleDir;
@@ -63,7 +64,10 @@ exports.catalogDomainNodeCount = catalogDomainNodeCount;
 exports.ensureMemoryDirs = ensureMemoryDirs;
 exports.loadApprovedPackets = loadApprovedPackets;
 exports.loadPendingPackets = loadPendingPackets;
+exports.buildStructuralFileForWorker = buildStructuralFileForWorker;
+exports.buildStructuralIndex = buildStructuralIndex;
 exports.writeLspSymbolIndex = writeLspSymbolIndex;
+exports.writeCodeIndex = writeCodeIndex;
 exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
@@ -114,7 +118,9 @@ exports.changelog = changelog;
 const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
+const node_worker_threads_1 = require("node:worker_threads");
 const ts = __importStar(require("typescript"));
 const index_js_1 = require("./registry/index.js");
 exports.PACKET_SCHEMA_VERSION = 2;
@@ -285,6 +291,9 @@ function graphRegistryDir(projectDir) {
 function codeGraphDir(projectDir) {
     return (0, node_path_1.join)(memoryRoot(projectDir), "code_graph");
 }
+function structuralIndexDir(projectDir) {
+    return (0, node_path_1.join)(memoryRoot(projectDir), "structural");
+}
 function branchesDir(projectDir) {
     return (0, node_path_1.join)(memoryRoot(projectDir), "branches");
 }
@@ -1299,10 +1308,11 @@ const CODE_EXTENSIONS = new Set([
     ".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 MAX_STRUCTURAL_EXTRACT_FILE_BYTES = positiveIntEnv("KAGE_MAX_STRUCTURAL_EXTRACT_FILE_BYTES", MAX_CODE_FILE_BYTES);
+const MAX_STRUCTURAL_WORKERS = positiveIntEnv("KAGE_STRUCTURAL_WORKERS", Math.max(1, Math.min(8, (0, node_os_1.availableParallelism)() - 1)));
+const MIN_STRUCTURAL_PARALLEL_FILES = positiveIntEnv("KAGE_STRUCTURAL_PARALLEL_MIN_FILES", 64);
 const CONFIG_NAMES = new Set([
     "package.json",
     "pyproject.toml",
@@ -1419,11 +1429,9 @@ function emptyCodeIndexManifest(projectDir) {
         project_dir: projectDir,
         repo_key: repoKey(projectDir),
         generated_at: nowIso(),
-        mode: "quick",
+        mode: "structural",
         limits: {
-            max_file_bytes: MAX_CODE_FILE_BYTES,
-            max_files: MAX_CODE_GRAPH_FILES,
-            max_symbols: MAX_CODE_GRAPH_SYMBOLS,
+            max_extract_file_bytes: MAX_STRUCTURAL_EXTRACT_FILE_BYTES,
             max_calls: MAX_CODE_GRAPH_CALLS,
             max_calls_per_file: MAX_CODE_GRAPH_CALLS_PER_FILE,
         },
@@ -1446,10 +1454,283 @@ function emptyCodeIndexManifest(projectDir) {
 function codeIndexManifestPath(projectDir) {
     return (0, node_path_1.join)(codeGraphDir(projectDir), "index-manifest.json");
 }
-function codeIndexSelection(projectDir) {
-    const candidates = [];
-    const deferred = [];
+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 codeIndexManifestFromStructural(projectDir, structural, fingerprint, cache) {
+    const manifest = emptyCodeIndexManifest(projectDir);
+    const metadataOnly = structural.files
+        .filter((file) => file.extraction === "metadata-only")
+        .map((file) => ({ path: file.path, size_bytes: file.size_bytes, reason: "over_structural_extract_file_size_limit" }));
+    manifest.mode = "structural";
+    manifest.coverage = {
+        indexable_files: structural.manifest.files.total,
+        indexed_files: structural.manifest.files.indexed,
+        deferred_files: metadataOnly.length,
+        ignored_files: structural.manifest.files.ignored,
+        coverage_percent: percent(structural.manifest.files.indexed, structural.manifest.files.total),
+        complete: metadataOnly.length === 0,
+    };
+    manifest.cache = cache;
+    manifest.fingerprint = fingerprint;
+    manifest.deferred_files = metadataOnly.sort((a, b) => a.path.localeCompare(b.path));
+    manifest.ignored_summary = structural.manifest.ignored_summary;
+    return manifest;
+}
+function listCodeFiles(projectDir) {
+    return scanStructuralFiles(projectDir).files;
+}
+function codeFileFromStructural(file) {
+    return {
+        id: `file:${slugify(file.path)}`,
+        path: file.path,
+        language: file.language,
+        parser: file.extraction === "metadata-only" ? "metadata" : codeParser(file.path),
+        kind: file.kind,
+        size_bytes: file.size_bytes,
+        line_count: file.line_count,
+        hash: file.hash,
+    };
+}
+function codeSymbolFromStructural(symbol) {
+    return {
+        id: symbol.id,
+        name: symbol.name,
+        kind: symbol.kind,
+        path: symbol.path,
+        language: symbol.language,
+        parser: symbol.parser,
+        export: symbol.export ?? false,
+        line: symbol.line,
+        end_line: symbol.end_line ?? null,
+        signature: symbol.signature ?? `${symbol.name}()`,
+    };
+}
+function importKey(item) {
+    return `${item.from_path}\0${item.to_path ?? ""}\0${item.specifier}\0${item.line}\0${item.kind}`;
+}
+function compactCodeGraphArtifact(projectDir, graph, structural) {
+    const structuralFiles = new Map(structural.files.map((file) => [file.path, codeFileFromStructural(file)]));
+    const structuralSymbols = new Map(structural.symbols.map((symbol) => [symbol.id, codeSymbolFromStructural(symbol)]));
+    const structuralImports = new Set(structural.imports.map(importKey));
+    const fileParserOverrides = graph.files
+        .filter((file) => structuralFiles.get(file.path)?.parser !== file.parser)
+        .map((file) => [file.path, file.parser]);
+    const symbolParserOverrides = graph.symbols
+        .filter((symbol) => structuralSymbols.has(symbol.id) && structuralSymbols.get(symbol.id)?.parser !== symbol.parser)
+        .map((symbol) => [symbol.id, symbol.parser]);
+    const extraSymbols = graph.symbols.filter((symbol) => !structuralSymbols.has(symbol.id));
+    const extraImports = graph.imports.filter((item) => !structuralImports.has(importKey(item)));
+    return {
+        schema_version: 1,
+        compact: true,
+        artifact_format: 2,
+        project_dir: graph.project_dir,
+        repo_key: graph.repo_key,
+        generated_at: graph.generated_at,
+        repo_state: graph.repo_state,
+        refs: {
+            files: (0, node_path_1.relative)(codeGraphDir(projectDir), (0, node_path_1.join)(structuralIndexDir(projectDir), "files.json")).replace(/\\/g, "/"),
+            symbols: (0, node_path_1.relative)(codeGraphDir(projectDir), (0, node_path_1.join)(structuralIndexDir(projectDir), "symbols.json")).replace(/\\/g, "/"),
+            imports: (0, node_path_1.relative)(codeGraphDir(projectDir), (0, node_path_1.join)(structuralIndexDir(projectDir), "imports.json")).replace(/\\/g, "/"),
+        },
+        ...(fileParserOverrides.length ? { file_parser_overrides: fileParserOverrides } : {}),
+        ...(symbolParserOverrides.length ? { symbol_parser_overrides: symbolParserOverrides } : {}),
+        ...(extraSymbols.length ? { extra_symbols: extraSymbols } : {}),
+        ...(extraImports.length ? { extra_imports: extraImports } : {}),
+        calls: graph.calls,
+        routes: graph.routes,
+        tests: graph.tests,
+        packages: graph.packages,
+    };
+}
+function isCompactCodeGraphArtifact(value) {
+    return Boolean(value && typeof value === "object" && value.compact === true && value.artifact_format === 2);
+}
+function hydrateCodeGraphArtifact(projectDir, artifact, structural) {
+    if (artifact.compact === true && !isCompactCodeGraphArtifact(artifact))
+        return null;
+    if (!isCompactCodeGraphArtifact(artifact))
+        return artifact;
+    const index = structural ?? readCurrentStructuralIndex(projectDir);
+    if (!index)
+        return null;
+    return {
+        schema_version: 1,
+        project_dir: artifact.project_dir,
+        repo_key: artifact.repo_key,
+        generated_at: artifact.generated_at,
+        repo_state: artifact.repo_state,
+        files: index.files.map(codeFileFromStructural).map((file) => {
+            const override = artifact.file_parser_overrides?.find(([path]) => path === file.path);
+            return override ? { ...file, parser: override[1] } : file;
+        }).sort((a, b) => a.path.localeCompare(b.path)),
+        symbols: [
+            ...index.symbols.map(codeSymbolFromStructural).map((symbol) => {
+                const override = artifact.symbol_parser_overrides?.find(([id]) => id === symbol.id);
+                return override ? { ...symbol, parser: override[1] } : symbol;
+            }),
+            ...(artifact.extra_symbols ?? []),
+        ].sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.name.localeCompare(b.name)),
+        imports: [
+            ...index.imports,
+            ...(artifact.extra_imports ?? []),
+        ].sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier)),
+        calls: artifact.calls ?? [],
+        routes: artifact.routes ?? [],
+        tests: artifact.tests ?? [],
+        packages: artifact.packages ?? [],
+    };
+}
+function removeLegacyCodeGraphSplits(projectDir) {
+    for (const name of ["files.json", "symbols.json", "imports.json", "calls.json", "routes.json", "tests.json", "packages.json"]) {
+        (0, node_fs_1.rmSync)((0, node_path_1.join)(codeGraphDir(projectDir), name), { force: true });
+    }
+}
+function readCachedCodeGraph(projectDir, fingerprint, structural) {
+    const path = (0, node_path_1.join)(codeGraphDir(projectDir), "graph.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const artifact = readJson(path);
+        if (readCodeIndexManifest(projectDir).fingerprint !== fingerprint)
+            return null;
+        if (!isCompactCodeGraphArtifact(artifact))
+            return null;
+        return hydrateCodeGraphArtifact(projectDir, artifact, structural);
+    }
+    catch {
+        return null;
+    }
+}
+function structuralManifestPath(projectDir) {
+    return (0, node_path_1.join)(structuralIndexDir(projectDir), "manifest.json");
+}
+function structuralFileCacheDir(projectDir) {
+    return (0, node_path_1.join)(structuralIndexDir(projectDir), "file-cache");
+}
+function structuralPackedFileCachePath(projectDir) {
+    return (0, node_path_1.join)(structuralIndexDir(projectDir), "file-cache.json");
+}
+function structuralFileCachePath(projectDir, rel, hash) {
+    return (0, node_path_1.join)(structuralFileCacheDir(projectDir), `${slugify(rel)}-${hash}.json`);
+}
+function emptyStructuralIndexManifest(projectDir) {
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        repo_key: repoKey(projectDir),
+        generated_at: nowIso(),
+        provider: "kage-structural",
+        limits: {
+            max_extract_file_bytes: MAX_STRUCTURAL_EXTRACT_FILE_BYTES,
+            max_workers: MAX_STRUCTURAL_WORKERS,
+            min_parallel_files: MIN_STRUCTURAL_PARALLEL_FILES,
+        },
+        files: {
+            total: 0,
+            indexed: 0,
+            metadata_only: 0,
+            ignored: 0,
+        },
+        cache: {
+            hits: 0,
+            misses: 0,
+        },
+        symbols: 0,
+        imports: 0,
+        edges: 0,
+        languages: {},
+        worker_count: 0,
+        ignored_summary: {},
+        deleted_files: [],
+        fingerprint: "",
+        file_entries: {},
+    };
+}
+function readStructuralIndexManifest(projectDir) {
+    const path = structuralManifestPath(projectDir);
+    if (!(0, node_fs_1.existsSync)(path))
+        return emptyStructuralIndexManifest(projectDir);
+    try {
+        const manifest = readJson(path);
+        if (manifest.schema_version !== 1 || manifest.provider !== "kage-structural")
+            return emptyStructuralIndexManifest(projectDir);
+        if (!manifest.file_entries)
+            manifest.file_entries = {};
+        if (!manifest.cache)
+            manifest.cache = { hits: 0, misses: 0 };
+        return manifest;
+    }
+    catch {
+        return emptyStructuralIndexManifest(projectDir);
+    }
+}
+function writeStructuralIndexManifest(projectDir, manifest) {
+    writeJson(structuralManifestPath(projectDir), manifest);
+}
+function readKageIgnore(projectDir) {
+    const path = (0, node_path_1.join)(projectDir, ".kageignore");
+    if (!(0, node_fs_1.existsSync)(path))
+        return [];
+    return (0, node_fs_1.readFileSync)(path, "utf8")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+function wildcardPattern(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\0/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
+function kageIgnoreMatches(rel, pattern) {
+    const normalized = pattern.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!normalized)
+        return false;
+    if (normalized.endsWith("/"))
+        return rel === normalized.slice(0, -1) || rel.startsWith(normalized);
+    if (normalized.includes("*"))
+        return wildcardPattern(normalized).test(rel);
+    return rel === normalized || rel.startsWith(`${normalized}/`) || rel.split("/").includes(normalized);
+}
+function isKageIgnored(rel, patterns) {
+    let ignored = false;
+    for (const pattern of patterns) {
+        if (pattern.startsWith("!")) {
+            if (kageIgnoreMatches(rel, pattern.slice(1)))
+                ignored = false;
+            continue;
+        }
+        if (kageIgnoreMatches(rel, pattern))
+            ignored = true;
+    }
+    return ignored;
+}
+function isStructuralIndexable(rel) {
+    const extension = extensionOf(rel);
+    return CODE_EXTENSIONS.has(extension) || CONFIG_NAMES.has((0, node_path_1.basename)(rel)) || rel === "README.md";
+}
+function scanStructuralFiles(projectDir) {
+    const files = [];
     const ignoredSummary = {};
+    const ignorePatterns = readKageIgnore(projectDir);
     const ignore = (reason) => {
         ignoredSummary[reason] = (ignoredSummary[reason] ?? 0) + 1;
     };
@@ -1463,110 +1744,219 @@ function codeIndexSelection(projectDir) {
                 ignore("generated_vendor_or_cache");
                 continue;
             }
+            if (isKageIgnored(rel, ignorePatterns)) {
+                ignore("kageignore");
+                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) {
+            if (!isStructuralIndexable(rel)) {
                 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);
+            files.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, "/");
-        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,
+    return {
+        files: files.sort((a, b) => codeFilePriority(projectDir, a) - codeFilePriority(projectDir, b) || a.localeCompare(b)),
+        ignoredSummary: Object.fromEntries(Object.entries(ignoredSummary).sort(([a], [b]) => a.localeCompare(b))),
     };
-    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 countBufferLines(buffer) {
+    if (buffer.length === 0)
+        return 0;
+    let lines = 1;
+    for (const byte of buffer) {
+        if (byte === 10)
+            lines += 1;
+    }
+    return lines;
+}
+function structuralConcepts(rel, symbols) {
+    const pathTerms = rel
+        .replace(/\.[^.]+$/, "")
+        .split(/[\/_.-]+/)
+        .flatMap((term) => term.split(/(?=[A-Z])/));
+    const symbolTerms = symbols.flatMap((symbol) => symbol.name.split(/[_\W]+|(?=[A-Z])/));
+    return unique([...pathTerms, ...symbolTerms]
+        .map((term) => term.toLowerCase())
+        .filter((term) => term.length >= 3 && !["src", "lib", "test", "spec", "index"].includes(term)))
+        .slice(0, 16);
+}
+function structuralSignals(rel, content, kind) {
+    const signals = new Set([kind]);
+    if (rel === "README.md")
+        signals.add("readme");
+    if (CONFIG_NAMES.has((0, node_path_1.basename)(rel)))
+        signals.add("config");
+    if (content && /\b(app|router)\.(get|post|put|patch|delete)\s*\(/.test(content))
+        signals.add("http-route");
+    if (content && /\b(describe|it|test)\s*\(/.test(content))
+        signals.add("test-suite");
+    if (content && /\b(auth|login|token|session)\b/i.test(content))
+        signals.add("auth");
+    return [...signals].sort();
+}
+function structuralEdgesFromFacts(rel, symbols, imports) {
+    const fileId = `file:${slugify(rel)}`;
+    return [
+        ...symbols.map((symbol) => ({
+            source: fileId,
+            target: symbol.id,
+            relation: "contains",
+            confidence: "EXTRACTED",
+            source_file: rel,
+            source_location: `L${symbol.line}`,
+            weight: 1,
+        })),
+        ...imports.map((item) => ({
+            source: fileId,
+            target: item.to_path ? `file:${slugify(item.to_path)}` : `external:${slugify(item.specifier)}`,
+            relation: "imports",
+            confidence: item.to_path ? "EXTRACTED" : "AMBIGUOUS",
+            source_file: rel,
+            source_location: `L${item.line}`,
+            weight: item.to_path ? 1 : 0.5,
+        })),
+    ];
 }
-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 compactStructuralCachedFile(cached) {
+    return {
+        schema_version: 2,
+        path: cached.path,
+        hash: cached.hash,
+        file: [
+            cached.file.language,
+            cached.file.kind,
+            cached.file.size_bytes,
+            cached.file.line_count,
+            cached.file.hash,
+            cached.file.mtime_ms,
+            cached.file.extraction,
+            cached.file.confidence,
+            cached.file.top_symbols,
+            cached.file.imports_preview,
+            cached.file.signals,
+            cached.file.concepts,
+        ],
+        symbols: cached.symbols.map((symbol) => [
+            symbol.id,
+            symbol.name,
+            symbol.kind,
+            symbol.parser,
+            symbol.export,
+            symbol.line,
+            symbol.end_line,
+            symbol.signature,
+            symbol.confidence,
+        ]),
+        imports: cached.imports.map((item) => [
+            item.to_path,
+            item.specifier,
+            item.imported,
+            item.kind,
+            item.parser,
+            item.line,
+        ]),
+    };
 }
-function listCodeFiles(projectDir) {
-    return codeIndexSelection(projectDir).files;
+function expandCompactStructuralCachedFile(compact) {
+    if (!Array.isArray(compact.file) || !Array.isArray(compact.symbols) || !Array.isArray(compact.imports))
+        return null;
+    const [language, kind, sizeBytes, lineCount, shortHash, mtimeMs, extraction, confidence, topSymbols, importsPreview, signals, concepts] = compact.file;
+    const file = {
+        schema_version: 1,
+        path: compact.path,
+        language,
+        kind,
+        size_bytes: sizeBytes,
+        line_count: lineCount,
+        hash: shortHash,
+        mtime_ms: mtimeMs,
+        extraction,
+        confidence,
+        top_symbols: topSymbols,
+        imports_preview: importsPreview,
+        signals,
+        concepts,
+    };
+    const symbols = compact.symbols.map((symbol) => ({
+        id: symbol[0],
+        name: symbol[1],
+        kind: symbol[2],
+        path: compact.path,
+        language,
+        parser: symbol[3],
+        export: symbol[4],
+        line: symbol[5],
+        end_line: symbol[6],
+        signature: symbol[7],
+        confidence: symbol[8],
+    }));
+    const imports = compact.imports.map((item) => ({
+        from_path: compact.path,
+        to_path: item[0],
+        specifier: item[1],
+        imported: item[2],
+        kind: item[3],
+        parser: item[4],
+        line: item[5],
+    }));
+    return {
+        schema_version: 1,
+        path: compact.path,
+        hash: compact.hash,
+        file,
+        symbols,
+        imports,
+        edges: structuralEdgesFromFacts(compact.path, symbols, imports),
+    };
 }
-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"));
+const packedStructuralCache = new Map();
+function structuralPackedCacheKey(rel, hash) {
+    return `${rel}\0${hash}`;
 }
-function readCachedCodeGraph(projectDir, fingerprint) {
-    const path = (0, node_path_1.join)(codeGraphDir(projectDir), "graph.json");
+function readPackedStructuralCache(projectDir) {
+    const path = structuralPackedFileCachePath(projectDir);
     if (!(0, node_fs_1.existsSync)(path))
-        return null;
+        return {};
+    const stats = (0, node_fs_1.statSync)(path);
+    const cacheKey = (0, node_path_1.resolve)(projectDir);
+    const cached = packedStructuralCache.get(cacheKey);
+    if (cached && cached.mtimeMs === stats.mtimeMs && cached.size === stats.size)
+        return cached.entries;
     try {
-        const graph = readJson(path);
-        if (readCodeIndexManifest(projectDir).fingerprint !== fingerprint)
-            return null;
-        return graph;
+        const packed = readJson(path);
+        const entries = packed.schema_version === 1 && packed.provider === "kage-structural-file-cache" && packed.entries ? packed.entries : {};
+        packedStructuralCache.set(cacheKey, { mtimeMs: stats.mtimeMs, size: stats.size, entries });
+        return entries;
     }
     catch {
-        return null;
+        return {};
     }
 }
-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);
+function readCachedStructuralFile(projectDir, rel, hash) {
+    const packed = readPackedStructuralCache(projectDir)[structuralPackedCacheKey(rel, hash)];
+    if (packed) {
+        const expanded = expandCompactStructuralCachedFile(packed);
+        if (expanded && expanded.path === rel && expanded.hash === hash)
+            return expanded;
+    }
+    const path = structuralFileCachePath(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)
+        const raw = readJson(path);
+        const cached = raw.schema_version === 2 ? expandCompactStructuralCachedFile(raw) : raw;
+        if (!cached || cached.schema_version !== 1 || cached.path !== rel || cached.hash !== hash)
+            return null;
+        if (!cached.file || !Array.isArray(cached.symbols) || !Array.isArray(cached.imports) || !Array.isArray(cached.edges))
             return null;
-        if (!cached.file || !Array.isArray(cached.symbols) || !Array.isArray(cached.imports))
+        if (cached.symbols.some((symbol) => typeof symbol.signature !== "string" || typeof symbol.export !== "boolean"))
             return null;
         return cached;
     }
@@ -1574,40 +1964,311 @@ function readCachedFileFacts(projectDir, rel, hash) {
         return null;
     }
 }
-function writeCachedFileFacts(projectDir, facts) {
-    ensureDir(fileFactCacheDir(projectDir));
-    writeJson(fileFactCachePath(projectDir, facts.path, facts.hash), facts);
+function writeStructuralFileCachePack(projectDir, results) {
+    const entries = {};
+    for (const result of results) {
+        entries[structuralPackedCacheKey(result.cached.path, result.cached.hash)] = compactStructuralCachedFile(result.cached);
+    }
+    writeJson(structuralPackedFileCachePath(projectDir), {
+        schema_version: 1,
+        provider: "kage-structural-file-cache",
+        entries: Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b))),
+    });
+    packedStructuralCache.delete((0, node_path_1.resolve)(projectDir));
+    (0, node_fs_1.rmSync)(structuralFileCacheDir(projectDir), { recursive: true, force: true });
 }
-function buildFileFacts(projectDir, absolutePath, knownFiles) {
+function buildStructuralFile(projectDir, absolutePath, knownFiles, prior) {
     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);
+    const stats = (0, node_fs_1.statSync)(absolutePath);
+    const priorEntry = prior.file_entries[rel];
+    const canReuseHash = priorEntry && priorEntry.size_bytes === stats.size && Math.round(priorEntry.mtime_ms) === Math.round(stats.mtimeMs);
+    let buffer = canReuseHash ? null : (0, node_fs_1.readFileSync)(absolutePath);
+    let hash = canReuseHash ? priorEntry.hash : sha256Hex(buffer ?? "");
+    let cached = readCachedStructuralFile(projectDir, rel, hash);
+    if (!cached && !buffer) {
+        buffer = (0, node_fs_1.readFileSync)(absolutePath);
+        hash = sha256Hex(buffer);
+        cached = readCachedStructuralFile(projectDir, rel, hash);
+    }
+    const entry = {
+        path: rel,
+        size_bytes: stats.size,
+        mtime_ms: stats.mtimeMs,
+        hash,
+        extraction: stats.size <= MAX_STRUCTURAL_EXTRACT_FILE_BYTES ? "structural" : "metadata-only",
+    };
     if (cached)
-        return { facts: cached, content, cacheHit: true };
+        return { cached, entry, cacheHit: true };
+    const content = stats.size <= MAX_STRUCTURAL_EXTRACT_FILE_BYTES ? (buffer ?? (0, node_fs_1.readFileSync)(absolutePath)).toString("utf8") : null;
+    const language = codeLanguage(rel);
+    const parser = content ? codeParser(rel) : "metadata";
+    const rawSymbols = [];
+    const rawImports = [];
+    if (content) {
+        if (TS_AST_EXTENSIONS.has(extensionOf(rel))) {
+            rawSymbols.push(...extractSymbols(rel, content));
+            rawImports.push(...extractImports(projectDir, rel, content, knownFiles));
+        }
+        else if (CODE_EXTENSIONS.has(extensionOf(rel))) {
+            rawSymbols.push(...extractGenericSymbols(rel, content));
+            rawImports.push(...extractGenericImports(projectDir, rel, content, knownFiles));
+        }
+    }
+    const symbols = rawSymbols.map((symbol) => ({
+        id: symbol.id,
+        name: symbol.name,
+        kind: symbol.kind,
+        path: symbol.path,
+        language: symbol.language,
+        parser: symbol.parser,
+        export: symbol.export,
+        line: symbol.line,
+        end_line: symbol.end_line,
+        signature: symbol.signature,
+        confidence: "EXTRACTED",
+    }));
+    const edges = structuralEdgesFromFacts(rel, symbols, rawImports);
     const file = {
-        id: `file:${slugify(rel)}`,
+        schema_version: 1,
         path: rel,
-        language: codeLanguage(rel),
-        parser: codeParser(rel),
+        language,
         kind: codeFileKind(rel),
-        size_bytes: Buffer.byteLength(content),
-        line_count: content.split(/\r?\n/).length,
-        hash: fullHash.slice(0, 16),
+        size_bytes: stats.size,
+        line_count: content ? content.split(/\r?\n/).length : countBufferLines(buffer ?? (0, node_fs_1.readFileSync)(absolutePath)),
+        hash: hash.slice(0, 16),
+        mtime_ms: stats.mtimeMs,
+        extraction: entry.extraction,
+        confidence: "EXTRACTED",
+        top_symbols: symbols.slice(0, 12).map((symbol) => symbol.name),
+        imports_preview: rawImports.slice(0, 20).map((item) => item.specifier),
+        signals: structuralSignals(rel, content, codeFileKind(rel)),
+        concepts: [],
     };
+    file.concepts = structuralConcepts(rel, symbols);
+    const next = { schema_version: 1, path: rel, hash, file, symbols, imports: rawImports, edges };
+    return { cached: next, entry, cacheHit: false };
+}
+function buildStructuralFileForWorker(projectDir, absolutePath, knownFiles, prior) {
+    return buildStructuralFile(projectDir, absolutePath, new Set(knownFiles), prior);
+}
+function structuralWorkerPath() {
+    return (0, node_path_1.join)(__dirname, "structural-worker.js");
+}
+function structuralWorkerCount(fileCount) {
+    if (fileCount < MIN_STRUCTURAL_PARALLEL_FILES)
+        return 1;
+    return Math.max(1, Math.min(MAX_STRUCTURAL_WORKERS, fileCount));
+}
+function splitStructuralBatches(files, count) {
+    const batches = Array.from({ length: count }, () => []);
+    files.forEach((file, index) => batches[index % count].push(file));
+    return batches.filter((batch) => batch.length > 0);
+}
+function buildStructuralFilesSerial(projectDir, scannedFiles, knownFiles, previous) {
+    return {
+        results: scannedFiles.map((absolutePath) => buildStructuralFile(projectDir, absolutePath, knownFiles, previous)),
+        workerCount: 1,
+    };
+}
+function buildStructuralFilesParallel(projectDir, scannedFiles, knownFiles, previous) {
+    const workerCount = structuralWorkerCount(scannedFiles.length);
+    if (workerCount <= 1)
+        return buildStructuralFilesSerial(projectDir, scannedFiles, knownFiles, previous);
+    const outDir = (0, node_path_1.join)(structuralIndexDir(projectDir), "worker-output", `${process.pid}-${Date.now()}`);
+    ensureDir(outDir);
+    const shared = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
+    const done = new Int32Array(shared);
+    const known = [...knownFiles];
+    const batches = splitStructuralBatches(scannedFiles, workerCount);
+    const workers = batches.map((files, index) => new node_worker_threads_1.Worker(structuralWorkerPath(), {
+        workerData: {
+            projectDir,
+            files,
+            knownFiles: known,
+            prior: previous,
+            outputPath: (0, node_path_1.join)(outDir, `worker-${index}.json`),
+            shared,
+        },
+    }));
+    const startedAt = Date.now();
+    while (Atomics.load(done, 0) < batches.length) {
+        const current = Atomics.load(done, 0);
+        Atomics.wait(done, 0, current, 1000);
+        if (Date.now() - startedAt > 10 * 60 * 1000) {
+            for (const worker of workers)
+                void worker.terminate();
+            (0, node_fs_1.rmSync)(outDir, { recursive: true, force: true });
+            throw new Error(`Structural index workers timed out after ${batches.length} batches`);
+        }
+    }
+    const results = [];
+    try {
+        for (let index = 0; index < batches.length; index++) {
+            const output = readJson((0, node_path_1.join)(outDir, `worker-${index}.json`));
+            if (!output.ok)
+                throw new Error(output.error ?? `Structural index worker ${index} failed`);
+            results.push(...output.results);
+        }
+    }
+    finally {
+        (0, node_fs_1.rmSync)(outDir, { recursive: true, force: true });
+    }
+    return { results, workerCount: batches.length };
+}
+function structuralReport(index) {
+    const languageLines = Object.entries(index.manifest.languages)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 20)
+        .map(([language, count]) => `- ${language}: ${count}`);
+    const conceptLines = Object.entries(countBy(index.files.flatMap((file) => file.concepts), (concept) => concept))
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 20)
+        .map(([concept, count]) => `- ${concept}: ${count}`);
+    return [
+        "# Kage Structural Index",
+        "",
+        "This is the full-repo structural index used for fast large-repo orientation. It is generated, cache-backed, and separate from repo memory packets.",
+        "",
+        "## Coverage",
+        "",
+        `- Files: ${index.manifest.files.indexed}/${index.manifest.files.total}`,
+        `- Metadata-only files: ${index.manifest.files.metadata_only}`,
+        `- Ignored files: ${index.manifest.files.ignored}`,
+        `- Symbols: ${index.symbols.length}`,
+        `- Imports: ${index.imports.length}`,
+        `- Edges: ${index.edges.length}`,
+        `- Cache: ${index.manifest.cache.hits} hits, ${index.manifest.cache.misses} misses`,
+        `- Workers: ${index.manifest.worker_count}`,
+        "",
+        "## Languages",
+        "",
+        ...(languageLines.length ? languageLines : ["- none"]),
+        "",
+        "## Top Concepts",
+        "",
+        ...(conceptLines.length ? conceptLines : ["- none"]),
+        "",
+    ].join("\n");
+}
+function buildStructuralIndex(projectDir) {
+    ensureMemoryDirs(projectDir);
+    ensureDir(structuralIndexDir(projectDir));
+    const previous = readStructuralIndexManifest(projectDir);
+    const scanned = scanStructuralFiles(projectDir);
+    const knownFiles = new Set(scanned.files.map((file) => (0, node_path_1.relative)(projectDir, file).replace(/\\/g, "/")));
+    const files = [];
     const symbols = [];
     const imports = [];
-    if (TS_AST_EXTENSIONS.has(extensionOf(rel))) {
-        symbols.push(...extractSymbols(rel, content));
-        imports.push(...extractImports(projectDir, rel, content, knownFiles));
+    const edges = [];
+    const fileEntries = {};
+    let hits = 0;
+    let misses = 0;
+    const builtFiles = buildStructuralFilesParallel(projectDir, scanned.files, knownFiles, previous);
+    for (const built of builtFiles.results) {
+        if (built.cacheHit)
+            hits += 1;
+        else
+            misses += 1;
+        files.push(built.cached.file);
+        symbols.push(...built.cached.symbols);
+        imports.push(...built.cached.imports);
+        edges.push(...built.cached.edges);
+        fileEntries[built.entry.path] = built.entry;
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    symbols.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.name.localeCompare(b.name));
+    imports.sort((a, b) => a.from_path.localeCompare(b.from_path) || a.line - b.line || a.specifier.localeCompare(b.specifier));
+    edges.sort((a, b) => a.source.localeCompare(b.source) || a.target.localeCompare(b.target) || a.relation.localeCompare(b.relation));
+    const fingerprint = sha256Hex(Object.values(fileEntries)
+        .map((entry) => `${entry.path}:${entry.size_bytes}:${Math.round(entry.mtime_ms)}:${entry.hash}`)
+        .sort()
+        .join("\n"));
+    const deletedFiles = Object.keys(previous.file_entries).filter((path) => !fileEntries[path]).sort();
+    writeStructuralFileCachePack(projectDir, builtFiles.results);
+    const manifest = {
+        schema_version: 1,
+        project_dir: projectDir,
+        repo_key: repoKey(projectDir),
+        generated_at: nowIso(),
+        provider: "kage-structural",
+        limits: {
+            max_extract_file_bytes: MAX_STRUCTURAL_EXTRACT_FILE_BYTES,
+            max_workers: MAX_STRUCTURAL_WORKERS,
+            min_parallel_files: MIN_STRUCTURAL_PARALLEL_FILES,
+        },
+        files: {
+            total: scanned.files.length,
+            indexed: files.length,
+            metadata_only: files.filter((file) => file.extraction === "metadata-only").length,
+            ignored: Object.values(scanned.ignoredSummary).reduce((sum, count) => sum + count, 0),
+        },
+        cache: {
+            hits,
+            misses,
+        },
+        symbols: symbols.length,
+        imports: imports.length,
+        edges: edges.length,
+        languages: countBy(files, (file) => file.language),
+        worker_count: builtFiles.workerCount,
+        ignored_summary: scanned.ignoredSummary,
+        deleted_files: deletedFiles,
+        fingerprint,
+        file_entries: fileEntries,
+    };
+    const index = { manifest, files, symbols, imports, edges, report: "" };
+    index.report = structuralReport(index);
+    writeJson((0, node_path_1.join)(structuralIndexDir(projectDir), "files.json"), files);
+    writeJson((0, node_path_1.join)(structuralIndexDir(projectDir), "symbols.json"), symbols);
+    writeJson((0, node_path_1.join)(structuralIndexDir(projectDir), "imports.json"), imports);
+    writeJson((0, node_path_1.join)(structuralIndexDir(projectDir), "edges.json"), edges);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(structuralIndexDir(projectDir), "report.md"), index.report, "utf8");
+    writeStructuralIndexManifest(projectDir, manifest);
+    writeJson((0, node_path_1.join)(indexesDir(projectDir), "structural.json"), {
+        schema_version: 1,
+        provider: "kage-structural",
+        files: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "files.json")),
+        symbols: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "symbols.json")),
+        imports: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "imports.json")),
+        edges: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "edges.json")),
+        report: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "report.md")),
+        manifest: (0, node_path_1.relative)(projectDir, structuralManifestPath(projectDir)),
+        file_count: files.length,
+        symbol_count: symbols.length,
+        import_count: imports.length,
+        edge_count: edges.length,
+        cache_hits: hits,
+        cache_misses: misses,
+        worker_count: builtFiles.workerCount,
+    });
+    return index;
+}
+function readCurrentStructuralIndex(projectDir) {
+    const manifestPath = structuralManifestPath(projectDir);
+    const filesPath = (0, node_path_1.join)(structuralIndexDir(projectDir), "files.json");
+    const symbolsPath = (0, node_path_1.join)(structuralIndexDir(projectDir), "symbols.json");
+    const importsPath = (0, node_path_1.join)(structuralIndexDir(projectDir), "imports.json");
+    const edgesPath = (0, node_path_1.join)(structuralIndexDir(projectDir), "edges.json");
+    if (![manifestPath, filesPath, symbolsPath, importsPath, edgesPath].every((path) => (0, node_fs_1.existsSync)(path)))
+        return null;
+    try {
+        const manifest = readJson(manifestPath);
+        if (manifest.schema_version !== 1 || manifest.provider !== "kage-structural")
+            return null;
+        return {
+            manifest,
+            files: readJson(filesPath),
+            symbols: readJson(symbolsPath),
+            imports: readJson(importsPath),
+            edges: readJson(edgesPath),
+            report: (0, node_fs_1.existsSync)((0, node_path_1.join)(structuralIndexDir(projectDir), "report.md"))
+                ? (0, node_fs_1.readFileSync)((0, node_path_1.join)(structuralIndexDir(projectDir), "report.md"), "utf8")
+                : "",
+        };
     }
-    else if (CODE_EXTENSIONS.has(extensionOf(rel))) {
-        symbols.push(...extractGenericSymbols(rel, content));
-        imports.push(...extractGenericImports(projectDir, rel, content, knownFiles));
+    catch {
+        return null;
     }
-    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, "/");
@@ -2135,6 +2796,47 @@ function codeGraphInputHash(projectDir, absoluteFiles = listCodeFiles(projectDir
         ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
     ]);
 }
+function codeGraphInputHashFromStructural(projectDir, structural) {
+    return codeGraphInputHashFromStructuralFingerprint(projectDir, structural.manifest.fingerprint);
+}
+function codeGraphInputHashFromStructuralFingerprint(projectDir, fingerprint) {
+    return graphInputHash([
+        { kind: "code_graph_input", path: ".agent_memory/structural/fingerprint", sha256: fingerprint },
+        ...fileInputEntries(projectDir, externalIndexFiles(projectDir).map((index) => index.path), "external_code_index"),
+    ]);
+}
+function currentStructuralFingerprint(projectDir, structural) {
+    const scanned = scanStructuralFiles(projectDir);
+    const entries = scanned.files
+        .map((absolutePath) => {
+        const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
+        const stats = (0, node_fs_1.statSync)(absolutePath);
+        const previous = structural.manifest.file_entries[rel];
+        const hash = previous && previous.size_bytes === stats.size && Math.round(previous.mtime_ms) === Math.round(stats.mtimeMs)
+            ? previous.hash
+            : sha256Hex((0, node_fs_1.readFileSync)(absolutePath));
+        return `${rel}:${stats.size}:${Math.round(stats.mtimeMs)}:${hash}`;
+    })
+        .sort();
+    return sha256Hex(entries.join("\n"));
+}
+function currentCodeGraphInputHash(projectDir) {
+    const structural = readCurrentStructuralIndex(projectDir);
+    return structural ? codeGraphInputHashFromStructuralFingerprint(projectDir, currentStructuralFingerprint(projectDir, structural)) : codeGraphInputHash(projectDir);
+}
+function codeGraphStructuralFingerprint(projectDir, structural) {
+    const entries = [
+        `structural:${structural.manifest.fingerprint}`,
+        ...externalIndexFiles(projectDir)
+            .map((index) => index.path)
+            .filter((path) => (0, node_fs_1.existsSync)(path))
+            .map((path) => {
+            const stats = (0, node_fs_1.statSync)(path);
+            return `external:${projectRelative(projectDir, path)}:${stats.size}:${Math.round(stats.mtimeMs)}`;
+        }),
+    ];
+    return sha256Hex(entries.sort().join("\n"));
+}
 function knowledgeGraphInputHash(projectDir, codeInputHash = codeGraphInputHash(projectDir)) {
     const packetEntries = loadPacketEntriesFromDir(packetsDir(projectDir))
         .filter((entry) => entry.packet.status === "approved")
@@ -2177,6 +2879,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) : [])
         : [];
@@ -2208,6 +2912,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 : [];
@@ -2280,9 +3040,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();
@@ -2380,50 +3250,39 @@ 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);
     const tree = gitTree(projectDir);
     const mergeBase = gitMergeBase(projectDir);
-    const selection = codeIndexSelection(projectDir);
-    const absoluteFiles = selection.files;
-    const fingerprint = codeGraphStatFingerprint(projectDir, absoluteFiles);
-    const cachedGraph = readCachedCodeGraph(projectDir, fingerprint);
+    const structural = buildStructuralIndex(projectDir);
+    const fingerprint = codeGraphStructuralFingerprint(projectDir, structural);
+    const cachedGraph = options.force ? null : readCachedCodeGraph(projectDir, fingerprint, structural);
     if (cachedGraph) {
-        selection.manifest.cache = { hits: absoluteFiles.length, misses: 0 };
-        selection.manifest.fingerprint = fingerprint;
-        writeCodeIndexManifest(projectDir, selection.manifest);
+        const manifest = codeIndexManifestFromStructural(projectDir, structural, fingerprint, { hits: structural.files.length, misses: 0 });
+        writeCodeIndexManifest(projectDir, manifest);
+        removeLegacyCodeGraphSplits(projectDir);
         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 = [];
-    const symbols = [];
-    const imports = [];
+    const inputHash = codeGraphInputHashFromStructural(projectDir, structural);
+    const files = structural.files.map(codeFileFromStructural);
+    const symbols = structural.symbols.map(codeSymbolFromStructural);
+    const imports = structural.imports.slice();
     const contents = new Map();
-    let cacheHits = 0;
-    let cacheMisses = 0;
-    for (const absolutePath of absoluteFiles) {
-        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);
+    for (const file of structural.files) {
+        if (!TS_AST_EXTENSIONS.has(extensionOf(file.path)))
+            continue;
+        if (file.size_bytes > MAX_CODE_FILE_BYTES)
+            continue;
+        const absolutePath = (0, node_path_1.join)(projectDir, file.path);
+        if ((0, node_fs_1.existsSync)(absolutePath))
+            contents.set(file.path, (0, node_fs_1.readFileSync)(absolutePath, "utf8"));
+    }
+    writeCodeIndexManifest(projectDir, codeIndexManifestFromStructural(projectDir, structural, fingerprint, structural.manifest.cache));
     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);
@@ -2489,17 +3348,105 @@ function buildCodeGraph(projectDir) {
         tests: tests.sort((a, b) => a.test_path.localeCompare(b.test_path) || a.line - b.line),
         packages: extractPackages(projectDir),
     };
-    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "files.json"), graph.files);
-    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "symbols.json"), graph.symbols);
-    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "imports.json"), graph.imports);
-    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "calls.json"), graph.calls);
-    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "routes.json"), graph.routes);
-    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);
+    removeLegacyCodeGraphSplits(projectDir);
+    writeJson((0, node_path_1.join)(codeGraphDir(projectDir), "graph.json"), compactCodeGraphArtifact(projectDir, graph, structural));
     graphMemoryCache.delete((0, node_path_1.resolve)(projectDir));
     return graph;
 }
+const PRECISE_MEMORY_CODE_PACKET_TYPES = new Set([
+    "bug_fix",
+    "code_explanation",
+    "constraint",
+    "convention",
+    "decision",
+    "gotcha",
+    "rationale",
+]);
+const GENERIC_MEMORY_CODE_SYMBOL_NAMES = new Set([
+    "app",
+    "body",
+    "code",
+    "config",
+    "context",
+    "current",
+    "data",
+    "edge",
+    "edges",
+    "entity",
+    "entities",
+    "file",
+    "files",
+    "from",
+    "graph",
+    "id",
+    "index",
+    "indexes",
+    "input",
+    "item",
+    "items",
+    "memory",
+    "name",
+    "next",
+    "node",
+    "nodes",
+    "output",
+    "packet",
+    "packets",
+    "path",
+    "paths",
+    "project",
+    "projectdir",
+    "query",
+    "result",
+    "results",
+    "root",
+    "state",
+    "status",
+    "summary",
+    "test",
+    "tests",
+    "title",
+    "to",
+    "type",
+    "types",
+    "value",
+]);
+const MAX_PRECISE_SYMBOL_LINKS_PER_PACKET = 24;
+const MAX_PRECISE_TEST_LINKS_PER_PACKET = 12;
+function isPreciseMemoryCodePacket(packet) {
+    return PRECISE_MEMORY_CODE_PACKET_TYPES.has(packet.type);
+}
+function meaningfulSymbolNameForMemoryLink(name) {
+    const normalized = name.trim();
+    if (normalized.length < 4)
+        return false;
+    const compact = normalized.toLowerCase().replace(/[^a-z0-9_$]/g, "");
+    if (!compact || compact.length < 4)
+        return false;
+    if (GENERIC_MEMORY_CODE_SYMBOL_NAMES.has(compact))
+        return false;
+    return /[a-z]/i.test(compact);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function packetTextMentionsIdentifier(packetTextLower, identifier) {
+    const text = identifier.trim().toLowerCase();
+    if (!text)
+        return false;
+    if (/^[a-z0-9_$]+$/.test(text)) {
+        return new RegExp(`(^|[^a-z0-9_$])${escapeRegex(text)}([^a-z0-9_$]|$)`).test(packetTextLower);
+    }
+    return packetTextLower.includes(text);
+}
+function symbolMatchesPacketText(packetTextLower, symbol) {
+    return meaningfulSymbolNameForMemoryLink(symbol.name) && packetTextMentionsIdentifier(packetTextLower, symbol.name);
+}
+function testMatchesPacketText(packetTextLower, test) {
+    return packetTextMentionsIdentifier(packetTextLower, test.title) ||
+        packetTextMentionsIdentifier(packetTextLower, test.test_symbol) ||
+        Boolean(test.covers_symbol && packetTextMentionsIdentifier(packetTextLower, test.covers_symbol));
+}
 function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir)) {
     ensureMemoryDirs(projectDir);
     const packets = loadApprovedPackets(projectDir).sort((a, b) => a.id.localeCompare(b.id));
@@ -2713,15 +3660,20 @@ function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir))
             : packet.type === "decision" || packet.type === "rationale" || packet.type === "constraint"
                 ? "informs_symbol"
                 : "explains_symbol";
+        let preciseSymbolLinks = 0;
         for (const symbol of codeGraph.symbols.filter((symbol) => packetPathSet.has(symbol.path))) {
-            if (packet.type !== "code_explanation" && !packetTextLower.includes(symbol.name.toLowerCase()))
+            if (!isPreciseMemoryCodePacket(packet))
+                continue;
+            if (preciseSymbolLinks >= MAX_PRECISE_SYMBOL_LINKS_PER_PACKET)
+                break;
+            if (!symbolMatchesPacketText(packetTextLower, symbol))
                 continue;
             const symbolEntityId = graphEntityId("symbol", symbol.id);
             addEntity(entities, {
                 id: symbolEntityId,
                 type: "symbol",
                 name: symbol.name,
-                aliases: [symbol.id, symbol.path],
+                aliases: [symbol.id],
                 summary: `${symbol.kind} in ${symbol.path}:${symbol.line}`,
                 first_seen_at: packet.created_at,
                 last_seen_at: packet.updated_at,
@@ -2739,14 +3691,15 @@ function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir))
                 commit: head,
                 evidence: [episodeId],
             });
+            preciseSymbolLinks += 1;
         }
-        for (const route of codeGraph.routes.filter((route) => packetPathSet.has(route.file_path) && packetTextLower.includes(route.path.toLowerCase()))) {
+        for (const route of codeGraph.routes.filter((route) => isPreciseMemoryCodePacket(packet) && packetPathSet.has(route.file_path) && packetTextMentionsIdentifier(packetTextLower, route.path))) {
             const routeEntityId = graphEntityId("route", route.id);
             addEntity(entities, {
                 id: routeEntityId,
                 type: "route",
                 name: `${route.method} ${route.path}`,
-                aliases: [route.id, route.file_path],
+                aliases: [route.id],
                 summary: `${route.framework} route in ${route.file_path}:${route.line}`,
                 first_seen_at: packet.created_at,
                 last_seen_at: packet.updated_at,
@@ -2765,13 +3718,20 @@ function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir))
                 evidence: [episodeId],
             });
         }
+        let preciseTestLinks = 0;
         for (const test of codeGraph.tests.filter((test) => packetPathSet.has(test.test_path) || Boolean(test.covers_path && packetPathSet.has(test.covers_path)))) {
+            if (!isPreciseMemoryCodePacket(packet))
+                continue;
+            if (preciseTestLinks >= MAX_PRECISE_TEST_LINKS_PER_PACKET)
+                break;
+            if (!testMatchesPacketText(packetTextLower, test))
+                continue;
             const testEntityId = graphEntityId("test", test.test_symbol);
             addEntity(entities, {
                 id: testEntityId,
                 type: "test",
                 name: test.title,
-                aliases: [test.test_symbol, test.test_path],
+                aliases: [test.test_symbol],
                 summary: `Test in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`,
                 first_seen_at: packet.created_at,
                 last_seen_at: packet.updated_at,
@@ -2789,6 +3749,7 @@ function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir))
                 commit: head,
                 evidence: [episodeId],
             });
+            preciseTestLinks += 1;
         }
     }
     const manifestCommands = npmScriptCommands(projectDir);
@@ -2842,10 +3803,47 @@ function buildKnowledgeGraph(projectDir, codeGraph = buildCodeGraph(projectDir))
     writeJson((0, node_path_1.join)(graphDir(projectDir), "episodes.json"), graph.episodes);
     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);
+    writeJson((0, node_path_1.join)(graphDir(projectDir), "graph.json"), compactKnowledgeGraphArtifact(projectDir, graph));
     graphMemoryCache.delete((0, node_path_1.resolve)(projectDir));
     return graph;
 }
+function compactKnowledgeGraphArtifact(projectDir, graph) {
+    return {
+        schema_version: 1,
+        compact: true,
+        project_dir: graph.project_dir,
+        repo_key: graph.repo_key,
+        generated_from_updated_at: graph.generated_from_updated_at,
+        repo_state: graph.repo_state,
+        refs: {
+            episodes: (0, node_path_1.relative)(graphDir(projectDir), (0, node_path_1.join)(graphDir(projectDir), "episodes.json")).replace(/\\/g, "/"),
+            entities: (0, node_path_1.relative)(graphDir(projectDir), (0, node_path_1.join)(graphDir(projectDir), "entities.json")).replace(/\\/g, "/"),
+            edges: (0, node_path_1.relative)(graphDir(projectDir), (0, node_path_1.join)(graphDir(projectDir), "edges.json")).replace(/\\/g, "/"),
+        },
+    };
+}
+function isCompactKnowledgeGraphArtifact(value) {
+    return Boolean(value && typeof value === "object" && value.compact === true && value.refs);
+}
+function hydrateKnowledgeGraphArtifact(projectDir, artifact) {
+    if (!isCompactKnowledgeGraphArtifact(artifact))
+        return artifact;
+    const episodesPath = (0, node_path_1.join)(graphDir(projectDir), artifact.refs.episodes);
+    const entitiesPath = (0, node_path_1.join)(graphDir(projectDir), artifact.refs.entities);
+    const edgesPath = (0, node_path_1.join)(graphDir(projectDir), artifact.refs.edges);
+    if (![episodesPath, entitiesPath, edgesPath].every((path) => (0, node_fs_1.existsSync)(path)))
+        return null;
+    return {
+        schema_version: 1,
+        project_dir: artifact.project_dir,
+        repo_key: artifact.repo_key,
+        generated_from_updated_at: artifact.generated_from_updated_at,
+        repo_state: artifact.repo_state,
+        episodes: readJson(episodesPath),
+        entities: readJson(entitiesPath),
+        edges: readJson(edgesPath),
+    };
+}
 function buildPacketIndexes(projectDir) {
     ensureMemoryDirs(projectDir);
     const packets = loadPacketsFromDir(packetsDir(projectDir)).sort((a, b) => a.id.localeCompare(b.id));
@@ -2897,8 +3895,17 @@ function readCurrentCodeGraph(projectDir, expectedInputHash) {
     if (!(0, node_fs_1.existsSync)(path))
         return null;
     try {
-        const graph = readJson(path);
-        const inputHash = expectedInputHash ?? codeGraphInputHash(projectDir, codeIndexSelection(projectDir).files);
+        const artifact = readJson(path);
+        const structural = expectedInputHash ? null : readCurrentStructuralIndex(projectDir);
+        if (!expectedInputHash && !structural)
+            return null;
+        const inputHash = expectedInputHash ?? codeGraphInputHashFromStructuralFingerprint(projectDir, currentStructuralFingerprint(projectDir, structural));
+        const graphInputHash = artifact.repo_state?.input_hash;
+        if (graphInputHash !== inputHash)
+            return null;
+        const graph = hydrateCodeGraphArtifact(projectDir, artifact, structural ?? undefined);
+        if (!graph)
+            return null;
         if (graph.repo_state?.input_hash !== inputHash)
             return null;
         return graph;
@@ -2912,8 +3919,13 @@ function readCurrentKnowledgeGraph(projectDir, codeGraph, expectedInputHash) {
     if (!(0, node_fs_1.existsSync)(path))
         return null;
     try {
-        const graph = readJson(path);
+        const artifact = readJson(path);
         const inputHash = expectedInputHash ?? knowledgeGraphInputHash(projectDir, codeGraph.repo_state.input_hash ?? codeGraphInputHash(projectDir));
+        if (artifact.repo_state?.input_hash !== inputHash)
+            return null;
+        const graph = hydrateKnowledgeGraphArtifact(projectDir, artifact);
+        if (!graph)
+            return null;
         if (graph.repo_state?.input_hash !== inputHash)
             return null;
         return graph;
@@ -2922,14 +3934,14 @@ function readCurrentKnowledgeGraph(projectDir, codeGraph, expectedInputHash) {
         return null;
     }
 }
-function graphFastFingerprint(projectDir, selection = codeIndexSelection(projectDir)) {
+function graphFastFingerprint(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,
+        ...scanStructuralFiles(projectDir).files,
         ...externalIndexFiles(projectDir).map((index) => index.path),
         ...packetPaths,
     ];
@@ -2943,14 +3955,16 @@ function graphFastFingerprint(projectDir, selection = codeIndexSelection(project
     return sha256Hex(entries.join("\n"));
 }
 function readCurrentGraphs(projectDir) {
-    const selection = codeIndexSelection(projectDir);
-    const fingerprint = graphFastFingerprint(projectDir, selection);
+    const fingerprint = graphFastFingerprint(projectDir);
     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 structural = readCurrentStructuralIndex(projectDir);
+    if (!structural)
+        return null;
+    const codeInputHash = codeGraphInputHashFromStructuralFingerprint(projectDir, currentStructuralFingerprint(projectDir, structural));
     const knowledgeInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
     if (cached?.codeInputHash === codeInputHash && cached.knowledgeInputHash === knowledgeInputHash) {
         cached.fingerprint = fingerprint;
@@ -2974,6 +3988,7 @@ function currentOrBuildGraphs(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), "structural.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "graph.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json"),
             ],
@@ -2983,9 +3998,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");
@@ -3000,13 +4015,11 @@ function buildGraphIndexes(projectDir) {
     });
     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")),
-        imports: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "imports.json")),
-        calls: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "calls.json")),
-        routes: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "routes.json")),
-        tests: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "tests.json")),
-        packages: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "packages.json")),
+        mode: "structural-references",
+        graph: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(codeGraphDir(projectDir), "graph.json")),
+        files: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "files.json")),
+        symbols: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "symbols.json")),
+        imports: (0, node_path_1.relative)(projectDir, (0, node_path_1.join)(structuralIndexDir(projectDir), "imports.json")),
         file_count: codeGraph.files.length,
         symbol_count: codeGraph.symbols.length,
         import_count: codeGraph.imports.length,
@@ -3022,7 +4035,7 @@ function buildGraphIndexes(projectDir) {
         knowledgeGraph,
     });
     return {
-        indexes: [...written, graphIndexPath, codeGraphIndexPath],
+        indexes: [...written, (0, node_path_1.join)(indexesDir(projectDir), "structural.json"), graphIndexPath, codeGraphIndexPath],
         codeGraph,
         knowledgeGraph,
     };
@@ -3040,7 +4053,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: {
@@ -3114,15 +4127,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));
@@ -3586,13 +4599,24 @@ function scoreText(terms, text, boosts = []) {
         score += 1 + Math.min(occurrences, 4);
         if (firstIndex < 80)
             score += 1;
-        if (boosts.some((boost) => boost.toLowerCase().includes(term) || term.includes(boost.toLowerCase())))
-            score += 2;
+        score += boosts.reduce((best, boost) => Math.max(best, boostTermScore(boost, term)), 0);
     }
     if (terms.length > 1 && terms.every((term) => haystack.includes(term)))
         score += 3;
     return score;
 }
+function boostTermScore(boost, term) {
+    const normalized = boost.toLowerCase();
+    if (normalized === term)
+        return 8;
+    if (tokenize(normalized).includes(term))
+        return 5;
+    if (term.length >= 6 && normalized.includes(term))
+        return 2;
+    if (normalized.length >= 6 && term.includes(normalized))
+        return 2;
+    return 0;
+}
 function queryCodeGraph(projectDir, query, limit = 10, graph) {
     graph = graph ?? readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const terms = tokenize(query);
@@ -3639,6 +4663,46 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
     const calls = graph.calls
         .filter((call) => symbolIds.has(call.to_symbol) || Boolean(call.from_symbol && symbolIds.has(call.from_symbol)))
         .slice(0, limit);
+    const structuralIndex = readCurrentStructuralIndex(projectDir);
+    const graphPaths = new Set(graph.files.map((file) => file.path));
+    const graphSymbolIds = new Set(graph.symbols.map((symbol) => symbol.id));
+    const structuralFiles = structuralIndex
+        ? structuralIndex.files
+            .map((file) => ({
+            file,
+            score: scoreText(terms, `${file.path} ${file.kind} ${file.language} ${file.extraction} ${file.signals.join(" ")} ${file.concepts.join(" ")} ${file.top_symbols.join(" ")}`, [file.path, file.language, ...file.concepts]),
+        }))
+            .filter((entry) => entry.score > 0 && !graphPaths.has(entry.file.path))
+            .sort((a, b) => b.score - a.score || a.file.path.localeCompare(b.file.path))
+            .slice(0, limit)
+            .map((entry) => entry.file)
+        : [];
+    const structuralSymbols = structuralIndex
+        ? structuralIndex.symbols
+            .map((symbol) => ({
+            symbol,
+            score: scoreText(terms, `${symbol.name} ${symbol.kind} ${symbol.path} ${symbol.language} ${symbol.parser}`, [symbol.name, symbol.path]),
+        }))
+            .filter((entry) => entry.score > 0 && !graphSymbolIds.has(entry.symbol.id))
+            .sort((a, b) => b.score - a.score || a.symbol.path.localeCompare(b.symbol.path) || a.symbol.line - b.symbol.line)
+            .slice(0, limit)
+            .map((entry) => entry.symbol)
+        : [];
+    const structuralRelevantPaths = new Set([
+        ...structuralFiles.map((file) => file.path),
+        ...structuralSymbols.map((symbol) => symbol.path),
+    ]);
+    const structuralEdges = structuralIndex
+        ? structuralIndex.edges
+            .map((edge) => ({
+            edge,
+            score: scoreText(terms, `${edge.relation} ${edge.source} ${edge.target} ${edge.source_file}`, [edge.source_file, edge.target]),
+        }))
+            .filter((entry) => entry.score > 0 || structuralRelevantPaths.has(entry.edge.source_file))
+            .sort((a, b) => b.score - a.score || a.edge.source_file.localeCompare(b.edge.source_file) || a.edge.target.localeCompare(b.edge.target))
+            .slice(0, limit)
+            .map((entry) => entry.edge)
+        : [];
     const lines = [
         "# Kage Code Graph Context",
         "",
@@ -3649,6 +4713,14 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         ...symbols.map((symbol, index) => `${index + 1}. [symbol] ${symbol.kind} ${symbol.name} in ${symbol.path}:${symbol.line} (${symbol.language}, ${symbol.parser})`),
         ...tests.map((test, index) => `${index + 1}. [test] ${test.title} in ${test.test_path}:${test.line}${test.covers_symbol ? ` covers ${test.covers_symbol}` : ""}`),
         ...files.slice(0, 5).map((file, index) => `${index + 1}. [file] ${file.path} (${file.kind}, ${file.language}, ${file.parser})`),
+        structuralFiles.length || structuralSymbols.length || structuralEdges.length ? "" : "",
+        structuralFiles.length || structuralSymbols.length || structuralEdges.length ? "## Structural Index" : "",
+        ...structuralSymbols.map((symbol, index) => `${index + 1}. [structural symbol] ${symbol.kind} ${symbol.name} in ${symbol.path}:${symbol.line} (${symbol.language}, ${symbol.parser})`),
+        ...structuralFiles.slice(0, 5).map((file, index) => `${index + 1}. [structural file] ${file.path} (${file.kind}, ${file.language}, ${file.extraction})`),
+        ...structuralEdges
+            .filter((edge) => edge.relation === "imports")
+            .slice(0, 5)
+            .map((edge, index) => `${index + 1}. [structural import] ${edge.source_file}${edge.source_location ? `:${edge.source_location.replace(/^L/, "")}` : ""} -> ${edge.target} (${edge.confidence})`),
         imports.length ? "" : "",
         imports.length ? "## Imports" : "",
         ...imports.map(({ item }, index) => `${index + 1}. ${item.from_path}:${item.line} ${item.kind} ${item.specifier}${item.to_path ? ` -> ${item.to_path}` : ""}`),
@@ -3656,7 +4728,19 @@ function queryCodeGraph(projectDir, query, limit = 10, graph) {
         calls.length ? "## Calls" : "",
         ...calls.map((call, index) => `${index + 1}. ${call.from_symbol ? symbolNameById.get(call.from_symbol) ?? call.from_symbol : call.path} calls ${symbolNameById.get(call.to_symbol) ?? call.to_symbol} at ${call.path}:${call.line}`),
     ];
-    return { query, context_block: lines.join("\n"), files, symbols, imports: imports.map((entry) => entry.item), calls, routes, tests };
+    return {
+        query,
+        context_block: lines.join("\n"),
+        files,
+        symbols,
+        imports: imports.map((entry) => entry.item),
+        calls,
+        routes,
+        tests,
+        structural_files: structuralFiles,
+        structural_symbols: structuralSymbols,
+        structural_edges: structuralEdges,
+    };
 }
 function queryGraph(projectDir, query, limit = 10, graph) {
     graph = graph ?? readCurrentGraphs(projectDir)?.knowledgeGraph ?? buildKnowledgeGraph(projectDir);
@@ -3739,6 +4823,7 @@ function kageMetrics(projectDir) {
     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 structuralManifest = readStructuralIndexManifest(projectDir);
     const sourceFiles = codeGraph.files.filter((file) => file.kind === "source" || file.kind === "test");
     const indexedSourceFiles = sourceFiles.filter((file) => file.parser !== "metadata");
     const coverage = indexManifest.coverage.indexable_files > 0 ? indexManifest.coverage.coverage_percent : percent(indexedSourceFiles.length, sourceFiles.length);
@@ -3789,6 +4874,17 @@ function kageMetrics(projectDir) {
             cache_hits: indexManifest.cache.hits,
             cache_misses: indexManifest.cache.misses,
         },
+        structural_index: {
+            files: structuralManifest.files.indexed,
+            symbols: structuralManifest.symbols,
+            edges: structuralManifest.edges,
+            metadata_only_files: structuralManifest.files.metadata_only,
+            ignored_files: structuralManifest.files.ignored,
+            languages: structuralManifest.languages,
+            worker_count: structuralManifest.worker_count,
+            cache_hits: structuralManifest.cache.hits,
+            cache_misses: structuralManifest.cache.misses,
+        },
         memory_graph: {
             approved_packets: approvedPackets,
             pending_packets: pendingPackets,
@@ -3842,7 +4938,9 @@ function auditProject(projectDir) {
     const preciseFiles = codeGraph.files.filter((file) => preciseParsers.includes(file.parser)).length;
     const astFiles = codeGraph.files.filter((file) => astParsers.includes(file.parser)).length;
     const fallbackFiles = codeGraph.files.filter((file) => file.parser === "generic-static" || file.parser === "metadata").length;
-    const memoryCodeEdges = knowledgeGraph.edges.filter((edge) => ["explains_symbol", "informs_symbol", "fixes_symbol", "applies_to_route", "verified_by_test"].includes(edge.relation)).length;
+    const preciseMemoryCodeEdges = knowledgeGraph.edges.filter((edge) => ["explains_symbol", "informs_symbol", "fixes_symbol", "applies_to_route", "verified_by_test"].includes(edge.relation)).length;
+    const pathMemoryCodeEdges = knowledgeGraph.edges.filter((edge) => edge.relation === "affects_path").length;
+    const memoryCodeEdges = preciseMemoryCodeEdges + pathMemoryCodeEdges;
     const stalePackets = quality.totals.stale;
     const duplicateCandidatesTotal = quality.totals.duplicate;
     const structuredCoverage = percent(structuredPackets.length, approved.length);
@@ -3864,8 +4962,11 @@ function auditProject(projectDir) {
     if (preciseFiles < indexableFiles) {
         recommendations.push("Add or extend SCIP/LSIF/LSP index artifacts in CI for remaining source files; keep AST/static extraction as fallback.");
     }
-    if (!memoryCodeEdges && approved.length && codeGraph.symbols.length) {
-        recommendations.push("Link memory packets to symbols, routes, and tests with code_explanation, bug_fix, decision, and verification context.");
+    if (!memoryCodeEdges && approved.length && codeGraph.files.length) {
+        recommendations.push("Ground memory packets to repo paths, symbols, routes, or tests so recall and the viewer can bridge memory to code.");
+    }
+    else if (!preciseMemoryCodeEdges && pathMemoryCodeEdges && codeGraph.symbols.length) {
+        recommendations.push("Path-level memory links exist; add symbol, route, or test names to high-value memories when you need precise code evidence.");
     }
     if (!validation.ok) {
         recommendations.push("Fix validation errors before relying on Kage in PR or agent-start workflows.");
@@ -3905,6 +5006,8 @@ function auditProject(projectDir) {
             },
             graph_links: {
                 memory_code_edges: memoryCodeEdges,
+                precise_memory_code_edges: preciseMemoryCodeEdges,
+                path_memory_code_edges: pathMemoryCodeEdges,
                 evidence_coverage_percent: percent(knowledgeGraph.edges.filter((edge) => edge.evidence.length > 0).length, knowledgeGraph.edges.length),
             },
         },
@@ -4273,6 +5376,7 @@ function kageMetricsShallow(projectDir, inputs = {}) {
     const knowledgeGraph = inputs.knowledgeGraph ?? buildKnowledgeGraph(projectDir, codeGraph);
     const validation = inputs.validation ?? validateProject(projectDir);
     const indexManifest = readCodeIndexManifest(projectDir);
+    const structuralManifest = readStructuralIndexManifest(projectDir);
     const sourceFiles = codeGraph.files.filter((file) => file.kind === "source" || file.kind === "test");
     const indexedSourceFiles = sourceFiles.filter((file) => file.parser !== "metadata");
     const coverage = indexManifest.coverage.indexable_files > 0 ? indexManifest.coverage.coverage_percent : percent(indexedSourceFiles.length, sourceFiles.length);
@@ -4305,6 +5409,17 @@ function kageMetricsShallow(projectDir, inputs = {}) {
             cache_hits: indexManifest.cache.hits,
             cache_misses: indexManifest.cache.misses,
         },
+        structural_index: {
+            files: structuralManifest.files.indexed,
+            symbols: structuralManifest.symbols,
+            edges: structuralManifest.edges,
+            metadata_only_files: structuralManifest.files.metadata_only,
+            ignored_files: structuralManifest.files.ignored,
+            languages: structuralManifest.languages,
+            worker_count: structuralManifest.worker_count,
+            cache_hits: structuralManifest.cache.hits,
+            cache_misses: structuralManifest.cache.misses,
+        },
         memory_graph: {
             approved_packets: loadPacketsFromDir(packetsDir(projectDir)).length,
             pending_packets: loadPacketsFromDir(pendingDir(projectDir)).length,
@@ -5476,7 +6591,7 @@ function prCheck(projectDir) {
     const rawStatus = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
     const validation = validateProject(projectDir);
     const tree = gitTree(projectDir);
-    const codeInputHash = codeGraphInputHash(projectDir);
+    const codeInputHash = currentCodeGraphInputHash(projectDir);
     const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
     const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
         .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))