crbro-memory 1.15.0 → 2.0.0

package/dist/engine/cortex.js

@@ -3,6 +3,7 @@
 // Neuron CRUD — create, read, update, list neurons
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cortex = void 0;
+exports.unionNeuron = unionNeuron;
 exports.normalizeKeys = normalizeKeys;
 const fs_js_1 = require("../utils/fs.js");
 const ids_js_1 = require("../utils/ids.js");
@@ -62,6 +63,171 @@ function sameNumbers(a, b) {
     const nb = b.match(/\d+/g) || [];
     return na.length === nb.length && na.every((v, i) => v === nb[i]);
 }
+/** Where a fact's lifecycle stands, for "take the furthest-along status". */
+function statusRank(status) {
+    return status === 'retracted' ? 2 : status === 'superseded' ? 1 : 0;
+}
+function earliestOf(a, b) {
+    if (!a)
+        return b || '';
+    if (!b)
+        return a;
+    return a < b ? a : b;
+}
+function copyFact(f) {
+    const out = { ...f };
+    if (f.keys)
+        out.keys = [...f.keys];
+    if (f.supersedes)
+        out.supersedes = [...f.supersedes];
+    return out;
+}
+/** Content hashes of every entry that can carry a date or a retirement. */
+function liveEntryKeys(n) {
+    return new Set([
+        ...n.decisions.map(d => d.text || ''),
+        ...n.patterns, ...n.preferences,
+        ...(n.errors || []), ...(n.debts || []),
+    ].map(ops_js_1.entryId));
+}
+/**
+ * Everything of `source` folded into `target`, as a new object.
+ *
+ * Shared by restoreNeuron (a quarantine copy back over a neuron that was
+ * re-created since) and mergeNeurons (two neurons that turned out to be one
+ * topic). Pure on purpose: neither input is touched, so the caller can diff
+ * the result against what it had and emit only what actually moved.
+ *
+ * Facts line up by id (the content hash), falling back to normalised text;
+ * on a collision the target's telling stays but takes the furthest-along
+ * status (active < superseded < retracted) and the earliest `added`, and the
+ * keys are unioned. Everything else is a set union keyed by normalised text
+ * with the target's order first. Local observations (heat, access_count)
+ * combine as max and sum; identity (id, name, domain, type) is the target's.
+ */
+function unionNeuron(target, source) {
+    const moved = { facts: 0, decisions: 0, patterns: 0, preferences: 0, errors: 0, debts: 0, tags: 0, map: 0 };
+    // ── Facts ──
+    const facts = target.facts.map(copyFact);
+    const byId = new Map();
+    const byText = new Map();
+    for (const f of facts) {
+        byId.set(f.id || (0, hash_js_1.factId)(f.text), f);
+        byText.set((0, ops_js_1.normalizeText)(f.text), f);
+    }
+    for (const sf of source.facts || []) {
+        const sid = sf.id || (0, hash_js_1.factId)(sf.text);
+        const hit = byId.get(sid) || byText.get((0, ops_js_1.normalizeText)(sf.text));
+        if (!hit) {
+            const copia = copyFact(sf);
+            copia.id = sid;
+            facts.push(copia);
+            byId.set(sid, copia);
+            byText.set((0, ops_js_1.normalizeText)(sf.text), copia);
+            moved.facts++;
+            continue;
+        }
+        if (statusRank(sf.status) > statusRank(hit.status)) {
+            hit.status = sf.status;
+            if (sf.revised)
+                hit.revised = sf.revised;
+            if (sf.revision_note)
+                hit.revision_note = sf.revision_note;
+            if (sf.superseded_by)
+                hit.superseded_by = sf.superseded_by;
+        }
+        hit.added = earliestOf(hit.added, sf.added);
+        const keys = normalizeKeys([...(hit.keys || []), ...(sf.keys || [])]);
+        if (keys.length)
+            hit.keys = keys;
+        else
+            delete hit.keys;
+    }
+    // ── Decisions: by normalised text, the target's rationale wins ──
+    const decisions = target.decisions.map(d => ({ ...d }));
+    const vistas = new Set(decisions.map(d => (0, ops_js_1.normalizeText)(d.text)));
+    for (const d of source.decisions || []) {
+        const k = (0, ops_js_1.normalizeText)(d.text);
+        if (vistas.has(k))
+            continue;
+        vistas.add(k);
+        decisions.push({ ...d });
+        moved.decisions++;
+    }
+    // ── Plain string lists: set union, target order first ──
+    const unir = (a, b) => {
+        const out = [...a];
+        const seen = new Set(a.map(ops_js_1.normalizeText));
+        let added = 0;
+        for (const t of b) {
+            const k = (0, ops_js_1.normalizeText)(t);
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(t);
+            added++;
+        }
+        return { out, added };
+    };
+    const patterns = unir(target.patterns || [], source.patterns || []);
+    const preferences = unir(target.preferences || [], source.preferences || []);
+    const errors = unir(target.errors || [], source.errors || []);
+    const debts = unir(target.debts || [], source.debts || []);
+    const tags = unir(target.tags || [], source.tags || []);
+    moved.patterns = patterns.added;
+    moved.preferences = preferences.added;
+    moved.errors = errors.added;
+    moved.debts = debts.added;
+    moved.tags = tags.added;
+    const neuron = {
+        ...target,
+        facts,
+        decisions,
+        patterns: patterns.out,
+        preferences: preferences.out,
+        errors: errors.out,
+        debts: debts.out,
+        tags: tags.out,
+        connections: [...new Set([...(target.connections || []), ...(source.connections || [])])]
+            .filter(c => c !== target.id && c !== source.id),
+        summary: target.summary || source.summary || '',
+        heat: Math.max(target.heat || 0, source.heat || 0),
+        access_count: (target.access_count || 0) + (source.access_count || 0),
+        created: earliestOf(target.created, source.created) || (0, fs_js_1.now)(),
+        last_accessed: (0, fs_js_1.now)(),
+    };
+    // ── Sidecars: union, then pruned to what is actually in the neuron ──
+    const vivos = liveEntryKeys(neuron);
+    const fechas = {};
+    for (const [k, v] of Object.entries(source.entry_dates || {}))
+        fechas[k] = v;
+    for (const [k, v] of Object.entries(target.entry_dates || {}))
+        fechas[k] = earliestOf(fechas[k], v);
+    const fechasVivas = {};
+    for (const k of Object.keys(fechas).sort())
+        if (vivos.has(k))
+            fechasVivas[k] = fechas[k];
+    neuron.entry_dates = fechasVivas;
+    const estados = { ...(source.entry_status || {}), ...(target.entry_status || {}) };
+    const estadosVivos = {};
+    for (const k of Object.keys(estados).sort())
+        if (vivos.has(k))
+            estadosVivos[k] = estados[k];
+    if (Object.keys(estadosVivos).length)
+        neuron.entry_status = estadosVivos;
+    else
+        delete neuron.entry_status;
+    // ── Map: the target's if it has one, else the source's ──
+    if (target.map)
+        neuron.map = { ...target.map };
+    else if (source.map) {
+        neuron.map = { ...source.map };
+        moved.map = 1;
+    }
+    else
+        delete neuron.map;
+    return { neuron, moved };
+}
 /**
  * Aliases a future question may use, as stored: trimmed, lower-cased, at
  * most 40 characters each, unique, at most eight. Order is kept.
@@ -87,6 +253,7 @@ class Cortex {
      */
     indexer = null;
     emitter = null;
