@nxuss/lemma 1.16.1 → 1.17.0

package/dist/esm/mcp/tools.js

@@ -24,7 +24,7 @@ import { findPattern, storePattern, getPatternStats } from "../utils/PromptPatte
 import { runAnalysis, parseDiff } from "../pr-review/PRReviewEngine.js";
 import { ReviewStore } from "../pr-review/ReviewStore.js";
 import { runPRReview } from "../pr-review/reviewRunner.js";
-import { getBrain, deriveProjectId } from "../subconscious/TheBrainV2.js";
+import { getBrain, deriveProjectId, currentGitContext } from "../subconscious/TheBrainV2.js";
 import { collapseContext } from "../utils/ContextCollapser.js";
 import { getSymbolSurgicalContext } from "../utils/SymbolSurgicalContext.js";
 import { compressWormhole } from "../utils/WormholeCompressor.js";
@@ -69,6 +69,10 @@ function isProUser() {
 const FREE_TOOLS = new Set([
     // Cache & Memory — the hook that shows instant value
     "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory", "downvote_memory", "verify_memory", "get_project_history",
+    // Memory upkeep. Deleting your own memories, re-verifying them, and getting them back out
+    // of the tool must never be behind a paywall — a user who cannot export or forget what a
+    // free tier collected does not really own it.
+    "forget_memory", "refresh_memory", "brain_stats", "brain_export", "brain_import",
     // Token optimization — shows what they're saving
     "token_budget", "squeeze_prompt", "turbosqueeze",
     // Utility — just enough to function
@@ -307,6 +311,81 @@ const toolDefinitions = [
             required: ["id"],
         },
     },
+    {
+        name: "forget_memory",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        description: "Permanently delete one memory from the Brain by id. Use when a memory is flat wrong, was captured by mistake, or should never have been stored — not when it is merely a poor match for one query (that is downvote_memory, which keeps it around for a different question later). Deletion is irreversible and the id will not come back from another session's copy.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The memory's id, from a search_memory or store_memory result." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "refresh_memory",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: "Re-anchor a STALE memory to the code as it stands now, keeping its id, hit count and derivedFrom links (storing a near-duplicate instead loses all three, and dedup often refuses it anyway). Call with just the id after you have verified the memory is still correct; pass filePaths/symbols instead when the code moved and it should track something new. Only call this once you have actually checked — it records your assertion that the memory is true today, it cannot verify that itself.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "The memory's id, from a search_memory or verify_memory result." },
+                filePaths: { type: "array", items: { type: "string" }, description: "New files to track instead of the current ones. Omit to re-hash whatever it already tracks." },
+                symbols: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            filePath: { type: "string" },
+                            symbolName: { type: "string" },
+                        },
+                        required: ["filePath", "symbolName"],
+                    },
+                    description: "New symbols to track instead of the current ones (e.g. the function was renamed or moved).",
+                },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "brain_stats",
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        description: "Health report for the Brain itself: entry count, how many memories no search has ever reused, how many were downvoted, what wrote them (manual vs. each auto-capture path), projects covered, and corpus size. Pass deep:true to also re-hash every tracked file and report the stale ratio — accurate but thousands of file reads on a large Brain.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                deep: { type: "boolean", description: "Also compute the stale ratio by re-hashing all tracked evidence. Slow.", default: false },
+            },
+        },
+    },
+    {
+        name: "brain_export",
+        annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
+        description: "Write memories to a portable NDJSON bundle for backup, moving to another machine, or sharing with a teammate. Defaults to this project's memories only, and to fresh ones only (a stale memory exported and imported elsewhere is just a wrong answer with a passport).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                outPath: { type: "string", description: "Where to write the bundle (relative to the workspace root)." },
+                allProjects: { type: "boolean", description: "Export every project's memories, not just this one.", default: false },
+                domain: { type: "string", description: "Only export memories tagged with this domain." },
+                includeStale: { type: "boolean", description: "Include memories whose tracked evidence no longer matches.", default: false },
+            },
+            required: ["outPath"],
+        },
+    },
+    {
+        name: "brain_import",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: "Merge a bundle written by brain_export into this Brain. Additive and non-destructive: an id already present keeps the newer version, and anything previously deleted with forget_memory stays deleted. Imported memories track the paths of the machine they came from, so most will read as stale here until refresh_memory re-anchors them.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the bundle file (relative to the workspace root)." },
+            },
+            required: ["path"],
+        },
+    },
     {
         name: "get_routing_advice",
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -1437,6 +1516,11 @@ const toolHandlers = {
     store_memory: handleStoreMemory,
     downvote_memory: handleDownvoteMemory,
     verify_memory: handleVerifyMemory,
+    forget_memory: handleForgetMemory,
+    refresh_memory: handleRefreshMemory,
+    brain_stats: handleBrainStats,
+    brain_export: handleBrainExport,
+    brain_import: handleBrainImport,
     get_routing_advice: handleGetRoutingAdvice,
     auto_heal: handleAutoHeal,
     read_workspace_file: handleReadWorkspaceFile,
@@ -1715,7 +1799,9 @@ async function handleSearchMemory(args) {
         throw new Error("Query is required");
     try {
         const brain = getBrain();
-        const results = brain.search(query, limit, minSimilarity, { projectId: deriveProjectId(), domain, semanticDiff });
+        // searchHybrid is search() plus one boolean check unless LEMMA_BRAIN_EMBEDDINGS is set,
+        // so this costs nothing by default and picks up the semantic re-rank when it is enabled.
+        const results = await brain.searchHybrid(query, limit, minSimilarity, { projectId: deriveProjectId(), domain, semanticDiff });
         if (results.length === 0) {
             recordReceiptEvent("reasoning", query.substring(0, 100), {
                 tool: "search_memory",
@@ -1766,7 +1852,15 @@ async function handleSearchMemory(args) {
         }
         if (stale.length > 0) {
             const staleText = stale
-                .map((r, i) => `${formatResult(r, i)}\nSTALE — changed since stored: ${r.staleFiles.join(", ")}`)
+                .map((r, i) => {
+                // "You are on a different branch" and "someone rewrote this function" are the same
+                // hash mismatch and completely different situations for the reader: the first is
+                // usually not a reason to distrust the memory at all.
+                const cause = r.staleCause === "branch-changed"
+                    ? `\nNOTE: stored on branch \`${r.storedOnBranch}\`, you are on \`${currentGitContext().branch || "an unknown branch"}\`. The difference may be the branch switch rather than an edit — check before discarding this.`
+                    : "";
+                return `${formatResult(r, i)}\nSTALE — changed since stored: ${r.staleFiles.join(", ")}${cause}`;
+            })
                 .join("\n\n---\n\n");
             parts.push(`${stale.length} more ${stale.length === 1 ? "memory is" : "memories are"} similar but STALE (underlying file(s) changed) — do not reuse verbatim, re-verify against current file state:\n\n${staleText}`);
         }
@@ -1800,7 +1894,7 @@ async function handleStoreMemory(args) {
         throw new Error("Query and response are required");
     try {
         const brain = getBrain();
-        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols, claims, domain, derivedFrom);
+        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols, claims, domain, derivedFrom, { source: "manual" });
         // Storing a memory saves nothing — it only creates the chance of a saving later.
         // Crediting tokens here inflated the ledger on write and then credited the same
         // answer again on every read. The saving is booked by search_memory on a fresh hit.
@@ -1823,7 +1917,11 @@ async function handleStoreMemory(args) {
             ? `\n\n⚠️ ${storeRes.conflicts.length} existing ${storeRes.conflicts.length === 1 ? "memory shares" : "memories share"} a symbol with this one but disagree on outcome — review before trusting either:\n` +
                 storeRes.conflicts.map((c) => `  - [${c.outcome}] ${c.id}: ${c.query.substring(0, 120)}`).join("\n")
             : "";
-        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}${claimsNote}${domainNote}${derivedFromNote}${conflictsNote}` }] };
+        // The id is the handle for every follow-up action on this memory — derivedFrom on a
+        // later store, verify_memory, refresh_memory, forget_memory. Without it the caller had
+        // to search for the memory it had just written to do anything with it.
+        const idNote = storeRes.id ? ` (id: ${storeRes.id})` : "";
+        return { content: [{ type: "text", text: `Success: Memory stored${idNote}. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}${claimsNote}${domainNote}${derivedFromNote}${conflictsNote}` }] };
     }
     catch (e) {
         logError("store_memory", e);
@@ -1843,6 +1941,138 @@ async function handleDownvoteMemory(args) {
         return { content: [{ type: "text", text: `Failed to downvote memory: ${e.message}` }] };
     }
 }
+/**
+ * Deleting a memory is the one Brain operation with no undo, so it asks the client to
+ * confirm where the client supports it, and echoes back what was destroyed where it doesn't
+ * — an irreversible action must at minimum leave a record of what it removed.
+ */
+async function handleForgetMemory(args) {
+    const id = args?.id;
+    if (!id)
+        throw new Error("id is required");
+    try {
+        const brain = getBrain();
+        const preview = brain.verifyByIds([id])[0];
+        if (preview?.status === "unknown") {
+            return { content: [{ type: "text", text: `No memory with id "${id}" in the Brain — nothing to delete.` }] };
+        }
+        const elicited = await tryElicitConfirmation(`Permanently delete Brain memory "${id}"? This cannot be undone.`);
+        if (elicited.supported && !elicited.confirmed) {
+            return { content: [{ type: "text", text: `Memory "${id}" was not deleted: declined during confirmation.` }] };
+        }
+        const result = brain.forget(id);
+        if (!result.ok || !result.forgotten) {
+            return { content: [{ type: "text", text: result.message }] };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: `${result.message}\n\nDeleted content, for the record (nothing else can recover it):\n  stored: ${result.forgotten.timestamp}\n  reused: ${result.forgotten.hits} time(s)\n  query: ${result.forgotten.query.substring(0, 300)}`,
+                }],
+        };
+    }
+    catch (e) {
+        logError("forget_memory", e);
+        return { content: [{ type: "text", text: `Failed to delete memory: ${e.message}` }] };
+    }
+}
+async function handleRefreshMemory(args) {
+    const id = args?.id;
+    if (!id)
+        throw new Error("id is required");
+    const filePaths = Array.isArray(args?.filePaths) ? args.filePaths.filter((p) => typeof p === "string" && p) : undefined;
+    const symbols = Array.isArray(args?.symbols)
+        ? args.symbols.filter((sym) => sym?.filePath && sym?.symbolName)
+        : undefined;
+    try {
+        const result = getBrain().refresh(id, { filePaths, symbols });
+        if (!result.ok)
+            return { content: [{ type: "text", text: result.message }] };
+        const retrackedNote = result.retracked && result.retracked.length > 0
+            ? `\nNow tracking: ${result.retracked.join(", ")}`
+            : "\nThis memory tracks no files or symbols, so there was nothing to re-anchor — its age clock was reset.";
+        return { content: [{ type: "text", text: `${result.message}${retrackedNote}` }] };
+    }
+    catch (e) {
+        logError("refresh_memory", e);
+        return { content: [{ type: "text", text: `Failed to refresh memory: ${e.message}` }] };
+    }
+}
+async function handleBrainStats(args) {
+    try {
+        const stats = getBrain().getStats({ deep: args?.deep === true });
+        const lines = [];
+        lines.push(`# Brain health`);
+        lines.push(`Entries: ${stats.totalEntries} (${stats.totalTerms} indexed terms, ${((stats.corpusBytes || 0) / 1024).toFixed(0)} KB on disk)`);
+        lines.push(`This session: ${stats.cacheHits} hit(s), ${stats.cacheMisses} miss(es)`);
+        if (stats.totalEntries > 0) {
+            const neverHitPct = ((stats.neverHit || 0) / stats.totalEntries) * 100;
+            lines.push(`Never reused: ${stats.neverHit} (${neverHitPct.toFixed(0)}% — these are evicted first)`);
+            lines.push(`Downvoted: ${stats.downvoted}`);
+            lines.push(`Projects: ${stats.projects}${stats.unscopedEntries ? ` (+${stats.unscopedEntries} entries predating project scoping)` : ""}`);
+            if (stats.oldestEntry)
+                lines.push(`Oldest entry: ${stats.oldestEntry}`);
+            if (stats.tombstones)
+                lines.push(`Deleted ids still suppressed: ${stats.tombstones}`);
+            const sources = Object.entries(stats.bySource || {}).sort((a, b) => b[1] - a[1]);
+            if (sources.length > 0) {
+                lines.push(`Written by: ${sources.map(([k, v]) => `${k}=${v}`).join(", ")}`);
+            }
+        }
+        if (stats.staleEntries !== undefined) {
+            lines.push(`Stale: ${stats.staleEntries} of the entries that track evidence (${((stats.staleRatio || 0) * 100).toFixed(0)}%) — refresh_memory re-anchors one, forget_memory drops it.`);
+        }
+        else {
+            lines.push(`(stale ratio not computed — pass deep:true)`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (e) {
+        logError("brain_stats", e);
+        return { content: [{ type: "text", text: `Failed to read Brain stats: ${e.message}` }] };
+    }
+}
+async function handleBrainExport(args) {
+    const outPath = args?.outPath;
+    if (!outPath)
+        throw new Error("outPath is required");
+    try {
+        const bundle = getBrain().exportBundle({
+            // Scoped to this project unless asked otherwise: exporting every project's memories
+            // by default is how a bundle meant for one teammate ends up carrying another client's
+            // codebase notes with it.
+            projectId: args?.allProjects === true ? undefined : deriveProjectId(),
+            domain: typeof args?.domain === "string" && args.domain.trim() ? args.domain.trim() : undefined,
+            includeStale: args?.includeStale === true,
+        });
+        const { resolved } = safeResolvePath(process.cwd(), outPath);
+        fs.mkdirSync(path.dirname(resolved), { recursive: true });
+        fs.writeFileSync(resolved, bundle.text, "utf8");
+        const staleNote = bundle.skippedStale > 0
+            ? ` Skipped ${bundle.skippedStale} stale memor${bundle.skippedStale === 1 ? "y" : "ies"} (pass includeStale:true to export those too).`
+            : "";
+        return { content: [{ type: "text", text: `Exported ${bundle.count} memor${bundle.count === 1 ? "y" : "ies"} to ${outPath}.${staleNote}` }] };
+    }
+    catch (e) {
+        logError("brain_export", e);
+        return { content: [{ type: "text", text: `Failed to export Brain: ${e.message}` }] };
+    }
+}
+async function handleBrainImport(args) {
+    const bundlePath = args?.path;
+    if (!bundlePath)
+        throw new Error("path is required");
+    try {
+        const { resolved } = safeResolvePath(process.cwd(), bundlePath);
+        const text = fs.readFileSync(resolved, "utf8");
+        const result = getBrain().importBundle(text);
+        return { content: [{ type: "text", text: result.message }] };
+    }
+    catch (e) {
+        logError("brain_import", e);
+        return { content: [{ type: "text", text: `Failed to import Brain bundle: ${e.message}` }] };
+    }
+}
 async function handleVerifyMemory(args) {
     const ids = Array.isArray(args?.ids) ? args.ids.filter((id) => typeof id === "string" && id) : [];
     const semanticDiff = args?.semanticDiff === true;
@@ -2030,7 +2260,7 @@ async function handleReadWorkspaceFile(args) {
                                     `If you no longer hold that copy, re-fetch with force:true.`,
                                     ``,
                                     delta.body,
-                                ].join("\n"),
+                                ].join("\n") + formatRecallNote(filePath),
                             },
                         ],
                     };
@@ -2039,7 +2269,7 @@ async function handleReadWorkspaceFile(args) {
         }
         recordSent(resolved, view, dedup.hash, content);
         warmNeighbors(workspaceRoot, resolved);
-        return { content: [{ type: "text", text: rangeHeader + content }] };
+        return { content: [{ type: "text", text: rangeHeader + content + formatRecallNote(filePath) }] };
     }
     catch (err) {
         logError("read_workspace_file", err);
@@ -2129,6 +2359,46 @@ function formatBlastRadiusNote(result) {
     const failedIds = result.failedHits.map((h) => h.id).join(", ");
     return `${base}\n⚠️ ${result.failedHits.length} of those document a PRIOR ATTEMPT THAT FAILED on related code: ${failedIds}. Review before continuing down this path.`;
 }
+/**
+ * The read-side counterpart to formatBlastRadiusNote.
+ *
+ * Fase E made the write path proactive: a tool that stales memories says so on the spot.
+ * The read path stayed entirely opt-in — the Brain only spoke when the agent remembered to
+ * call search_memory, which is exactly the moment an agent that doesn't know a memory exists
+ * has no reason to. This closes that asymmetry: reading code the Brain already has notes on
+ * surfaces them, including any documented dead end, before the investigation restarts from
+ * scratch.
+ *
+ * Same rules as the write-side note: advisory only, never blocks, never mutates, and adds no
+ * tool schema (it enriches an existing response), so it costs nothing per turn. It reports
+ * ids rather than content — pulling whole memories into every file read would spend far more
+ * context than it saves; search_memory or verify_memory fetches the ones that matter.
+ */
+const _recallNoted = new Set();
+function formatRecallNote(filePath, symbolName) {
+    try {
+        const result = getBrain().findBlastRadius(filePath, symbolName);
+        if (result.hits.length === 0)
+            return "";
+        // Repeating the identical note on every read of the same file is nagging, not signal.
+        // Keyed by the memory set, so a note reappears when the set genuinely changes.
+        const ids = result.hits.map((h) => h.id).sort();
+        const key = `${path.resolve(filePath)}::${symbolName || ""}::${ids.join(",")}`;
+        if (_recallNoted.has(key))
+            return "";
+        _recallNoted.add(key);
+        const subject = symbolName ? `\`${symbolName}\`` : "this file";
+        const base = `\n\n🧠 The Brain already has ${result.hits.length} memor${result.hits.length === 1 ? "y" : "ies"} about ${subject}: ${ids.join(", ")}. Call verify_memory on them before investigating from scratch.`;
+        if (result.failedHits.length === 0)
+            return base;
+        const failedIds = result.failedHits.map((h) => h.id).join(", ");
+        return `${base}\n⚠️ ${result.failedHits.length} of those document an approach that was tried here and FAILED: ${failedIds}. Read those first so you don't repeat it.`;
+    }
+    catch {
+        // A recall note must never be the reason a file read fails.
+        return "";
+    }
+}
 async function applyMatch(match, filePath, resolved, originalContent, searchContent, replaceContent) {
     let updatedContent;
     if (match.strategy === "exact" && match.charStart !== undefined && match.charEnd !== undefined) {
@@ -5047,7 +5317,7 @@ async function handleGetSymbolSurgicalContext(args) {
             filePath
         });
         return {
-            content: [{ type: "text", text: output }]
+            content: [{ type: "text", text: output + formatRecallNote(filePath, symbolName) }]
         };
     }
     catch (err) {
@@ -5228,7 +5498,7 @@ async function handleSmartFileSlice(args) {
                 resultText += `${i + 1}: ${lines[i]}\n`;
             }
         });
-        return { content: [{ type: "text", text: resultText }] };
+        return { content: [{ type: "text", text: resultText + formatRecallNote(filePath) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: `Error slicing file: ${e.message}` }] };
@@ -5256,7 +5526,7 @@ function autoStoreGreenTests(command, workspaceRoot) {
         const domain = deriveDomainForFile(changed[0]);
         const query = `tests passing after changes to ${changed.slice(0, 5).join(", ")}${changed.length > 5 ? ` and ${changed.length - 5} more file(s)` : ""}`;
         const response = `\`${command}\` passed with these files changed (uncommitted at capture time):\n${changed.join("\n")}`;
-        const storeRes = getBrain().store(query, response, "test_oracle_auto", 0.92, changed, undefined, "confirmed", undefined, undefined, domain);
+        const storeRes = getBrain().store(query, response, "test_oracle_auto", 0.92, changed, undefined, "confirmed", undefined, undefined, domain, undefined, { source: "auto-test" });
         if (!storeRes.stored)
             return "";
         return `\n\n[Lemma] Auto-captured this green state in Brain (${changed.length} file(s), tagged confirmed) — search_memory will surface it, and will flag it stale the moment any of these files change again.`;