@nxuss/lemma 1.22.1 → 1.23.0

package/dist/esm/subconscious/TheBrainV2.js

@@ -16,6 +16,8 @@ import crypto from 'crypto';
 import { execSync } from 'child_process';
 import { LocalFsResolver } from './freshness/LocalFsResolver.js';
 import { EmbeddingSidecar, embeddingsEnabled, semanticRerank } from './BrainEmbeddings.js';
+import { scrubSecretsForStorage } from '../security/scrubForStorage.js';
+import { BRAIN_ENC_MAGIC, decryptEnvelope, encryptEnvelope, encryptionActive, resolveBrainKey, } from './BrainEncryption.js';
 /**
  * Default resolver for the local MCP path. Behaviour is byte-for-byte identical to
  * the pre-refactor inline `fs.readFileSync` hashing — it never returns `null`, so
@@ -75,13 +77,20 @@ const LOCK_FILE = path.join(BRAIN_DIR, '.write.lock');
 /** Sidecar vector cache for the optional semantic re-rank. See BrainEmbeddings.ts. */
 const EMBEDDINGS_FILE = path.join(BRAIN_DIR, 'embeddings.ndjson');
 /**
- * Append-only archive of everything forget() destroyed. Deletion is the one Brain operation
- * with no undo, and the deleted body is by definition the only copy of that text — telling the
- * caller "nothing else can recover it" and then handing back metadata only is the worst of both
- * worlds. The id stays tombstoned (a deliberate deletion must not come back through a merge),
- * so this file is an archive to read, not a bundle to re-import.
+ * The trash: an append-only archive of everything forget() removed, and the restore path
+ * for it (see restoreForgotten/purgeForgotten). The id stays tombstoned (a deliberate
+ * deletion must not come back through a merge), so this file is read as history and
+ * restored from by id — never re-imported as a bundle.
  */
 const FORGOTTEN_FILE = path.join(BRAIN_DIR, 'forgotten.ndjson');
+/** Whole-file sha256 of entries.ndjson, written alongside it on every save. */
+const ENTRIES_SHA_FILE = `${ENTRIES_FILE}.sha256`;
+/** Last known-good copy of entries.ndjson, rotated on every clean save. */
+const ENTRIES_PREV_FILE = `${ENTRIES_FILE}.prev`;
+/** Timestamped full-corpus copies taken before destructive operations. See snapshotCorpus(). */
+const SNAP_DIR = path.join(BRAIN_DIR, 'snapshots');
+/** How many snapshots to keep — a rollback history, not an archive. */
+const MAX_SNAPSHOTS = 10;
 // ─── Cross-process durability ─────────────────────────────────────────────────
 //
 // Every MCP client session starts its own server process, and each one holds the whole
@@ -176,6 +185,95 @@ function writeFileAtomic(target, data) {
         throw err;
     }
 }
