@nxuss/lemma 1.24.1 → 1.26.0

package/dist/cjs/utils/PromptPatternCache.js

@@ -8,10 +8,18 @@ exports.storePattern = storePattern;
 exports.getPatternStats = getPatternStats;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const scrubForStorage_1 = require("../security/scrubForStorage");
 const CACHE_FILE = '.lemma/prompt-patterns.json';
+/** A lock older than this is assumed to belong to a process that died holding it. */
+const LOCK_STALE_MS = 10000;
+/** How long a writer waits for another process's lock before proceeding regardless. */
+const LOCK_WAIT_MS = 2000;
 function getCachePath(projectRoot) {
     return path_1.default.join(projectRoot, CACHE_FILE);
 }
+function getLockPath(projectRoot) {
+    return `${getCachePath(projectRoot)}.lock`;
+}
 function loadCache(projectRoot) {
     try {
         const p = getCachePath(projectRoot);
@@ -31,14 +39,113 @@ function loadCache(projectRoot) {
     catch { }
     return { patterns: [], lastUpdated: Date.now() };
 }
+/** Blocking sleep — callers here are synchronous and must not observe a half-merged cache. */
+function sleepSync(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch {
+        const until = Date.now() + ms;
+        while (Date.now() < until) { /* busy wait */ }
+    }
+}
+/**
+ * Advisory cross-process write lock, same shape as TheBrainV2's: fail-open, never blocks
+ * forever. Every path through the loop body sleeps or returns before looping again — an
+ * `ENOENT` because the parent directory doesn't exist yet (as opposed to `EEXIST`, the only
+ * case that means "someone else holds it") must never be read as "retry immediately", or
+ * this spins at 100% CPU forever instead of backing off. Callers must create the parent
+ * directory before calling this.
+ */
+function acquireLock(projectRoot) {
+    const lockPath = getLockPath(projectRoot);
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            return fs_1.default.openSync(lockPath, 'wx');
+        }
+        catch (err) {
+            if (err?.code === 'EEXIST') {
+                try {
+                    if (Date.now() - fs_1.default.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                        fs_1.default.unlinkSync(lockPath);
+                        continue; // freed a stale lock — retry immediately against the now-open path
+                    }
+                }
+                catch {
+                    continue; // lock vanished between open and stat — the holder just released it
+                }
+            }
+            if (Date.now() >= deadline)
+                return null;
+            sleepSync(15);
+        }
+    }
+}
+function releaseLock(projectRoot, fd) {
+    if (fd === null)
+        return;
+    try {
+        fs_1.default.closeSync(fd);
+    }
+    catch { }
+    try {
+        fs_1.default.unlinkSync(getLockPath(projectRoot));
+    }
+    catch { }
+}
+function writeFileAtomic(target, data) {
+    const tmp = `${target}.tmp.${process.pid}.${Date.now().toString(36)}`;
+    try {
+        fs_1.default.writeFileSync(tmp, data, 'utf8');
+        fs_1.default.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            fs_1.default.unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}
+/**
+ * Merge `patterns` (the caller's in-memory view, already mutated) onto whatever is on disk
+ * right now, under the write lock — a blind overwrite would erase patterns a concurrent
+ * session stored since this process last loaded. Same fix TheBrainV2 applies to entries.ndjson.
+ */
+function mergePatterns(base, onDisk) {
+    const byId = new Map();
+    for (const p of onDisk)
+        byId.set(p.id, p);
+    for (const p of base)
+        byId.set(p.id, p); // in-memory wins for ids both sides know about
+    return Array.from(byId.values())
+        .sort((a, b) => (b.hitCount * b.avgTokensSaved) - (a.hitCount * a.avgTokensSaved))
+        .slice(0, 50);
+}
 function saveCache(projectRoot, data) {
+    const dir = path_1.default.join(projectRoot, '.lemma');
+    let lockFd = null;
     try {
-        const dir = path_1.default.join(projectRoot, '.lemma');
+        // Must exist before acquireLock: opening a lock file under a missing directory throws
+        // ENOENT on every attempt, not just the first, which is exactly the busy-loop acquireLock
+        // is written to avoid mistaking for lock contention.
         if (!fs_1.default.existsSync(dir))
             fs_1.default.mkdirSync(dir, { recursive: true });
-        fs_1.default.writeFileSync(getCachePath(projectRoot), JSON.stringify(data, null, 2), 'utf8');
+        lockFd = acquireLock(projectRoot);
+        const onDisk = loadCache(projectRoot);
+        const merged = {
+            patterns: mergePatterns(data.patterns, onDisk.patterns),
+            lastUpdated: Date.now(),
+        };
+        writeFileAtomic(getCachePath(projectRoot), JSON.stringify(merged, null, 2));
+    }
+    catch {
+        // Persistence is best-effort — a failed save must not break find/store for the caller.
+    }
+    finally {
+        releaseLock(projectRoot, lockFd);
     }
-    catch { }
 }
 function extractKeywords(text) {
     return text.toLowerCase()
@@ -79,17 +186,21 @@ function storePattern(query, template, tokensSaved, projectRoot) {
     const cache = loadCache(projectRoot);
     const keywords = extractKeywords(query);
     const id = `pattern-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    // Templates and their source query can carry pasted secrets — redact before they ever
+    // touch disk, the same policy TheBrainV2 applies to every stored query/response/claim.
+    const scrubbedTemplate = (0, scrubForStorage_1.scrubSecretsForStorage)(template).text;
     const existing = cache.patterns.find(p => matchScore(keywords, p.keywords) > 0.7);
     if (existing) {
         existing.hitCount++;
         existing.avgTokensSaved = (existing.avgTokensSaved + tokensSaved) / 2;
+        existing.template = scrubbedTemplate;
         saveCache(projectRoot, cache);
         return existing;
     }
     const pattern = {
         id,
         keywords,
-        template,
+        template: scrubbedTemplate,
         hitCount: 1,
         avgTokensSaved: tokensSaved,
     };

package/dist/cjs/utils/PromptPatternCache.js.map

@@ -1 +1 @@
-{"version":3,"file":"PromptPatternCache.js","sourceRoot":"","sources":["../../../src/utils/PromptPatternCache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PromptPatternCache.js","sourceRoot":"","sources":["../../../src/utils/PromptPatternCache.ts"],"names":[],"mappings":"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"}

package/dist/esm/mcp/tools/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tools/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhE,eAAO,MAAM,uBAAuB,EAAE,cAAc,EAoTnD,CAAC;AAgrBF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAe5D,CAAC"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../../src/mcp/tools/memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhE,eAAO,MAAM,uBAAuB,EAAE,cAAc,EAoUnD,CAAC;AAmxBF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAgB5D,CAAC"}

package/dist/esm/mcp/tools/memory.js

@@ -14,6 +14,21 @@ import { logError, safeResolvePath, DEFAULT_MEMORY_SIMILARITY_FLOOR, tryElicitCo
 import { deriveDomainForFile } from "../cognitiveMap.js";
 import { getRecentEvidence } from "../../utils/SessionEvidence.js";
 export const MEMORY_TOOL_DEFINITIONS = [
+    {
+        name: "list_memories",
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        description: "Browse stored memories by project/domain/outcome, newest first — no query string, no BM25 ranking, no similarity floor. Use this for 'what do you have stored about X project' instead of forcing that into a search_memory phrasing, or to see the ids a prior brain_upkeep batch referred to. Returns short summaries (id, truncated query, hits, tokensSaved) — call get_memory for a full entry.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectId: { type: "string", description: "Only list memories from this project. Defaults to the current project; pass an empty string to list across all projects." },
+                domain: { type: "string", description: "Only list memories tagged with this domain." },
+                outcome: { type: "string", enum: ["confirmed", "failed"], description: "Only list memories with this outcome." },
+                limit: { type: "number", description: "Max entries to return (1-200).", default: 25 },
+                offset: { type: "number", description: "Skip this many entries (for paging past `limit`).", default: 0 },
+            },
+        },
+    },
     {
         name: "search_memory",
         annotations: { readOnlyHint: true, openWorldHint: false },
@@ -245,14 +260,15 @@ export const MEMORY_TOOL_DEFINITIONS = [
     },
     {
         name: "brain_upkeep",
-        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-        description: "Tend the Brain in one read-only call: revalidates the most-reused memories, lists duplicates/merge candidates/dead weight/savings, each with its fix (refresh_memory, brain_merge, forget_memory). Never deletes or rewrites anything. Run when returning to a repo after a while.",
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: false },
+        description: "AUTO-ANCHORS evidence-free memories naming real repo files: snapshots first, then re-anchors them (undo via brain_trash restore-snapshot); autoAnchor:false = read-only. Lists duplicates, dead weight, savings with fixes. Run on returning to a repo.",
         inputSchema: {
             type: "object",
             properties: {
-                topN: { type: "number", description: "How many of the most-reused memories to revalidate. Default 20.", default: 20 },
-                sample: { type: "number", description: "How many entries to sweep for duplicates. Default 50 (bounded: each issues one internal search).", default: 50 },
-                deep: { type: "boolean", description: "Also re-hash all tracked evidence for a corpus-wide stale ratio. Slow on large Brains.", default: false },
+                topN: { type: "number", description: "Top memories to revalidate. Default 20.", default: 20 },
+                sample: { type: "number", description: "Entries to sweep for duplicates. Default 50.", default: 50 },
+                deep: { type: "boolean", description: "Re-hash all evidence for a stale ratio. Slow.", default: false },
+                autoAnchor: { type: "boolean", description: "Re-anchor untracked memories naming real repo files (snapshot first). Default true.", default: true },
             },
         },
     },
@@ -264,6 +280,7 @@ export const MEMORY_TOOL_DEFINITIONS = [
             type: "object",
             properties: {
                 id: { type: "string", description: "The memory's id, from a search_memory or verify_memory result." },
+                ids: { type: "array", items: { type: "string" }, description: "Verified ids to refresh in one call, instead of id." },
                 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",
@@ -278,7 +295,6 @@ export const MEMORY_TOOL_DEFINITIONS = [
                     description: "New symbols to track instead of the current ones (e.g. the function was renamed or moved).",
                 },
             },
-            required: ["id"],
         },
     },
     {
@@ -349,8 +365,12 @@ async function handleSearchMemory(args) {
                     }],
             };
         }
-        const fresh = results.filter((r) => r.fresh);
+        // An entry that tracks nothing reports `fresh: true` vacuously (checkEntryFreshness has
+        // nothing to compare) — it must NOT land in the verified-fresh bucket, be credited as a
+        // cache hit, or be told "from cache". It gets its own UNTRACKED bucket instead.
+        const fresh = results.filter((r) => r.fresh && !r.untracked);
         const stale = results.filter((r) => !r.fresh);
+        const untracked = results.filter((r) => r.fresh && r.untracked);
         const formatClaims = (r) => {
             if (!Array.isArray(r.claims) || r.claims.length === 0)
                 return "";
@@ -389,6 +409,12 @@ async function handleSearchMemory(args) {
                 memoryId: bestFresh.id,
             });
         }
+        else if (untracked.length > 0) {
+            recordReceiptEvent("reasoning", query.substring(0, 100), {
+                tool: "search_memory",
+                reason: `${untracked.length} similar but UNTRACKED — no evidence to verify, not credited as a cache hit`,
+            });
+        }
         else {
             recordReceiptEvent("reasoning", query.substring(0, 100), {
                 tool: "search_memory",
@@ -399,6 +425,12 @@ async function handleSearchMemory(args) {
         if (fresh.length > 0) {
             parts.push(`Lemma found ${fresh.length} fresh ${fresh.length === 1 ? "memory" : "memories"} (from cache — say so if you use this):\n\n${fresh.map(formatResult).join("\n\n---\n\n")}`);
         }
+        if (untracked.length > 0) {
+            const untrackedText = untracked
+                .map((r, i) => formatResult(r, i))
+                .join("\n\n---\n\n");
+            parts.push(`⚠️ ${untracked.length} ${untracked.length === 1 ? "memory is" : "memories are"} similar but UNTRACKED — ${untracked.length === 1 ? "it tracks" : "they track"} no files or symbols, so nothing was verified against current code (${untracked.length === 1 ? "it is" : "they are"} vacuously "fresh": there was nothing to check). ${untracked.length === 1 ? "It may" : "They may"} describe state that no longer exists — treat as a hint, re-verify against the repo before acting on it, and use update_memory/refresh_memory with filePaths/symbols so it becomes verifiable next time:\n\n${untrackedText}`);
+        }
         if (stale.length > 0) {
             const staleText = stale
                 .map((r, i) => {
@@ -747,21 +779,54 @@ async function handleBrainMerge(args) {
 }
 async function handleBrainUpkeep(args) {
     try {
+        const autoAnchor = args?.autoAnchor !== false;
         const report = getBrain().upkeep({
             topN: typeof args?.topN === "number" ? args.topN : undefined,
             sample: typeof args?.sample === "number" ? args.sample : undefined,
             deep: args?.deep === true,
         });
+        // Auto-anchor pass: an untracked memory that names real repo files is re-anchored to
+        // them, snapshotted first so the whole pass is reversible via brain_trash
+        // restore-snapshot. Anything the extractor cannot find a path for stays manual.
+        const anchored = [];
+        let snapshotName = null;
+        const anchorable = report.revalidated.untracked.filter((u) => u.anchorCandidates && u.anchorCandidates.length > 0);
+        if (autoAnchor && anchorable.length > 0) {
+            const brain = getBrain();
+            snapshotName = brain.snapshotCorpus("auto-anchor");
+            for (const u of anchorable) {
+                try {
+                    const res = brain.refresh(u.id, { filePaths: u.anchorCandidates });
+                    const tracked = (res.retracked || []).join(", ");
+                    anchored.push({
+                        ok: res.ok,
+                        id: u.id,
+                        detail: `${res.message}${tracked ? ` Now tracking: ${tracked}` : ""}`,
+                    });
+                }
+                catch (e) {
+                    anchored.push({ ok: false, id: u.id, detail: e.message });
+                }
+            }
+        }
+        const anchoredIds = new Set(anchored.filter((a) => a.ok).map((a) => a.id));
+        const stillUntracked = report.revalidated.untracked.filter((u) => !anchoredIds.has(u.id));
         const lines = [];
         lines.push(`# Brain upkeep (${report.totalEntries} entries, checked ${report.checkedAt})`);
         const r = report.revalidated;
         lines.push(`Revalidated top ${r.checked}: ${r.fresh.length} fresh, ${r.stale.length} stale, ${r.untracked.length} untracked, ${r.unverified.length} unverified.`);
         for (const s of r.stale)
             lines.push(`  ✗ STALE ${s.id}: ${s.query} (changed: ${s.staleFiles.join(", ") || "upstream memory"}) → ${s.action}`);
-        for (const u of r.untracked)
+        for (const u of stillUntracked)
             lines.push(`  ? UNTRACKED ${u.id}: ${u.query} → ${u.action}`);
         for (const u of r.unverified)
             lines.push(`  ? UNVERIFIED ${u.id}: ${u.query} → ${u.action}`);
+        if (anchored.length > 0) {
+            lines.push(`Auto-anchored ${anchored.length} untracked ${anchored.length === 1 ? "memory" : "memories"} → now verifiable${snapshotName ? ` (snapshot: ${snapshotName}; undo with brain_trash restore-snapshot)` : ""}:`);
+            for (const a of anchored) {
+                lines.push(`  ${a.ok ? "✔" : "✗"} ${a.id}: ${a.detail}`);
+            }
+        }
         if (report.duplicatePairs.length > 0) {
             lines.push(`Exact duplicates (${report.duplicatePairs.length}):`);
             for (const d of report.duplicatePairs) {
@@ -794,20 +859,38 @@ async function handleBrainUpkeep(args) {
 }
 async function handleRefreshMemory(args) {
     const id = args?.id;
-    if (!id)
-        throw new Error("id is required");
+    const ids = Array.isArray(args?.ids) ? args.ids.filter((v) => typeof v === "string" && v) : undefined;
+    if (!id && (!ids || ids.length === 0))
+        throw new Error("id or ids is required");
+    const formatOne = (oneId, result) => {
+        if (!result.ok)
+            return `${oneId}: ${result.message}`;
+        const retrackedNote = result.retracked && result.retracked.length > 0
+            ? `Now tracking: ${result.retracked.join(", ")}`
+            : "Tracks no files or symbols, so there was nothing to re-anchor — its age clock was reset.";
+        return `${result.message}\n${retrackedNote}`;
+    };
+    // A batch call re-hashes current tracking only — filePaths/symbols re-target a single
+    // memory's anchors and have no sensible meaning applied identically across several ids.
+    if (ids && ids.length > 0) {
+        const brain = getBrain();
+        const lines = ids.map((oneId) => {
+            try {
+                return formatOne(oneId, brain.refresh(oneId, {}));
+            }
+            catch (e) {
+                return `${oneId}: failed — ${e.message}`;
+            }
+        });
+        return { content: [{ type: "text", text: lines.join("\n\n") }] };
+    }
     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}` }] };
+        return { content: [{ type: "text", text: formatOne(id, result) }] };
     }
     catch (e) {
         logError("refresh_memory", e);
@@ -960,7 +1043,31 @@ async function handleVerifyMemory(args) {
         return { content: [{ type: "text", text: `Failed to verify memory: ${e.message}` }] };
     }
 }
+async function handleListMemories(args) {
+    // "" means "every project" — deriveProjectId() never returns "", so it can't collide
+    // with the default-to-current-project behavior below.
+    const projectId = args?.projectId === "" ? undefined : (typeof args?.projectId === "string" ? args.projectId : deriveProjectId());
+    const domain = typeof args?.domain === "string" && args.domain.trim() ? args.domain.trim() : undefined;
+    const outcome = args?.outcome === "confirmed" || args?.outcome === "failed" ? args.outcome : undefined;
+    const limit = typeof args?.limit === "number" ? args.limit : 25;
+    const offset = typeof args?.offset === "number" ? args.offset : 0;
+    try {
+        const { total, items } = getBrain().list({ projectId, domain, outcome, limit, offset });
+        if (items.length === 0) {
+            return { content: [{ type: "text", text: `No memories found for this filter (${total} total match before paging).` }] };
+        }
+        const lines = items.map((it) => `${it.id} (${it.timestamp}${it.domain ? `, domain: ${it.domain}` : ""}${it.outcome === "failed" ? ", FAILED" : ""}) ` +
+            `hits: ${it.hits}${it.tokensSaved ? `, tokensSaved: ${it.tokensSaved}` : ""}\n  ${it.query}`);
+        const pageNote = `Showing ${items.length} of ${total}${offset > 0 ? ` (offset ${offset})` : ""}.`;
+        return { content: [{ type: "text", text: `${pageNote}\n\n${lines.join("\n\n")}` }] };
+    }
+    catch (e) {
+        logError("list_memories", e);
+        return { content: [{ type: "text", text: `Failed to list memories: ${e.message}` }] };
+    }
+}
 export const MEMORY_TOOL_HANDLERS = {
+    list_memories: handleListMemories,
     search_memory: handleSearchMemory,
     get_memory: handleGetMemory,
     store_memory: handleStoreMemory,