@kage-core/kage-graph-mcp 1.1.36 → 1.1.38

package/dist/index.js

@@ -89,6 +89,7 @@ function listTools() {
                     project_dir: { type: "string", description: "Absolute path to the project root" },
                     query: { type: "string", description: "The task or question — used for both memory recall and code graph search" },
                     limit: { type: "number", description: "Max memory packets to return (default 5)" },
+                    session_id: { type: "string", description: "Optional active agent session id for memory reconciliation" },
                     targets: { type: "array", items: { type: "string" }, description: "Optional files the agent may edit or explain; used for risk context" },
                     changed_files: { type: "array", items: { type: "string" }, description: "Optional changed files for pre-edit or PR risk context" },
                 },
@@ -149,6 +150,7 @@ function listTools() {
                     project_dir: { type: "string" },
                     limit: { type: "number" },
                     explain: { type: "boolean" },
+                    embeddings: { type: "boolean" },
                     json: { type: "boolean" },
                 },
                 required: ["query", "project_dir"],
@@ -254,6 +256,80 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_profile",
+            description: "Return a compact project profile for agent orientation: repo totals, languages, top code+memory concepts, key files, memory focus, run commands, and next actions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_xray",
+            description: "Return a first-use Repo X-Ray: code structure layers for entry points, core files, risk, tests, memory overlay, and knowledge gaps.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_capabilities",
+            description: "Return an evidence-backed Kage memory-system capability audit across repo memory, collaboration/session proof, benchmarks, and dashboard/viewer readiness.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_context_slots",
+            description: "List repo-local pinned context slots. Pinned slots are small, reviewable facts that Kage includes in recall/context before task-specific memory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_context_slot_set",
+            description: "Create or update a repo-local pinned context slot. Use for durable, high-signal repo guidance that should always be included without loading all memory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    label: { type: "string" },
+                    content: { type: "string" },
+                    description: { type: "string" },
+                    pinned: { type: "boolean" },
+                    size_limit: { type: "number" },
+                    paths: { type: "array", items: { type: "string" } },
+                    tags: { type: "array", items: { type: "string" } },
+                },
+                required: ["project_dir", "label", "content"],
+            },
+        },
+        {
+            name: "kage_context_slot_delete",
+            description: "Delete a repo-local context slot by label.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    label: { type: "string" },
+                },
+                required: ["project_dir", "label"],
+            },
+        },
         {
             name: "kage_decisions",
             description: "Summarize Kage why-memory for a repo: decisions, gotchas, runbooks, conventions, code explanations, path coverage, weak/stale memory, and important code paths that still lack decision memory.",
@@ -298,6 +374,17 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_memory_access",
+            description: "Report which repo-local memory packets have actually been recalled recently. This uses local ignored access telemetry and does not mutate shareable packet files.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_module_health",
             description: "Return local module health scorecards from Kage's code graph, test signals, cleanup candidates, git churn, and ownership concentration.",
@@ -399,6 +486,19 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_memory_reconcile",
+            description: "Return agent-owned memory reconciliation work when source files linked to existing memory changed. Agents must update, supersede, or mark stale memory before final handoff.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    session_id: { type: "string" },
+                    limit: { type: "number" },
+                },
+                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.",
@@ -410,13 +510,87 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_memory_lifecycle",
+            description: "Return a repo-local memory lifecycle report: healthy, hot, cold, stale, disputed, ungrounded, pending, generated, and concrete review actions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_memory_timeline",
+            description: "Return recent repo-memory activity for teammate handoff: added, updated, pending, and deprecated packets with review actions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    days: { type: "number" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_memory_lineage",
+            description: "Return memory supersession chains so agents can use current replacement packets and keep retired memory as audit history.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_memory_audit",
+            description: "Return the repo-local audit trail for explicit memory mutations: capture, feedback, review, supersede, deprecate, and delete.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_memory_handoff",
+            description: "Return a teammate/agent handoff queue by combining memory inbox, lifecycle, audit, timeline, and lineage into concrete next actions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_supersede",
+            description: "Mark one repo-local memory packet as superseded by a replacement packet and write bidirectional lineage edges.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    packet_id: { type: "string" },
+                    replacement_packet_id: { type: "string" },
+                    reason: { type: "string" },
+                },
+                required: ["project_dir", "packet_id", "replacement_packet_id"],
+            },
+        },
         {
             name: "kage_benchmark",
-            description: "Return Kage proof metrics: runbook, bug-fix, decision and code-flow coverage, recall hit rate, estimated rediscovery avoided, tokens saved, and time-to-first-use.",
+            description: "Return Kage proof metrics, or set mode=memory_quality / memory_scale for synthetic memory retrieval benchmarks.",
             inputSchema: {
                 type: "object",
                 properties: {
                     project_dir: { type: "string" },
+                    mode: { type: "string", enum: ["project", "memory_quality", "memory_scale"] },
+                    sizes: { type: "array", items: { type: "number" } },
+                    top_k: { type: "number" },
                 },
                 required: ["project_dir"],
             },
@@ -446,6 +620,17 @@ function listTools() {
                 required: ["agent", "project_dir"],
             },
         },