+    remover = null;
     /** What this session has actually written, for an honest consolidate(). */
     tally = { facts: 0, decisions: 0, topics: new Set() };
     constructor(brain) {
@@ -109,6 +276,37 @@ class Cortex {
     setEmitter(emitter) {
         this.emitter = emitter;
     }
+    setRemover(remover) {
+        this.remover = remover;
+    }
+    async unindex(neuronId) {
+        if (!this.remover)
+            return;
+        try {
+            await this.remover(neuronId);
+        }
+        catch {
+            // The index is derived data; a stale chunk is a nuisance, not a loss.
+        }
+    }
+    /**
+     * Copy a whole neuron to .quarantine/ with a timestamp, before anything
+     * destructive. Same stamp format everywhere, so restoreNeuron can pick the
+     * newest copy by name alone.
+     */
+    async quarantine(neuron) {
+        const sello = (0, fs_js_1.now)().replace(/[:.]/g, '-');
+        const backup = `${this.brain.paths.quarantine}/${neuron.id}.${sello}.json`;
+        await (0, fs_js_1.writeJSON)(backup, neuron);
+        return backup;
+    }
+    /** Remove the neuron file, drop its chunks, and keep the manifest honest. */
+    async deleteNeuronFile(id) {
+        await (0, fs_js_1.deleteJSON)(this.brain.paths.neuron(id));
+        await this.unindex(id);
+        const manifest = await this.brain.getManifest();
+        await this.brain.updateManifest({ total_neurons: Math.max(0, manifest.total_neurons - 1) });
+    }
     async emit(neuronId, change) {
         if (!this.emitter)
             return;
@@ -292,7 +490,11 @@ class Cortex {
         }
         if (!neuron) {
             if (options?.createIfMissing === false) {
-                return { neuron: null, action: 'skipped', superseded: 0, supersedes_unmatched: options?.supersedes || [], near_duplicates: [], redacted: limpio.found };
+                return {
+                    neuron: null, action: 'skipped', superseded: 0,
+                    supersedes_unmatched: options?.supersedes || [], near_duplicates: [], redacted: limpio.found,
+                    duplicate: false, updated_in_place: false, skipped_retired: null,
+                };
             }
             const nType = options?.neuronType || (0, ids_js_1.inferNeuronType)(topic);
             const domain = options?.domain || 'general';
@@ -306,6 +508,19 @@ class Cortex {
         let supersedesUnmatched = [];
         let nearDuplicates = [];
         let emitir = null;
+        let duplicate = false;
+        let updatedInPlace = false;
+        let skippedRetired = null;
+        // A retired decision, pattern, error or debt must not come back through
+        // learn: the sidecar says so, and the index already hides it.
+        const retirada = (n, text) => {
+            const k = (0, ops_js_1.entryId)(text);
+            const est = n.entry_status?.[k];
+            if (!est)
+                return false;
+            skippedRetired = { id: k, status: est.status, revised: est.revised, note: est.note };
+            return true;
+        };
         // From here on we work on a fresh read inside the lock. Mutating the copy
         // fetched a moment ago and saving it over the top is exactly how a
         // concurrent writer's facts disappeared.
@@ -323,16 +538,53 @@ class Cortex {
                     const id = (0, hash_js_1.factId)(content);
                     const keys = normalizeKeys(options?.keys);
                     const existente = n.facts.find(f => f.text.toLowerCase() === content.toLowerCase());
+                    if (existente && (existente.status === 'superseded' || existente.status === 'retracted')) {
+                        // The same line was deliberately retired. Re-adding it would
+                        // undo that revision by accident; report it and write nothing.
+                        skippedRetired = {
+                            id: existente.id || (0, hash_js_1.factId)(existente.text),
+                            status: existente.status,
+                            revised: existente.revised,
+                            note: existente.revision_note,
+                        };
+                        return null;
+                    }
                     const isDuplicate = existente !== undefined;
-                    if (existente && keys.length) {
-                        // The same line again, with aliases: merge them, no sibling.
-                        // The indexer re-indexes the neuron afterwards, keys included.
-                        const merged = normalizeKeys([...(existente.keys || []), ...keys]);
-                        if (merged.length !== (existente.keys || []).length) {
-                            existente.keys = merged;
+                    if (existente) {
+                        // The same line again: no sibling, but confidence and aliases
+                        // may be edited in place. The indexer re-indexes the neuron
+                        // afterwards, keys included.
+                        duplicate = true;
+                        let cambiado = false;
+                        if (options?.confidence !== undefined && options.confidence !== existente.confidence) {
+                            existente.confidence = options.confidence;
+                            cambiado = true;
+                        }
+                        if (options?.keysReplace) {
+                            const actuales = existente.keys || [];
+                            if (keys.length !== actuales.length || keys.some((k, i) => k !== actuales[i])) {
+                                if (keys.length)
+                                    existente.keys = keys;
+                                else
+                                    delete existente.keys;
+                                cambiado = true;
+                            }
+                        }
+                        else if (keys.length) {
+                            const merged = normalizeKeys([...(existente.keys || []), ...keys]);
+                            if (merged.length !== (existente.keys || []).length) {
+                                existente.keys = merged;
+                                cambiado = true;
+                            }
+                        }
+                        if (cambiado) {
+                            // Note for shared neurons: materialize takes max(conf) and
+                            // unions keys, so lowering confidence or dropping an alias
+                            // stays local. Documented, not fought — the log is append-only.
+                            updatedInPlace = true;
                             this.tally.topics.add(n.id);
                             emitir = { kind: 'fact', text: existente.text, fid: existente.id || id,
-                                conf: existente.confidence ?? 1, at: existente.added, src: existente.source, keys: merged };
+                                conf: existente.confidence ?? 1, at: existente.added, src: existente.source, keys: existente.keys };
                         }
                     }
                     if (!isDuplicate) {
@@ -367,6 +619,8 @@ class Cortex {
                     break;
                 }
                 case 'decision': {
+                    if (retirada(n, content))
+                        return null;
                     const decision = {
                         text: content,
                         date: (0, fs_js_1.now)(),
@@ -380,6 +634,8 @@ class Cortex {
                     break;
                 }
                 case 'pattern': {
+                    if (retirada(n, content))
+                        return null;
                     if (!n.patterns.includes(content)) {
                         n.patterns.push(content);
                         fechar(n, content);
@@ -395,6 +651,8 @@ class Cortex {
                     break;
                 }
                 case 'error': {
+                    if (retirada(n, content))
+                        return null;
                     if (!n.errors)
                         n.errors = [];
                     if (!n.errors.includes(content)) {
@@ -406,6 +664,8 @@ class Cortex {
                     break;
                 }
                 case 'debt': {
+                    if (retirada(n, content))
+                        return null;
                     if (!n.debts)
                         n.debts = [];
                     if (!n.debts.includes(content)) {
@@ -425,12 +685,24 @@ class Cortex {
             return n;
         });
         const final = (actualizada || neuron);
+        if (skippedRetired) {
+            // Nothing was written, so nothing to index, emit or tally.
+            return {
+                neuron: final, action: 'skipped_retired', superseded: 0, supersedes_unmatched: [],
+                near_duplicates: [], redacted: limpio.found,
+                duplicate: false, updated_in_place: false, skipped_retired: skippedRetired,
+            };
+        }
         await this.reindex(final);
         // Preferences are never emitted: they are the field most likely to hold a
         // key and the least likely to be worth sharing.
         if (emitir)
             await this.emit(final.id, emitir);
-        return { neuron: final, action, superseded, supersedes_unmatched: supersedesUnmatched, near_duplicates: nearDuplicates, redacted: limpio.found };
+        return {
+            neuron: final, action, superseded, supersedes_unmatched: supersedesUnmatched,
+            near_duplicates: nearDuplicates, redacted: limpio.found,
+            duplicate, updated_in_place: updatedInPlace, skipped_retired: null,
+        };
     }
     /**
      * Mark facts as no longer current.
@@ -445,11 +717,14 @@ class Cortex {
         const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
         if (!neuron)
             return { neuron: null, revised: 0, unmatched: targets.slice() };
+        const status = options?.status || 'superseded';
         let revised = 0;
         let unmatched = targets.slice();
         const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
             const n = current || neuron;
-            const retirado = this.retire(n, targets, options?.replacedBy, options?.status || 'superseded', options?.note);
+            const retirado = status === 'active'
+                ? this.reactivate(n, targets, options?.note)
+                : this.retire(n, targets, options?.replacedBy, status, options?.note);
             revised = retirado.count;
             unmatched = retirado.unmatched;
             if (revised === 0)
@@ -462,8 +737,12 @@ class Cortex {
             // which is exactly the failure this feature exists to close.
             const n = (actualizada || neuron);
             await this.reindex(n);
-            // 'active' is not a retirement, so it is never emitted as one.
-            const estado = options?.status === 'retracted' ? 'retracted' : 'superseded';
+            // 'active' is not a retirement, so it is never emitted: StatusOp only
+            // moves forward, and on a shared neuron the next sync re-applies the
+            // retirement from the log. Reactivation is local; the server says so.
+            if (status === 'active')
+                return { neuron: n, revised, unmatched };
+            const estado = status === 'retracted' ? 'retracted' : 'superseded';
             for (const t of targets) {
                 const f = n.facts.find(x => (x.id || '') === t || x.text.trim().toLowerCase() === t.trim().toLowerCase());
                 if (f?.id) {
@@ -541,6 +820,168 @@ class Cortex {
         }
         return { count, unmatched: targets.filter((_, i) => !hit.has(i)) };
     }
+    /**
+     * Bring retired facts back. The inverse of retire: only superseded or
+     * retracted facts match, by id or by trimmed lower-cased text. Clears
+     * superseded_by (the replacement no longer replaces it) and stamps the
+     * revision date; the note, if given, records why it came back.
+     */
+    reactivate(neuron, targets, note) {
+        let count = 0;
+        const wanted = targets.map(t => t.trim().toLowerCase());
+        const hit = new Set();
+        for (const fact of neuron.facts) {
+            if (fact.status !== 'superseded' && fact.status !== 'retracted')
+                continue;
+            const fid = fact.id || (0, hash_js_1.factId)(fact.text);
+            const idPos = wanted.indexOf(fid.toLowerCase());
+            const textPos = wanted.indexOf(fact.text.trim().toLowerCase());
+            if (idPos === -1 && textPos === -1)
+                continue;
+            if (idPos !== -1)
+                hit.add(idPos);
+            if (textPos !== -1)
+                hit.add(textPos);
+            fact.id = fid;
+            fact.status = 'active';
+            delete fact.superseded_by;
+            fact.revised = (0, fs_js_1.now)();
+            if (note)
+                fact.revision_note = note;
+            count++;
+        }
+        return { count, unmatched: targets.filter((_, i) => !hit.has(i)) };
+    }
+    /**
+     * Retire — or reactivate — decisions, patterns, errors and debts by exact
+     * text (trimmed, case-insensitive). These are plain strings, so their
+     * status lives in the entry_status sidecar keyed by entryId(text), the
+     * same way their dates do. A retired entry stays in the file and leaves
+     * recall exactly like a superseded fact; status 'active' deletes the key.
+     *
+     * Never emitted: the sidecar travels only through the local file and
+     * survives a sync because applyOps copies and prunes it.
+     */
+    async retireEntries(neuronRef, targets, options) {
+        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        if (!neuron)
+            return { neuron: null, revised: 0, unmatched: targets.slice() };
+        const status = options?.status || 'superseded';
+        const wanted = targets.map(t => (0, ops_js_1.normalizeText)(t).toLowerCase());
+        let revised = 0;
+        let unmatched = targets.slice();
+        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
+            const n = current || neuron;
+            const estados = n.entry_status || {};
+            const hit = new Set();
+            const cuando = (0, fs_js_1.now)();
+            const textos = [
+                ...n.decisions.map(d => d.text || ''),
+                ...n.patterns,
+                ...(n.errors || []),
+                ...(n.debts || []),
+            ];
+            for (const t of textos) {
+                const pos = wanted.indexOf((0, ops_js_1.normalizeText)(t).toLowerCase());
+                if (pos === -1)
+                    continue;
+                const k = (0, ops_js_1.entryId)(t);
+                const retirado = estados[k] !== undefined;
+                if (status === 'active') {
+                    // Only a retired entry can come back.
+                    if (!retirado)
+                        continue;
+                    delete estados[k];
+                }
+                else {
+                    // An already-retired entry never matches again.
+                    if (retirado)
+                        continue;
+                    const est = { status: status, revised: cuando };
+                    if (options?.note)
+                        est.note = options.note;
+                    estados[k] = est;
+                }
+                hit.add(pos);
+                revised++;
+            }
+            unmatched = targets.filter((_, i) => !hit.has(i));
+            if (revised === 0)
+                return null;
+            if (Object.keys(estados).length)
+                n.entry_status = estados;
+            else
+                delete n.entry_status;
+            n.last_accessed = cuando;
+            return n;
+        });
+        const n = (actualizada || neuron);
+        // The index drops retired entries (and picks reactivated ones back up).
+        if (revised > 0)
+            await this.reindex(n);
+        return { neuron: n, revised, unmatched };
+    }
+    /**
+     * Edit a neuron's metadata: summary, domain, tags, name.
+     *
+     * Only fields that actually differ are written and reported; a call that
+     * changes nothing writes nothing. `tags` replaces the whole list — protocol
+     * neurons keep their 'priority:'/'source:' tags only if the caller re-sends
+     * them. `name` changes the display name only: the id, and with it the file,
+     * the synapses, the shared map and the connections, never move. `domain`
+     * replaces unconditionally, unlike learn, which only fills in 'general'.
+     *
+     * Not emitted: NeuronOp is only an announcement, and metadata is local.
+     */
+    async setMeta(neuronRef, meta) {
+        const neuron = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        if (!neuron)
+            return { neuron: null, changed: [], redacted: [] };
+        let redacted = [];
+        let summary;
+        if (meta.summary !== undefined) {
+            const limpio = (0, secrets_js_1.redact)(meta.summary);
+            summary = limpio.text;
+            redacted = limpio.found;
+        }
+        const tags = meta.tags === undefined
+            ? undefined
+            : [...new Set(meta.tags.map(t => String(t || '').trim()).filter(Boolean))];
+        const domain = meta.domain === undefined ? undefined : meta.domain.trim();
+        const name = meta.name === undefined ? undefined : meta.name.trim();
+        const changed = [];
+        const actualizada = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuron.id), current => {
+            const n = current || neuron;
+            if (summary !== undefined && summary !== n.summary) {
+                n.summary = summary;
+                changed.push('summary');
+            }
+            if (domain !== undefined && domain && domain !== n.domain) {
+                n.domain = domain;
+                changed.push('domain');
+            }
+            if (tags !== undefined) {
+                const actuales = n.tags || [];
+                if (tags.length !== actuales.length || tags.some((t, i) => t !== actuales[i])) {
+                    n.tags = tags;
+                    changed.push('tags');
+                }
+            }
+            if (name !== undefined && name && name !== n.name) {
+                n.name = name;
+                changed.push('name');
+            }
+            if (changed.length === 0)
+                return null;
+            n.last_accessed = (0, fs_js_1.now)();
+            return n;
+        });
+        const n = (actualizada || neuron);
+        // The header chunk carries name and tags; the summary is indexed too.
+        if (changed.length > 0)
+            await this.reindex(n);
+        return { neuron: n, changed, redacted };
+    }
     /**
      * Replace the neuron's system map.
      *
@@ -613,9 +1054,10 @@ class Cortex {
         }
         // Sort by heat (descending)
         neurons.sort((a, b) => b.heat - a.heat);
-        // Apply limit
+        // Apply offset, then limit
         const limit = options?.limit || 50;
-        return neurons.slice(0, limit);
+        const offset = Math.max(0, options?.offset || 0);
+        return neurons.slice(offset, offset + limit);
     }
     /**
      * Update a neuron's summary.
@@ -663,9 +1105,7 @@ class Cortex {
         const found = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
         if (!found)
             return { neuron_id: null, removed: 0, backup: null };
-        const sello = (0, fs_js_1.now)().replace(/[:.]/g, '-');
-        const backup = `${this.brain.paths.quarantine}/${found.id}.${sello}.json`;
-        await (0, fs_js_1.writeJSON)(backup, found);
+        const backup = await this.quarantine(found);
         let removed = 0;
         const wanted = targets.map(t => t.trim().toLowerCase());
         const after = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(found.id), current => {
@@ -716,6 +1156,17 @@ class Cortex {
                         delete current.entry_dates[k];
                 }
             }
+            // Same for retirements: a key whose entry is gone is pruned, so the
+            // sidecar cannot hide a line that no longer exists.
+            if (current.entry_status) {
+                const vivos = liveEntryKeys(current);
+                for (const k of Object.keys(current.entry_status)) {
+                    if (!vivos.has(k))
+                        delete current.entry_status[k];
+                }
+                if (Object.keys(current.entry_status).length === 0)
+                    delete current.entry_status;
+            }
             current.last_accessed = (0, fs_js_1.now)();
             return current;
         });
@@ -733,6 +1184,16 @@ class Cortex {
                     await this.emit(found.id, { kind: 'status', fid: f.id || (0, hash_js_1.factId)(f.text), to: 'retracted', at: cuando, why: 'forgotten' });
                 }
             }
+            for (const d of found.decisions || []) {
+                if (wanted.includes((d.text || '').trim().toLowerCase())) {
+                    await this.emit(found.id, { kind: 'decision_purge', key: (0, ops_js_1.entryId)(d.text), at: cuando });
+                }
+            }
+            for (const p of found.patterns || []) {
+                if (wanted.includes((p || '').trim().toLowerCase())) {
+                    await this.emit(found.id, { kind: 'pattern_purge', key: (0, ops_js_1.entryId)(p), at: cuando });
+                }
+            }
             for (const e of found.errors || []) {
                 if (wanted.includes((e || '').trim().toLowerCase())) {
                     await this.emit(found.id, { kind: 'error_purge', key: (0, ops_js_1.entryId)(e), at: cuando });
@@ -749,6 +1210,167 @@ class Cortex {
         }
         return { neuron_id: found.id, removed, backup: removed > 0 ? backup : null };
     }
+    /**
+     * Delete a whole neuron. Quarantine copy first, then the file goes, the
+     * index drops its chunks and the manifest is decremented.
+     *
+     * Synapses are not touched here (the Cortex has no Synapses): the server
+     * calls synapses.removeAllFor(id) right after. Nor is shared state checked
+     * — the server refuses beforehand when the neuron is shared, because the
+     * next sync would simply re-create it from the team log. Nothing is
+     * emitted: there is no neuron-delete op.
+     */
+    async forgetNeuron(neuronRef) {
+        const found = (await this.peek(neuronRef)) || (await this.findByName(neuronRef));
+        if (!found) {
+            return {
+                neuron_id: null, backup: null,
+                counts: { facts: 0, decisions: 0, patterns: 0, preferences: 0, errors: 0, debts: 0, connections: 0 },
+            };
+        }
+        const backup = await this.quarantine(found);
+        await this.deleteNeuronFile(found.id);
+        return {
+            neuron_id: found.id,
+            backup,
+            counts: {
+                facts: (found.facts || []).length,
+                decisions: (found.decisions || []).length,
+                patterns: (found.patterns || []).length,
+                preferences: (found.preferences || []).length,
+                errors: (found.errors || []).length,
+                debts: (found.debts || []).length,
+                connections: (found.connections || []).length,
+            },
+        };
+    }
+    /**
+     * Quarantine copies of one neuron, newest first. Stamps sort lexically, so
+     * the file name alone orders them.
+     */
+    async quarantineCopies(neuronId) {
+        const prefijo = `${neuronId}.`;
+        const files = await (0, fs_js_1.listJSONFiles)(this.brain.paths.quarantine);
+        return files.filter(f => f.startsWith(prefijo)).sort().reverse();
+    }
+    /**
+     * Bring a neuron back from quarantine.
+     *
+     * The newest copy is used unless `file` names an exact basename. If the
+     * neuron no longer exists the copy is written back as it was; if it does
+     * (a forget of facts, or the topic was re-created since) the copy is
+     * unioned into it. The quarantine file stays where it is, so a restore is
+     * repeatable. Nothing is emitted.
+     */
+    async restoreNeuron(neuronId, options) {
+        const nada = { neuron: null, restored_from: null, merged_into_existing: false, moved: null };
+        let basename = null;
+        if (options?.file) {
+            const pedido = options.file.replace(/\.json$/i, '');
+            const copias = await this.quarantineCopies(neuronId);
+            basename = copias.includes(pedido) ? pedido : null;
+        }
+        else {
+            basename = (await this.quarantineCopies(neuronId))[0] || null;
+        }
+        if (!basename)
+            return nada;
+        const ruta = `${this.brain.paths.quarantine}/${basename}.json`;
+        const copia = await (0, fs_js_1.readJSON)(ruta);
+        if (!copia || !copia.id)
+            return nada;
+        copia.id = neuronId;
+        // Decide inside the lock, like create: whether the neuron exists again is
+        // only known for sure while nobody else can write it.
+        let escrita = false;
+        let moved = null;
+        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(neuronId), current => {
+            if (!current) {
+                escrita = true;
+                return copia;
+            }
+            const r = unionNeuron(current, copia);
+            moved = r.moved;
+            return r.neuron;
+        });
+        const final = (saved || copia);
+        if (escrita) {
+            const manifest = await this.brain.getManifest();
+            await this.brain.updateManifest({ total_neurons: manifest.total_neurons + 1 });
+        }
+        await this.reindex(final);
+        return { neuron: final, restored_from: ruta, merged_into_existing: !escrita, moved };
+    }
+    /**
+     * Fold one neuron into another and delete the first.
+     *
+     * `from` is quarantined, unioned into `into`, and then removed exactly like
+     * forgetNeuron. Each element that actually moved is emitted for `into`, so
+     * a shared target receives the knowledge (the emitter no-ops when `into`
+     * is unshared). Synapses are not touched — the server calls
+     * synapses.rewire(from, into) right after — and the server refuses
+     * beforehand when `from` is shared (unshare first, or the next sync
+     * re-creates it).
+     */
+    async mergeNeurons(fromRef, intoRef) {
+        const from = (await this.peek(fromRef)) || (await this.findByName(fromRef));
+        const into = (await this.peek(intoRef)) || (await this.findByName(intoRef));
+        if (!from || !into || from.id === into.id) {
+            return { from: from?.id ?? null, into: into?.id ?? null, backup: null, moved: null };
+        }
+        const backup = await this.quarantine(from);
+        let antes = into;
+        let moved = null;
+        const saved = await (0, fs_js_1.updateJSON)(this.brain.paths.neuron(into.id), current => {
+            antes = current || into;
+            const r = unionNeuron(antes, from);
+            moved = r.moved;
+            return r.neuron;
+        });
+        const final = (saved || into);
+        await this.reindex(final);
+        // Emit what moved, by diffing the result against what `into` had. The
+        // union is pure, so this is exact: nothing the target already held is
+        // re-announced.
+        const cuando = (0, fs_js_1.now)();
+        const teniaFact = new Set(antes.facts.map(f => f.id || (0, hash_js_1.factId)(f.text)));
+        for (const f of final.facts) {
+            const fid = f.id || (0, hash_js_1.factId)(f.text);
+            if (teniaFact.has(fid))
+                continue;
+            await this.emit(final.id, { kind: 'fact', text: f.text, fid, conf: f.confidence ?? 1, at: f.added, src: f.source, keys: f.keys });
+            // A moved fact that was already retired must arrive retired, or the
+            // teammates would see as current what the source had superseded.
+            if (f.status === 'superseded' || f.status === 'retracted') {
+                await this.emit(final.id, { kind: 'status', fid, to: f.status, at: f.revised || cuando, why: f.revision_note });
+            }
+        }
+        const teniaDecision = new Set(antes.decisions.map(d => (0, ops_js_1.normalizeText)(d.text)));
+        for (const d of final.decisions) {
+            if (teniaDecision.has((0, ops_js_1.normalizeText)(d.text)))
+                continue;
+            await this.emit(final.id, { kind: 'decision', text: d.text, why: d.rationale || undefined, at: d.date || cuando });
+        }
+        const fecha = (t) => final.entry_dates?.[(0, ops_js_1.entryId)(t)] || cuando;
+        const teniaPattern = new Set((antes.patterns || []).map(ops_js_1.normalizeText));
+        for (const p of final.patterns) {
+            if (!teniaPattern.has((0, ops_js_1.normalizeText)(p)))
+                await this.emit(final.id, { kind: 'pattern', text: p, at: fecha(p) });
+        }
+        const teniaError = new Set((antes.errors || []).map(ops_js_1.normalizeText));
+        for (const e of final.errors || []) {
+            if (!teniaError.has((0, ops_js_1.normalizeText)(e)))
+                await this.emit(final.id, { kind: 'error', text: e, at: fecha(e) });
+        }
+        const teniaDebt = new Set((antes.debts || []).map(ops_js_1.normalizeText));
+        for (const d of final.debts || []) {
+            if (!teniaDebt.has((0, ops_js_1.normalizeText)(d)))
+                await this.emit(final.id, { kind: 'debt', text: d, at: fecha(d) });
+        }
+        // Preferences are never emitted, here as in learn.
+        await this.deleteNeuronFile(from.id);
+        return { from: from.id, into: into.id, backup, moved };
+    }
     /**
      * Which neurons hold something that looks like a credential.
      * Reports the kind and where it is, never the value.