@kage-core/kage-graph-mcp 1.1.5 → 1.1.7

package/README.md

@@ -158,6 +158,11 @@ ranking: text, graph, path/type/tag, freshness, quality, feedback, and a vector
 placeholder for future local or external embedding providers. Current fallback
 is deterministic text plus graph retrieval.
 
+`kage_context` is the primary MCP entrypoint for agents. It validates repo
+memory, recalls relevant packets, and returns code/knowledge graph context in
+one call. Agents should use it at task start instead of loading separate
+`kage_validate`, `kage_recall`, `kage_code_graph`, and `kage_graph` schemas.
+
 `kage daemon start` exposes the optional local REST runtime on
 `127.0.0.1:3111`:
 
@@ -203,6 +208,7 @@ confidence, and token-savings metrics connect.
 
 Local repo tools:
 
+- `kage_context`
 - `kage_recall`
 - `kage_code_graph`
 - `kage_metrics`
@@ -288,14 +294,12 @@ Minimum policy:
 
 ```md
 Before code changes or repo-specific answers:
-1. Call `kage_validate`.
-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. 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.
+1. Call `kage_context` with `project_dir` and the user task as `query`.
+2. Capture reusable learnings with `kage_learn` or `kage_capture`.
+3. After meaningful file changes, call `kage_refresh`.
+4. Before finishing changed-file tasks, call `kage_propose_from_diff` or `kage_pr_summarize`.
+5. Before merge, call `kage_pr_check`.
+6. Never publish or promote org/global memory automatically.
 ```
 
 Run `kage setup verify-agent --agent codex --project <repo>` after setup. The

package/dist/index.js

@@ -54,9 +54,25 @@ 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.0" }, { capabilities: { tools: {} } });
+const server = new index_js_1.Server({ name: "kage-graph", version: "1.1.7" }, { capabilities: { tools: {} } });
 function listTools() {
     return [
+        {
+            // Combined entry-point tool: validate + recall + code_graph + graph in one call.
+            // Agents should load this schema first (one ToolSearch) instead of loading four
+            // separate deferred schemas. Cuts session start from 4 schema loads to 1.
+            name: "kage_context",
+            description: "Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task instead of calling kage_validate, kage_recall, kage_code_graph, and kage_graph separately.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    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)" },
+                },
+                required: ["project_dir", "query"],
+            },
+        },
         {
             name: "kage_search",
             description: "Search the kage community knowledge graph for gotchas, patterns, configs, and architectural decisions across auth, database, payments, deployment, frontend, testing, and more. Returns node summaries ranked by relevance.",
@@ -608,6 +624,28 @@ async function callTool(name, args) {
             content: [{ type: "text", text: content }],
         };
     }