+        {
+            name: "kage_setup_doctor",
+            description: "Audit Kage setup across supported agents, including Claude Code ambient hook readiness when applicable.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_verify_agent",
             description: "Verify that Kage is truly active for the current agent: config, repo policy, indexes, recall, code graph, and this live MCP tool reachability.",
@@ -552,6 +737,43 @@ function listTools() {
                 required: ["project_dir", "session_id"],
             },
         },
+        {
+            name: "kage_sessions",
+            description: "Summarize local agent observation sessions, durable capture candidates, and next distillation actions without exposing raw transcript replay.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_learning_ledger",
+            description: "Return an agent-facing ledger that classifies observed session events into save, ignore, needs-evidence, or already-distilled memory decisions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    session_id: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_session_replay",
+            description: "Return a privacy-preserving replay digest for observed agent sessions: timeline, touched paths, commands, durable candidates, and distill actions without raw transcript text.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    session_id: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_feedback",
             description: "Record usefulness feedback on an approved repo-local memory packet: helpful, wrong, or stale.",
@@ -840,11 +1062,29 @@ async function callTool(name, args) {
         const dependencyResult = wantsDependencyPath(query) && pathHints.length >= 2
             ? (0, kernel_js_1.kageDependencyPath)(projectDir, pathHints[0], pathHints[1])
             : null;
+        const reconciliation = (0, kernel_js_1.kageMemoryReconciliation)(projectDir, {
+            sessionId: typeof args?.session_id === "string" ? args.session_id : undefined,
+            limit: 5,
+        });
+        const teammateBrief = (0, kernel_js_1.kageTeammateBrief)(projectDir, {
+            query,
+            targets: explicitTargets,
+            changedFiles,
+            recallResult,
+            riskResult,
+            reconciliation,
+        });
+        const learningLedger = typeof args?.session_id === "string" && args.session_id.trim()
+            ? (0, kernel_js_1.kageSessionLearningLedger)(projectDir, { sessionId: args.session_id, limit: 20 })
+            : null;
         const sections = [
             recallResult.context_block,
+            teammateBrief.context_block,
+            learningLedger ? learningLedger.context_block : "",
             graphResult.context_block ? `\n## Graph Facts\n${graphResult.context_block}` : "",
             riskResult ? riskContextBlock(riskResult) : "",
             dependencyResult ? `\n## Dependency Path\n${dependencyResult.summary}${dependencyResult.path.length ? `\nPath: ${dependencyResult.path.join(" -> ")}` : ""}` : "",
+            reconciliation.unresolved_count ? `\n## Memory Reconciliation\n${reconciliation.agent_instruction}` : "",
             `\n_${validationText}_`,
         ].filter(Boolean).join("");
         return {
@@ -852,7 +1092,9 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_recall") {
-        const result = (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain));
+        const result = args?.embeddings
+            ? await (0, kernel_js_1.recallWithEmbeddings)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain))
+            : (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain));
         return {
             content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : result.context_block }],
         };
