@kage-core/kage-graph-mcp 1.1.1 → 1.1.3

package/README.md

@@ -27,6 +27,7 @@ kage init --project /path/to/repo
 kage policy --project /path/to/repo
 kage doctor --project /path/to/repo
 kage index --project /path/to/repo
+kage refresh --project /path/to/repo
 kage branch --project /path/to/repo
 kage code-graph --project /path/to/repo
 kage code-graph "createApp routes tests" --project /path/to/repo
@@ -45,6 +46,8 @@ kage learn --project /path/to/repo --learning "Decision: use kage_learn for actu
 kage feedback --project /path/to/repo --packet <approved-packet-id> --kind stale
 kage capture --project /path/to/repo --type runbook --title "Webhook tests" --body "Run pnpm test:api -- webhooks."
 kage propose --project /path/to/repo --from-diff
+kage pr summarize --project /path/to/repo
+kage pr check --project /path/to/repo
 kage review-artifact --project /path/to/repo
 kage registry --project /path/to/repo
 kage marketplace --project /path/to/repo
@@ -57,6 +60,7 @@ kage layered-recall "how do I run tests" --project /path/to/repo --org acme --gl
 kage global build --project /path/to/repo --org acme
 kage review --project /path/to/repo
 kage validate --project /path/to/repo
+kage upgrade --dry-run
 ```
 
 `kage init` is the first-run command. It creates `.agent_memory/`, migrates
@@ -121,6 +125,16 @@ and parser coverage, code graph counts, evidence coverage, approved vs pending
 memory, validation status, estimated tokens saved per recall, duplicate
 candidates, average memory quality, and a readiness score.
 
+Use `kage refresh --project <repo>` or the `kage_refresh` MCP tool after
+meaningful file changes. Refresh rebuilds indexes, code graph, memory graph,
+metrics, and stale-memory metadata. Memory is marked stale when status or
+feedback says it is stale, its TTL expires, or grounded paths disappear.
+
+Use `kage pr summarize --project <repo>` / `kage_pr_summarize` before handoff to
+write branch review metadata and repo-local change memory from the git diff.
+Use `kage pr check --project <repo>` / `kage_pr_check` before merge to verify
+validation, graph freshness, stale packets, and memory packet changes.
+
 Review artifacts include memory quality reasons, risks, duplicate candidates,
 and estimated token savings for legacy pending/quarantine packets and promotion
 review.
@@ -185,6 +199,9 @@ Local repo tools:
 - `kage_recall`
 - `kage_code_graph`
 - `kage_metrics`
+- `kage_refresh`
+- `kage_pr_summarize`
+- `kage_pr_check`
 - `kage_quality`
 - `kage_benchmark`
 - `kage_setup_agent`
@@ -267,8 +284,10 @@ Before code changes or repo-specific answers:
 2. Call `kage_recall` with the user task as the query.
 3. Call `kage_graph` with the user task as the query.
 4. Capture reusable learnings with `kage_learn` or `kage_capture`.
-5. Before finishing changed-file tasks, call `kage_propose_from_diff`.
-6. Never publish or promote org/global memory automatically.
+5. After meaningful file changes, call `kage_refresh`.
+6. Before finishing changed-file tasks, call `kage_propose_from_diff` or `kage_pr_summarize`.
+7. Before merge, call `kage_pr_check`.
+8. Never publish or promote org/global memory automatically.
 ```
 
 Run `kage setup verify-agent --agent codex --project <repo>` after setup. The

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
 const promises_1 = require("node:readline/promises");
 const node_process_1 = require("node:process");
 const daemon_js_1 = require("./daemon.js");
@@ -22,6 +23,10 @@ Usage:
   kage daemon status --project <dir> [--json]
   kage daemon doctor --project <dir> [--json]
   kage viewer --project <dir> [--port 3113]
+  kage refresh --project <dir> [--json]
+  kage pr summarize --project <dir> [--json]
+  kage pr check --project <dir> [--json]
+  kage upgrade [--dry-run]
   kage branch --project <dir> [--json]
   kage metrics --project <dir> [--json]
   kage quality --project <dir> [--json]
@@ -296,6 +301,97 @@ async function main() {
         await (0, daemon_js_1.startViewer)(projectArg(args), { port: numberArg(args, "--port", 3113) });
         return;
     }