+/**
+ * Disk protection: every byte that reaches the corpus files passes through protectForDisk
+ * (encrypted when a key resolves, plaintext otherwise), and every byte read back passes
+ * through unprotectFromDisk. An envelope without a resolvable key — or one that fails
+ * authentication — returns null, which the checked loader treats exactly like corruption:
+ * fall back, never serve half a corpus.
+ */
+function protectForDisk(plain) {
+    const key = brainDiskKey();
+    return key ? encryptEnvelope(key, plain) : plain;
+}
+function unprotectFromDisk(stored) {
+    if (!stored.startsWith(BRAIN_ENC_MAGIC))
+        return stored;
+    const key = brainDiskKey();
+    if (!key)
+        return null;
+    return decryptEnvelope(key, stored);
+}
+/**
+ * Process-wide data key, resolved once from env/key-file (see BrainEncryption) and
+ * validated eagerly by the constructor — a malformed key configuration fails loud at
+ * startup, never as silent plaintext mid-session.
+ */
+let cachedDiskKey = undefined;
+function brainDiskKey() {
+    if (cachedDiskKey === undefined)
+        cachedDiskKey = resolveBrainKey(BRAIN_DIR);
+    return cachedDiskKey;
+}
+/** Test seam: drop the cached key so a test can rotate env/key-file mid-process. */
+export function resetBrainKeyCache() {
+    cachedDiskKey = undefined;
+}
+function sha256hex(text) {
+    return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/**
+ * Read a corpus file with whole-file verification. No sidecar hash (files written before
+ * this existed) means legacy trust: parse it as before. A sidecar mismatch means the file
+ * changed outside a save() — bitrot, a killed process mid-rename, a foreign write — and
+ * the raw bytes still come back (verified:false) so the caller can salvage intact lines;
+ * only an unreadable or absent file comes back with text:null.
+ */
+function readStoredText(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return { text: null, verified: true, present: false }; // absent file: nothing to distrust
+    }
+    let expected = null;
+    try {
+        expected = fs.readFileSync(`${file}.sha256`, 'utf8').trim() || null;
+    }
+    catch { /* legacy file without a sidecar */ }
+    if (!expected)
+        return { text: raw, verified: true, present: true };
+    return sha256hex(raw) === expected
+        ? { text: raw, verified: true, present: true }
+        : { text: raw, verified: false, present: true };
+}
+/** Move an untrustworthy corpus file aside instead of deleting it — it may hold recoverable text. */
+function quarantineFile(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        const dest = path.join(path.dirname(file), `corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}.ndjson`);
+        fs.renameSync(file, dest);
+        try {
+            fs.unlinkSync(`${file}.sha256`);
+        }
+        catch { /* sidecar already describes garbage */ }
+        return dest;
+    }
+    catch {
+        return null;
+    }
+}
+/** Names of rollback snapshots on disk, newest last. */
+export function listSnapshotNames() {
+    try {
+        return fs.readdirSync(SNAP_DIR).filter((n) => n.endsWith('.ndjson')).sort();
+    }
+    catch {
+        return [];
+    }
+}
 function stampOf(file) {
     try {
         const s = fs.statSync(file);
@@ -190,32 +288,125 @@ function sameStamp(a, b) {
         return a === b;
     return a.mtimeMs === b.mtimeMs && a.size === b.size;
 }
-/** Parses entries.ndjson exactly the way load() does, without touching instance state. */
-function readEntriesFile() {
+/** Parse NDJSON corpus text into entries, counting skipped lines. Pure: no filesystem. */
+function parseEntriesWithStats(raw) {
     const out = new Map();
-    let raw;
-    try {
-        raw = fs.readFileSync(ENTRIES_FILE, 'utf8');
-    }
-    catch {
-        return out;
-    }
+    let skipped = 0;
     for (const line of raw.split('\n')) {
         if (!line)
             continue;
         try {
             const entry = JSON.parse(line);
-            if (!entry || typeof entry.id !== 'string')
+            if (!entry || typeof entry.id !== 'string') {
+                skipped++;
                 continue;
+            }
             // Entries written before the format was compacted still carry `terms`; newer ones
             // don't. Rebuilding from termFreq covers both without a migration step.
             if (!Array.isArray(entry.terms))
                 entry.terms = Object.keys(entry.termFreq || {});
             out.set(entry.id, entry);
         }
-        catch { /* skip corrupt lines */ }
+        catch {
+            skipped++;
+        }
     }
-    return out;
+    return { entries: out, skipped };
+}
+/** Parse NDJSON corpus text into entries, skipping corrupt lines. Pure: no filesystem. */
+function parseEntriesText(raw) {
+    return parseEntriesWithStats(raw).entries;
+}
+/** Parses entries.ndjson exactly the way load() does, without touching instance state. */
+function readEntriesFile() {
+    try {
+        return parseEntriesText(fs.readFileSync(ENTRIES_FILE, 'utf8'));
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * Load the corpus with verification and graceful degradation. Policy, in order:
+ *
+ * 1. Verified file (or legacy file without a sidecar): serve everything, no incident.
+ * 2. Changed out-of-band but with intact lines: serve the survivors and record a
+ *    `partial-corpus` incident — discarding good memories because one line rotted would
+ *    be worse than the rot. The next save() rewrites the file clean and heals this.
+ * 3. Total loss (nothing parses, or the envelope won't decrypt): fall back to the .prev
+ *    backup, or start empty if there is none — quarantining the bad bytes either way
+ *    when asked, never deleting them.
+ * 4. No main file at all: a fresh canvas. The .prev backup is deliberately NOT consulted
+ *    here — absence of the corpus is a state (fresh install, clear()), not damage, and
+ *    resurrecting an old backup over it would undo exactly that.
+ *
+ * Only load() — the startup path — quarantines: a long-lived process that quarantined on
+ * every racing read could destroy the corpus a concurrent writer is mid-merge on. save()
+ * and syncIfChanged() record the issue and heal on their own terms instead.
+ */
+function loadCorpusChecked(opts) {
+    const at = new Date().toISOString();
+    const main = readStoredText(ENTRIES_FILE);
+    if (!main.present || main.text === null) {
+        return { entries: new Map(), issue: null, diskUsable: true };
+    }
+    const plain = unprotectFromDisk(main.text);
+    const parsed = plain !== null ? parseEntriesWithStats(plain) : { entries: new Map(), skipped: Number.MAX_SAFE_INTEGER };
+    if (main.verified && plain !== null && parsed.skipped === 0) {
+        return { entries: parsed.entries, issue: null, diskUsable: true };
+    }
+    if (parsed.entries.size > 0) {
+        return {
+            entries: parsed.entries,
+            issue: {
+                at,
+                file: ENTRIES_FILE,
+                action: 'partial-corpus',
+                detail: plain === null
+                    ? 'entries.ndjson could not be decrypted with the available key; serving intact lines only.'
+                    : `entries.ndjson changed outside a save() (${parsed.skipped} unreadable line(s) skipped); serving the intact entries. The next save rewrites the file clean.`,
+            },
+            diskUsable: true,
+        };
+    }
+    // Total loss: fall back to the backup, which has no sidecar of its own — acceptance is
+    // parse-ability, and a backup that parses to entries is strictly better than bytes that
+    // verify to nothing.
+    let prevEntries = null;
+    try {
+        const prevRaw = fs.readFileSync(ENTRIES_PREV_FILE, 'utf8');
+        const prevPlain = unprotectFromDisk(prevRaw);
+        if (prevPlain !== null) {
+            const prevParsed = parseEntriesText(prevPlain);
+            if (prevParsed.size > 0)
+                prevEntries = prevParsed;
+        }
+    }
+    catch { /* no usable backup */ }
+    if (opts.quarantine)
+        quarantineFile(ENTRIES_FILE);
+    if (prevEntries) {
+        return {
+            entries: prevEntries,
+            issue: {
+                at,
+                file: ENTRIES_FILE,
+                action: 'fallback-to-backup',
+                detail: 'entries.ndjson is entirely unreadable; serving the last known-good backup instead. The bad file was quarantined, not deleted.',
+            },
+            diskUsable: true,
+        };
+    }
+    return {
+        entries: new Map(),
+        issue: {
+            at,
+            file: ENTRIES_FILE,
+            action: 'fresh-start',
+            detail: 'entries.ndjson is entirely unreadable and no usable backup exists; starting empty. The bad file was quarantined, not deleted.',
+        },
+        diskUsable: false,
+    };
 }
 /** Reads the tombstone map straight off disk, for absorbing a peer process's deletions. */
 function readTombstonesFile() {
@@ -264,11 +455,19 @@ export function mergeEntryMaps(mine, theirs, tombstones = new Set()) {
             return;
         }
         const winner = effectiveTime(entry) > effectiveTime(existing) ? entry : existing;
-        merged.set(entry.id, {
+        const mergedEntry = {
             ...winner,
             hits: Math.max(entry.hits || 0, existing.hits || 0),
             demerits: Math.max(entry.demerits || 0, existing.demerits || 0),
-        });
+        };
+        // ROI is a monotonic tally like hits: keep the best either side collected, and keep
+        // the field absent (not zero) when neither side ever saved anything.
+        const bestSavings = Math.max(entry.tokensSaved || 0, existing.tokensSaved || 0);
+        if (bestSavings > 0)
+            mergedEntry.tokensSaved = bestSavings;
+        else
+            delete mergedEntry.tokensSaved;
+        merged.set(entry.id, mergedEntry);
     };
     for (const entry of mine.values())
         put(entry);
@@ -975,6 +1174,13 @@ export class TheBrainV2 {
         this.diskStamp = null;
         /** id -> ISO deletion time, for ids that must not come back through a merge. */
         this.tombstones = new Map();
+        /**
+         * Last integrity incident on the corpus files (corrupt main file, undecryptable
+         * envelope, skipped sync). Set by load()/save()/syncIfChanged(), never cleared
+         * except by a clean verified read — health() and brain_stats surface it so a silent
+         * fallback never looks like a healthy Brain.
+         */
+        this.integrityIssue = null;
         /**
          * id -> terms of that entry's own `query` field. Derived state, never persisted: `terms`
          * covers query+response together, so scoring the query field on its own (see the
@@ -986,6 +1192,10 @@ export class TheBrainV2 {
         this.queryTermCache = new Map();
         this.sidecar = null;
         this.ensureDir();
+        // Validate key configuration before touching the corpus: a malformed LEMMA_BRAIN_KEY
+        // or corrupt key file throws here, loud, instead of degrading into silent plaintext
+        // (or an unreadable corpus) mid-session.
+        brainDiskKey();
         this.load();
     }
     ensureDir() {
@@ -1003,7 +1213,12 @@ export class TheBrainV2 {
                 this.avgDocLength = meta.avgDocLength || 0;
                 this.tombstones = readTombstones(meta);
             }
-            this.entries = readEntriesFile();
+            // Checked: a corrupt main file falls back to the .prev backup (quarantining the
+            // bad bytes) instead of silently starting empty and letting the next save()
+            // legitimize the data loss with a fresh sidecar hash.
+            const checked = loadCorpusChecked({ quarantine: true });
+            this.integrityIssue = checked.issue;
+            this.entries = checked.entries;
             for (const id of this.tombstones.keys())
                 this.entries.delete(id);
             this.diskStamp = stampOf(ENTRIES_FILE);
@@ -1064,10 +1279,23 @@ export class TheBrainV2 {
             return;
         try {
             this.absorbPeerTombstones();
-            const onDisk = readEntriesFile();
+            // No quarantine here (see loadCorpusChecked): a mismatch on a live read is most
+            // likely a racing writer, so record it, keep serving memory, and let save()/load()
+            // do the healing. The stamp still advances — re-reading the same bad bytes on
+            // every search would turn one incident into a permanent slowdown.
+            const checked = loadCorpusChecked({ quarantine: false });
+            if (checked.issue) {
+                this.integrityIssue = { ...checked.issue, action: 'sync-skipped' };
+                this.diskStamp = stamp;
+                return;
+            }
+            const onDisk = checked.entries;
             const before = this.entries.size;
             this.entries = mergeEntryMaps(this.entries, onDisk, new Set(this.tombstones.keys()));
             this.diskStamp = stamp;
+            // A clean verified read heals a previously recorded incident — the next save()
+            // rewrites the sidecar, so whatever was wrong is gone, not just unnoticed.
+            this.integrityIssue = null;
             if (this.entries.size !== before || onDisk.size > 0) {
                 this.rebuildIndex();
                 this.recalcAvgDocLength();
@@ -1099,6 +1327,7 @@ export class TheBrainV2 {
     }
     save() {
         const fd = acquireLock();
+        let wroteClean = false;
         try {
             this.ensureDir();
             // Merge before writing. A full rewrite of what this process happens to hold would
@@ -1106,8 +1335,15 @@ export class TheBrainV2 {
             // this whole section exists to close. After the merge the file we write is a superset
             // of both views, so a writer can only ever add.
             this.absorbPeerTombstones();
-            const onDisk = readEntriesFile();
-            if (onDisk.size > 0) {
+            const checked = loadCorpusChecked({ quarantine: false });
+            if (checked.issue) {
+                // The file on disk doesn't verify. Merge only what the fallback recovered (the
+                // backup, never the corrupt bytes), surface the issue, and — critically — do NOT
+                // rotate .prev below: the corrupt main file must not become the "last good" copy.
+                this.integrityIssue = checked.issue;
+            }
+            const onDisk = checked.issue && checked.issue.action === 'fresh-start' ? new Map() : checked.entries;
+            if (checked.diskUsable && onDisk.size > 0) {
                 this.entries = mergeEntryMaps(this.entries, onDisk, new Set(this.tombstones.keys()));
                 this.rebuildIndex();
                 this.recalcAvgDocLength();
@@ -1116,13 +1352,39 @@ export class TheBrainV2 {
             // Post-merge, so the file we write respects the cap even when the merge pulled in
             // entries a peer had already evicted.
             this.evictIfOverCapacity();
+            // Total loss on disk (nothing parseable, or an envelope this key cannot open):
+            // preserve those bytes before overwriting. They may be a corpus under a different
+            // key, and an overwrite is forever while a quarantine is a rename. No-op when
+            // load() already quarantined them at startup.
+            if (checked.issue && (checked.issue.action === 'fresh-start' || checked.issue.action === 'fallback-to-backup')) {
+                quarantineFile(ENTRIES_FILE);
+            }
+            // Rotate the backup BEFORE overwriting, but only when the file being replaced is
+            // itself trustworthy — rotating a corrupt file would destroy the last good copy.
+            if (!checked.issue) {
+                try {
+                    if (fs.existsSync(ENTRIES_FILE))
+                        fs.copyFileSync(ENTRIES_FILE, ENTRIES_PREV_FILE);
+                }
+                catch { /* backup rotation is best-effort; the write below is what matters */ }
+            }
             // Write NDJSON entries. `terms` is dropped: it is exactly Object.keys(termFreq),
             // and persisting both made the entry file 38% redundant bytes that every session
             // re-read at startup. load() reconstructs it.
             const ndjson = Array.from(this.entries.values())
                 .map(({ terms: _terms, ...persisted }) => JSON.stringify(persisted))
                 .join('\n');
-            writeFileAtomic(ENTRIES_FILE, ndjson);
+            const stored = protectForDisk(ndjson);
+            writeFileAtomic(ENTRIES_FILE, stored);
+            // Sidecar hash over the exact bytes on disk, so any out-of-band change fails the
+            // next checked read instead of being served as corpus.
+            try {
+                writeFileAtomic(ENTRIES_SHA_FILE, sha256hex(stored));
+                // Whatever was wrong before is gone: what is on disk now is exactly this
+                // process's verified corpus, so a recorded incident must not linger past it.
+                wroteClean = true;
+            }
+            catch { /* an unverified corpus still beats no corpus */ }
             // Write inverted index. load() rebuilds this from the entries rather than reading it
             // back, so it is now purely an inspection artifact for the dashboard and for anyone
             // poking at the brain directory — kept because removing a file other tooling may read
@@ -1147,6 +1409,8 @@ export class TheBrainV2 {
         finally {
             releaseLock(fd);
         }
+        if (wroteClean)
+            this.integrityIssue = null;
     }
     /**
      * Pull in deletions made by other processes.
@@ -1204,6 +1468,22 @@ export class TheBrainV2 {
         // Another session may have stored this exact thing since we loaded; without the sync
         // the dedup check below would miss it and write a second copy.
         this.syncIfChanged();
+        // Secrets never reach the corpus: redact before dedup, indexing, and persistence
+        // alike, so the inverted index and the NDJSON see only the redacted text. Two fixes
+        // differing only in their pasted API keys correctly dedup to one entry afterwards.
+        const scrubbedQuery = scrubSecretsForStorage(query);
+        const scrubbedResponse = scrubSecretsForStorage(response);
+        query = scrubbedQuery.text;
+        response = scrubbedResponse.text;
+        let redactions = scrubbedQuery.redactions + scrubbedResponse.redactions;
+        let scrubbedClaims = claimInputs;
+        if (claimInputs && claimInputs.length > 0) {
+            scrubbedClaims = claimInputs.map((c) => {
+                const s = scrubSecretsForStorage(c.text);
+                redactions += s.redactions;
+                return s.redactions > 0 ? { ...c, text: s.text } : c;
+            });
+        }
         // Quick bloom check
         const queryKey = query.trim().toLowerCase().substring(0, 200);
         if (this.bloom.has(queryKey)) {
@@ -1214,6 +1494,7 @@ export class TheBrainV2 {
                     stored: false,
                     reason: `Duplicate detected (${(existing[0].similarity * 100).toFixed(1)}% similar)`,
                     duplicate: existing[0],
+                    redactions,
                 };
             }
         }
@@ -1221,24 +1502,10 @@ export class TheBrainV2 {
         // outcome, is worth flagging before this one is even written — two memories about one
         // function disagreeing on whether an approach works is a trap for whoever searches next.
         // Not a block, just a warning: the newer entry may legitimately supersede the older one.
-        let conflicts;
-        if (symbolRefs && symbolRefs.length > 0) {
-            const newKeys = new Set(symbolRefs.map((r) => `${path.resolve(r.filePath)}::${r.symbolName}`));
-            const newOutcome = outcome === 'failed' ? 'failed' : 'confirmed';
-            const found = [];
-            for (const existingEntry of this.entries.values()) {
-                if (!existingEntry.symbolHashes)
-                    continue;
-                const existingOutcome = existingEntry.outcome === 'failed' ? 'failed' : 'confirmed';
-                if (existingOutcome === newOutcome)
-                    continue;
-                const sharesSymbol = Object.keys(existingEntry.symbolHashes).some((k) => newKeys.has(k));
-                if (sharesSymbol)
-                    found.push({ id: existingEntry.id, query: existingEntry.query, outcome: existingOutcome });
-            }
-            if (found.length > 0)
-                conflicts = found;
-        }
+        const foundConflicts = symbolRefs && symbolRefs.length > 0
+            ? this.findOutcomeConflicts(symbolRefs, outcome === 'failed' ? 'failed' : 'confirmed')
+            : [];
+        const conflicts = foundConflicts.length > 0 ? foundConflicts : undefined;
         const terms = tokenize(query + ' ' + response);
         const termFreq = termFrequencies(terms);
         // Salted with random bytes, not just the clock: the id used to be sha1(queryKey + now),
@@ -1273,7 +1540,8 @@ export class TheBrainV2 {
                 (symbolRefs && symbolRefs.length > 0 ? hashSymbolsForFreshness(symbolRefs) : undefined),
             symbolNormalizedHashes: options.evidence?.symbolsNormalized ??
                 (symbolRefs && symbolRefs.length > 0 ? hashSymbolsNormalizedForFreshness(symbolRefs) : undefined),
-            claims: claimInputs && claimInputs.length > 0 ? buildClaims(claimInputs) : undefined,
+            claims: scrubbedClaims && scrubbedClaims.length > 0 ? buildClaims(scrubbedClaims) : undefined,
+            ...(redactions > 0 ? { redactions } : {}),
             domain,
             derivedFrom: derivedFrom && derivedFrom.length > 0 ? derivedFrom : undefined,
             source: options.source || 'manual',
@@ -1293,7 +1561,7 @@ export class TheBrainV2 {
         this.recalcAvgDocLength();
         this.evictIfOverCapacity();
         this.scheduleSave();
-        return { stored: true, reason: 'Stored successfully', id, conflicts };
+        return { stored: true, reason: 'Stored successfully', id, conflicts, redactions };
     }
     /**
      * Evict the lowest-value entries once the Brain is over capacity. Value = hits (proven
@@ -1425,25 +1693,41 @@ export class TheBrainV2 {
             let similarity = exactPrompt
                 ? 1
                 : (s.bm25 / maxBm25) * BM25_WEIGHT + s.jaccard * JACCARD_WEIGHT + queryFieldMatch * QUERY_FIELD_WEIGHT;
+            // whyShown: the human-readable half of the adjustments below. A memory the caller
+            // can't audit is a memory the caller can't trust — and a downvote without a visible
+            // reason teaches the ranker nothing. Only signals that actually fired are listed.
+            const whyShown = [];
+            if (exactPrompt)
+                whyShown.push('exact-prompt-match');
             // Popularity prior: entries other searches actually reused are more likely to be
             // reused again. Log-scaled and capped at +0.08 so a handful of hits can't outrank a
             // much better textual match.
-            similarity += Math.min(Math.log2(s.entry.hits + 1) * 0.02, 0.08);
+            const popularityBonus = Math.min(Math.log2(s.entry.hits + 1) * 0.02, 0.08);
+            similarity += popularityBonus;
+            if (s.entry.hits > 0)
+                whyShown.push(`reused ${s.entry.hits}x (+${popularityBonus.toFixed(2)})`);
             // A documented dead end ranking above a working fix is actively harmful — it reads as
             // a suggestion even with the "STALE"/"FAILED" label attached downstream. Demote, don't
             // hide: the warning is still worth surfacing, just not first.
-            if (s.entry.outcome === 'failed')
+            if (s.entry.outcome === 'failed') {
                 similarity -= 0.15;
+                whyShown.push('failed-attempt (-0.15)');
+            }
             // Soft domain preference (see projectId scoping above for why this stays soft): an
             // entry tagged with the requested domain is more likely relevant, but an untagged or
             // cross-domain entry may still be the right answer.
-            if (options.domain && s.entry.domain === options.domain)
+            if (options.domain && s.entry.domain === options.domain) {
                 similarity += 0.05;
+                whyShown.push(`domain '${options.domain}' match (+0.05)`);
+            }
             // Explicit negative feedback from downvote() — a caller saying "this was wrong" is a
             // stronger, more deliberate signal than the absence of hits, so it outweighs the
             // popularity prior above rather than just canceling it out.
-            if (s.entry.demerits)
-                similarity -= Math.min(s.entry.demerits * 0.06, 0.25);
+            if (s.entry.demerits) {
+                const demeritPenalty = Math.min(s.entry.demerits * 0.06, 0.25);
+                similarity -= demeritPenalty;
+                whyShown.push(`downvoted x${s.entry.demerits} (-${demeritPenalty.toFixed(2)})`);
+            }
             // Age decay. Every other signal here is about the memory's track record; none of them
             // notice that the codebase it describes has been rewritten twice since. A confirmed
             // memory from a year ago is not as likely to be current as yesterday's, and until now
@@ -1452,9 +1736,20 @@ export class TheBrainV2 {
             // which is the point of refresh(): a re-verified memory really is current again.
             const ageDays = (Date.now() - effectiveTime(s.entry)) / 86400000;
             if (Number.isFinite(ageDays) && ageDays > RECENCY_GRACE_DAYS) {
-                similarity -= Math.min((ageDays - RECENCY_GRACE_DAYS) / RECENCY_FULL_DECAY_DAYS, 1) * MAX_RECENCY_PENALTY;
+                const agePenalty = Math.min((ageDays - RECENCY_GRACE_DAYS) / RECENCY_FULL_DECAY_DAYS, 1) * MAX_RECENCY_PENALTY;
+                similarity -= agePenalty;
+                whyShown.push(`age ${Math.floor(ageDays)}d (-${agePenalty.toFixed(2)})`);
             }
-            return { entry: s.entry, similarity: Math.max(0, similarity) };
+            if (s.entry.refreshedAt)
+                whyShown.push(`re-verified ${s.entry.refreshedAt.slice(0, 10)}`);
+            // Evidence the freshness verdict was judged against: absolute tracked paths and
+            // path::symbol keys. Handlers relativize these for display; the Brain keeps them
+            // absolute because cwd is a caller-side notion.
+            const evidence = [
+                ...Object.keys(s.entry.fileHashes || {}),
+                ...Object.keys(s.entry.symbolHashes || {}),
+            ];
+            return { entry: s.entry, similarity: Math.max(0, similarity), whyShown, evidence };
         });
         // 6. Sort and filter
         combined.sort((a, b) => b.similarity - a.similarity);
@@ -1480,6 +1775,10 @@ export class TheBrainV2 {
                 provider: r.entry.provider,
                 timestamp: r.entry.timestamp,
                 fresh,
+                ...(r.entry.hits ? { hits: r.entry.hits } : {}),
+                ...(r.entry.tokensSaved ? { tokensSaved: r.entry.tokensSaved } : {}),
+                ...(r.whyShown.length > 0 ? { whyShown: r.whyShown } : {}),
+                ...(r.evidence.length > 0 ? { evidence: r.evidence } : {}),
                 ...(fresh ? {} : { staleFiles, ...(unverified ? {} : attributeStaleness(r.entry, git)) }),
                 ...(unverifiedFiles.length > 0 ? { unverifiedFiles } : {}),
                 ...(r.entry.outcome ? { outcome: r.entry.outcome } : {}),
@@ -1575,6 +1874,28 @@ export class TheBrainV2 {
     getEntriesForProject(projectId) {
         return Array.from(this.entries.values()).filter((e) => e.projectId === undefined || e.projectId === projectId);
     }
+    /**
+     * Opposite-outcome entries tracking any of these symbols. Shared by store() (warn before
+     * writing) and previewImport() (warn before importing): two memories about one function
+     * disagreeing on whether an approach works is a trap for whoever searches next.
+     */
+    findOutcomeConflicts(symbolRefs, outcome, excludeIds = new Set()) {
+        const newKeys = new Set(symbolRefs.map((r) => `${path.resolve(r.filePath)}::${r.symbolName}`));
+        const found = [];
+        for (const existingEntry of this.entries.values()) {
+            if (excludeIds.has(existingEntry.id))
+                continue;
+            if (!existingEntry.symbolHashes)
+                continue;
+            const existingOutcome = existingEntry.outcome === 'failed' ? 'failed' : 'confirmed';
+            if (existingOutcome === outcome)
+                continue;
+            const sharesSymbol = Object.keys(existingEntry.symbolHashes).some((k) => newKeys.has(k));
+            if (sharesSymbol)
+                found.push({ id: existingEntry.id, query: existingEntry.query, outcome: existingOutcome });
+        }
+        return found;
+    }
     // ─── Dedup Check ─────────────────────────────────────────────────────────
     /**
      * Check if a query is likely a duplicate before storing.
@@ -1652,7 +1973,44 @@ export class TheBrainV2 {
         this.scheduleSave();
         return { ok: true, message: `Recorded negative feedback on entry "${id}" (demerits: ${entry.demerits}). It will rank lower and be evicted sooner.` };
     }
+    /**
+     * Book tokens saved by reusing a memory, called by search_memory on a fresh hit — the
+     * same event that books the savings ledger, so the two can never disagree about
+     * whether a reuse happened. Unknown ids fail silently (a peer may have forgotten the
+     * entry since the search ranked it); savings attribution must never break a search.
+     */
+    creditSavings(id, tokens) {
+        if (!Number.isFinite(tokens) || tokens <= 0)
+            return;
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        entry.tokensSaved = (entry.tokensSaved || 0) + Math.floor(tokens);
+        this.scheduleSave();
+    }
     // ─── Deletion ───────────────────────────────────────────────────────────────
+    /**
+     * Archive one entry to the trash, drop it from the corpus, and tombstone the id so no
+     * merge resurrects it. Shared by forget() (one memory) and mergeEntries() (folded
+     * fragments). Returns whether the archive write succeeded — a failure never blocks the
+     * removal itself, it only narrows the restore paths.
+     */
+    dropWithArchive(entry) {
+        try {
+            this.ensureDir();
+            const { terms: _terms, ...persisted } = entry;
+            fs.appendFileSync(FORGOTTEN_FILE, JSON.stringify({ ...persisted, forgottenAt: new Date().toISOString() }) + '\n', 'utf8');
+        }
+        catch {
+            // An unwritable trash must not block a removal the caller asked for.
+            this.dropEntry(entry);
+            this.tombstone(entry.id);
+            return false;
+        }
+        this.dropEntry(entry);
+        this.tombstone(entry.id);
+        return true;
+    }
     /**
      * Permanently remove one memory.
      *
@@ -1672,21 +2030,13 @@ export class TheBrainV2 {
         const entry = this.entries.get(id);
         if (!entry)
             return { ok: false, message: `No entry with id "${id}" in the Brain.` };
+        // Snapshot BEFORE destroying: forget() with no restore point is exactly the data-loss
+        // story snapshots exist to prevent.
+        this.snapshotCorpus('forget');
         // Archived before it is dropped: the body is the only copy of that text anywhere, and
-        // "nothing else can recover it" has to be a description of the archive, not of a gap.
-        let archivePath;
-        try {
-            this.ensureDir();
-            const { terms: _terms, ...persisted } = entry;
-            fs.appendFileSync(FORGOTTEN_FILE, JSON.stringify({ ...persisted, forgottenAt: new Date().toISOString() }) + '\n', 'utf8');
-            archivePath = FORGOTTEN_FILE;
-        }
-        catch {
-            // An unwritable archive must not block a deletion the user asked for — the body still
-            // comes back in the result below, which is the copy that matters in the moment.
-        }
-        this.dropEntry(entry);
-        this.tombstone(id);
+        // the trash is what makes this deletion restorable.
+        const archived = this.dropWithArchive(entry);
+        const archivePath = archived ? FORGOTTEN_FILE : undefined;
         this.recalcAvgDocLength();
         this.scheduleSave();
         return {
@@ -1700,6 +2050,320 @@ export class TheBrainV2 {
             ...(archivePath ? { archivePath } : {}),
         };
     }
+    // ─── Consolidation ──────────────────────────────────────────────────────────
+    //
+    // Long-lived Brains accumulate near-duplicate fragments about the same topic — each
+    // stored in a different session, each partially overlapping. findMergeCandidates()
+    // finds the pairs; this folds them: every folded fragment becomes a claim on the
+    // keeper (carrying its own evidence, so per-claim freshness survives the merge), the
+    // keeper inherits the counters, and the fragments leave through the same trash door
+    // as forget(). The keeper's own text is untouched — merging rewrites nothing, it only
+    // attaches.
+    /**
+     * Fold entries into a keeper. All-or-nothing on validation (unknown keeper, unknown or
+     * repeated fragment, keeper listed as its own fragment all fail before anything
+     * changes), then one snapshot covers the whole operation.
+     */
+    mergeEntries(keepId, foldIds) {
+        this.syncIfChanged();
+        const keeper = this.entries.get(keepId);
+        if (!keeper)
+            return { ok: false, message: `No memory with id "${keepId}" in the Brain.` };
+        const folds = [...new Set(foldIds || [])].filter((id) => id !== keepId);
+        if (folds.length === 0) {
+            return { ok: false, message: `Nothing to fold into "${keepId}" — name at least one other memory id.` };
+        }
+        const missing = folds.filter((id) => !this.entries.has(id));
+        if (missing.length > 0) {
+            return { ok: false, message: `Cannot merge: ${missing.map((id) => `"${id}"`).join(', ')} ${missing.length === 1 ? 'is' : 'are'} not in the Brain. Nothing was changed.` };
+        }
+        this.snapshotCorpus('merge');
+        // Out of the index before mutating, same as update(): postings built from the old
+        // text would keep serving the keeper under words the merge removed.
+        this.dropEntry(keeper);
+        const newClaims = [];
+        for (const foldId of folds) {
+            const folded = this.entries.get(foldId);
+            newClaims.push({
+                id: crypto.createHash('sha1').update(`merge:${keepId}:${foldId}:${Date.now()}:${crypto.randomBytes(4).toString('hex')}`).digest('hex').substring(0, 10),
+                text: `[merged from ${foldId} — "${folded.query.slice(0, 120)}"] ${folded.response}`,
+                ...(folded.fileHashes ? { fileHashes: { ...folded.fileHashes } } : {}),
+                ...(folded.symbolHashes ? { symbolHashes: { ...folded.symbolHashes } } : {}),
+                ...(folded.symbolNormalizedHashes ? { symbolNormalizedHashes: { ...folded.symbolNormalizedHashes } } : {}),
+            });
+            keeper.hits += folded.hits || 0;
+            keeper.demerits = Math.max(keeper.demerits || 0, folded.demerits || 0);
+            keeper.tokensSaved = (keeper.tokensSaved || 0) + (folded.tokensSaved || 0);
+            if (keeper.tokensSaved === 0)
+                delete keeper.tokensSaved;
+            if (folded.redactions)
+                keeper.redactions = (keeper.redactions || 0) + folded.redactions;
+            keeper.mergedFrom = [...(keeper.mergedFrom || []), foldId];
+            // Folded fragments leave through the trash door: individually restorable, and the
+            // merge snapshot restores the pre-merge corpus wholesale. No per-fragment snapshot
+            // here — one snapshot already covers the operation.
+            this.dropWithArchive(folded);
+        }
+        keeper.claims = [...(keeper.claims || []), ...newClaims];
+        // The curator just reviewed this memory against the folded fragments: its age clock
+        // restarts, exactly as refresh() does after a human re-verification.
+        keeper.refreshedAt = new Date().toISOString();
+        const terms = tokenize(keeper.query + ' ' + keeper.response);
+        keeper.terms = [...new Set(terms)];
+        keeper.termFreq = termFrequencies(terms);
+        keeper.charCount = keeper.query.length + keeper.response.length;
+        this.entries.set(keepId, keeper);
+        for (const term of keeper.terms) {
+            let ids = this.invertedIndex.get(term);
+            if (!ids) {
+                ids = new Set();
+                this.invertedIndex.set(term, ids);
+            }
+            ids.add(keepId);
+        }
+        this.bloom.add(keeper.query.trim().toLowerCase().substring(0, 200));
+        this.recalcAvgDocLength();
+        this.scheduleSave();
+        return {
+            ok: true,
+            kept: keepId,
+            folded: folds,
+            claimsAdded: newClaims.length,
+            message: `Merged ${folds.length} ${folds.length === 1 ? 'fragment' : 'fragments'} into "${keepId}" as independently-verifiable claims (evidence carried over). The fragments are in the trash individually, and the pre-merge corpus is snapshotted — both undo paths work.`,
+        };
+    }
+    // ─── Rollback: snapshots + trash ──────────────────────────────────────────
+    //
+    // forget() used to be a one-way door with the archive as its only safety net, and
+    // import/clear had no net at all. Snapshots are automatic, timestamped, pruned full
+    // copies taken before every destructive operation; the trash (forgotten.ndjson) is the
+    // per-memory undo. Neither is consulted by freshness, ranking, or export — rollback
+    // state must never leak into retrieval.
+    /**
+     * Persist the current in-memory corpus as a timestamped snapshot. Best-effort and
+     * synchronous like save(): a failed snapshot must never block the operation it
+     * protects. Returns the snapshot name, or null when nothing was written.
+     */
+    snapshotCorpus(reason) {
+        try {
+            this.ensureDir();
+            fs.mkdirSync(SNAP_DIR, { recursive: true });
+            const safeReason = reason.replace(/[^a-z0-9-]+/gi, '-').slice(0, 24) || 'manual';
+            const name = `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}-${crypto.randomBytes(3).toString('hex')}-${safeReason}.ndjson`;
+            const ndjson = Array.from(this.entries.values())
+                .map(({ terms: _terms, ...persisted }) => JSON.stringify(persisted))
+                .join('\n');
+            writeFileAtomic(path.join(SNAP_DIR, name), protectForDisk(ndjson));
+            // Prune oldest, newest-last ordering: a rollback history, not an archive.
+            const names = listSnapshotNames();
+            for (const old of names.slice(0, Math.max(0, names.length - MAX_SNAPSHOTS))) {
+                try {
+                    fs.unlinkSync(path.join(SNAP_DIR, old));
+                }
+                catch { /* keep the rest */ }
+            }
+            return name;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Rollback points on disk, newest last: name, size, and modification time. */
+    listSnapshots() {
+        return listSnapshotNames().map((name) => {
+            try {
+                const st = fs.statSync(path.join(SNAP_DIR, name));
+                return { name, bytes: st.size, mtime: st.mtime.toISOString() };
+            }
+            catch {
+                return { name, bytes: 0, mtime: '' };
+            }
+        });
+    }
+    /**
+     * Replace the corpus with a snapshot. The current state is snapshotted first
+     * (`pre-restore`), so a restore is itself undoable. Deliberately does NOT tombstone
+     * the ids that vanish: a peer session holding unflushed memories would lose them on
+     * its next read, and "restore never destroys" beats "restore is total" — whatever a
+     * peer still holds comes back on its next flush, honestly, through the normal merge.
+     */
+    restoreSnapshot(name) {
+        if (typeof name !== 'string' || name.includes('/') || name.includes('\\') || !name.endsWith('.ndjson')) {
+            return { ok: false, message: `Refusing to read "${name}": not a snapshot name.` };
+        }
+        if (!listSnapshotNames().includes(name)) {
+            return { ok: false, message: `No snapshot named "${name}". Use brain_trash action=snapshots to list them.` };
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(SNAP_DIR, name), 'utf8');
+        }
+        catch {
+            return { ok: false, message: `Could not read snapshot "${name}".` };
+        }
+        const plain = unprotectFromDisk(raw);
+        if (plain === null) {
+            return { ok: false, message: `Snapshot "${name}" cannot be decrypted with the available key — refusing to wipe the live corpus for bytes I cannot read.` };
+        }
+        const { entries } = parseEntriesWithStats(plain);
+        if (entries.size === 0) {
+            return { ok: false, message: `Snapshot "${name}" parses to zero entries — refusing to replace a live corpus with an empty one.` };
+        }
+        this.syncIfChanged();
+        this.snapshotCorpus('pre-restore');
+        this.entries = entries;
+        this.rebuildIndex();
+        this.queryTermCache.clear();
+        this.recalcAvgDocLength();
+        // Fresh bloom: the filter cannot un-add the deleted queries, and a restored corpus
+        // with a stale filter would keep reporting ghosts as possible duplicates.
+        this.bloom = new BloomFilter();
+        for (const entry of this.entries.values()) {
+            this.bloom.add(entry.query.trim().toLowerCase().substring(0, 200));
+        }
+        // A restored id was deliberately brought back — its old tombstone must not suppress it.
+        for (const id of this.entries.keys())
+            this.tombstones.delete(id);
+        this.scheduleSave();
+        return { ok: true, restored: entries.size, message: `Restored ${entries.size} memories from snapshot "${name}". The pre-restore state was snapshotted, so this is undoable too.` };
+    }
+    /** What the trash holds: one row per archived deletion, newest last. */
+    listForgotten() {
+        const out = [];
+        let raw;
+        try {
+            raw = fs.readFileSync(FORGOTTEN_FILE, 'utf8');
+        }
+        catch {
+            return out;
+        }
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            try {
+                const archived = JSON.parse(line);
+                if (!archived || typeof archived.id !== 'string')
+                    continue;
+                out.push({
+                    id: archived.id,
+                    query: typeof archived.query === 'string' ? archived.query.slice(0, 120) : '',
+                    timestamp: archived.timestamp || '',
+                    hits: typeof archived.hits === 'number' ? archived.hits : 0,
+                    forgottenAt: archived.forgottenAt || '',
+                });
+            }
+            catch { /* a half-written archive line is not worth failing the listing */ }
+        }
+        return out;
+    }
+    /**
+     * Bring a forgotten memory back. The archived copy becomes a live entry again under its
+     * original id (so any external reference to the id keeps working), its old tombstone is
+     * lifted, and freshness is re-judged on the next search like any other entry. The
+     * archive line stays as history — the trash is append-only, restore doesn't rewrite it.
+     */
+    restoreForgotten(id) {
+        this.syncIfChanged();
+        if (this.entries.has(id)) {
+            return { ok: false, message: `Memory "${id}" is already in the Brain — nothing to restore.` };
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(FORGOTTEN_FILE, 'utf8');
+        }
+        catch {
+            return { ok: false, message: `The trash is empty — nothing to restore.` };
+        }
+        let found = null;
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            try {
+                const archived = JSON.parse(line);
+                if (archived && archived.id === id && typeof archived.query === 'string')
+                    found = archived;
+            }
+            catch { /* skip */ }
+        }
+        if (!found)
+            return { ok: false, message: `No forgotten memory with id "${id}" in the trash.` };
+        const { forgottenAt: _forgottenAt, ...revived } = found;
+        if (!Array.isArray(revived.terms))
+            revived.terms = Object.keys(revived.termFreq || {});
+        if (revived.terms.length === 0) {
+            const terms = tokenize(revived.query + ' ' + (revived.response || ''));
+            revived.terms = [...new Set(terms)];
+            revived.termFreq = termFrequencies(terms);
+        }
+        this.entries.set(id, revived);
+        for (const term of revived.terms) {
+            let ids = this.invertedIndex.get(term);
+            if (!ids) {
+                ids = new Set();
+                this.invertedIndex.set(term, ids);
+            }
+            ids.add(id);
+        }
+        this.bloom.add(revived.query.trim().toLowerCase().substring(0, 200));
+        this.tombstones.delete(id);
+        this.recalcAvgDocLength();
+        this.scheduleSave();
+        return { ok: true, message: `Restored memory "${id}" from the trash (${revived.hits || 0} prior reuse(s) kept). Its freshness will be re-judged on the next search.` };
+    }
+    /**
+     * Permanently drop archived deletions. Without a filter this empties the whole trash;
+     * with olderThanDays it keeps recent deletions restorable. Tombstones are untouched —
+     * purging the archive removes the restore path, not the deletion itself, so purged ids
+     * still cannot come back through a merge or an import.
+     */
+    purgeForgotten(olderThanDays) {
+        let raw = '';
+        try {
+            raw = fs.readFileSync(FORGOTTEN_FILE, 'utf8');
+        }
+        catch {
+            return { purged: 0, remaining: 0 };
+        }
+        const cutoff = typeof olderThanDays === 'number' && Number.isFinite(olderThanDays) && olderThanDays > 0
+            ? Date.now() - olderThanDays * 86400000
+            : null;
+        const kept = [];
+        let purged = 0;
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            let drop = false;
+            try {
+                const archived = JSON.parse(line);
+                if (!archived || typeof archived.id !== 'string')
+                    drop = true; // useless line, not a memory
+                else if (cutoff !== null) {
+                    const at = Date.parse(archived.forgottenAt || '');
+                    drop = Number.isFinite(at) && at < cutoff;
+                }
+                else
+                    drop = true;
+            }
+            catch {
+                drop = true; // half-written line: un-restorable, so purging loses nothing
+            }
+            if (drop)
+                purged++;
+            else
+                kept.push(line);
+        }
+        if (purged > 0) {
+            const fd = acquireLock();
+            try {
+                writeFileAtomic(FORGOTTEN_FILE, kept.join('\n') + (kept.length > 0 ? '\n' : ''));
+            }
+            catch { /* best-effort; counts below still report honestly */ }
+            finally {
+                releaseLock(fd);
+            }
+        }
+        return { purged, remaining: kept.length };
+    }
     // ─── Re-anchoring ───────────────────────────────────────────────────────────
     /**
      * Re-verify a memory against the code as it stands now, keeping its identity.
@@ -1830,6 +2494,28 @@ export class TheBrainV2 {
         const entry = this.entries.get(id);
         if (!entry)
             return { ok: false, message: `No entry with id "${id}" in the Brain.` };
+        // 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;
+        if (typeof patch.query === 'string' && patch.query) {
+            const s = scrubSecretsForStorage(patch.query);
+            patch.query = s.text;
+            updateRedactions += s.redactions;
+        }
+        if (typeof patch.response === 'string' && patch.response) {
+            const s = scrubSecretsForStorage(patch.response);
+            patch.response = s.text;
+            updateRedactions += s.redactions;
+        }
+        if (patch.claims !== undefined) {
+            patch.claims = patch.claims.map((c) => {
+                const s = scrubSecretsForStorage(c.text);
+                updateRedactions += s.redactions;
+                return s.redactions > 0 ? { ...c, text: s.text } : c;
+            });
+        }
+        if (updateRedactions > 0)
+            entry.redactions = (entry.redactions || 0) + updateRedactions;
         const beforeChars = entry.charCount;
         // Out of the index before its terms change: a posting list built from the old text would
         // keep serving this entry under words the new text no longer contains.
@@ -1955,6 +2641,126 @@ export class TheBrainV2 {
         this.syncIfChanged();
         return findBlastRadius(this.entries, filePath, symbolName);
     }
+    // ─── Upkeep: one command to tend the corpus ───────────────────────────────
+    //
+    // Every maintenance primitive existed (verify/refresh/forget/downvote/stats) but each
+    // one needed the agent to remember it, name an id, and interpret the result — so in
+    // practice nobody maintained anything and the corpus rotted by default. upkeep() inverts
+    // that: one call revalidates what gets reused most, surfaces duplicates and dead
+    // weight, and reports the savings ledger. It never deletes, merges, or refreshes
+    // anything itself — refresh() records a human assertion no automation can make, and a
+    // janitor that destroys memories on its own schedule is a data-loss vector, not care.
+    /**
+     * Near-duplicate entry pairs worth consolidating with brain_merge (see Fase E). Pairs
+     * at or above `hi` are excluded: those should have been refused at store time, so a
+     * surviving one is a `forget one of them` case, not a merge — report those separately
+     * via the same call with lo=hi. Bounded: at most `sample` entries each issue one
+     * search, and at most 20 pairs come back.
+     */
+    findMergeCandidates(opts = {}) {
+        const lo = opts.lo ?? 0.6;
+        const hi = opts.hi ?? 0.92;
+        const sample = Math.max(0, opts.sample ?? 100);
+        this.syncIfChanged();
+        const pool = Array.from(this.entries.values())
+            .sort((a, b) => (b.hits - a.hits) || (effectiveTime(b) - effectiveTime(a)))
+            .slice(0, sample);
+        const seen = new Set();
+        const out = [];
+        for (const entry of pool) {
+            // Internal sweep, not a question: must not move hit counters or the ledger.
+            const results = this.search(entry.query, 6, lo, { countStats: false });
+            for (const r of results) {
+                if (r.id === entry.id)
+                    continue;
+                if (r.similarity >= hi)
+                    continue;
+                const key = [entry.id, r.id].sort().join('|');
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const other = this.entries.get(r.id);
+                out.push({
+                    ids: [entry.id, r.id],
+                    similarity: Number(r.similarity.toFixed(3)),
+                    queries: [entry.query.slice(0, 100), (other?.query || '').slice(0, 100)],
+                });
+                if (out.length >= 20)
+                    return out;
+            }
+        }
+        return out;
+    }
+    /**
+     * Full upkeep pass. Read-only over the corpus: revalidates the top-N most-reused
+     * memories by hash-compare, lists exact duplicates and merge candidates, dead weight,
+     * and the savings ledger — with a concrete suggested action per finding.
+     */
+    upkeep(opts = {}) {
+        this.syncIfChanged();
+        const topN = Math.max(0, opts.topN ?? 20);
+        const top = Array.from(this.entries.values())
+            .sort((a, b) => (b.hits - a.hits) || (effectiveTime(b) - effectiveTime(a)))
+            .slice(0, topN);
+        const verdicts = this.verifyByIds(top.map((e) => e.id));
+        const queryOf = (id) => this.entries.get(id)?.query.slice(0, 100) || '';
+        const revalidated = { checked: top.length, fresh: [], stale: [], untracked: [], unverified: [] };
+        for (const v of verdicts) {
+            if (v.status === 'fresh')
+                revalidated.fresh.push(v.id);
+            else if (v.status === 'stale') {
+                revalidated.stale.push({ id: v.id, query: queryOf(v.id), staleFiles: v.staleFiles || [], action: 'refresh_memory after checking it is still true' });
+            }
+            else if (v.status === 'untracked') {
+                revalidated.untracked.push({ id: v.id, query: queryOf(v.id), action: 'update_memory with filePaths/symbols so it becomes verifiable' });
+            }
+            else if (v.status === 'unverified') {
+                revalidated.unverified.push({ id: v.id, query: queryOf(v.id), action: 'check the tracked paths exist on this machine, then refresh_memory' });
+            }
+        }
+        // Exact duplicates (>= store threshold) slipped in through imports or forced stores:
+        // merging paraphrases is brain_merge's job, but a 98%-identical pair just needs one
+        // of them forgotten.
+        const duplicatePairs = this.findMergeCandidates({ sample: opts.sample ?? 50, lo: 0.92, hi: 1.01 })
+            .map((c) => ({ ...c, action: 'forget_memory one of the pair (they are the same memory twice)' }));
+        const mergeCandidates = this.findMergeCandidates({ sample: opts.sample ?? 50, lo: 0.75, hi: 0.92 })
+            .map((c) => ({ ...c, action: 'brain_merge the pair into one canonical memory' }));
+        const neverHitIds = [];
+        const downvoted = [];
+        for (const entry of this.entries.values()) {
+            if (!entry.hits && neverHitIds.length < 10)
+                neverHitIds.push(entry.id);
+            if (entry.demerits)
+                downvoted.push({ id: entry.id, demerits: entry.demerits });
+        }
+        downvoted.sort((a, b) => b.demerits - a.demerits);
+        const stats = this.getStats({ deep: opts.deep === true });
+        const report = {
+            checkedAt: new Date().toISOString(),
+            totalEntries: this.entries.size,
+            revalidated,
+            duplicatePairs,
+            mergeCandidates,
+            deadWeight: {
+                neverHit: stats.neverHit || 0,
+                neverHitSample: neverHitIds,
+                downvoted,
+                action: 'forget_memory entries that are both never reused and downvoted; leave the rest — an unused memory costs bytes, a deleted one costs knowledge',
+            },
+            savings: {
+                totalTokensSaved: stats.totalTokensSaved || 0,
+                topSavers: (stats.topSavers || []).slice(0, 3),
+            },
+        };
+        if (stats.staleEntries !== undefined) {
+            report.deep = {
+                staleEntries: stats.staleEntries,
+                staleRatio: stats.staleRatio || 0,
+                action: 'work the revalidated.stale list above oldest-first; refresh_memory what still holds, forget_memory what does not',
+            };
+        }
+        return report;
+    }
     // ─── Portability ────────────────────────────────────────────────────────────
     /**
      * Serialize memories to a portable NDJSON bundle: a header line, then one entry per line.
@@ -1994,6 +2800,149 @@ export class TheBrainV2 {
         const body = selected.map(({ terms: _t, ...persisted }) => JSON.stringify(persisted));
         return { text: [header, ...body].join('\n'), count: selected.length, skippedStale };
     }
+    /**
+     * Classify one bundle line without touching the corpus. The single planning step behind
+     * both importBundle() (which then applies the plan) and previewImport() (which only
+     * reports it) — one classifier means a dry run can never disagree with the real thing
+     * about what would happen. Scrubbing the freshly-parsed object is safe: it is not
+     * corpus state yet.
+     */
+    planImportLine(line, markSource) {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            return { disposition: 'skip', reason: 'unparseable line' };
+        }
+        if (!entry || typeof entry.id !== 'string' || typeof entry.query !== 'string') {
+            return { disposition: 'skip', reason: 'missing id/query' };
+        }
+        if (this.tombstones.has(entry.id)) {
+            return { disposition: 'skip', reason: 'id was deliberately forgotten here', entry, tombstoned: true };
+        }
+        // Bundles from pre-scrub Brains (or hand-written ones) can carry live secrets;
+        // redact on the way in. Already-scrubbed `[NAME_n]` spans pass through untouched.
+        if (typeof entry.query === 'string')
+            entry.query = scrubSecretsForStorage(entry.query).text;
+        if (typeof entry.response === 'string')
+            entry.response = scrubSecretsForStorage(entry.response).text;
+        if (Array.isArray(entry.claims)) {
+            for (const claim of entry.claims) {
+                if (claim && typeof claim.text === 'string')
+                    claim.text = scrubSecretsForStorage(claim.text).text;
+            }
+        }
+        if (!Array.isArray(entry.terms))
+            entry.terms = Object.keys(entry.termFreq || {});
+        if (entry.terms.length === 0) {
+            // A bundle from a version that persisted neither terms nor termFreq — re-tokenize
+            // rather than admit an entry the inverted index could never retrieve.
+            const terms = tokenize(entry.query + ' ' + (entry.response || ''));
+            entry.terms = [...new Set(terms)];
+            entry.termFreq = termFrequencies(terms);
+        }
+        if (markSource)
+            entry.source = 'import';
+        const existing = this.entries.get(entry.id);
+        if (existing) {
+            if (effectiveTime(entry) <= effectiveTime(existing)) {
+                return { disposition: 'skip', reason: 'local copy is newer or same age', entry };
+            }
+            return { disposition: 'update', reason: 'bundle copy is newer', entry };
+        }
+        return { disposition: 'import', reason: 'new id', entry };
+    }
+    /** Fold the other side's counters into ours without losing feedback either side collected. */
+    absorbImportCounters(existing, incoming) {
+        existing.hits = Math.max(existing.hits || 0, incoming.hits || 0);
+        existing.demerits = Math.max(existing.demerits || 0, incoming.demerits || 0);
+        const bestSavings = Math.max(existing.tokensSaved || 0, incoming.tokensSaved || 0);
+        if (bestSavings > 0)
+            existing.tokensSaved = bestSavings;
+        else
+            delete existing.tokensSaved;
+    }
+    /** Split a bundle into candidate lines. No header means raw entries — see below. */
+    static splitBundleLines(text) {
+        const lines = text.split('\n').filter(Boolean);
+        if (lines.length === 0)
+            return { lines: [] };
+        try {
+            const header = JSON.parse(lines[0]);
+            if (header && header.lemmaBrainExport)
+                return { lines: lines.slice(1) };
+        }
+        catch {
+            // No header — treat the whole file as entries. A raw entries.ndjson copied off another
+            // machine is a perfectly reasonable thing to hand this, and rejecting it would be
+            // pedantry rather than safety.
+        }
+        return { lines };
+    }
+    /**
+     * What importBundle() WOULD do, without writing anything: counts, the first 50 items,
+     * and opposite-outcome conflicts against the live corpus. Run this before importing a
+     * bundle from a teammate or another machine — especially a large one — so a flood of
+     * stale, wrong-project memories is a preview, not a surprise.
+     */
+    previewImport(text, opts = {}) {
+        this.syncIfChanged();
+        const { lines } = TheBrainV2.splitBundleLines(text);
+        const empty = { ok: false, wouldImport: 0, wouldUpdate: 0, wouldSkip: 0, items: [], truncated: false, conflicts: [], message: 'Bundle is empty.' };
+        if (lines.length === 0)
+            return empty;
+        const markSource = opts.markSource !== false;
+        let wouldImport = 0;
+        let wouldUpdate = 0;
+        let wouldSkip = 0;
+        const items = [];
+        const conflicts = [];
+        const seenConflicts = new Set();
+        for (const line of lines) {
+            const plan = this.planImportLine(line, markSource);
+            if (plan.disposition === 'import')
+                wouldImport++;
+            else if (plan.disposition === 'update')
+                wouldUpdate++;
+            else
+                wouldSkip++;
+            if (items.length < 50) {
+                items.push({
+                    id: plan.entry?.id ?? '(unparseable)',
+                    query: (plan.entry?.query || '').slice(0, 100),
+                    action: plan.disposition,
+                    reason: plan.reason,
+                });
+            }
+            if (plan.entry && plan.disposition !== 'skip' && plan.entry.symbolHashes) {
+                const refs = Object.keys(plan.entry.symbolHashes).map((key) => {
+                    const sep = key.lastIndexOf('::');
+                    return { filePath: key.substring(0, sep), symbolName: key.substring(sep + 2) };
+                });
+                const outcome = plan.entry.outcome === 'failed' ? 'failed' : 'confirmed';
+                for (const c of this.findOutcomeConflicts(refs, outcome, new Set([plan.entry.id]))) {
+                    const ck = `${c.id}|${plan.entry.id}`;
+                    if (seenConflicts.has(ck))
+                        continue;
+                    seenConflicts.add(ck);
+                    conflicts.push({ ...c, against: plan.entry.id });
+                }
+            }
+        }
+        return {
+            ok: true,
+            wouldImport,
+            wouldUpdate,
+            wouldSkip,
+            items,
+            truncated: lines.length > items.length,
+            conflicts,
+            message: `Dry run: would import ${wouldImport}, update ${wouldUpdate}, skip ${wouldSkip}.` +
+                (conflicts.length > 0 ? ` ${conflicts.length} opposite-outcome conflict(s) with live memories — review before importing.` : '') +
+                ` Nothing was written.`,
+        };
+    }
     /**
      * Merge a bundle produced by exportBundle into this Brain.
      *
@@ -2009,64 +2958,35 @@ export class TheBrainV2 {
      */
     importBundle(text, opts = {}) {
         this.syncIfChanged();
-        const lines = text.split('\n').filter(Boolean);
+        const { lines } = TheBrainV2.splitBundleLines(text);
         if (lines.length === 0)
             return { ok: false, imported: 0, updated: 0, skipped: 0, message: 'Bundle is empty.' };
-        let start = 0;
-        try {
-            const header = JSON.parse(lines[0]);
-            if (header && header.lemmaBrainExport)
-                start = 1;
-        }
-        catch {
-            // No header — treat the whole file as entries. A raw entries.ndjson copied off another
-            // machine is a perfectly reasonable thing to hand this, and rejecting it would be
-            // pedantry rather than safety.
-        }
+        // Snapshot before merging foreign entries: an import is the easiest way to flood a
+        // clean corpus with hundreds of stale, wrong-project memories.
+        this.snapshotCorpus('import');
         let imported = 0;
         let updated = 0;
         let skipped = 0;
         const markSource = opts.markSource !== false;
-        for (const line of lines.slice(start)) {
-            let entry;
-            try {
-                entry = JSON.parse(line);
-            }
-            catch {
-                skipped++;
-                continue;
-            }
-            if (!entry || typeof entry.id !== 'string' || typeof entry.query !== 'string') {
-                skipped++;
-                continue;
-            }
-            if (this.tombstones.has(entry.id)) {
+        for (const line of lines) {
+            const plan = this.planImportLine(line, markSource);
+            if (plan.disposition === 'skip') {
+                // Tombstoned skips excepted: a deliberately forgotten id gets no counter updates,
+                // exactly as before the planner existed — the deletion stands completely.
+                if (plan.entry && !plan.tombstoned) {
+                    const existing = this.entries.get(plan.entry.id);
+                    // Older or same age: keep ours, but never lose feedback the other side collected.
+                    if (existing)
+                        this.absorbImportCounters(existing, plan.entry);
+                }
                 skipped++;
                 continue;
             }
-            if (!Array.isArray(entry.terms))
-                entry.terms = Object.keys(entry.termFreq || {});
-            if (entry.terms.length === 0) {
-                // A bundle from a version that persisted neither terms nor termFreq — re-tokenize
-                // rather than admit an entry the inverted index could never retrieve.
-                const terms = tokenize(entry.query + ' ' + (entry.response || ''));
-                entry.terms = [...new Set(terms)];
-                entry.termFreq = termFrequencies(terms);
-            }
-            if (markSource)
-                entry.source = 'import';
+            const entry = plan.entry;
             const existing = this.entries.get(entry.id);
             if (existing) {
-                if (effectiveTime(entry) <= effectiveTime(existing)) {
-                    // Older or same age: keep ours, but never lose feedback the other side collected.
-                    existing.hits = Math.max(existing.hits || 0, entry.hits || 0);
-                    existing.demerits = Math.max(existing.demerits || 0, entry.demerits || 0);
-                    skipped++;
-                    continue;
-                }
                 this.dropEntry(existing);
-                entry.hits = Math.max(existing.hits || 0, entry.hits || 0);
-                entry.demerits = Math.max(existing.demerits || 0, entry.demerits || 0);
+                this.absorbImportCounters(entry, existing);
                 updated++;
             }
             else {
@@ -2120,6 +3040,8 @@ export class TheBrainV2 {
         let unscoped = 0;
         let untracked = 0;
         let oldest = '';
+        let totalTokensSaved = 0;
+        const savers = [];
         const bySource = {};
         const projects = new Set();
         for (const entry of this.entries.values()) {
@@ -2133,11 +3055,20 @@ export class TheBrainV2 {
                 projects.add(entry.projectId);
             if (trackedArtifactCount(entry) === 0)
                 untracked++;
+            if (entry.tokensSaved) {
+                totalTokensSaved += entry.tokensSaved;
+                savers.push({ id: entry.id, query: entry.query.slice(0, 80), tokensSaved: entry.tokensSaved, hits: entry.hits });
+            }
             const src = entrySource(entry);
             bySource[src] = (bySource[src] || 0) + 1;
             if (entry.timestamp && (!oldest || entry.timestamp < oldest))
                 oldest = entry.timestamp;
         }
+        savers.sort((a, b) => b.tokensSaved - a.tokensSaved);
+        base.totalTokensSaved = totalTokensSaved;
+        if (savers.length > 0)
+            base.topSavers = savers.slice(0, 5);
+        base.integrity = this.health();
         base.neverHit = neverHit;
         base.downvoted = downvoted;
         base.bySource = bySource;
@@ -2166,7 +3097,26 @@ export class TheBrainV2 {
         }
         return base;
     }
+    /**
+     * Integrity + rollback posture in one cheap call (no hashing, no disk reads beyond a
+     * directory listing). `ok` is false while an unverified read, a backup fallback, or an
+     * undecryptable envelope is the reason this process is serving what it serves.
+     */
+    health() {
+        this.syncIfChanged();
+        return {
+            ok: this.integrityIssue === null,
+            lastIssue: this.integrityIssue,
+            snapshots: listSnapshotNames().length,
+            backups: fs.existsSync(ENTRIES_PREV_FILE),
+            encrypted: encryptionActive(BRAIN_DIR).enabled,
+        };
+    }
     clear() {
+        // Even a deliberate wipe gets a restore point: "I didn't mean that clear" is a
+        // support ticket, "I didn't mean that clear and there is no snapshot" is data loss.
+        if (this.entries.size > 0)
+            this.snapshotCorpus('clear');
         this.entries.clear();
         this.invertedIndex.clear();
         this.bloom = new BloomFilter();
@@ -2176,9 +3126,14 @@ export class TheBrainV2 {
         this.tombstones.clear();
         this.diskStamp = null;
         this.sidecar = null;
+        this.integrityIssue = null;
         try {
             if (fs.existsSync(ENTRIES_FILE))
                 fs.unlinkSync(ENTRIES_FILE);
+            if (fs.existsSync(ENTRIES_SHA_FILE))
+                fs.unlinkSync(ENTRIES_SHA_FILE);
+            if (fs.existsSync(ENTRIES_PREV_FILE))
+                fs.unlinkSync(ENTRIES_PREV_FILE);
             if (fs.existsSync(INDEX_FILE))
                 fs.unlinkSync(INDEX_FILE);
             if (fs.existsSync(META_FILE))
@@ -2187,6 +3142,8 @@ export class TheBrainV2 {
                 fs.unlinkSync(LOCK_FILE);
             if (fs.existsSync(EMBEDDINGS_FILE))
                 fs.unlinkSync(EMBEDDINGS_FILE);
+            // Snapshots deliberately survive clear(): they are the rollback history, and a wipe
+            // that also destroys every restore point is not a wipe, it is data loss.
         }
         catch { /* ignore */ }
     }