@@ -914,6 +1156,50 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_profile") {
+        const result = (0, kernel_js_1.kageProjectProfile)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_xray") {
+        const result = (0, kernel_js_1.kageRepoXray)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_capabilities") {
+        const result = (0, kernel_js_1.kageCapabilityAudit)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_context_slots") {
+        const result = (0, kernel_js_1.kageContextSlots)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_context_slot_set") {
+        const result = (0, kernel_js_1.setContextSlot)(String(args?.project_dir ?? ""), {
+            label: String(args?.label ?? ""),
+            content: String(args?.content ?? ""),
+            description: args?.description == null ? undefined : String(args.description),
+            pinned: args?.pinned == null ? undefined : Boolean(args.pinned),
+            size_limit: args?.size_limit == null ? undefined : Number(args.size_limit),
+            paths: arrayArg(args?.paths),
+            tags: arrayArg(args?.tags),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_context_slot_delete") {
+        const result = (0, kernel_js_1.deleteContextSlot)(String(args?.project_dir ?? ""), String(args?.label ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_decisions") {
         const result = (0, kernel_js_1.kageDecisionIntelligence)(String(args?.project_dir ?? ""));
         return {
@@ -939,6 +1225,48 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_memory_access") {
+        const result = (0, kernel_js_1.kageMemoryAccess)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_memory_lifecycle") {
+        const result = (0, kernel_js_1.kageMemoryLifecycle)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_memory_timeline") {
+        const result = (0, kernel_js_1.kageMemoryTimeline)(String(args?.project_dir ?? ""), Number(args?.days ?? 14));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_memory_lineage") {
+        const result = (0, kernel_js_1.kageMemoryLineage)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_memory_audit") {
+        const result = (0, kernel_js_1.kageMemoryAudit)(String(args?.project_dir ?? ""), Number(args?.limit ?? 100));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_memory_handoff") {
+        const result = (0, kernel_js_1.kageMemoryHandoff)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_supersede") {
+        const result = (0, kernel_js_1.supersedeMemory)(String(args?.project_dir ?? ""), String(args?.packet_id ?? ""), String(args?.replacement_packet_id ?? ""), typeof args?.reason === "string" ? args.reason : "");
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_module_health") {
         const result = (0, kernel_js_1.kageModuleHealth)(String(args?.project_dir ?? ""));
         return {
@@ -998,6 +1326,16 @@ async function callTool(name, args) {
             isError: !result.ok,
         };
     }
+    if (name === "kage_memory_reconcile") {
+        const result = (0, kernel_js_1.kageMemoryReconciliation)(String(args?.project_dir ?? ""), {
+            sessionId: typeof args?.session_id === "string" ? args.session_id : undefined,
+            limit: Number(args?.limit ?? 25),
+        });
+        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 {
@@ -1005,7 +1343,15 @@ async function callTool(name, args) {
         };
     }
     if (name === "kage_benchmark") {
-        const result = (0, kernel_js_1.benchmarkProject)(String(args?.project_dir ?? ""));
+        const mode = String(args?.mode ?? "project");
+        const result = mode === "memory_quality"
+            ? (0, kernel_js_1.benchmarkCodingMemoryQuality)({ topK: Number(args?.top_k ?? 10) })
+            : mode === "memory_scale"
+                ? (0, kernel_js_1.benchmarkMemoryScale)({
+                    sizes: Array.isArray(args?.sizes) ? args.sizes.map(Number) : undefined,
+                    topK: Number(args?.top_k ?? 10),
+                })
+                : (0, kernel_js_1.benchmarkProject)(String(args?.project_dir ?? ""));
         return {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
@@ -1022,6 +1368,12 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_setup_doctor") {
+        const result = (0, kernel_js_1.setupDoctor)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_verify_agent") {
         const result = (0, kernel_js_1.verifyAgentActivation)(String(args?.agent ?? ""), String(args?.project_dir ?? ""), { mcpToolReachable: true });
         return {
@@ -1104,6 +1456,33 @@ async function callTool(name, args) {
             isError: !result.ok,
         };
     }
+    if (name === "kage_sessions") {
+        const result = (0, kernel_js_1.kageSessionCaptureReport)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    }
+    if (name === "kage_learning_ledger") {
+        const result = (0, kernel_js_1.kageSessionLearningLedger)(String(args?.project_dir ?? ""), {
+            sessionId: args?.session_id ? String(args.session_id) : undefined,
+            limit: typeof args?.limit === "number" ? args.limit : undefined,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    }
+    if (name === "kage_session_replay") {
+        const result = (0, kernel_js_1.kageSessionReplay)(String(args?.project_dir ?? ""), {
+            sessionId: args?.session_id ? String(args.session_id) : undefined,
+            limit: typeof args?.limit === "number" ? args.limit : undefined,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: false,
+        };
+    }
     if (name === "kage_feedback") {
         const result = (0, kernel_js_1.recordFeedback)(String(args?.project_dir ?? ""), String(args?.packet_id ?? ""), String(args?.kind ?? ""));
         return {