@kage-core/kage-graph-mcp 1.1.12 → 1.1.14

package/dist/kernel.js

@@ -40,6 +40,7 @@ exports.pendingDir = pendingDir;
 exports.publicCandidatesDir = publicCandidatesDir;
 exports.indexesDir = indexesDir;
 exports.graphDir = graphDir;
+exports.graphRegistryDir = graphRegistryDir;
 exports.codeGraphDir = codeGraphDir;
 exports.branchesDir = branchesDir;
 exports.reviewDir = reviewDir;
@@ -62,6 +63,7 @@ exports.catalogDomainNodeCount = catalogDomainNodeCount;
 exports.ensureMemoryDirs = ensureMemoryDirs;
 exports.loadApprovedPackets = loadApprovedPackets;
 exports.loadPendingPackets = loadPendingPackets;
+exports.writeLspSymbolIndex = writeLspSymbolIndex;
 exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
@@ -74,6 +76,8 @@ exports.queryCodeGraph = queryCodeGraph;
 exports.queryGraph = queryGraph;
 exports.graphMermaid = graphMermaid;
 exports.kageMetrics = kageMetrics;
+exports.auditProject = auditProject;
+exports.memoryInbox = memoryInbox;
 exports.qualityReport = qualityReport;
 exports.benchmarkProject = benchmarkProject;
 exports.benchmarkTaskComparison = benchmarkTaskComparison;