+    if (command === "refresh") {
+        const result = (0, kernel_js_1.refreshProject)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        console.log(`Refreshed ${result.project_dir}`);
+        console.log(`Packets indexed: ${result.index.packets}`);
+        console.log(`Packet metadata updated: ${result.updated_packets}`);
+        console.log(`Code graph: ${result.code_graph.files} files, ${result.code_graph.symbols} symbols, ${result.code_graph.imports} imports, ${result.code_graph.calls} calls`);
+        console.log(`Memory graph: ${result.memory_graph.entities} entities, ${result.memory_graph.edges} edges, ${result.memory_graph.episodes} episodes`);
+        console.log(`Stale packets: ${result.stale_packets.length}`);
+        for (const packet of result.stale_packets.slice(0, 8)) {
+            console.log(`  - ${packet.title} (${packet.id}): ${packet.reasons.join("; ")}`);
+        }
+        console.log(result.validation.ok ? "Validation: passed" : "Validation: failed");
+        if (result.validation.errors.length)
+            console.log(`Errors:\n${result.validation.errors.map((error) => `  - ${error}`).join("\n")}`);
+        if (result.validation.warnings.length)
+            console.log(`Warnings:\n${result.validation.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+        console.log(`Next actions:\n${result.next_actions.map((action) => `  - ${action}`).join("\n")}`);
+        if (!result.ok)
+            process.exit(2);
+        return;
+    }
+    if (command === "pr") {
+        const action = args[1];
+        if (action === "summarize") {
+            const result = (0, kernel_js_1.prSummarize)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            console.log(`PR summary for ${result.project_dir}`);
+            console.log(`Branch: ${result.branch ?? "(detached)"}`);
+            console.log(`Changed files: ${result.changed_files.join(", ") || "(none)"}`);
+            if (result.diff_memory_packet_id)
+                console.log(`Repo memory: ${result.diff_memory_packet_id}`);
+            if (result.branch_summary_path)
+                console.log(`Branch summary: ${result.branch_summary_path}`);
+            if (result.review_artifact_path)
+                console.log(`Review artifact: ${result.review_artifact_path}`);
+            if (result.warnings.length)
+                console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+            if (result.errors.length)
+                console.log(`Errors:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        if (action === "check") {
+            const result = (0, kernel_js_1.prCheck)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            console.log(`PR memory check for ${result.project_dir}`);
+            console.log(`Branch: ${result.branch ?? "(detached)"}`);
+            console.log(`Changed files: ${result.changed_files.length}`);
+            console.log(`Memory packet changes: ${result.memory_packet_changes.length}`);
+            console.log(`Code graph current: ${result.code_graph_current ? "yes" : "no"}`);
+            console.log(`Memory graph current: ${result.memory_graph_current ? "yes" : "no"}`);
+            console.log(`Stale packets: ${result.stale_packets.length}`);
+            if (result.warnings.length)
+                console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+            if (result.errors.length)
+                console.log(`Errors:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            console.log(`Required actions:\n${result.required_actions.map((action) => `  - ${action}`).join("\n")}`);
+            if (!result.ok)
+                process.exit(2);
+            return;
+        }
+        usage();
+    }
+    if (command === "upgrade") {
+        const commandLine = "npm install -g @kage-core/kage-graph-mcp@latest";
+        if (args.includes("--dry-run")) {
+            console.log(commandLine);
+            return;
+        }
+        console.log(`Running: ${commandLine}`);
+        (0, node_child_process_1.execFileSync)("npm", ["install", "-g", "@kage-core/kage-graph-mcp@latest"], { stdio: "inherit" });
+        console.log("Kage upgraded. Restart Codex or Claude Code so the MCP process reloads the new package.");
+        return;
+    }
     if (command === "graph") {
         const query = firstPositional(args);
         if (query) {

package/dist/index.js

@@ -154,6 +154,39 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_refresh",
+            description: "Rebuild repo indexes, code graph, memory graph, metrics, and stale-memory metadata. Agents should run this after meaningful file changes and before PR checks.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_pr_summarize",
+            description: "Create a PR/branch memory summary from local git diff metadata and write repo-local change memory. Use when a branch is ready to hand off.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_pr_check",
+            description: "Check whether repo memory, code graph, memory graph, and stale-memory state are ready for merge.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_quality",
             description: "Return memory quality metrics: useful memory ratio, duplicate burden, stale/wrong feedback, evidence coverage, path grounding, and review queue size.",
@@ -595,6 +628,27 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_refresh") {
+        const result = (0, kernel_js_1.refreshProject)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
+    if (name === "kage_pr_summarize") {
+        const result = (0, kernel_js_1.prSummarize)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
+    if (name === "kage_pr_check") {
+        const result = (0, kernel_js_1.prCheck)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.ok,
+        };
+    }
     if (name === "kage_quality") {
         const result = (0, kernel_js_1.qualityReport)(String(args?.project_dir ?? ""));
         return {

package/dist/kernel.js

@@ -66,6 +66,7 @@ exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
+exports.refreshProject = refreshProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.recall = recall;
 exports.queryCodeGraph = queryCodeGraph;
@@ -86,6 +87,8 @@ exports.distillSession = distillSession;
 exports.proposeFromDiff = proposeFromDiff;
 exports.buildBranchOverlay = buildBranchOverlay;
 exports.createReviewArtifact = createReviewArtifact;
+exports.prSummarize = prSummarize;
+exports.prCheck = prCheck;
 exports.exportPublicBundle = exportPublicBundle;
 exports.orgStatus = orgStatus;
 exports.orgUploadPacket = orgUploadPacket;
@@ -447,12 +450,41 @@ function packetFeedbackScore(packet) {
     const quality = packet.quality;
     return Number(quality.votes_up ?? 0) * 2 - Number(quality.votes_down ?? 0) * 3 - Number(quality.reports_stale ?? 0) * 4;
 }
+function meaningfulMemoryPath(path) {
+    return path !== "root" && path !== "." && !isNoisePath(path);
+}
+function staleMemoryReasons(projectDir, packet) {
+    const reasons = [];
+    const quality = packet.quality;
+    const freshness = packet.freshness;
+    if (packet.status === "deprecated" || packet.status === "superseded") {
+        reasons.push(`packet status is ${packet.status}`);
+    }
+    if (Number(quality.reports_stale ?? 0) > 0) {
+        reasons.push("user or agent reported this memory stale");
+    }
+    const ttlDays = Number(freshness.ttl_days ?? freshness.ttlDays ?? 0);
+    const verifiedAt = Date.parse(String(freshness.last_verified_at ?? packet.updated_at ?? packet.created_at));
+    if (Number.isFinite(ttlDays) && ttlDays > 0 && Number.isFinite(verifiedAt)) {
+        const ageDays = (Date.now() - verifiedAt) / (1000 * 60 * 60 * 24);
+        if (ageDays > ttlDays)
+            reasons.push(`freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`);
+    }
+    const paths = packet.paths.filter(meaningfulMemoryPath);
+    const missingPaths = paths.filter((path) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, path)));
+    if (paths.length > 0 && missingPaths.length === paths.length) {
+        reasons.push(`all referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
+    }
+    else if (missingPaths.length > 0) {
+        reasons.push(`some referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
+    }
+    return unique(reasons);
+}
 function classifyPacket(projectDir, packet) {
     const quality = evaluateMemoryQuality(projectDir, packet);
     const score = Number(quality.score);
     const duplicates = quality.duplicate_candidates;
-    const q = packet.quality;
-    if (Number(q.reports_stale ?? 0) > 0 || packet.status === "deprecated" || packet.status === "superseded")
+    if (staleMemoryReasons(projectDir, packet).length)
         return "stale";
     if (duplicates.length)
         return "duplicate";
@@ -522,11 +554,17 @@ function evaluateMemoryQuality(projectDir, packet) {
         score -= 18;
         risks.push("possible duplicate memory");
     }
+    const staleReasons = staleMemoryReasons(projectDir, packet);
+    if (staleReasons.length) {
+        score -= 22;
+        risks.push(...staleReasons);
+    }
     return {
         score: Math.max(0, Math.min(100, score)),
         reasons,
         risks,
         duplicate_candidates: duplicates,
+        stale_reasons: staleReasons,
         estimated_tokens_saved: Math.max(40, estimateTokens(packet.body) * 2),
     };
 }
@@ -769,6 +807,17 @@ function loadPacketsFromDir(dir) {
         .sort()
         .map((name) => readJson((0, node_path_1.join)(dir, name)));
 }
+function loadPacketEntriesFromDir(dir) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    return (0, node_fs_1.readdirSync)(dir)
+        .filter((name) => name.endsWith(".json"))
+        .sort()
+        .map((name) => {
+        const path = (0, node_path_1.join)(dir, name);
+        return { path, packet: readJson(path) };
+    });
+}
 function loadApprovedPackets(projectDir) {
     return loadPacketsFromDir(packetsDir(projectDir)).filter((packet) => packet.status === "approved");
 }
@@ -837,14 +886,15 @@ function isNoisePath(filePath) {
 function parsePorcelainStatus(status) {
     return unique(status
         .split(/\r?\n/)
-        .map((line) => {
-        const raw = line.length > 2 && line[2] === " " ? line.slice(3) : line.slice(2);
-        return raw.trim();
-    })
+        .map(parsePorcelainPath)
         .map((path) => path.replace(/^.* -> /, ""))
         .filter(Boolean)
         .filter((path) => !shouldSkipRepoMemoryPath(path))).sort();
 }
+function parsePorcelainPath(line) {
+    const raw = line.length > 2 && line[2] === " " ? line.slice(3) : line.slice(2);
+    return raw.trim();
+}
 function shouldSkipRepoMemoryPath(relativePath) {
     return isNoisePath(relativePath) || shouldSkipCodePath(relativePath);
 }
@@ -2342,6 +2392,104 @@ function indexProject(projectDir) {
         policyPath: (0, node_path_1.relative)(projectDir, policy.path),
     };
 }
+function staleSuggestedAction(reasons) {
+    if (reasons.some((reason) => reason.includes("status is")))
+        return "mark_stale";
+    if (reasons.some((reason) => reason.includes("missing")))
+        return "update";
+    if (reasons.some((reason) => reason.includes("reported")))
+        return "supersede";
+    return "verify";
+}
+function staleFinding(packet, reasons) {
+    return {
+        id: packet.id,
+        title: packet.title,
+        type: packet.type,
+        status: packet.status,
+        paths: packet.paths,
+        reasons,
+        suggested_action: staleSuggestedAction(reasons),
+    };
+}
+function refreshPacketStaleness(projectDir) {
+    const findings = [];
+    let updated = 0;
+    for (const entry of loadPacketEntriesFromDir(packetsDir(projectDir))) {
+        const reasons = staleMemoryReasons(projectDir, entry.packet);
+        const oldQuality = entry.packet.quality;
+        const oldFreshness = entry.packet.freshness;
+        let nextQuality;
+        if (reasons.length) {
+            const finding = staleFinding(entry.packet, reasons);
+            findings.push(finding);
+            nextQuality = {
+                ...oldQuality,
+                stale: true,
+                stale_reasons: reasons,
+                suggested_action: finding.suggested_action,
+            };
+        }
+        else {
+            const { stale: _stale, stale_reasons: _staleReasons, suggested_action: _suggestedAction, ...rest } = oldQuality;
+            nextQuality = rest;
+        }
+        const nextFreshness = oldFreshness;
+        const changed = JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
+            || JSON.stringify(oldFreshness) !== JSON.stringify(nextFreshness);
+        if (changed) {
+            writeJson(entry.path, {
+                ...entry.packet,
+                freshness: nextFreshness,
+                quality: nextQuality,
+                updated_at: nowIso(),
+            });
+            updated += 1;
+        }
+    }
+    return { findings, updated };
+}
+function refreshProject(projectDir) {
+    const index = indexProject(projectDir);
+    const stale = refreshPacketStaleness(projectDir);
+    const indexes = stale.updated > 0 ? buildIndexes(projectDir).map((path) => (0, node_path_1.relative)(projectDir, path)) : index.indexes;
+    const validation = validateProject(projectDir);
+    const metrics = kageMetrics(projectDir);
+    const nextActions = [];
+    if (stale.findings.length)
+        nextActions.push("Update, verify, or supersede stale repo memories before relying on them.");
+    if (!validation.ok)
+        nextActions.push("Fix validation errors before merging or sharing memory.");
+    if (validation.warnings.length)
+        nextActions.push("Review validation warnings for grounding, indexes, or generated artifacts.");
+    if (!nextActions.length)
+        nextActions.push("Repo memory, code graph, and indexes are current.");
+    return {
+        ok: validation.ok,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        index,
+        validation,
+        metrics,
+        stale_packets: stale.findings,
+        updated_packets: stale.updated,
+        indexes,
+        code_graph: {
+            files: metrics.code_graph.files,
+            symbols: metrics.code_graph.symbols,
+            imports: metrics.code_graph.imports,
+            calls: metrics.code_graph.calls,
+            routes: metrics.code_graph.routes,
+            tests: metrics.code_graph.tests,
+        },
+        memory_graph: {
+            entities: metrics.memory_graph.entities,
+            edges: metrics.memory_graph.edges,
+            episodes: metrics.memory_graph.episodes,
+        },
+        next_actions: nextActions,
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");
@@ -3847,7 +3995,7 @@ function proposeFromDiff(projectDir) {
 }
 function buildBranchOverlay(projectDir) {
     ensureMemoryDirs(projectDir);
-    const status = readGit(projectDir, ["status", "--porcelain"]) ?? "";
+    const status = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
     const overlay = {
         schema_version: 1,
         project_dir: projectDir,
@@ -3925,6 +4073,91 @@ function createReviewArtifact(projectDir) {
     (0, node_fs_1.writeFileSync)(path, `${lines.join("\n").trim()}\n`, "utf8");
     return { path, pending: pending.length };
 }
+function graphIsCurrent(projectDir, relativePath, head) {
+    const path = (0, node_path_1.join)(projectDir, relativePath);
+    if (!(0, node_fs_1.existsSync)(path))
+        return false;
+    if (!head)
+        return true;
+    try {
+        const graph = readJson(path);
+        return graph.repo_state?.head === head;
+    }
+    catch {
+        return false;
+    }
+}
+function prSummarize(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const proposal = proposeFromDiff(projectDir);
+    const artifact = createReviewArtifact(projectDir);
+    const validation = validateProject(projectDir);
+    const warnings = [...validation.warnings];
+    if (!proposal.ok)
+        warnings.push(...proposal.errors);
+    return {
+        ok: proposal.ok && validation.ok,
+        project_dir: projectDir,
+        branch: gitBranch(projectDir),
+        head: gitHead(projectDir),
+        changed_files: proposal.changedFiles,
+        diff_memory_packet_id: proposal.packet?.id,
+        diff_memory_packet_path: proposal.packetPath,
+        branch_summary_path: proposal.path,
+        review_artifact_path: artifact.path,
+        validation,
+        errors: validation.errors,
+        warnings,
+    };
+}
+function prCheck(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const overlay = buildBranchOverlay(projectDir);
+    const rawStatus = readGit(projectDir, ["status", "--porcelain", "-uall"]) ?? "";
+    const validation = validateProject(projectDir);
+    const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
+        .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
+        .filter((entry) => entry.reasons.length)
+        .map((entry) => staleFinding(entry.packet, entry.reasons));
+    const memoryPacketChanges = unique(rawStatus
+        .split(/\r?\n/)
+        .map(parsePorcelainPath)
+        .map((path) => path.replace(/^.* -> /, ""))
+        .filter((path) => path.startsWith(".agent_memory/packets/") && path.endsWith(".json"))).sort();
+    const codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", overlay.head);
+    const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", overlay.head);
+    const errors = [...validation.errors];
+    const warnings = [...validation.warnings];
+    const requiredActions = [];
+    if (stalePackets.length) {
+        errors.push(`${stalePackets.length} stale memory packet(s) require update, verification, or supersession.`);
+        requiredActions.push("Run kage refresh, then update or supersede stale packets.");
+    }
+    if (!codeGraphCurrent || !memoryGraphCurrent) {
+        errors.push("Generated graph artifacts are missing or not current for this branch head.");
+        requiredActions.push("Run kage refresh --project <dir> before merge.");
+    }
+    if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {
+        warnings.push("No repo memory packet changed for this branch. If durable knowledge was learned, run kage propose --from-diff or kage learn.");
+    }
+    if (!requiredActions.length)
+        requiredActions.push("PR memory and graph checks passed.");
+    return {
+        ok: errors.length === 0,
+        project_dir: projectDir,
+        branch: overlay.branch,
+        head: overlay.head,
+        changed_files: overlay.changed_files,
+        validation,
+        stale_packets: stalePackets,
+        memory_packet_changes: memoryPacketChanges,
+        code_graph_current: codeGraphCurrent,
+        memory_graph_current: memoryGraphCurrent,
+        errors,
+        warnings,
+        required_actions: requiredActions,
+    };
+}
 function exportPublicBundle(projectDir) {
     ensureMemoryDirs(projectDir);
     const candidates = loadPacketsFromDir(publicCandidatesDir(projectDir));

package/package.json

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

package/viewer/app.js

@@ -35,21 +35,37 @@
 
   var palette = {
     repo: "#41ff8f",
-    memory: "#b88cff",
+    memory: "#41ff8f",
     path: "#ff6b6b",
     tag: "#ffd166",
     package: "#6ad7ff",
     command: "#9be7c0",
     memory_type: "#41ff8f",
     file: "#6ad7ff",
-    symbol: "#b88cff",
-    route: "#ff8fab",
+    symbol: "#9be7c0",
+    route: "#6ad7ff",
     test: "#ffd166",
-    external: "#93a4a0",
+    external: "#62776b",
     script: "#6ad7ff",
     default: "#9be7c0"
   };
 
+  var graphPalette = {
+    background: "#020503",
+    grid: "rgba(65,255,143,0.040)",
+    gridStrong: "rgba(65,255,143,0.070)",
+    text: "#d7f9df",
+    muted: "#6ea77d",
+    memory: "#41ff8f",
+    code: "#6ad7ff",
+    amber: "#ffd166",
+    danger: "#ff6b6b",
+    dependency: "#62776b",
+    body: "rgba(4,12,8,0.88)",
+    bodyCode: "rgba(5,16,18,0.88)",
+    bodyMemory: "rgba(5,18,10,0.90)"
+  };
+
   var els = {
     graphFile: document.getElementById("graphFile"),
     graphSummary: document.getElementById("graphSummary"),
@@ -454,7 +470,7 @@
   function render() {
     if (!state.graph) return;
 
-    var query = normalize(els.searchInput.value);
+    var query = parseSearchQuery(els.searchInput.value);
     var mode = els.viewMode.value;
     var type = els.typeFilter.value;
     var relation = els.relationFilter.value;
@@ -464,7 +480,7 @@
     state.entities.forEach(function (entity) {
       if (mode !== "combined" && entity.graph_kind !== mode) return;
       var passesType = !type || entity.type === type;
-      var passesSearch = !query || searchableText(entity).indexOf(query) !== -1;
+      var passesSearch = matchesSearchQuery(entity, query);
       if (passesType && passesSearch) matchedEntityIds.add(entity.id);
     });
 
@@ -472,7 +488,7 @@
       if (mode !== "combined" && edge.graph_kind !== mode) return;
       var fromMatched = matchedEntityIds.has(edge.from);
       var toMatched = matchedEntityIds.has(edge.to);
-      var edgeMatchesSearch = !query || searchableText(edge).indexOf(query) !== -1;
+      var edgeMatchesSearch = matchesSearchQuery(edge, query);
       var passesRelation = !relation || edge.relation === relation;
       if (passesRelation && (edgeMatchesSearch || fromMatched || toMatched)) {
         matchedEdgeIds.add(edge.id);
@@ -483,7 +499,7 @@
       }
     });
 
-    if (!query && !type && !relation) {
+    if (!query.active && !type && !relation) {
       matchedEntityIds = new Set(state.entities.filter(function (entity) { return mode === "combined" || entity.graph_kind === mode; }).map(function (entity) { return entity.id; }));
       matchedEdgeIds = new Set(state.edges.filter(function (edge) { return mode === "combined" || edge.graph_kind === mode; }).map(function (edge) { return edge.id; }));
     }
@@ -520,7 +536,7 @@
       Array.from(entities).forEach(function (id) {
         var entity = state.entityById.get(id);
         if (!entity) return;
-        if (isDependencyEntity(entity) && !(options.query && searchableText(entity).indexOf(options.query) !== -1)) {
+        if (isDependencyEntity(entity) && !matchesSearchQuery(entity, options.query)) {
           entities.delete(id);
         }
       });
@@ -751,9 +767,15 @@
 
   function drawCanvasGrid(ctx, width, height) {
     ctx.save();
-    ctx.fillStyle = "#020503";
+    ctx.fillStyle = graphPalette.background;
     ctx.fillRect(0, 0, width, height);
-    ctx.strokeStyle = "rgba(65,255,143,0.045)";
+    var gradient = ctx.createRadialGradient(width * 0.52, height * 0.44, 40, width * 0.52, height * 0.44, Math.max(width, height) * 0.72);
+    gradient.addColorStop(0, "rgba(65,255,143,0.080)");
+    gradient.addColorStop(0.48, "rgba(65,255,143,0.018)");
+    gradient.addColorStop(1, "rgba(2,5,3,0)");
+    ctx.fillStyle = gradient;
+    ctx.fillRect(0, 0, width, height);
+    ctx.strokeStyle = graphPalette.grid;
     ctx.lineWidth = 1;
     var grid = 28;
     for (var x = 0; x < width; x += grid) {
@@ -768,22 +790,29 @@
       ctx.lineTo(width, y);
       ctx.stroke();
     }
+    ctx.strokeStyle = graphPalette.gridStrong;
+    ctx.beginPath();
+    ctx.moveTo(0, height / 2);
+    ctx.lineTo(width, height / 2);
+    ctx.moveTo(width / 2, 0);
+    ctx.lineTo(width / 2, height);
+    ctx.stroke();
     ctx.restore();
   }
 
   function drawCanvasEdges(ctx) {
     var nodeMap = state.sim.nodeById;
     var focusId = focusedCanvasNodeId();
-    var query = normalize(els.searchInput.value);
+    var query = parseSearchQuery(els.searchInput.value);
     var dense = state.sim.nodes.length > 55;
     state.sim.edges.forEach(function (edge) {
       var from = nodeMap.get(edge.from);
       var to = nodeMap.get(edge.to);
       if (!from || !to) return;
       var connected = focusId && (edge.from === focusId || edge.to === focusId);
-      var matches = !query || searchableText(edge).indexOf(query) !== -1 || searchableText(from.entity).indexOf(query) !== -1 || searchableText(to.entity).indexOf(query) !== -1;
-      var alpha = !matches ? 0.04 : focusId ? (connected ? 0.78 : 0.07) : (dense ? 0.18 : 0.34);
-      var color = hexToRgb(palette[from.entity.type] || palette[from.entity.graph_kind] || palette.default);
+      var matches = matchesSearchQuery(edge, query) || matchesSearchQuery(from.entity, query) || matchesSearchQuery(to.entity, query);
+      var alpha = !matches ? 0.035 : focusId ? (connected ? 0.62 : 0.055) : (dense ? 0.13 : 0.22);
+      var color = hexToRgb(edgeThemeColor(edge, from.entity, to.entity));
       var dx = to.x - from.x;
       var dy = to.y - from.y;
       var dist = Math.max(1, Math.sqrt(dx * dx + dy * dy));
@@ -794,7 +823,7 @@
       ctx.moveTo(from.x, from.y);
       ctx.quadraticCurveTo(cx, cy, to.x, to.y);
       ctx.strokeStyle = "rgba(" + color.r + "," + color.g + "," + color.b + "," + alpha + ")";
-      ctx.lineWidth = connected ? 2.8 : 1.2;
+      ctx.lineWidth = connected ? 2.2 : 1;
       ctx.stroke();
       if (connected || (!dense && state.sim.zoom > 1.25)) drawArrow(ctx, from, to, cx, cy, color, alpha);
       if (connected && state.sim.zoom > 0.62) drawEdgeLabel(ctx, edge, cx, cy);
@@ -803,7 +832,7 @@
 
   function drawCanvasNodes(ctx) {
     var focusId = focusedCanvasNodeId();
-    var query = normalize(els.searchInput.value);
+    var query = parseSearchQuery(els.searchInput.value);
     var dense = state.sim.nodes.length > 55;
     state.sim.nodes.forEach(function (node) {
       var entity = node.entity;
@@ -812,35 +841,42 @@
       var connected = focusId && (node.id === focusId || state.sim.edges.some(function (edge) {
         return (edge.from === focusId && edge.to === node.id) || (edge.to === focusId && edge.from === node.id);
       }));
-      var matches = !query || searchableText(entity).indexOf(query) !== -1;
+      var matches = matchesSearchQuery(entity, query);
       var alpha = !matches ? 0.12 : focusId && !connected ? 0.20 : 1;
-      var color = palette[entity.type] || palette[entity.graph_kind] || palette.default;
+      var color = nodeThemeColor(entity);
       ctx.save();
       ctx.globalAlpha = alpha;
-      if (selected || hovered || (!focusId && !dense)) {
+      if (selected || hovered) {
         ctx.shadowColor = color;
-        ctx.shadowBlur = selected ? 20 : hovered ? 16 : 5;
+        ctx.shadowBlur = selected ? 14 : 10;
       }
       drawNodeShape(ctx, node.x, node.y, node.r, entity);
-      var grad = ctx.createRadialGradient(node.x - node.r * 0.3, node.y - node.r * 0.3, 1, node.x, node.y, node.r * 1.35);
-      grad.addColorStop(0, brighten(color, 54));
-      grad.addColorStop(1, color);
-      ctx.fillStyle = grad;
+      ctx.fillStyle = nodeFillColor(entity);
       ctx.fill();
+      ctx.strokeStyle = color;
+      ctx.lineWidth = selected || hovered ? 2.2 : 1.2;
+      ctx.stroke();
+      if (entity.graph_kind === "memory") {
+        ctx.fillStyle = color;
+        ctx.globalAlpha = alpha * 0.85;
+        ctx.beginPath();
+        ctx.arc(node.x, node.y, Math.max(2.4, node.r * 0.18), 0, Math.PI * 2);
+        ctx.fill();
+      }
       ctx.restore();
 
       if (selected || hovered) {
         ctx.save();
         drawNodeShape(ctx, node.x, node.y, node.r + 4, entity);
         ctx.strokeStyle = color;
-        ctx.lineWidth = selected ? 3 : 2;
+        ctx.lineWidth = selected ? 2.6 : 1.8;
         ctx.shadowColor = color;
-        ctx.shadowBlur = 12;
+        ctx.shadowBlur = 8;
         ctx.stroke();
         ctx.restore();
       }
 
-      var shouldLabel = matches && (selected || hovered || (query && matches) || (!dense && state.sim.zoom > 0.75) || (dense && state.sim.zoom > 1.55 && node.r > 13));
+      var shouldLabel = matches && (selected || hovered || (query.active && matches) || (!dense && state.sim.zoom > 0.75) || (dense && state.sim.zoom > 1.55 && node.r > 13));
       if (shouldLabel) drawNodeLabel(ctx, node, selected || hovered);
     });
   }
@@ -851,8 +887,8 @@
     var tipY = to.y - to.r * Math.sin(angle);
     ctx.beginPath();
     ctx.moveTo(tipX, tipY);
-    ctx.lineTo(tipX - 8 * Math.cos(angle - 0.35), tipY - 8 * Math.sin(angle - 0.35));
-    ctx.lineTo(tipX - 8 * Math.cos(angle + 0.35), tipY - 8 * Math.sin(angle + 0.35));
+    ctx.lineTo(tipX - 6 * Math.cos(angle - 0.32), tipY - 6 * Math.sin(angle - 0.32));
+    ctx.lineTo(tipX - 6 * Math.cos(angle + 0.32), tipY - 6 * Math.sin(angle + 0.32));
     ctx.closePath();
     ctx.fillStyle = "rgba(" + color.r + "," + color.g + "," + color.b + "," + Math.min(0.85, alpha + 0.10) + ")";
     ctx.fill();
@@ -861,9 +897,9 @@
   function drawEdgeLabel(ctx, edge, x, y) {
     var inv = 1 / state.sim.zoom;
     ctx.save();
-    ctx.font = "700 " + (10 * inv).toFixed(1) + "px ui-monospace, Menlo, monospace";
+    ctx.font = "700 " + (9 * inv).toFixed(1) + "px ui-monospace, Menlo, monospace";
     ctx.textAlign = "center";
-    ctx.fillStyle = "rgba(215,249,223,0.82)";
+    ctx.fillStyle = "rgba(155,231,192,0.72)";
     ctx.fillText(shortName(edge.relation || "related", 22), x, y - 5 * inv);
     ctx.restore();
   }
@@ -872,17 +908,17 @@
     var inv = 1 / state.sim.zoom;
     var label = shortName(displayName(node.entity), strong ? 30 : 20);
     ctx.save();
-    ctx.font = (strong ? "800 " : "700 ") + (12 * inv).toFixed(1) + "px ui-monospace, Menlo, monospace";
+    ctx.font = (strong ? "800 " : "700 ") + (11 * inv).toFixed(1) + "px ui-monospace, Menlo, monospace";
     var width = ctx.measureText(label).width + 16 * inv;
     var height = 20 * inv;
     var x = node.x - width / 2;
     var y = node.y + node.r + 8 * inv;
-    ctx.fillStyle = "rgba(3,6,4,0.88)";
+    ctx.fillStyle = "rgba(2,5,3,0.92)";
     roundedRect(ctx, x, y, width, height, 4 * inv);
     ctx.fill();
-    ctx.strokeStyle = strong ? "rgba(65,255,143,0.55)" : "rgba(65,255,143,0.18)";
+    ctx.strokeStyle = strong ? "rgba(65,255,143,0.45)" : "rgba(65,255,143,0.14)";
     ctx.stroke();
-    ctx.fillStyle = strong ? "#d7f9df" : "#9be7c0";
+    ctx.fillStyle = strong ? graphPalette.text : graphPalette.muted;
     ctx.textAlign = "center";
     ctx.fillText(label, node.x, y + 14 * inv);
     ctx.restore();
@@ -919,6 +955,30 @@
     ctx.arc(x, y, r, 0, Math.PI * 2);
   }
 
+  function nodeThemeColor(entity) {
+    if (isDependencyEntity(entity) || entity.type === "external") return graphPalette.dependency;
+    if (entity.type === "test" || entity.type === "tag") return graphPalette.amber;
+    if (entity.type === "bug_fix" || entity.type === "path") return graphPalette.danger;
+    if (entity.graph_kind === "memory" || ["memory", "repo", "memory_type", "decision", "runbook", "workflow", "convention", "gotcha", "reference", "policy"].indexOf(entity.type) !== -1) return graphPalette.memory;
+    if (entity.graph_kind === "code" || ["file", "symbol", "route", "script", "command", "package"].indexOf(entity.type) !== -1) return graphPalette.code;
+    return graphPalette.muted;
+  }
+
+  function nodeFillColor(entity) {
+    if (isDependencyEntity(entity) || entity.type === "external") return "rgba(7,13,10,0.88)";
+    if (entity.graph_kind === "memory" || entity.type === "memory") return graphPalette.bodyMemory;
+    if (entity.graph_kind === "code") return graphPalette.bodyCode;
+    return graphPalette.body;
+  }
+
+  function edgeThemeColor(edge, fromEntity, toEntity) {
+    if (edge.relation && /test|covers/i.test(edge.relation)) return graphPalette.amber;
+    if (edge.relation && /invalid|risk|missing|bug/i.test(edge.relation)) return graphPalette.danger;
+    if (isDependencyEntity(fromEntity) || isDependencyEntity(toEntity)) return graphPalette.dependency;
+    if (fromEntity.graph_kind === "memory" || toEntity.graph_kind === "memory") return graphPalette.memory;
+    return graphPalette.code;
+  }
+
   function renderSvg() {
     els.edgeLayer.textContent = "";
     els.nodeLayer.textContent = "";
@@ -1461,7 +1521,7 @@
     }
     var entity = node.entity;
     var relationCount = state.sim.edges.filter(function (edge) { return edge.from === node.id || edge.to === node.id; }).length;
-    var color = palette[entity.type] || palette[entity.graph_kind] || palette.default;
+    var color = nodeThemeColor(entity);
     els.tooltip.innerHTML = [
       "<div class=\"tt-name\"></div>",
       "<div class=\"tt-type\"></div>",
@@ -1653,6 +1713,77 @@
     return normalize(JSON.stringify(value || {}));
   }
 
+  function parseSearchQuery(value) {
+    var raw = normalize(value);
+    var tokens = raw
+      .replace(/[^a-z0-9_./:-]+/g, " ")
+      .split(/\s+/)
+      .map(searchStem)
+      .filter(Boolean)
+      .filter(function (token) { return !SEARCH_STOP_WORDS.has(token); });
+    if ((tokens.indexOf("run") !== -1 || tokens.indexOf("runn") !== -1) && tokens.indexOf("test") !== -1) tokens.push("runtest");
+    var groups = tokens.map(function (token) {
+      return unique([token].concat(SEARCH_SYNONYMS[token] || []).map(searchStem).filter(Boolean));
+    });
+    return {
+      active: raw.trim().length > 0,
+      raw: raw,
+      tokens: unique(groups.reduce(function (all, group) { return all.concat(group); }, [])),
+      groups: groups
+    };
+  }
+
+  var SEARCH_STOP_WORDS = new Set([
+    "a", "an", "and", "are", "about", "can", "do", "does", "for", "from", "how", "i", "in", "is", "it", "me", "of", "on", "or", "please", "show", "that", "the", "there", "this", "to", "what", "when", "where", "which", "who", "why", "with"
+  ]);
+
+  var SEARCH_SYNONYMS = {
+    memory: ["packet", "runbook", "decision", "workflow", "gotcha", "reference"],
+    test: ["tests", "testing", "vitest", "jest", "pytest", "spec"],
+    run: ["running", "command", "script", "npm", "pnpm", "yarn"],
+    runn: ["run", "running", "command", "script", "npm", "pnpm", "yarn"],
+    runtest: ["run", "test", "runbook", "command"],
+    start: ["serve", "dev", "launch"],
+    build: ["compile", "tsc"],
+    bug: ["fix", "gotcha", "error"],
+    route: ["endpoint", "api"],
+    file: ["path"],
+    dependency: ["package", "external", "deps"]
+  };
+
+  function matchesSearchQuery(value, query) {
+    if (!query || !query.active) return true;
+    var text = searchableText(value);
+    if (query.raw && text.indexOf(query.raw) !== -1) return true;
+    if (!query.tokens.length) return true;
+    var textTokens = new Set(text
+      .replace(/[^a-z0-9_./:-]+/g, " ")
+      .split(/\s+/)
+      .map(searchStem)
+      .filter(Boolean));
+    var requiredGroups = (query.groups || []).filter(function (group) {
+      return group.some(function (token) { return SEARCH_SOFT_TOKENS.has(token) ? text.indexOf(token) !== -1 || textTokens.has(token) : true; });
+    });
+    if (!requiredGroups.length) requiredGroups = query.groups || [query.tokens];
+    return requiredGroups.every(function (group) {
+      return group.some(function (token) {
+        if (text.indexOf(token) !== -1) return true;
+        return textTokens.has(token);
+      });
+    });
+  }
+
+  var SEARCH_SOFT_TOKENS = new Set(["memory", "packet", "about"]);
+
+  function searchStem(value) {
+    var token = String(value || "").toLowerCase();
+    if (token.length > 5 && token.endsWith("ing")) token = token.slice(0, -3);
+    if (token.length > 4 && token.endsWith("ies")) token = token.slice(0, -3) + "y";
+    if (token.length > 4 && token.endsWith("es")) token = token.slice(0, -2);
+    if (token.length > 3 && token.endsWith("s")) token = token.slice(0, -1);
+    return token;
+  }
+
   function shortName(value, max) {
     var text = String(value || "");
     return text.length > max ? text.slice(0, Math.max(1, max - 1)) + "..." : text;

package/viewer/styles.css

@@ -331,7 +331,7 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
   height: 100%;
   overflow: hidden;
   background:
-    radial-gradient(circle at 52% 46%, rgba(65, 255, 143, 0.10), transparent 44%),
+    radial-gradient(circle at 52% 46%, rgba(65, 255, 143, 0.055), transparent 44%),
     #020503;
 }
 
@@ -367,10 +367,10 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
   display: none;
   max-width: min(320px, calc(100% - 28px));
   padding: 10px 12px;
-  border: 1px solid rgba(65, 255, 143, 0.32);
-  border-radius: 6px;
-  background: rgba(3, 6, 4, 0.90);
-  box-shadow: 0 14px 34px rgba(0, 0, 0, 0.38), inset 0 0 0 1px rgba(65, 255, 143, 0.08);
+  border: 1px solid rgba(65, 255, 143, 0.28);
+  border-radius: 4px;
+  background: rgba(2, 5, 3, 0.94);
+  box-shadow: 0 14px 34px rgba(0, 0, 0, 0.42), inset 0 0 0 1px rgba(65, 255, 143, 0.06);
   backdrop-filter: blur(12px);
   color: var(--text);
   pointer-events: none;
@@ -378,14 +378,14 @@ input:focus, select:focus, button:focus, .file-picker:focus-within {
 .graph-tooltip.visible { display: block; }
 .tt-name {
   color: var(--terminal);
-  font-weight: 850;
+  font-weight: 820;
   overflow-wrap: anywhere;
 }
 .tt-type {
   margin-top: 4px;
   font-size: 10px;
   font-weight: 800;
-  letter-spacing: 0.08em;
+  letter-spacing: 0.10em;
   text-transform: uppercase;
 }
 .tt-summary {