@kage-core/kage-graph-mcp 1.1.6 → 1.1.8

package/README.md

@@ -137,6 +137,11 @@ 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 gc --project <repo> --dry-run` to preview stale packet cleanup.
+`kage gc --project <repo>` marks stale repo packets deprecated, rebuilds
+indexes/graphs/metrics, and keeps helpful-voted memories unless `--force` is
+used.
+
 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

package/dist/cli.js

@@ -24,6 +24,7 @@ Usage:
   kage daemon doctor --project <dir> [--json]
   kage viewer --project <dir> [--port 3113]
   kage refresh --project <dir> [--json]
+  kage gc --project <dir> [--dry-run] [--force] [--json]
   kage pr summarize --project <dir> [--json]
   kage pr check --project <dir> [--json]
   kage upgrade [--dry-run]
@@ -302,6 +303,32 @@ async function main() {
         await (0, daemon_js_1.startViewer)(projectArg(args), { port: numberArg(args, "--port", 3113) });
         return;
     }
+    if (command === "gc") {
+        const project = projectArg(args);
+        const dryRun = args.includes("--dry-run");
+        const force = args.includes("--force");
+        const result = (0, kernel_js_1.gcProject)(project, { dryRun, force });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const label = dryRun ? " [dry-run]" : "";
+        console.log(`Kage GC${label} — scanned ${result.total_scanned} packets`);
+        if (result.deprecated.length) {
+            console.log(`\nDeprecated (${result.deprecated.length}):`);
+            for (const p of result.deprecated)
+                console.log(`  ✗ ${p.title} — ${p.reason}`);
+        }
+        if (result.deleted.length) {
+            console.log(`\nDeleted (${result.deleted.length}):`);
+            for (const p of result.deleted)
+                console.log(`  🗑  ${p.title}`);
+        }
+        if (!result.deprecated.length && !result.deleted.length) {
+            console.log("No stale packets found — memory is clean.");
+        }
+        return;
+    }
     if (command === "refresh") {
         const result = (0, kernel_js_1.refreshProject)(projectArg(args));
         if (args.includes("--json")) {

package/dist/index.js

@@ -54,7 +54,7 @@ function arrayArg(value) {
         return value.split(",").map((item) => item.trim()).filter(Boolean);
     return [];
 }
-const server = new index_js_1.Server({ name: "kage-graph", version: "1.1.6" }, { capabilities: { tools: {} } });
+const server = new index_js_1.Server({ name: "kage-graph", version: "1.1.7" }, { capabilities: { tools: {} } });
 function listTools() {
     return [
         {

package/dist/kernel.js

@@ -67,6 +67,7 @@ exports.buildKnowledgeGraph = buildKnowledgeGraph;
 exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
+exports.gcProject = gcProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.recall = recall;
 exports.queryCodeGraph = queryCodeGraph;
@@ -335,6 +336,9 @@ function repoKey(projectDir) {
     }
     return slugify((0, node_path_1.basename)(projectDir));
 }
+function repoDisplayName(projectDir) {
+    return (0, node_path_1.basename)((0, node_path_1.resolve)(projectDir));
+}
 function makePacketId(projectDir, type, title, suffix) {
     const raw = suffix ? `${title}-${suffix}` : title;
     return `repo:${repoKey(projectDir)}:${type}:${slugify(raw)}`;
@@ -931,14 +935,14 @@ function createRepoOverviewPacket(projectDir) {
     const readmePath = (0, node_path_1.join)(projectDir, "README.md");
     if (!(0, node_fs_1.existsSync)(packagePath) && !(0, node_fs_1.existsSync)(readmePath))
         return null;
-    let title = `${(0, node_path_1.basename)(projectDir)} repo overview`;
+    let title = `${repoDisplayName(projectDir)} repo overview`;
     const tags = ["repo", "overview"];
     const bodyParts = [];
     const paths = ["root"];
     const stack = [];
     if ((0, node_fs_1.existsSync)(packagePath)) {
         const pkg = readJson(packagePath);
-        title = `${String(pkg.name ?? (0, node_path_1.basename)(projectDir))} repo overview`;
+        title = `${String(pkg.name ?? repoDisplayName(projectDir))} repo overview`;
         const scripts = pkg.scripts && typeof pkg.scripts === "object" ? Object.keys(pkg.scripts) : [];
         const deps = {
             ...pkg.dependencies,
@@ -1050,8 +1054,8 @@ function createRepoStructurePacket(projectDir) {
     ].filter(Boolean).join("\n");
     return {
         schema_version: exports.PACKET_SCHEMA_VERSION,
-        id: makePacketId(projectDir, "repo_map", `${(0, node_path_1.basename)(projectDir)} repo structure`, "auto-structure"),
-        title: `${(0, node_path_1.basename)(projectDir)} repo structure`,
+        id: makePacketId(projectDir, "repo_map", `${repoDisplayName(projectDir)} repo structure`, "auto-structure"),
+        title: `${repoDisplayName(projectDir)} repo structure`,
         summary: summarize(body),
         body,
         type: "repo_map",
@@ -1083,7 +1087,18 @@ function createRepoStructurePacket(projectDir) {
 }
 function upsertGeneratedPacket(projectDir, packet) {
     const dir = packetsDir(projectDir);
-    const existing = loadPacketsFromDir(dir).find((candidate) => candidate.id === packet.id);
+    const entries = loadPacketEntriesFromDir(dir);
+    const generatedKind = packet.tags.includes("overview") ? "overview" : packet.tags.includes("structure") ? "structure" : null;
+    for (const entry of entries) {
+        if (generatedKind &&
+            entry.packet.id !== packet.id &&
+            entry.packet.type === packet.type &&
+            entry.packet.quality?.reviewer === "kage-indexer" &&
+            entry.packet.tags.includes(generatedKind)) {
+            (0, node_fs_1.unlinkSync)(entry.path);
+        }
+    }
+    const existing = entries.find((entry) => entry.packet.id === packet.id)?.packet;
     if (existing && existing.quality?.reviewer !== "kage-indexer")
         return;
     if (existing) {
@@ -2502,6 +2517,57 @@ function refreshProject(projectDir) {
         next_actions: nextActions,
     };
 }
+function gcProject(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const packetEntries = loadPacketEntriesFromDir(packetsDir(projectDir));
+    const deprecated = [];
+    const deleted = [];
+    const skipped = [];
+    for (const { path, packet } of packetEntries) {
+        if (packet.status === "deprecated") {
+            skipped.push({ id: packet.id, title: packet.title, reason: "already deprecated" });
+            continue;
+        }
+        const reasons = staleMemoryReasons(projectDir, packet);
+        if (!reasons.length) {
+            skipped.push({ id: packet.id, title: packet.title, reason: "healthy" });
+            continue;
+        }
+        const quality = packet.quality;
+        const hasHelpfulVotes = Number(quality?.votes_up ?? 0) > 0;
+        if (hasHelpfulVotes && !options.force) {
+            skipped.push({ id: packet.id, title: packet.title, reason: `stale but has helpful votes (use --force to override)` });
+            continue;
+        }
+        // Mark as deprecated (or hard-delete if --force)
+        if (options.force && !hasHelpfulVotes) {
+            if (!options.dryRun) {
+                (0, node_fs_1.unlinkSync)(path);
+            }
+            deleted.push({ id: packet.id, title: packet.title });
+        }
+        else {
+            if (!options.dryRun) {
+                const updated = { ...packet, status: "deprecated", updated_at: nowIso() };
+                writeJson(path, updated);
+            }
+            deprecated.push({ id: packet.id, title: packet.title, reason: reasons[0] });
+        }
+    }
+    if (!options.dryRun && (deprecated.length || deleted.length)) {
+        buildIndexes(projectDir);
+        buildKnowledgeGraph(projectDir);
+        writeJson((0, node_path_1.join)(memoryRoot(projectDir), "metrics.json"), kageMetrics(projectDir));
+    }
+    return {
+        ok: true,
+        project_dir: projectDir,
+        deprecated,
+        deleted,
+        skipped,
+        total_scanned: packetEntries.length,
+    };
+}
 function installAgentPolicy(projectDir) {
     const agentsPath = (0, node_path_1.join)(projectDir, "AGENTS.md");
     const claudePath = (0, node_path_1.join)(projectDir, "CLAUDE.md");

package/package.json

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