@nxuss/lemma 1.23.0 → 1.24.1

package/dist/cjs/subconscious/TheBrainV2.js

@@ -331,6 +331,12 @@ function parseEntriesWithStats(raw) {
             // don't. Rebuilding from termFreq covers both without a migration step.
             if (!Array.isArray(entry.terms))
                 entry.terms = Object.keys(entry.termFreq || {});
+            // Entries written before clear-path persistence keep only hashes: backfill the
+            // labels from the hash keys so old memories become navigable on first read.
+            // Next save() persists the backfill — no separate migration step, no rewrite.
+            syncClearEvidencePaths(entry);
+            for (const claim of entry.claims || [])
+                syncClearEvidencePaths(claim);
             out.set(entry.id, entry);
         }
         catch {
@@ -1114,16 +1120,38 @@ function trackedClaimArtifactCount(claim) {
     return Object.keys(claim.fileHashes || {}).length + Object.keys(claim.symbolHashes || {}).length;
 }
 /** Builds the persisted `Claim[]` for an entry from the caller-supplied claim inputs. */
+/**
+ * Re-derive the clear-path labels from the hash keys they describe. One-way only:
+ * hashes are the source of truth, these fields are the navigable label. Called on
+ * every path that (re)writes evidence — store(), reanchorEvidence(), and the load
+ * backfill — so the three can never disagree about which file a memory means.
+ */
+function syncClearEvidencePaths(target) {
+    const files = target.fileHashes ? Object.keys(target.fileHashes).sort() : [];
+    if (files.length > 0)
+        target.filePaths = files;
+    else
+        delete target.filePaths;
+    const syms = target.symbolHashes ? Object.keys(target.symbolHashes).sort() : [];
+    if (syms.length > 0)
+        target.symbols = syms;
+    else
+        delete target.symbols;
+}
 function buildClaims(inputs) {
     return inputs
         .filter((c) => c?.text)
-        .map((c) => ({
-        id: crypto_1.default.createHash('sha1').update(c.text.trim().toLowerCase()).digest('hex').substring(0, 10),
-        text: c.text.trim(),
-        fileHashes: c.filePaths && c.filePaths.length > 0 ? hashFilesForFreshness(c.filePaths) : undefined,
-        symbolHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsForFreshness(c.symbols) : undefined,
-        symbolNormalizedHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsNormalizedForFreshness(c.symbols) : undefined,
-    }));
+        .map((c) => {
+        const claim = {
+            id: crypto_1.default.createHash('sha1').update(c.text.trim().toLowerCase()).digest('hex').substring(0, 10),
+            text: c.text.trim(),
+            fileHashes: c.filePaths && c.filePaths.length > 0 ? hashFilesForFreshness(c.filePaths) : undefined,
+            symbolHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsForFreshness(c.symbols) : undefined,
+            symbolNormalizedHashes: c.symbols && c.symbols.length > 0 ? hashSymbolsNormalizedForFreshness(c.symbols) : undefined,
+        };
+        syncClearEvidencePaths(claim);
+        return claim;
+    });
 }
 /**
  * Same hash-compare as checkEntryFreshness, scoped to one claim's own evidence — a claim
@@ -1352,6 +1380,22 @@ class TheBrainV2 {
                 this.save();
         }, 500);
     }
+    /**
+     * Synchronously persist pending writes, if any. The debounced scheduleSave() above
+     * is correct for a long-lived server but loses data when the process is about to
+     * die: one-shot clients (lemma-call, the Muse skill path) kill the MCP server right
+     * after the tool response, so without this every one-shot store/update/forget is
+     * silently dropped. Installed as a SIGTERM/SIGINT handler by the MCP bootstrap —
+     * never called on the hot path, where the debounce still applies.
+     */
+    flushSync() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.dirty)
+            this.save();
+    }
     save() {
         const fd = acquireLock();
         let wroteClean = false;
@@ -1575,6 +1619,9 @@ class TheBrainV2 {
             ...(git.commit ? { gitCommit: git.commit } : {}),
             ...(git.branch ? { gitBranch: git.branch } : {}),
         };
+        // Persist the tracked paths in clear next to the hashes (AN-03) — the labels
+        // display and navigation read from here; freshness keeps reading the hashes.
+        syncClearEvidencePaths(entry);
         this.entries.set(id, entry);
         // Update inverted index
         for (const term of entry.terms) {
@@ -1687,6 +1734,11 @@ class TheBrainV2 {
             const entry = this.entries.get(id);
             if (!entry)
                 continue;
+            // A superseded entry is a known-wrong conclusion with a named successor (AN-22) — it
+            // must never rank as if still live, unlike a downvote which only demotes. get_memory
+            // still resolves it directly and points at the successor; search() just never offers it.
+            if (entry.supersededBy)
+                continue;
             const bm25 = bm25Score(queryTerms, entry.termFreq, entry.terms.length, this.avgDocLength || 10, idf);
             const docTermSet = new Set(entry.terms);
             const jaccard = jaccardSimilarity(queryTermSet, docTermSet);
@@ -2470,6 +2522,11 @@ class TheBrainV2 {
                 }
             }
         }
+        // Hashes were just rewritten — re-derive the clear labels so they track the same
+        // files (covers both the re-point and the re-anchor branches above, and update()).
+        syncClearEvidencePaths(entry);
+        for (const claim of entry.claims || [])
+            syncClearEvidencePaths(claim);
         return retracked;
     }
     refresh(id, opts = {}) {
@@ -2521,6 +2578,16 @@ class TheBrainV2 {
         const entry = this.entries.get(id);
         if (!entry)
             return { ok: false, message: `No entry with id "${id}" in the Brain.` };
+        if (patch.supersededBy !== undefined) {
+            const successorId = patch.supersededBy.trim();
+            if (successorId && successorId === id) {
+                return { ok: false, message: `"${id}" cannot supersede itself.` };
+            }
+            if (successorId && !this.entries.has(successorId)) {
+                return { ok: false, message: `supersededBy target "${successorId}" is not an entry in the Brain — check the id with get_memory first.` };
+            }
+            entry.supersededBy = successorId || undefined;
+        }
         // Same one-way redaction as store(): a corrected response pasted with a fresh secret
         // must not be the one write path that persists credentials.
         let updateRedactions = 0;
@@ -3066,6 +3133,7 @@ class TheBrainV2 {
         let downvoted = 0;
         let unscoped = 0;
         let untracked = 0;
+        let withClearPaths = 0;
         let oldest = '';
         let totalTokensSaved = 0;
         const savers = [];
@@ -3082,6 +3150,9 @@ class TheBrainV2 {
                 projects.add(entry.projectId);
             if (trackedArtifactCount(entry) === 0)
                 untracked++;
+            else if (entry.filePaths !== undefined || entry.symbols !== undefined ||
+                (entry.claims || []).some((c) => c.filePaths !== undefined || c.symbols !== undefined))
+                withClearPaths++;
             if (entry.tokensSaved) {
                 totalTokensSaved += entry.tokensSaved;
                 savers.push({ id: entry.id, query: entry.query.slice(0, 80), tokensSaved: entry.tokensSaved, hits: entry.hits });
@@ -3102,6 +3173,7 @@ class TheBrainV2 {
         base.projects = projects.size;
         base.unscopedEntries = unscoped;
         base.untrackedEntries = untracked;
+        base.withClearPaths = withClearPaths;
         base.tombstones = this.tombstones.size;
         if (oldest)
             base.oldestEntry = oldest;