+    if (name === "kage_context") {
+        const projectDir = String(args?.project_dir ?? "");
+        const query = String(args?.query ?? "");
+        const limit = Number(args?.limit ?? 5);
+        // validate
+        const validation = (0, kernel_js_1.validateProject)(projectDir);
+        const validationText = validation.ok
+            ? "Memory healthy."
+            : `Warnings: ${validation.warnings.join("; ")}`;
+        // recall (memory + code graph + knowledge graph combined)
+        const recallResult = (0, kernel_js_1.recall)(projectDir, query, limit, false);
+        // graph facts on top of recall
+        const graphResult = (0, kernel_js_1.queryGraph)(projectDir, query, 5);
+        const sections = [
+            recallResult.context_block,
+            graphResult.context_block ? `\n## Graph Facts\n${graphResult.context_block}` : "",
+            `\n_${validationText}_`,
+        ].filter(Boolean).join("");
+        return {
+            content: [{ type: "text", text: sections }],
+        };
+    }
     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));
         return {

package/dist/kernel.js

@@ -151,12 +151,11 @@ This repo uses Kage as an automatic memory harness for coding agents.
 
 Before making code changes, answering repo-specific implementation questions, debugging failures, or proposing architecture:
 
-1. Call \`kage_validate\` for this repo.
-2. Call \`kage_recall\` with the user's task as the query.
-3. Call \`kage_code_graph\` when the task mentions files, APIs, routes, symbols, tests, dependencies, or code flow.
-4. Call \`kage_graph\` with the user's task as the query when the task depends on decisions, bugs, workflows, commands, or conventions.
-5. Use returned memory only when it is relevant, source-backed, and not stale.
-6. Prefer repo memory over public/community memory when they conflict.
+1. Call \`kage_context\` with \`project_dir\` and the task as \`query\`.
+   This validates memory, recalls relevant packets, and queries both the code graph
+   and knowledge graph in one call — replacing the old four-step validate/recall/code_graph/graph sequence.
+2. Use returned memory only when it is relevant, source-backed, and not stale.
+3. Prefer repo memory over public/community memory when they conflict.
 
 Do this without waiting for the user to ask. Kage should feel like ambient repo memory, not a manual search command.
 
@@ -217,17 +216,13 @@ If recalled memory materially helped, call \`kage_feedback\` with \`helpful\`.
 
 For normal coding tasks:
 
-1. \`kage_validate\`
-2. \`kage_recall\`
-3. \`kage_code_graph\` for source flow, routes, symbols, tests, and dependencies
-4. \`kage_graph\` for remembered decisions, bugs, workflows, and conventions
-5. Work on the task
-6. \`kage_learn\` for concrete learnings
-7. \`kage_refresh\` after meaningful file changes
-8. \`kage_pr_summarize\` or \`kage_propose_from_diff\` before the final response to create repo-local change memory
-9. \`kage_pr_check\` before final handoff or merge readiness claims
+1. \`kage_context\` — validate + recall + code graph + knowledge graph in one call
+2. Work on the task
+3. \`kage_learn\` for concrete learnings
+4. \`kage_refresh\` after meaningful file changes
+5. \`kage_propose_from_diff\` before the final response to create repo-local change memory
 
-For quick factual questions, \`kage_recall\` alone is enough. For status or demo requests, call \`kage_metrics\`.
+For quick factual questions, \`kage_context\` alone is enough. For status or demo requests, call \`kage_metrics\`.
 ${AGENTS_POLICY_END}
 `;
 const STOPWORDS = new Set([
@@ -340,6 +335,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)}`;
@@ -580,7 +578,9 @@ function evaluateMemoryQuality(projectDir, packet) {
         risks,
         duplicate_candidates: duplicates,
         stale_reasons: staleReasons,
-        estimated_tokens_saved: Math.max(40, estimateTokens(packet.body) * 2),
+        // Tokens an agent saves by reading this packet instead of the files it references.
+        // Approximated as the token size of the files it grounds to (or the packet body if no paths).
+        estimated_tokens_saved: Math.max(20, estimateTokens(packet.body)),
     };
 }
 function evaluateMemoryAdmission(projectDir, packet) {
@@ -934,14 +934,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,
@@ -1053,8 +1053,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",
@@ -1086,7 +1086,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) {
@@ -2906,8 +2917,13 @@ function kageMetrics(projectDir) {
     const duplicatePairs = allPackets.reduce((sum, packet) => sum + duplicateCandidates(projectDir, packet).length, 0);
     const indexedSourceTokens = Math.ceil(sourceFiles.reduce((sum, file) => sum + file.size_bytes, 0) / 4);
     const memoryTokens = allPackets.reduce((sum, packet) => sum + estimateTokens(packetText(packet)), 0);
+    // Estimated size of a typical recall response: structured packet summaries + code graph
+    // slice, capped at ~1 800 tokens. This is what actually reaches the agent per recall call.
     const recallContextTokens = Math.max(250, Math.min(1800, codeGraph.symbols.length * 12 + codeGraph.routes.length * 10 + knowledgeGraph.edges.length * 14 + 180));
-    const tokensSaved = Math.max(0, indexedSourceTokens + memoryTokens - recallContextTokens);
+    // Honest saving: tokens an agent would spend reading all source files minus tokens a
+    // targeted recall costs. Only meaningful when an agent would otherwise read everything.
+    // memoryTokens is storage cost, not context sent — excluded from this calculation.
+    const tokensSaved = Math.max(0, indexedSourceTokens - recallContextTokens);
     const readinessScore = Math.max(0, Math.min(100, Math.round(coverage * 0.35 +
         percent(evidenceBackedEdges, knowledgeGraph.edges.length) * 0.25 +
         (approvedPackets > 0 ? 20 : 0) +
@@ -3213,7 +3229,7 @@ function kageMetricsShallow(projectDir) {
             estimated_indexed_source_tokens: indexedSourceTokens,
             estimated_memory_tokens: memoryTokens,
             estimated_recall_context_tokens: recallContextTokens,
-            estimated_tokens_saved_per_recall: Math.max(0, indexedSourceTokens + memoryTokens - recallContextTokens),
+            estimated_tokens_saved_per_recall: Math.max(0, indexedSourceTokens - recallContextTokens),
         },
         harness: {
             policy_installed: (0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, "AGENTS.md")),
@@ -3528,10 +3544,8 @@ fi
 if [[ -z "$POLICY" ]]; then
   POLICY="This repo uses Kage as an automatic memory harness for coding agents.
 Before making code changes or answering implementation questions:
-1. Call kage_validate for this repo.
-2. Call kage_recall with the user task as the query.
-3. Call kage_code_graph for file, symbol, route, test, or dependency questions.
-4. Call kage_graph for decisions, bugs, workflows, and conventions.
+1. Call kage_context with project_dir and the user task as query.
+2. Use returned memory only when it is relevant, source-backed, and not stale.
 When you learn something reusable: kage_learn.
 After meaningful file changes: kage_refresh.
 Before finishing a task that changed files: kage_pr_summarize or kage_propose_from_diff, then kage_pr_check.

package/package.json

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