@kage-core/kage-graph-mcp 2.5.0 → 2.5.2

package/dist/cli.js

@@ -1411,20 +1411,30 @@ async function main() {
         const query = takeArg(args, "--query") ?? firstPositional(args);
         if (!query)
             usage();
-        const result = (0, kernel_js_1.recall)(projectArg(args), query, 5, false, {});
+        const project = projectArg(args);
+        const result = (0, kernel_js_1.recall)(project, query, 5, false, {});
+        // Surface any nudges the kage-watcher wrote (marks them surfaced so each shows once) —
+        // this is what makes recall/nudges felt instead of silently sitting in a file.
+        const nudges = (0, kernel_js_1.surfacePendingNudges)(project);
         if (args.includes("--json")) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify({ ...result, nudges: nudges.items }, null, 2));
             return;
         }
-        if (!result.results.length)
-            return;
-        let out = result.context_block;
-        if (result.value_receipt) {
-            const r = result.value_receipt;
+        const parts = [];
+        if (result.results.length) {
+            // Lead with felt behavior, not a vanity/gameable token number: tell the agent these are
+            // verified team memories to follow. (The tokens/$ ledger lives in `kage gains`.) Keep
+            // only the trust-relevant stale-withheld signal here.
             const plural = result.results.length === 1 ? "y" : "ies";
-            out += `\n\n_↳ Kage recalled ${result.results.length} verified memor${plural} · ~${(0, kernel_js_1.formatTokenCount)(r.tokens_saved)} tokens saved this recall · ${r.stale_withheld} stale withheld._`;
+            const withheld = result.value_receipt?.stale_withheld ?? 0;
+            parts.push(result.context_block);
+            parts.push(`_${result.results.length} verified team memor${plural} above — follow them.${withheld ? ` ${withheld} stale memor${withheld === 1 ? "y" : "ies"} withheld (code changed under them).` : ""}_`);
         }
-        console.log(out);
+        if (nudges.block)
+            parts.push(nudges.block.trimStart());
+        if (!parts.length)
+            return;
+        console.log(parts.join("\n\n"));
         return;
     }
     if (command === "memory-access") {

package/dist/kernel.js

@@ -102,6 +102,7 @@ exports.compactProject = compactProject;
 exports.installAgentPolicy = installAgentPolicy;
 exports.createDenseEmbeddingProvider = createDenseEmbeddingProvider;
 exports.buildEmbeddingIndex = buildEmbeddingIndex;
+exports.surfacePendingNudges = surfacePendingNudges;
 exports.recall = recall;
 exports.recallWithEmbeddings = recallWithEmbeddings;
 exports.queryCodeGraph = queryCodeGraph;
@@ -7942,7 +7943,10 @@ function isSerializedDumpTitle(title) {
     return /^(workflow|runbook)\s*:?\s*[{[]/i.test(t)
         || t.startsWith('{"')
         || /^<(task-notification|div|svg|html)\b/i.test(t)
-        || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title);
+        || /\btool_use_id\b|toolu_[A-Za-z0-9]{10}/.test(title)
+        // Shell-prompt / terminal paste, e.g. "user@host dir % cmd" or "user@host:path$ cmd" —
+        // a pasted command transcript, not a durable learning.
+        || /^[\w.+-]+@[\w.+-]+[\s:].*[%$#]\s/.test(t);
 }
 // Durable-learning size ceiling. A memory packet body is a distilled insight, not a
 // document; anything past this is almost certainly a raw transcript, file-content, or
@@ -7961,6 +7965,51 @@ function isSerializedDumpBody(body) {
     return isSerializedDumpTitle(t)
         || /<task-notification\b|<tool-use-id\b|"hookSpecificOutput"|"isImage"\s*:|"noOutputExpected"\s*:|"interrupted"\s*:\s*(true|false)/i.test(t.slice(0, 4000));
 }
+// Surface watcher nudges: read the nudge inbox the kage-watcher writes, return the
+// unsurfaced ones as a prominent block, and mark them surfaced so each shows exactly once.
+// This is what makes recall/nudges FELT — the UserPromptSubmit hook injects this block, so
+// the agent sees "act on this" memory instead of it sitting silently in a file.
+function surfacePendingNudges(projectDir) {
+    const path = (0, node_path_1.join)(projectDir, ".agent_memory", "nudges", "pending.jsonl");
+    if (!(0, node_fs_1.existsSync)(path))
+        return { block: "", items: [], count: 0 };
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return { block: "", items: [], count: 0 };
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === "object")
+                records.push(parsed);
+        }
+        catch { /* drop malformed lines */ }
+    }
+    const unsurfaced = records.filter((record) => record.surfaced !== true && typeof record.message === "string");
+    if (!unsurfaced.length)
+        return { block: "", items: [], count: 0 };
+    const items = unsurfaced.map((record) => ({
+        message: String(record.message),
+        file: typeof record.file === "string" ? record.file : undefined,
+        kind: typeof record.kind === "string" ? record.kind : undefined,
+    }));
+    for (const record of unsurfaced)
+        record.surfaced = true;
+    try {
+        (0, node_fs_1.writeFileSync)(path, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`, "utf8");
+    }
+    catch { /* best-effort; recall still works */ }
+    const block = ["", "## ⚠ Kage nudges — act on these before proceeding",
+        ...items.map((item) => `- ${item.file ? `${item.file}: ` : ""}${item.message}`)].join("\n");
+    return { block, items, count: items.length };
+}
 // Collapse whitespace and hard-cap a value rendered inline in a context block, so one
 // oversized field (e.g. a graph fact whose body is a raw transcript) can never blow up
 // the assembled output — the 270k-char overflow that motivated this guard.
@@ -8102,14 +8151,23 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         ...scored.flatMap((entry, index) => {
             const contradicts = (entry.packet.quality ?? {}).contradicts;
             const contested = Array.isArray(contradicts) && contradicts.length > 0;
+            // Felt format: lead with an imperative "Team memory:" claim the agent should follow,
+            // dated and cited to file — not machinery (confidence/why-matched/source read as vanity
+            // and noise). The behavior change is the value, not the metadata.
+            const when = (entry.packet.created_at || entry.packet.updated_at || "").slice(0, 10);
+            const verb = entry.packet.type === "decision" ? "decided"
+                : entry.packet.type === "bug_fix" ? "fixed"
+                    : entry.packet.type === "convention" ? "convention since"
+                        : "noted";
+            const cited = entry.packet.paths.slice(0, 3).join(", ");
+            const meta = `${verb}${when ? ` ${when}` : ""}${cited ? ` · ${cited}` : ""}`;
             return [
                 "",
-                `${index + 1}. [${entry.packet.type} | ${entry.packet.scope} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
-                `   Summary: ${entry.packet.summary}`,
-                `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
-                `   Source: ${sourceLabel(entry.packet)}`,
+                `${index + 1}. Team memory: ${entry.packet.title}`,
+                `   ${entry.packet.summary}`,
+                ...(meta.trim() ? [`   (${meta})`] : []),
                 ...(contested
-                    ? [`   ⚠ Contested: this memory contradicts ${contradicts.length} other packet(s) (${contradicts.join(", ")}). Resolve with kage conflicts / kage supersede before relying on it.`]
+                    ? [`   ⚠ Contested: contradicts ${contradicts.length} other packet(s) (${contradicts.join(", ")}) — resolve with kage conflicts / kage supersede before relying on it.`]
                     : []),
             ];
         }),
@@ -14622,6 +14680,13 @@ function loadObservations(projectDir, sessionId) {
 // and echoes of Kage's own demo/receipt output. Manual `kage learn`/`kage capture`
 // and manual `kage distill` are never gated — explicit intent outranks the heuristic.
 exports.AUTO_DISTILL_SIGNAL_THRESHOLD = 0.4;
+// Auto-promote gate: a distilled draft jumps straight to trusted (approved, recallable)
+// memory — instead of waiting in the pending inbox — only when it is clearly-good AND
+// code-grounded AND not a duplicate. Everything else still goes to review. This is what
+// makes the capture flywheel actually spin; KAGE_AUTO_PROMOTE=0 disables it. Grounding keeps
+// the verification wedge intact: a promoted memory is still checked against the code, just
+// not gated on a human.
+const AUTO_PROMOTE_ENABLED = process.env.KAGE_AUTO_PROMOTE !== "0";
 // Markers of hook/system plumbing payloads that sometimes leak into observation text
 // (e.g. a raw <task-notification> block stored as a "user prompt").
 const HOOK_PAYLOAD_MARKERS = [
@@ -15274,16 +15339,44 @@ function distillSession(projectDir, sessionId, options = {}) {
                 observation_count: observations.length,
             },
         ];
+        const admission = evaluateMemoryAdmission(projectDir, result.packet);
         result.packet.quality = {
             ...result.packet.quality,
             ...(sessionDiscoveryTokens > 0
                 ? { discovery_tokens: sessionDiscoveryTokens, discovery_tokens_estimated: true }
                 : {}),
             distillation: auto ? "auto_distill" : "automatic_observation_candidate",
-            admission: evaluateMemoryAdmission(projectDir, result.packet),
+            admission,
             suggested_review_action: suggestedAction(classifyPacket(projectDir, result.packet), result.packet.status),
         };
-        writeJson(result.path, result.packet);
+        // Auto-promote the clearly-good, code-grounded, non-duplicate drafts straight to trusted
+        // recall so the flywheel spins without manual review; borderline / ungrounded / path-less
+        // drafts stay in the pending inbox for a quick review.
+        const groundedHighSignal = AUTO_PROMOTE_ENABLED
+            && auto
+            && result.packet.status === "pending"
+            && admission.admit
+            && admission.class === "high_signal"
+            && result.packet.paths.length > 0
+            && result.packet.paths.every((path) => pathExistsInRepo(projectDir, path))
+            && duplicateCandidates(projectDir, result.packet).length === 0
+            && detectContradictions(projectDir, result.packet).length === 0;
+        if (groundedHighSignal) {
+            result.packet.status = "approved";
+            result.packet.tags = unique([...result.packet.tags, "auto-promoted"]);
+            result.packet.quality.suggested_review_action = suggestedAction(classifyPacket(projectDir, result.packet), "approved");
+            const promotedPath = writePacket(projectDir, result.packet, "packets");
+            if (result.path && result.path !== promotedPath) {
+                try {
+                    (0, node_fs_1.unlinkSync)(result.path);
+                }
+                catch { }
+            }
+            result.path = promotedPath;
+        }
+        else {
+            writeJson(result.path, result.packet);
+        }
         return result;
     };
     const autoTags = auto ? [exports.AUTO_DISTILL_TAG] : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
   "main": "dist/index.js",
   "files": [