@@ -119,11 +123,16 @@ exports.MEMORY_TYPES = [
     "runbook",
     "bug_fix",
     "decision",
+    "rationale",
     "convention",
     "workflow",
     "gotcha",
     "reference",
     "policy",
+    "issue_context",
+    "code_explanation",
+    "negative_result",
+    "constraint",
 ];
 exports.SETUP_AGENTS = [
     "codex",
@@ -174,10 +183,13 @@ Capture examples:
 - A bug cause and verified fix.
 - A convention future agents should follow.
 - A decision and its rationale.
+- Why code, architecture, product, or release behavior ended up this way.
+- A non-obvious issue state, failed approach, or code explanation.
 - A gotcha that caused rediscovery or wasted time.
 - A path-specific workflow or dependency relationship.
 
-Keep captures concise and future-facing. Do not store raw transcripts.
+Keep captures concise, source-backed, and useful for future understanding,
+decisions, debugging, explanation, or action. Do not store raw transcripts.
 
 ## End-Of-Task Proposal
 
@@ -264,6 +276,9 @@ function indexesDir(projectDir) {
 function graphDir(projectDir) {
     return (0, node_path_1.join)(memoryRoot(projectDir), "graph");
 }
+function graphRegistryDir(projectDir) {
+    return (0, node_path_1.join)(memoryRoot(projectDir), "graph_registry");
+}
 function codeGraphDir(projectDir) {
     return (0, node_path_1.join)(memoryRoot(projectDir), "code_graph");
 }
@@ -526,7 +541,7 @@ function evaluateMemoryQuality(projectDir, packet) {
     const bodyTokens = tokenize(packet.body);
     const hasEvidence = packet.source_refs.length > 0;
     const hasPaths = packet.paths.length > 0;
-    const highValueType = ["runbook", "bug_fix", "decision", "convention", "workflow", "gotcha", "policy"].includes(packet.type);
+    const highValueType = ["runbook", "bug_fix", "decision", "rationale", "convention", "workflow", "gotcha", "policy", "issue_context", "code_explanation", "negative_result", "constraint"].includes(packet.type);
     if (highValueType) {
         score += 14;
         reasons.push("high-value memory type");
@@ -589,7 +604,7 @@ function evaluateMemoryAdmission(projectDir, packet) {
     const risks = [];
     const text = `${packet.title}\n${packet.summary}\n${packet.body}`.toLowerCase();
     let score = 0;
-    if (["runbook", "bug_fix", "decision", "convention", "workflow", "gotcha", "policy"].includes(packet.type)) {
+    if (["runbook", "bug_fix", "decision", "rationale", "convention", "workflow", "gotcha", "policy", "issue_context", "code_explanation", "negative_result", "constraint"].includes(packet.type)) {
         score += 18;
         reasons.push("durable memory type");
     }
@@ -601,9 +616,9 @@ function evaluateMemoryAdmission(projectDir, packet) {
         score += 12;
         reasons.push("repo scoped or path grounded");
     }
-    if (/(when|after|before|because|requires|must|avoid|prefer|use this|run this|root cause|decision|convention|gotcha|workaround|fix|policy)/i.test(packet.body)) {
+    if (/(when|after|before|because|requires|must|avoid|prefer|use this|run this|root cause|rationale|decision|convention|gotcha|workaround|fix|policy|issue|hypothesis|unresolved|explains?|data flow|invariant|coupling|constraint)/i.test(packet.body)) {
         score += 18;
-        reasons.push("has future trigger or rationale");
+        reasons.push("has durable trigger, rationale, issue context, or explanation");
     }
     if (/(verified by|evidence:|test passed|reproduced|root cause)/i.test(packet.body)) {
         score += 10;
@@ -986,6 +1001,15 @@ function createRepoOverviewPacket(projectDir) {
             ...((0, node_fs_1.existsSync)(packagePath) ? [{ kind: "file", path: "package.json" }] : []),
             ...((0, node_fs_1.existsSync)(readmePath) ? [{ kind: "file", path: "README.md" }] : []),
         ],
+        context: {
+            fact: "Generated repo overview summarizes package metadata and the README as a navigation aid for agent startup.",
+            why: "Agents need fast repo orientation before deeper recall or code graph queries, but generated overview memory should stay separate from human rationale.",
+            trigger: "Recall when an agent needs first-pass repo purpose, scripts, stack, or README context.",
+            action: "Use this as orientation only, then inspect source-backed memory and code graph facts for implementation decisions.",
+            verification: "Generated from package.json and README.md when present.",
+            risk_if_forgotten: "Agents may waste context rediscovering basic repo purpose or treat generated overview text as deeper semantic memory.",
+            stale_when: "package.json or README.md changes enough that the generated overview no longer matches the repo.",
+        },
         freshness: {
             ttl_days: 90,
             last_verified_at: createdAt.slice(0, 10),
@@ -1068,6 +1092,15 @@ function createRepoStructurePacket(projectDir) {
         paths: existing.filter((entry) => pathExistsInRepo(projectDir, entry)),
         stack: [],
         source_refs: existing.map((path) => ({ kind: "file", path })),
+        context: {
+            fact: "Generated repo structure summarizes top-level files, workflows, and test files as a navigation aid.",
+            why: "Agents need a quick map of repo entry points before choosing which files, workflows, or tests to inspect.",
+            trigger: "Recall when orienting to this repo's layout, CI workflows, or test locations.",
+            action: "Use this as a starting map and verify details against the current filesystem or code graph before editing.",
+            verification: "Generated from files present in the repository.",
+            risk_if_forgotten: "Agents may miss important entry points such as AGENTS.md, workflows, or MCP tests during initial orientation.",
+            stale_when: "Top-level repo structure, workflow files, or test files change.",
+        },
         freshness: {
             ttl_days: 30,
             last_verified_at: createdAt.slice(0, 10),
@@ -1102,7 +1135,7 @@ function upsertGeneratedPacket(projectDir, packet) {
     if (existing && existing.quality?.reviewer !== "kage-indexer")
         return;
     if (existing) {
-        const comparableFields = ["title", "summary", "body", "tags", "paths", "stack", "source_refs", "freshness"];
+        const comparableFields = ["title", "summary", "body", "tags", "paths", "stack", "source_refs", "context", "freshness"];
         const same = comparableFields.every((field) => JSON.stringify(existing[field]) === JSON.stringify(packet[field]));
         if (same)
             return;
@@ -1170,6 +1203,9 @@ function packetGroundingWarnings(projectDir, packet, source) {
     const hasGroundedSource = packet.source_refs.some((ref) => {
         if (typeof ref.path === "string")
             return !shouldSkipRepoMemoryPath(ref.path) && pathExistsInRepo(projectDir, ref.path);
+        if (Array.isArray(ref.changed_files)) {
+            return ref.changed_files.some((path) => typeof path === "string" && !shouldSkipRepoMemoryPath(path) && pathExistsInRepo(projectDir, path));
+        }
         if (typeof ref.kind === "string" && ["explicit_capture", "local_public_candidate"].includes(ref.kind))
             return true;
         return typeof ref.url === "string";
@@ -1894,6 +1930,54 @@ function parseLspDocumentSymbols(projectDir, path) {
     }
     return { symbols, imports: [], calls: [] };
 }
+function writeLspSymbolIndex(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const outDir = (0, node_path_1.join)(memoryRoot(projectDir), "code_index");
+    ensureDir(outDir);
+    const outPath = (0, node_path_1.join)(outDir, "lsp-symbols.json");
+    const documents = [];
+    let symbolCount = 0;
+    const errors = [];
+    for (const absolutePath of listCodeFiles(projectDir)) {
+        const rel = (0, node_path_1.relative)(projectDir, absolutePath).replace(/\\/g, "/");
+        if (!TS_AST_EXTENSIONS.has(extensionOf(rel)))
+            continue;
+        try {
+            const content = (0, node_fs_1.readFileSync)(absolutePath, "utf8");
+            const symbols = extractSymbols(rel, content).map((symbol) => ({
+                name: symbol.name,
+                kind: symbol.kind,
+                detail: symbol.signature,
+                range: {
+                    start: { line: Math.max(0, symbol.line - 1), character: 0 },
+                    end: { line: Math.max(0, (symbol.end_line ?? symbol.line) - 1), character: 0 },
+                },
+            }));
+            if (!symbols.length)
+                continue;
+            symbolCount += symbols.length;
+            documents.push({ path: rel, symbols });
+        }
+        catch (error) {
+            errors.push(`${rel}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    writeJson(outPath, {
+        schema_version: 1,
+        generator: "kage-lsp-symbol-index",
+        generated_at: nowIso(),
+        documents,
+    });
+    return {
+        ok: errors.length === 0,
+        project_dir: projectDir,
+        path: outPath,
+        parser: "lsp",
+        documents: documents.length,
+        symbols: symbolCount,
+        errors,
+    };
+}
 function parseLsif(projectDir, path) {
     const docs = new Map();
     const ranges = new Map();
@@ -2030,9 +2114,14 @@ function buildCodeGraph(projectDir) {
     const addSymbol = (symbol) => {
         if (!fileByPath.has(symbol.path))
             return;
-        if (symbols.some((existing) => existing.id === symbol.id))
-            return;
         const file = fileByPath.get(symbol.path);
+        const existing = symbols.find((candidate) => candidate.id === symbol.id);
+        if (existing) {
+            existing.parser = strongerParser(existing.parser, symbol.parser);
+            if (file)
+                file.parser = strongerParser(file.parser, symbol.parser);
+            return;
+        }
         if (file)
             file.parser = strongerParser(file.parser, symbol.parser);
         symbols.push(symbol);
@@ -2105,6 +2194,7 @@ function buildKnowledgeGraph(projectDir) {
     const episodes = [];
     const repoEntityId = graphEntityId("repo", repoKey(projectDir));
     const generatedFrom = packets.map((packet) => packet.updated_at).sort().at(-1) ?? null;
+    const codeGraph = buildCodeGraph(projectDir);
     addEntity(entities, {
         id: repoEntityId,
         type: "repo",
@@ -2270,6 +2360,118 @@ function buildKnowledgeGraph(projectDir) {
                 evidence: [episodeId],
             });
         }
+        const context = engineeringContextFor(packet);
+        if (context.verification) {
+            const command = normalizeCommandText(context.verification);
+            if (command) {
+                const commandId = graphEntityId("command", command);
+                addEntity(entities, {
+                    id: commandId,
+                    type: "command",
+                    name: command,
+                    summary: `Verification command from structured memory context.`,
+                    first_seen_at: packet.created_at,
+                    last_seen_at: packet.updated_at,
+                    evidence: [episodeId],
+                });
+                addEdge(edges, {
+                    from: memoryId,
+                    to: commandId,
+                    relation: "verified_by",
+                    fact: `"${packet.title}" is verified by "${command}".`,
+                    confidence: packet.confidence,
+                    valid_from: packet.updated_at,
+                    invalidated_at: null,
+                    branch,
+                    commit: head,
+                    evidence: [episodeId],
+                });
+            }
+        }
+        const packetTextLower = `${packet.title}\n${packet.summary}\n${packet.body}`.toLowerCase();
+        const packetPathSet = new Set(packet.paths);
+        const symbolRelation = packet.type === "bug_fix"
+            ? "fixes_symbol"
+            : packet.type === "decision" || packet.type === "rationale" || packet.type === "constraint"
+                ? "informs_symbol"
+                : "explains_symbol";
+        for (const symbol of codeGraph.symbols.filter((symbol) => packetPathSet.has(symbol.path))) {
+            if (packet.type !== "code_explanation" && !packetTextLower.includes(symbol.name.toLowerCase()))
+                continue;
+            const symbolEntityId = graphEntityId("symbol", symbol.id);
+            addEntity(entities, {
+                id: symbolEntityId,
+                type: "symbol",
+                name: symbol.name,
+                aliases: [symbol.id, symbol.path],
+                summary: `${symbol.kind} in ${symbol.path}:${symbol.line}`,
+                first_seen_at: packet.created_at,
+                last_seen_at: packet.updated_at,
+                evidence: [episodeId],
+            });
+            addEdge(edges, {
+                from: memoryId,
+                to: symbolEntityId,
+                relation: symbolRelation,
+                fact: `"${packet.title}" ${symbolRelation.replace(/_/g, " ")} ${symbol.name} in ${symbol.path}.`,
+                confidence: packet.confidence,
+                valid_from: packet.updated_at,
+                invalidated_at: null,
+                branch,
+                commit: head,
+                evidence: [episodeId],
+            });
+        }
+        for (const route of codeGraph.routes.filter((route) => packetPathSet.has(route.file_path) && packetTextLower.includes(route.path.toLowerCase()))) {
+            const routeEntityId = graphEntityId("route", route.id);
+            addEntity(entities, {
+                id: routeEntityId,
+                type: "route",
+                name: `${route.method} ${route.path}`,
+                aliases: [route.id, route.file_path],
+                summary: `${route.framework} route in ${route.file_path}:${route.line}`,
+                first_seen_at: packet.created_at,
+                last_seen_at: packet.updated_at,
+                evidence: [episodeId],
+            });
+            addEdge(edges, {
+                from: memoryId,
+                to: routeEntityId,
+                relation: "applies_to_route",
+                fact: `"${packet.title}" applies to route ${route.method} ${route.path}.`,
+                confidence: packet.confidence,
+                valid_from: packet.updated_at,
+                invalidated_at: null,
+                branch,
+                commit: head,
+                evidence: [episodeId],
+            });
+        }
+        for (const test of codeGraph.tests.filter((test) => packetPathSet.has(test.test_path) || Boolean(test.covers_path && packetPathSet.has(test.covers_path)))) {
+            const testEntityId = graphEntityId("test", test.test_symbol);
+            addEntity(entities, {
+                id: testEntityId,
+                type: "test",
+                name: test.title,
+                aliases: [test.test_symbol, test.test_path],
+                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,
+                evidence: [episodeId],
+            });
+            addEdge(edges, {
+                from: memoryId,
+                to: testEntityId,
+                relation: "verified_by_test",
+                fact: `"${packet.title}" is related to test "${test.title}".`,
+                confidence: packet.confidence,
+                valid_from: packet.updated_at,
+                invalidated_at: null,
+                branch,
+                commit: head,
+                evidence: [episodeId],
+            });
+        }
     }
     const manifestCommands = npmScriptCommands(projectDir);
     if (manifestCommands.length) {
@@ -2702,38 +2904,148 @@ function scorePacket(queryTerms, packet) {
         score += 1;
     return { score, why: unique(why).slice(0, 8) };
 }
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const BM25_FIELD_WEIGHTS = {
+    title: 4,
+    summary: 2.4,
+    tag: 2.8,
+    path: 2.4,
+    type: 1.8,
+    body: 1,
+};
+function lexicalStem(term) {
+    if (term.length > 5 && term.endsWith("ing"))
+        return term.slice(0, -3);
+    if (term.length > 4 && term.endsWith("ies"))
+        return `${term.slice(0, -3)}y`;
+    if (term.length > 4 && term.endsWith("es"))
+        return term.slice(0, -2);
+    if (term.length > 3 && term.endsWith("s"))
+        return term.slice(0, -1);
+    return term;
+}
+function expandQueryTerms(terms) {
+    return unique(terms.flatMap((term) => unique([term, lexicalStem(term)].filter(Boolean))));
+}
+function bm25Document(packet) {
+    const termFrequency = new Map();
+    const fieldHits = new Map();
+    let length = 0;
+    const addField = (field, text) => {
+        const weight = BM25_FIELD_WEIGHTS[field];
+        for (const token of tokenize(text)) {
+            termFrequency.set(token, (termFrequency.get(token) ?? 0) + weight);
+            if (!fieldHits.has(token))
+                fieldHits.set(token, new Set());
+            fieldHits.get(token).add(field);
+            length += weight;
+        }
+    };
+    addField("title", packet.title);
+    addField("summary", packet.summary);
+    addField("tag", packet.tags.join(" "));
+    addField("path", packet.paths.join(" "));
+    addField("type", packet.type);
+    addField("body", packet.body);
+    return { packet, termFrequency, fieldHits, length: Math.max(1, length) };
+}
+function scorePacketsBm25(queryTerms, packets) {
+    const terms = expandQueryTerms(queryTerms);
+    const documents = packets.map(bm25Document);
+    const result = new Map();
+    if (!terms.length || !documents.length)
+        return result;
+    const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+    const documentFrequency = new Map();
+    for (const term of terms) {
+        documentFrequency.set(term, documents.filter((document) => document.termFrequency.has(term)).length);
+    }
+    for (const document of documents) {
+        let score = 0;
+        const why = [];
+        for (const term of terms) {
+            const termFrequency = document.termFrequency.get(term) ?? 0;
+            if (termFrequency <= 0)
+                continue;
+            const df = documentFrequency.get(term) ?? 0;
+            const idf = Math.log(1 + (documents.length - df + 0.5) / (df + 0.5));
+            const denominator = termFrequency + BM25_K1 * (1 - BM25_B + BM25_B * (document.length / averageLength));
+            score += idf * ((termFrequency * (BM25_K1 + 1)) / denominator);
+            const fields = Array.from(document.fieldHits.get(term) ?? []).sort();
+            if (fields.length)
+                why.push(`bm25:${fields.join("+")}:${term}`);
+        }
+        if (score > 0)
+            result.set(document.packet.id, { score: Number(score.toFixed(2)), why: unique(why).slice(0, 8) });
+    }
+    return result;
+}
+function recallIntentBoost(queryTerms, packet) {
+    const terms = new Set(expandQueryTerms(queryTerms));
+    const commandIntent = ["run", "test", "tests", "build", "command", "commands"].some((term) => terms.has(term));
+    const debugIntent = ["bug", "fix", "error", "fail", "debug"].some((term) => terms.has(term));
+    const gotchaIntent = terms.has("gotcha");
+    const decisionIntent = terms.has("decision");
+    const packetText = `${packet.title}\n${packet.summary}\n${packet.body}\n${packet.tags.join(" ")}`;
+    const hasCommandEvidence = /\b(?:npm|pnpm|yarn|bun|node|python|pytest|vitest|cargo|go)\s+(?:run\s+)?(?:test|tests|build|dev|start)\b|package\.json|scripts?/i.test(packetText);
+    let score = 0;
+    if (commandIntent) {
+        if (packet.type === "runbook")
+            score += hasCommandEvidence ? 22 : 8;
+        if (packet.type === "repo_map" && hasCommandEvidence)
+            score += 34;
+        if (!["runbook", "repo_map", "workflow"].includes(packet.type) && !debugIntent)
+            score -= 8;
+        if (packet.type === "decision" && /release|verified by|passed|published/i.test(`${packet.title}\n${packet.body}`))
+            score -= 3;
+    }
+    if (debugIntent && packet.type === "bug_fix")
+        score += 10;
+    if (gotchaIntent)
+        score += packet.type === "gotcha" ? 18 : -4;
+    if (decisionIntent)
+        score += packet.type === "decision" ? 12 : 0;
+    return score;
+}
 function recallBreakdown(projectDir, terms, packet, textScore) {
     const graph = buildKnowledgeGraph(projectDir);
     const packetEntityId = graph.entities.find((entity) => entity.type === "memory" && entity.aliases.includes(packet.id))?.id;
-    const graphScore = packetEntityId
+    const rawGraphScore = packetEntityId
         ? graph.edges.filter((edge) => edge.from === packetEntityId || edge.to === packetEntityId).reduce((sum, edge) => sum + scoreText(terms, edge.fact), 0)
         : 0;
+    const graphScore = Math.min(rawGraphScore * 0.45, textScore > 0 ? textScore * 1.5 + 12 : 8);
     const pathTypeTag = scoreText(terms, `${packet.type} ${packet.tags.join(" ")} ${packet.paths.join(" ")}`, [packet.type, ...packet.tags, ...packet.paths]);
+    const intent = recallIntentBoost(terms, packet);
     const freshness = packet.status === "approved" ? 2 : packet.status === "pending" ? 0 : -5;
     const quality = Number(packet.quality.score ?? evaluateMemoryQuality(projectDir, packet).score) / 10;
     const feedback = packetFeedbackScore(packet);
     const vector = 0;
-    const final = Number((textScore + graphScore * 0.45 + pathTypeTag * 0.8 + vector + freshness + quality + feedback).toFixed(2));
-    return { text: textScore, graph: graphScore, path_type_tag: pathTypeTag, vector, freshness, quality: Number(quality.toFixed(2)), feedback, final };
+    const final = Number((textScore + graphScore + pathTypeTag * 0.8 + intent + vector + freshness + quality + feedback).toFixed(2));
+    return { bm25: textScore, text: textScore, graph: Number(graphScore.toFixed(2)), path_type_tag: pathTypeTag, intent, vector, freshness, quality: Number(quality.toFixed(2)), feedback, final };
 }
 function recall(projectDir, query, limit = 5, explain = false) {
     indexProject(projectDir);
     const terms = tokenize(query);
-    const scored = loadApprovedPackets(projectDir)
+    const approvedPackets = loadApprovedPackets(projectDir);
+    const lexicalScores = scorePacketsBm25(terms, approvedPackets);
+    const scored = approvedPackets
         .map((packet) => {
-        const { score, why } = scorePacket(terms, packet);
+        const { score, why } = lexicalScores.get(packet.id) ?? { score: 0, why: [] };
         const score_breakdown = recallBreakdown(projectDir, terms, packet, score);
-        const relevance = score + score_breakdown.graph + score_breakdown.path_type_tag + score_breakdown.vector;
-        return { packet, score: explain ? score_breakdown.final : score, relevance, why_matched: why, score_breakdown };
+        const relevance = score + score_breakdown.graph + score_breakdown.path_type_tag + score_breakdown.intent + score_breakdown.vector;
+        return { packet, score: score_breakdown.final, relevance, why_matched: why, score_breakdown };
     })
         .filter((entry) => entry.relevance > 0)
         .sort((a, b) => b.score - a.score || a.packet.title.localeCompare(b.packet.title))
         .slice(0, limit)
         .map(({ relevance, ...entry }) => entry);
     const pendingSeen = new Set();
-    const pendingScored = recallablePendingPackets(projectDir)
+    const pendingPackets = recallablePendingPackets(projectDir);
+    const pendingLexicalScores = scorePacketsBm25(terms, pendingPackets);
+    const pendingScored = pendingPackets
         .map((packet) => {
-        const { score, why } = scorePacket(terms, packet);
+        const { score, why } = pendingLexicalScores.get(packet.id) ?? { score: 0, why: [] };
         return { packet, score, why_matched: why };
     })
         .filter((entry) => entry.score > 0)
@@ -2788,7 +3100,7 @@ function recall(projectDir, query, limit = 5, explain = false) {
             ? scored.map((entry) => ({
                 packet_id: entry.packet.id,
                 title: entry.packet.title,
-                provider: "text",
+                provider: "bm25",
                 score_breakdown: entry.score_breakdown,
                 why_matched: entry.why_matched,
             }))
@@ -3039,6 +3351,206 @@ function kageMetrics(projectDir) {
         },
     };
 }
+function auditProject(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const validation = validateProject(projectDir);
+    const quality = qualityReport(projectDir);
+    const codeGraph = buildCodeGraph(projectDir);
+    const knowledgeGraph = buildKnowledgeGraph(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const pending = loadPendingPackets(projectDir);
+    const structuredPackets = approved.filter(hasStructuredEngineeringContext);
+    const preciseParsers = ["scip", "lsif", "lsp"];
+    const astParsers = ["typescript-ast", "tree-sitter"];
+    const indexableFiles = codeGraph.files.filter((file) => file.parser !== "metadata").length;
+    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 stalePackets = quality.totals.stale;
+    const duplicateCandidatesTotal = quality.totals.duplicate;
+    const structuredCoverage = percent(structuredPackets.length, approved.length);
+    const preciseCoverage = percent(preciseFiles, indexableFiles);
+    const memoryCodeCoverage = percent(Math.min(memoryCodeEdges, approved.length), approved.length);
+    const recommendations = [];
+    if (structuredPackets.length < approved.length) {
+        recommendations.push("Add structured context fields to high-value memories: why, verification, risk_if_forgotten, and stale_when.");
+    }
+    if (pending.length) {
+        recommendations.push("Review pending memory inbox packets and approve, reject, merge, or supersede them before handoff.");
+    }
+    if (stalePackets) {
+        recommendations.push("Run kage gc --dry-run and update or deprecate stale memory before trusting recall.");
+    }
+    if (duplicateCandidatesTotal) {
+        recommendations.push("Merge or supersede duplicate memory packets so agents do not receive conflicting context.");
+    }
+    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 (!validation.ok) {
+        recommendations.push("Fix validation errors before relying on Kage in PR or agent-start workflows.");
+    }
+    const trustScore = Math.max(0, Math.min(100, Math.round((validation.ok ? 25 : 0) +
+        quality.useful_memory_ratio_percent * 0.25 +
+        structuredCoverage * 0.2 +
+        memoryCodeCoverage * 0.15 +
+        Math.max(0, 15 - pending.length * 3 - stalePackets * 5 - duplicateCandidatesTotal * 4))));
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        ok: validation.ok && stalePackets === 0 && duplicateCandidatesTotal === 0,
+        trust_score: trustScore,
+        checks: {
+            validation,
+            memory_inbox: {
+                approved_packets: approved.length,
+                pending_packets: pending.length,
+                stale_packets: stalePackets,
+                duplicate_candidates: duplicateCandidatesTotal,
+            },
+            structured_memory: {
+                total_packets: approved.length,
+                structured_packets: structuredPackets.length,
+                coverage_percent: structuredCoverage,
+                missing_context_packet_ids: approved.filter((packet) => !structuredPackets.includes(packet)).map((packet) => packet.id),
+            },
+            code_graph: {
+                files: codeGraph.files.length,
+                precise_files: preciseFiles,
+                ast_files: astFiles,
+                fallback_files: fallbackFiles,
+                precise_coverage_percent: preciseCoverage,
+                indexer_coverage_percent: percent(codeGraph.files.filter((file) => file.parser !== "metadata").length, indexableFiles),
+            },
+            graph_links: {
+                memory_code_edges: memoryCodeEdges,
+                evidence_coverage_percent: percent(knowledgeGraph.edges.filter((edge) => edge.evidence.length > 0).length, knowledgeGraph.edges.length),
+            },
+        },
+        recommendations,
+    };
+}
+function memoryInbox(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const validation = validateProject(projectDir);
+    const quality = qualityReport(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const pending = loadPendingPackets(projectDir);
+    const items = [];
+    for (const packet of pending) {
+        const qualityDetails = evaluateMemoryQuality(projectDir, packet);
+        items.push({
+            kind: "pending",
+            severity: "warning",
+            packet_id: packet.id,
+            title: packet.title,
+            type: packet.type,
+            status: packet.status,
+            paths: packet.paths,
+            summary: packet.summary,
+            reasons: [
+                ...(qualityDetails.risks ?? []),
+                `quality score ${qualityDetails.score}/100`,
+            ],
+            action: "Approve, reject, merge, or keep pending after reviewing source refs and sensitivity.",
+        });
+    }
+    for (const packet of approved) {
+        const reasons = staleMemoryReasons(projectDir, packet);
+        if (reasons.length) {
+            items.push({
+                kind: "stale",
+                severity: "blocker",
+                packet_id: packet.id,
+                title: packet.title,
+                type: packet.type,
+                status: packet.status,
+                paths: packet.paths,
+                summary: packet.summary,
+                reasons,
+                action: `${staleSuggestedAction(reasons)} this packet before trusting recall.`,
+            });
+        }
+    }
+    for (const packet of approved.filter((packet) => !hasStructuredEngineeringContext(packet))) {
+        items.push({
+            kind: "missing_context",
+            severity: "info",
+            packet_id: packet.id,
+            title: packet.title,
+            type: packet.type,
+            status: packet.status,
+            paths: packet.paths,
+            summary: packet.summary,
+            reasons: ["missing explicit why, verification, risk, stale condition, trigger, or action"],
+            action: "Add structured context if this packet carries durable rationale, bug, issue, or code explanation.",
+        });
+    }
+    for (const packet of quality.packets.filter((packet) => packet.classification === "duplicate")) {
+        const source = [...approved, ...pending].find((candidate) => candidate.id === packet.id);
+        items.push({
+            kind: "duplicate",
+            severity: "warning",
+            packet_id: packet.id,
+            title: packet.title,
+            type: packet.type,
+            status: packet.status,
+            paths: source?.paths,
+            summary: source?.summary ?? packet.title,
+            reasons: packet.risks.length ? packet.risks : ["duplicate candidate detected by quality report"],
+            action: "Merge, supersede, or deprecate overlapping memory before handoff.",
+        });
+    }
+    for (const error of validation.errors) {
+        items.push({
+            kind: "validation_error",
+            severity: "blocker",
+            summary: error,
+            reasons: [error],
+            action: "Fix validation errors before relying on Kage in agent or PR workflows.",
+        });
+    }
+    for (const warning of validation.warnings) {
+        items.push({
+            kind: "validation_warning",
+            severity: "warning",
+            summary: warning,
+            reasons: [warning],
+            action: "Review grounding, indexes, generated artifacts, or packet quality.",
+        });
+    }
+    const counts = {
+        approved: approved.length,
+        pending: pending.length,
+        stale: items.filter((item) => item.kind === "stale").length,
+        duplicates: items.filter((item) => item.kind === "duplicate").length,
+        missing_context: items.filter((item) => item.kind === "missing_context").length,
+        validation_errors: validation.errors.length,
+        validation_warnings: validation.warnings.length,
+    };
+    const recommendations = unique([
+        ...(counts.pending ? ["Review pending memory packets before handoff."] : []),
+        ...(counts.stale ? ["Update, verify, supersede, or deprecate stale memory packets."] : []),
+        ...(counts.duplicates ? ["Merge or supersede duplicate memory packets."] : []),
+        ...(counts.missing_context ? ["Add structured why, verification, risk, and stale_when context to high-value packets."] : []),
+        ...(counts.validation_errors ? ["Fix validation errors before trusting recall."] : []),
+        ...(counts.validation_warnings ? ["Review validation warnings so memory remains source-grounded."] : []),
+    ]);
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        ok: counts.pending === 0 && counts.stale === 0 && counts.duplicates === 0 && counts.validation_errors === 0,
+        counts,
+        items,
+        recommendations,
+    };
+}
 function qualityReport(projectDir) {
     ensureMemoryDirs(projectDir);
     const packets = [...loadPacketsFromDir(packetsDir(projectDir)), ...loadPacketsFromDir(pendingDir(projectDir))];
@@ -3116,17 +3628,57 @@ function benchmarkProject(projectDir) {
     const metrics = kageMetricsShallow(projectDir);
     const quality = qualityReport(projectDir);
     const typeCoverage = quality.memory_type_coverage;
+    const recallHitRate = percent(scenarios.filter((scenario) => scenario.hit).length, scenarios.length);
+    const codeFlowCoverage = metrics.code_graph.files > 0 && metrics.code_graph.symbols > 0 ? 100 : 0;
+    const gates = [
+        {
+            name: "recall_hit_rate",
+            target: 60,
+            actual: recallHitRate,
+            unit: "percent",
+            pass: recallHitRate >= 60,
+            required: true,
+        },
+        {
+            name: "evidence_coverage",
+            target: 80,
+            actual: quality.evidence_coverage_percent,
+            unit: "percent",
+            pass: quality.evidence_coverage_percent >= 80,
+            required: true,
+        },
+        {
+            name: "useful_memory_ratio",
+            target: 70,
+            actual: quality.useful_memory_ratio_percent,
+            unit: "percent",
+            pass: quality.useful_memory_ratio_percent >= 70,
+            required: true,
+        },
+        {
+            name: "code_flow_coverage",
+            target: 100,
+            actual: codeFlowCoverage,
+            unit: "percent",
+            pass: codeFlowCoverage >= 100,
+            required: true,
+        },
+    ];
+    const gateScore = Math.round(gates.reduce((sum, gate) => sum + Math.min(100, Math.round((gate.actual / Math.max(1, gate.target)) * 100)), 0) / gates.length);
     return {
         schema_version: 1,
         project_dir: projectDir,
         generated_at: nowIso(),
+        ok: gates.filter((gate) => gate.required).every((gate) => gate.pass),
+        overall_score: gateScore,
+        gates,
         scenarios,
         pain_metrics: {
             setup_runbook_coverage_percent: typeCoverage.runbook ? 100 : 0,
             bug_fix_coverage_percent: typeCoverage.bug_fix ? 100 : 0,
             decision_coverage_percent: typeCoverage.decision ? 100 : 0,
-            code_flow_coverage_percent: metrics.code_graph.files > 0 && metrics.code_graph.symbols > 0 ? 100 : 0,
-            recall_hit_rate_percent: percent(scenarios.filter((scenario) => scenario.hit).length, scenarios.length),
+            code_flow_coverage_percent: codeFlowCoverage,
+            recall_hit_rate_percent: recallHitRate,
             estimated_rediscovery_avoided: scenarios.filter((scenario) => scenario.hit).length,
             estimated_tokens_saved: metrics.savings.estimated_tokens_saved_per_recall,
             time_to_first_use_seconds: metrics.harness.policy_installed ? 30 : 90,
@@ -3296,10 +3848,20 @@ function inferLearningType(input) {
     if (input.type)
         return input.type;
     const text = `${input.title ?? ""} ${input.learning}`.toLowerCase();
+    if (/(issue context|issue|hypothesis|blocked|unresolved|attempted fix)/.test(text))
+        return "issue_context";
     if (/(bug|fix|error|fail|failure|broken|regression)/.test(text))
         return "bug_fix";
-    if (/(decided|decision|rationale|tradeoff|chose|choose)/.test(text))
+    if (/(code explanation|explains|data flow|invariant|coupling|module purpose)/.test(text))
+        return "code_explanation";
+    if (/(constraint|external requirement|legal|compliance|performance budget)/.test(text))
+        return "constraint";
+    if (/(negative result|tried|failed because|rejected)/.test(text))
+        return "negative_result";
+    if (/(decided|decision|tradeoff|chose|choose)/.test(text))
         return "decision";
+    if (/(why|rationale|because)/.test(text))
+        return "rationale";
     if (/(run|command|setup|install|build|test|deploy)/.test(text))
         return "runbook";
     if (/(convention|always|prefer|avoid|pattern)/.test(text))
@@ -3312,6 +3874,58 @@ function titleFromLearning(learning) {
     const sentence = learning.split(/[.!?]\s+/)[0]?.trim() || learning.trim();
     return sentence.slice(0, 90) || "Session learning";
 }
+const MEMORY_CONTEXT_FIELD_LABELS = [
+    "Fact",
+    "Decision",
+    "Why",
+    "Rationale",
+    "Because",
+    "When",
+    "Trigger",
+    "Action",
+    "Do",
+    "Use",
+    "Verified by",
+    "Verification",
+    "Evidence",
+    "Risk if forgotten",
+    "Risk",
+    "Stale when",
+    "Invalid when",
+    "Revisit when",
+    "Rejected alternatives",
+];
+function labeledMemoryField(text, labels) {
+    const escaped = labels.map((label) => label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const allLabels = MEMORY_CONTEXT_FIELD_LABELS.map((label) => label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+    const match = text.match(new RegExp(`(?:^|\\n|\\b)(?:${escaped})\\s*:\\s*([\\s\\S]*?)(?=(?:\\s|\\n)+(?:${allLabels})\\s*:|$)`, "i"));
+    return match?.[1]?.trim().replace(/\s+$/, "");
+}
+function inferEngineeringContext(input) {
+    const body = input.body.trim();
+    const firstParagraph = body
+        .split(/\n\s*\n/)
+        .find((part) => !/^\s*(why|verified by|verification|risk if forgotten|stale when|trigger|action|rejected alternatives)\s*:/i.test(part))
+        ?.trim();
+    const context = {
+        fact: input.context?.fact ?? labeledMemoryField(body, ["Fact", "Decision"]) ?? firstParagraph ?? input.title,
+        why: input.context?.why ?? labeledMemoryField(body, ["Why", "Rationale", "Because"]),
+        trigger: input.context?.trigger ?? labeledMemoryField(body, ["When", "Trigger"]),
+        action: input.context?.action ?? labeledMemoryField(body, ["Action", "Do", "Use"]),
+        verification: input.context?.verification ?? labeledMemoryField(body, ["Verified by", "Verification", "Evidence"]),
+        risk_if_forgotten: input.context?.risk_if_forgotten ?? labeledMemoryField(body, ["Risk if forgotten", "Risk"]),
+        stale_when: input.context?.stale_when ?? labeledMemoryField(body, ["Stale when", "Invalid when", "Revisit when"]),
+        rejected_alternatives: input.context?.rejected_alternatives,
+    };
+    return Object.fromEntries(Object.entries(context).filter(([, value]) => Array.isArray(value) ? value.length : Boolean(value)));
+}
+function engineeringContextFor(packet) {
+    return inferEngineeringContext({ title: packet.title, body: packet.body, context: packet.context });
+}
+function hasStructuredEngineeringContext(packet) {
+    const context = engineeringContextFor(packet);
+    return Boolean(context.why || context.verification || context.risk_if_forgotten || context.stale_when || context.trigger || context.action);
+}
 function learn(input) {
     const type = inferLearningType(input);
     const title = input.title?.trim() || titleFromLearning(input.learning);
@@ -3329,6 +3943,7 @@ function learn(input) {
         tags: unique(["session-learning", ...(input.tags ?? [])]),
         paths: input.paths,
         stack: input.stack,
+        context: input.context,
     });
 }
 function capture(input) {
@@ -3366,6 +3981,7 @@ function capture(input) {
                 captured_at: createdAt,
             },
         ],
+        context: inferEngineeringContext({ title: input.title, body: input.body, context: input.context }),
         freshness: {
             ttl_days: 365,
             last_verified_at: createdAt,
@@ -3903,6 +4519,15 @@ function reusableFileObservation(event) {
         "dispatch",
         "convention",
         "decision",
+        "rationale",
+        "root cause",
+        "issue",
+        "hypothesis",
+        "unresolved",
+        "code explanation",
+        "explains",
+        "data flow",
+        "invariant",
         "gotcha",
         "workflow",
         "runbook",
@@ -3974,9 +4599,20 @@ function reusablePromptObservation(event) {
         "convention",
         "policy",
         "gotcha",
+        "bug",
+        "issue",
+        "issue context",
+        "hypothesis",
+        "unresolved",
+        "rationale",
+        "why:",
+        "because",
+        "code explanation",
+        "explains",
+        "data flow",
+        "root cause",
         "runbook",
         "workflow",
-        "root cause",
         "use this",
         "always",
         "never",
@@ -3985,7 +4621,7 @@ function reusablePromptObservation(event) {
     ];
     if (!durableSignals.some((signal) => lower.includes(signal)))
         return "";
-    if (/^(fix|build|create|implement|update|continue|show me|what is|why is|can you)\b/i.test(text) && !/(decision|convention|policy|gotcha|remember|prefer|avoid)/i.test(text))
+    if (/^(fix|build|create|implement|update|continue|show me|what is|why is|can you)\b/i.test(text) && !/(decision|convention|policy|gotcha|remember|prefer|avoid|bug|issue|hypothesis|rationale|because|root cause|code explanation|explains)/i.test(text))
         return "";
     return text;
 }
@@ -4112,7 +4748,8 @@ function createDiffChangeMemory(projectDir, summary) {
         "",
         "Improve this packet when more context is known:",
         "- The actual feature, fix, or refactor rationale.",
-        "- The package, API, command, or architectural pattern future agents should reuse.",
+        "- Why the change was made, including relevant bugs, issues, decisions, and code explanations.",
+        "- The package, API, command, or architectural pattern future agents should understand, verify, or reuse.",
         "- Any gotchas, follow-up risks, or branch-specific assumptions.",
         "",
         "Promote beyond this repo only after explicit org/global review.",
@@ -4143,6 +4780,15 @@ function createDiffChangeMemory(projectDir, summary) {
                 summary_path: (0, node_path_1.join)(reviewDir(projectDir), `branch-summary-${slugify(branch)}.json`),
             },
         ],
+        context: {
+            fact: `Current branch ${branch} changes ${summary.changed_files.length} repo path${summary.changed_files.length === 1 ? "" : "s"}.`,
+            why: "Branch change memory gives future agents durable context from the git diff when they continue, review, or verify this work.",
+            trigger: "Recall when asking what changed on this branch, preparing a PR review, or resuming this work.",
+            action: "Use the changed file list and diff summary as orientation, then inspect the actual diff and source files before making further edits.",
+            verification: "Generated from git diff and refreshed by kage pr summarize or kage propose --from-diff.",
+            risk_if_forgotten: "Future agents may repeat orientation work, miss branch-specific assumptions, or ignore files touched by this change.",
+            stale_when: "The branch diff changes substantially, the branch is merged, or a newer change-memory packet supersedes it.",
+        },
         freshness: {
             last_verified_at: now,
             ttl_days: 180,
@@ -4435,9 +5081,10 @@ function loadOrgInboxPackets(projectDir, org) {
 }
 function recallFromPackets(query, packets, limit, label) {
     const terms = tokenize(query);
+    const lexicalScores = scorePacketsBm25(terms, packets);
     const scored = packets
         .map((packet) => {
-        const { score, why } = scorePacket(terms, packet);
+        const { score, why } = lexicalScores.get(packet.id) ?? { score: 0, why: [] };
         return { packet, score, why_matched: why };
     })
         .filter((result) => result.score > 0)