linksee-memory 0.17.2 → 0.18.1

package/dist/mcp/server.js

@@ -8,9 +8,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { openDb, runMigrations, DbRefusedError } from '../db/migrate.js';
 import { computeHeat } from '../lib/heat-index.js';
-import { decideForgetting } from '../lib/forgetting.js';
 import { refreshMomentumForEntity } from '../lib/momentum.js';
-import { consolidate as runConsolidate, autoConsolidateEnabled } from '../lib/consolidate.js';
+import { consolidate as runConsolidate, autoConsolidateEnabled, planConsolidate, CONSOLIDATED_SQL } from '../lib/consolidate.js';
 import { isPastedExternalContent } from '../lib/session-parser.js';
 import { inferAltitude, inferType, inferState } from '../lib/session-extractor.js';
 import { normalizeEntityName } from '../lib/normalize.js';
@@ -27,6 +26,7 @@ import { logAnchorTouch } from '../lib/anchor-touch.js';
 import { triageDistillQueue, distillPending } from '../lib/distill-triage.js';
 import { whereAmI, listMapProjects } from '../lib/map-view.js';
 import { buildShareDraft, KINDS, RUNTIMES } from '../lib/share-draft.js';
+import { parseSupersedesArg, checkSupersedes, applySupersedes, SupersedeRefused, mcpSource, byFromSource } from '../lib/supersede.js';
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -66,6 +66,7 @@ const SUBCOMMANDS = {
     'share-draft': 'share-draft.js',
     migrate: 'migrate-legacy.js', // 0.17.2: schema 1–5 → current, without starting the server
     runtime: 'runtime.js', // 0.17.2: runtime list | prune
+    consolidate: 'consolidate.js', // 0.18.1: consolidate --dry-run | --apply (marks, never deletes)
 };
 const subcommand = process.argv[2];
 if (subcommand && Object.prototype.hasOwnProperty.call(SUBCOMMANDS, subcommand)) {
@@ -100,35 +101,46 @@ try {
 catch { /* never block startup */ }
 // Auto-maintenance: consolidate stale memories on startup (non-blocking).
 //
-// OFF by default since 0.17.1 (L-1-106 / audit F1): consolidate deletes the original rows after
-// writing a summary that keeps only the top 3 × 200 characters, ignores thread_id, and cascades
-// away their edges — reasons and history lost with no action from the user. It now runs only
-// when asked: LINKSEE_AUTO_CONSOLIDATE=1 (or `--auto-consolidate` on the server command line).
-// There is no `consolidate` tool (merged away in 0.7.0). Rows already removed by earlier versions
-// are not restored.
-if (autoConsolidateEnabled(process.env, process.argv.slice(2)))
-    setTimeout(() => {
+// OFF by default (0.17.1 intended this; 0.18.1 makes it hold and takes the delete out):
+// up to 0.18.0 consolidate deleted the original rows after writing a summary that kept only the
+// top 3 × 200 characters, then a forget-sweep deleted every other cold row — reasons and history
+// lost with no action from the user (1,360 rows on 2026-10-29, 559 on 2026-11-05 on the
+// maintainer's DB). Since 0.18.1 nothing is deleted: originals are marked `consolidated_into`
+// and hidden from the default recall. It still runs only when asked: LINKSEE_AUTO_CONSOLIDATE=1
+// (or `--auto-consolidate` on the server command line); by hand: `npx linksee-memory consolidate
+// --dry-run | --apply`. When off, one stderr line says how many rows a run would fold, so a
+// growing database is noticed without anything being touched. There is no `consolidate` MCP tool
+// (merged away in 0.7.0). Rows already removed by earlier versions are not restored.
+const autoConsolidateOn = autoConsolidateEnabled(process.env, process.argv.slice(2));
+setTimeout(() => {
+    try {
+        if (!autoConsolidateOn) {
+            // Read-only: count what a run would fold. Never throws out of here, never writes.
+            const plan = planConsolidate(db, { min_age_days: 7 });
+            process.stderr.write(`[linksee-memory] auto-consolidate is off (set LINKSEE_AUTO_CONSOLIDATE=1 to enable); ${plan.wouldFold} cold memories would be folded` +
+                ` (run: npx linksee-memory consolidate --dry-run)\n`);
+            return;
+        }
+        let shouldRun = true;
         try {
-            let shouldRun = true;
-            try {
-                // Check if consolidations table exists before querying
-                const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='consolidations'").get();
-                if (tableExists) {
-                    const lastRow = db.prepare('SELECT MAX(created_at) as ts FROM consolidations').get();
-                    if (lastRow?.ts && (Date.now() / 1000 - lastRow.ts) / 86400 < 7)
-                        shouldRun = false;
-                }
-            }
-            catch {
-                shouldRun = false; /* genuinely unexpected — skip to be safe */
-            }
-            if (shouldRun) {
-                runConsolidate(db, { scope: 'all', min_age_days: 7 });
-                process.stderr.write('[linksee-memory] auto-consolidate complete\n');
+            // Check if consolidations table exists before querying
+            const tableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='consolidations'").get();
+            if (tableExists) {
+                const lastRow = db.prepare('SELECT MAX(created_at) as ts FROM consolidations').get();
+                if (lastRow?.ts && (Date.now() / 1000 - lastRow.ts) / 86400 < 7)
+                    shouldRun = false;
             }
         }
-        catch { /* non-fatal */ }
-    }, 3000);
+        catch {
+            shouldRun = false; /* genuinely unexpected — skip to be safe */
+        }
+        if (shouldRun) {
+            const r = runConsolidate(db, { scope: 'all', min_age_days: 7 });
+            process.stderr.write(`[linksee-memory] auto-consolidate complete: ${r.clustersCompressed} summaries, ${r.memoriesFolded} rows marked consolidated_into (0 deleted)\n`);
+        }
+    }
+    catch { /* non-fatal */ }
+}, 3000);
 const server = new Server({ name: 'linksee-memory', version: SERVER_VERSION }, {
     capabilities: {
         tools: {},
@@ -202,6 +214,10 @@ const TOOLS = [
                 force: { type: 'boolean', default: false, description: 'Bypass paste-back quality check.' },
                 memory_id: { type: 'number', description: 'Set to update an existing memory instead of creating. Only content/layer/importance are changed.' },
                 forget: { type: 'boolean', default: false, description: 'Set true + memory_id to delete a memory. Caveat-layer and pinned memories cannot be deleted.' },
+                supersedes: {
+                    description: 'Create mode only: the memory id(s) this new memory replaces (a reversed or updated decision). Writes a supersedes link and marks the old memory superseded; recall then hides it unless include_superseded is true. Refused — and nothing is saved — if an id does not exist, belongs to another entity, or is a raw session capture — and when content is JSON missing any of altitude/type/state (send plain text or all three).',
+                    anyOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' } }],
+                },
             },
         },
     },
@@ -226,6 +242,8 @@ const TOOLS = [
                 path: { type: 'string', description: 'File path or substring. When set, returns file edit history with per-edit user-intent context instead of memory search.' },
                 max_intents: { type: 'number', description: 'For file mode: max user-intent snippets. Default 10.', default: 10 },
                 scope_to_roots: { type: 'boolean', default: false, description: 'For file mode: filter to client-provided roots.' },
+                include_superseded: { type: 'boolean', default: false, description: 'Also return memories that a newer memory superseded (hidden by default; each carries superseded_by).' },
+                include_consolidated: { type: 'boolean', default: false, description: 'Also return memories that consolidate folded into a summary (hidden by default, still in the DB; each carries consolidated_into = the summary id).' },
                 explain: { type: 'boolean', default: false, description: 'Include ranking internals (composite, heat, band, momentum, match_reasons, score_breakdown). Off by default so more memories fit the token budget.' },
                 where: { description: 'Locate on the Current Truth Map. A topic string, or true to auto-locate from the files you edited recently. Returns your node, journey stage, blast radius, and the decision behind it.', anyOf: [{ type: 'string' }, { type: 'boolean' }] },
                 project: { type: 'string', description: 'With where: the Map project slug, when several maps are imported.' },
@@ -502,7 +520,16 @@ function handleRemember(args) {
             hint: 'If you meant to save an extracted insight from that paste, summarize it in your own words first.',
         });
     }
-    const entityId = upsertEntity({ name: args.entity_name, kind: args.entity_kind, key: args.entity_key });
+    // supersedes: parse before anything is written; a malformed value refuses the whole call.
+    let supersedeIds;
+    try {
+        supersedeIds = parseSupersedesArg(args.supersedes);
+    }
+    catch (e) {
+        if (e instanceof SupersedeRefused)
+            return JSON.stringify({ ok: false, rejected: 'supersedes', reason: e.message, saved: false });
+        throw e;
+    }
     const importance = Math.min(1, Math.max(0, Number(args.importance ?? 0.5)));
     // Auto-classify: if content is plain text (not JSON with 3-axis fields),
     // wrap it in structured JSON so VIRTUAL generated columns can extract axes.
@@ -514,6 +541,24 @@ function handleRemember(args) {
         }
     }
     catch { /* not JSON = needs wrapping */ }
+    // With supersedes, a JSON object that lacks any of altitude/type/state is refused before
+    // anything is written: it would be re-wrapped as {what: "<the JSON>"} and its state re-guessed,
+    // so an explicit state in it could not be honoured or even confirmed. No clever rescue —
+    // plain text, or JSON with all three, only.
+    if (supersedeIds.length > 0 && !isAlreadyStructured) {
+        let parsedObj = false;
+        try {
+            const p = JSON.parse(rawContent);
+            parsedObj = p !== null && typeof p === 'object';
+        }
+        catch { /* plain text */ }
+        if (parsedObj) {
+            return JSON.stringify({
+                ok: false, rejected: 'supersedes', saved: false,
+                reason: 'with supersedes, content must be plain text or JSON with all of altitude, type and state. This JSON lacks at least one, so its state cannot be confirmed. Send the content as plain text, or add altitude/type/state, and save again.',
+            });
+        }
+    }
     if (!isAlreadyStructured) {
         const structured = {
             altitude: inferAltitude(rawContent),
@@ -523,20 +568,97 @@ function handleRemember(args) {
         };
         rawContent = JSON.stringify(structured);
     }
-    const result = db
-        .prepare('INSERT INTO memories (entity_id, layer, content, importance, protected, thread_id) VALUES (?, ?, ?, ?, ?, ?)')
-        .run(entityId, layer, rawContent, importance, importance >= 0.9 ? 1 : 0, args.thread_id ?? null);
-    db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)').run(entityId, 'memory_stored', JSON.stringify({ layer, memory_id: result.lastInsertRowid }));
-    const mom = refreshMomentumForEntity(db, entityId);
-    const memoryId = Number(result.lastInsertRowid);
+    // A memory that names what it supersedes IS the current decision.
+    //  • State GUESSED from the text (inferState reads 「代わりに」 / "replaced" — words about the
+    //    OLD decision — as this row being superseded): corrected to 'decided', and the reply says so.
+    //  • State given EXPLICITLY as 'superseded' together with supersedes: the two contradict each
+    //    other and we cannot tell which one the caller meant, so nothing is written.
+    let stateNote;
+    if (supersedeIds.length > 0) {
+        let c;
+        try {
+            c = JSON.parse(rawContent);
+        }
+        catch {
+            c = null; /* structured above, always JSON */
+        }
+        if (c && typeof c === 'object' && c.state === 'superseded') {
+            if (isAlreadyStructured) {
+                return JSON.stringify({
+                    ok: false, rejected: 'supersedes', saved: false,
+                    reason: 'content says state "superseded" but the memory also supersedes another one — a memory that replaces an older one is the current one. Remove state "superseded" (or set the state you mean) and save again.',
+                });
+            }
+            c.state = 'decided';
+            rawContent = JSON.stringify(c);
+            stateNote = 'the state guessed from the text was "superseded"; stored as "decided" because this memory supersedes another one';
+        }
+    }
+    // Who wrote it: the client name/version the MCP host sent in initialize (self-reported).
+    const source = mcpSource(server.getClientVersion());
+    // Entity, row, event, supersedes edges and the old rows' state change commit together or not
+    // at all: if any supersedes id cannot be confirmed, nothing — not even a new entity — is left.
+    let entityId, memoryId, supersededAnchors = [];
+    try {
+        ({ entityId, memoryId, supersededAnchors } = db.transaction(() => {
+            const eid = upsertEntity({ name: args.entity_name, kind: args.entity_kind, key: args.entity_key });
+            const result = db
+                .prepare('INSERT INTO memories (entity_id, layer, content, importance, protected, source, thread_id) VALUES (?, ?, ?, ?, ?, ?, ?)')
+                .run(eid, layer, rawContent, importance, importance >= 0.9 ? 1 : 0, source, args.thread_id ?? null);
+            const mid = Number(result.lastInsertRowid);
+            // Checked after the INSERT so a self-reference is seen as one (the id exists only now);
+            // a refusal throws and the transaction rolls the INSERT back.
+            const oldRows = supersedeIds.length > 0 ? checkSupersedes(db, supersedeIds, eid, mid) : [];
+            if (oldRows.length > 0)
+                applySupersedes(db, mid, oldRows);
+            db.prepare('INSERT INTO events (entity_id, kind, payload) VALUES (?, ?, ?)').run(eid, 'memory_stored', JSON.stringify(supersedeIds.length > 0 ? { layer, memory_id: mid, supersedes: supersedeIds } : { layer, memory_id: mid }));
+            const anchors = [];
+            for (const r of oldRows) {
+                try {
+                    const c = JSON.parse(r.content);
+                    if (c && Number.isInteger(c.anchor_id))
+                        anchors.push(c.anchor_id);
+                }
+                catch { /* plain text */ }
+            }
+            return { entityId: eid, memoryId: mid, supersededAnchors: anchors };
+        })());
+    }
+    catch (e) {
+        if (e instanceof SupersedeRefused) {
+            return JSON.stringify({ ok: false, rejected: 'supersedes', memory_id: e.memoryId, reason: e.message, saved: false });
+        }
+        throw e;
+    }
+    // The memory is committed from here on. Helpers that fail after this point must not turn a
+    // saved memory into ok:false — the caller would retry and save it twice.
+    const warnings = [];
+    let mom = null;
+    try {
+        mom = refreshMomentumForEntity(db, entityId);
+    }
+    catch (e) {
+        warnings.push(`saved, but the momentum refresh failed: ${String(e?.message ?? e).slice(0, 200)}`);
+    }
     const out = {
         ok: true,
         memory_id: memoryId,
         entity_id: entityId,
         layer,
         pinned: importance >= 0.9,
-        momentum: { score: mom.score, band: mom.band },
+        ...(mom ? { momentum: { score: mom.score, band: mom.band } } : {}),
     };
+    if (warnings.length > 0)
+        out.warnings = warnings;
+    if (supersedeIds.length > 0)
+        out.supersedes = supersedeIds;
+    if (stateNote)
+        out.state_note = stateNote;
+    if (supersededAnchors.length > 0) {
+        // The memory link does not touch the gate. Say so instead of retiring an anchor on our own.
+        out.anchors_still_enforced = supersededAnchors;
+        out.anchor_hint = `The superseded memory is enforced as anchor ${supersededAnchors.map((a) => '#' + a).join(', ')}; the gate still applies it. To retire it: resolve_drift({ anchor_id, action: 'supersede', superseded_by: <new anchor id> }).`;
+    }
     // "Remember" and "enforce" used to be two tools with two schemas, and an agent had to pick.
     // Picking remember meant the decision was stored but never re-injected — the exact failure
     // the product exists to prevent. One call now does both when the caller asks for it.
@@ -631,12 +753,33 @@ function appendAxisFilters(sql, params, filters) {
     }
     return sql;
 }
-function runFtsQuery(query, layer, limit, axis) {
+// NULL-safe: plain-text rows and JSON without a state have mem_state NULL, and
+// `NOT (NULL = 'superseded' OR …)` is NULL — which would drop them (Codex review 2 of #21).
+const SUPERSEDED_SQL = `(COALESCE(m.mem_state, '') = 'superseded' OR EXISTS (SELECT 1 FROM memory_edges me WHERE me.to_memory_id = m.id AND me.relation = 'supersedes'))`;
+const SHOW_ALL = { sup: 'include', con: 'include' };
+function appendSupersededFilter(sql, mode) {
+    if (mode === 'exclude')
+        return sql + ` AND NOT ${SUPERSEDED_SQL}`;
+    if (mode === 'only')
+        return sql + ` AND ${SUPERSEDED_SQL}`;
+    return sql;
+}
+function appendConsolidatedFilter(sql, mode) {
+    if (mode === 'exclude')
+        return sql + ` AND NOT ${CONSOLIDATED_SQL}`;
+    if (mode === 'only')
+        return sql + ` AND ${CONSOLIDATED_SQL}`;
+    return sql;
+}
+function appendHiddenFilters(sql, h) {
+    return appendConsolidatedFilter(appendSupersededFilter(sql, h.sup), h.con);
+}
+function runFtsQuery(query, layer, limit, axis, hidden = SHOW_ALL) {
     let sql = `
     SELECT m.id, m.entity_id, e.name as entity_name, e.kind as entity_kind, e.momentum_score,
            m.layer, m.content, m.importance, m.created_at, m.last_accessed_at, m.access_count,
            m.altitude as _altitude, m.mem_type as _mem_type, m.mem_state as _mem_state, m.thread_id as _thread_id,
-           bm25(memories_fts) as bm25_score
+           m.source as _source, bm25(memories_fts) as bm25_score
     FROM memories_fts
     JOIN memories m ON m.id = memories_fts.rowid
     JOIN entities e ON e.id = m.entity_id
@@ -649,16 +792,17 @@ function runFtsQuery(query, layer, limit, axis) {
     }
     if (axis)
         sql = appendAxisFilters(sql, params, axis);
+    sql = appendHiddenFilters(sql, hidden);
     sql += ' ORDER BY bm25_score ASC LIMIT ?';
     params.push(limit);
     return db.prepare(sql).all(...params);
 }
-function runLikeQuery(query, entityName, layer, limit, axis) {
+function runLikeQuery(query, entityName, layer, limit, axis, hidden = SHOW_ALL) {
     let sql = `
     SELECT m.id, m.entity_id, e.name as entity_name, e.kind as entity_kind, e.momentum_score,
            m.layer, m.content, m.importance, m.created_at, m.last_accessed_at, m.access_count,
            m.altitude as _altitude, m.mem_type as _mem_type, m.mem_state as _mem_state, m.thread_id as _thread_id,
-           0 as bm25_score
+           m.source as _source, 0 as bm25_score
     FROM memories m
     JOIN entities e ON e.id = m.entity_id
     WHERE 1=1
@@ -674,6 +818,7 @@ function runLikeQuery(query, entityName, layer, limit, axis) {
     }
     if (axis)
         sql = appendAxisFilters(sql, params, axis);
+    sql = appendHiddenFilters(sql, hidden);
     if (query && !entityName) {
         sql += ' AND (e.name LIKE ? OR m.content LIKE ?)';
         params.push(`%${query}%`, `%${query}%`);
@@ -727,6 +872,13 @@ function contentSignature(raw, entityId) {
         return ''; // too short to dedup safely
     return `${entityId}::${norm}`;
 }
+// The summary id a folded row points at (0.18.1), or undefined for an unfolded / plain-text row.
+function consolidatedIntoOf(parsedContent) {
+    if (!parsedContent || typeof parsedContent !== 'object' || Array.isArray(parsedContent))
+        return undefined;
+    const v = parsedContent.consolidated_into;
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
 function handleRecall(args) {
     // max_tokens is enforced for real at assembly time (greedy fill by measured
     // serialized size), not via a crude fixed per-memory estimate. hardLimit caps COUNT.
@@ -750,9 +902,37 @@ function handleRecall(args) {
     let searchMethod = 'like';
     const ftsQuery = toFtsQuery(args.query ?? '');
     const canUseFts = !!ftsQuery && !args.entity_name;
+    // Superseded rows are left out in SQL by default; asking for them (include_superseded, or
+    // mem_state:'superseded') keeps them. The hidden ones are counted with the same filters.
+    const showSuperseded = args?.include_superseded === true || axis.mem_state === 'superseded';
+    // Consolidated rows (0.18.1: marked `consolidated_into`, kept in the table) are hidden the
+    // same way; include_consolidated shows them. The two counts do not overlap: a row that is
+    // both superseded and consolidated is counted once, under superseded.
+    const showConsolidated = args?.include_consolidated === true;
+    const sup = showSuperseded ? 'include' : 'exclude';
+    const con = showConsolidated ? 'include' : 'exclude';
+    const hidden = { sup, con };
+    const HIDDEN_COUNT_CAP = 1000;
+    const countHidden = (h) => {
+        const hiddenIds = new Set();
+        if (canUseFts) {
+            for (const r of runFtsQuery(ftsQuery, layer, HIDDEN_COUNT_CAP, axis, h))
+                hiddenIds.add(r.id);
+            for (const r of runLikeQuery(args.query, undefined, layer, HIDDEN_COUNT_CAP, axis, h))
+                hiddenIds.add(r.id);
+        }
+        else {
+            for (const r of runLikeQuery(args.query, args.entity_name, layer, HIDDEN_COUNT_CAP, axis, h))
+                hiddenIds.add(r.id);
+        }
+        return hiddenIds.size;
+    };
+    const supersededHidden = showSuperseded ? 0 : countHidden({ sup: 'only', con: 'include' });
+    const consolidatedHidden = showConsolidated ? 0 : countHidden({ sup, con: 'only' });
+    const capped = (n) => (n >= HIDDEN_COUNT_CAP ? `${HIDDEN_COUNT_CAP}+` : n);
     if (canUseFts) {
-        const ftsRows = runFtsQuery(ftsQuery, layer, fetchLimit, axis);
-        const likeRows = runLikeQuery(args.query, undefined, layer, fetchLimit, axis);
+        const ftsRows = runFtsQuery(ftsQuery, layer, fetchLimit, axis, hidden);
+        const likeRows = runLikeQuery(args.query, undefined, layer, fetchLimit, axis, hidden);
         const seen = new Map();
         for (const r of ftsRows)
             seen.set(r.id, { ...r, _via: 'fts' });
@@ -773,7 +953,7 @@ function handleRecall(args) {
             searchMethod = 'like';
     }
     else {
-        rows = runLikeQuery(args.query, args.entity_name, layer, fetchLimit, axis).map((r) => ({ ...r, _via: 'like' }));
+        rows = runLikeQuery(args.query, args.entity_name, layer, fetchLimit, axis, hidden).map((r) => ({ ...r, _via: 'like' }));
         searchMethod = 'like';
     }
     const useFts = searchMethod !== 'like';
@@ -868,8 +1048,27 @@ function handleRecall(args) {
             },
         };
     });
+    // Supersedes links among the candidates, both directions (indexed on both columns).
+    const supersededBy = new Map(); // old id → newest id that supersedes it
+    const supersedesOf = new Map(); // new id → old ids
+    const allIds = scored.map((r) => r.id);
+    for (let i = 0; i < allIds.length; i += 400) { // chunked: offset can make the pool large
+        const ids = allIds.slice(i, i + 400);
+        const ph = ids.map(() => '?').join(',');
+        const links = db.prepare(`SELECT from_memory_id AS f, to_memory_id AS t FROM memory_edges
+        WHERE relation = 'supersedes' AND (from_memory_id IN (${ph}) OR to_memory_id IN (${ph}))
+        ORDER BY from_memory_id ASC`).all(...ids, ...ids);
+        for (const l of links) {
+            if (supersededBy.has(l.t) && (supersedesOf.get(l.f) ?? []).includes(l.t))
+                continue; // seen in an earlier chunk
+            supersededBy.set(l.t, Math.max(supersededBy.get(l.t) ?? 0, l.f));
+            supersedesOf.set(l.f, [...(supersedesOf.get(l.f) ?? []), l.t]);
+        }
+    }
+    // Superseded rows were already left out in SQL (before the LIMIT) unless asked for.
+    const visible = scored;
     // Apply band filter AFTER scoring (needs heat.band)
-    const filtered = band ? scored.filter((s) => s.heat_band === band) : scored;
+    const filtered = band ? visible.filter((s) => s.heat_band === band) : visible;
     // Sort by composite (best first)
     filtered.sort((a, b) => b.composite_score - a.composite_score);
     // Dedup near-identical memories (same entity + near-identical core text).
@@ -922,6 +1121,11 @@ function handleRecall(args) {
             content: parsedContent,
             importance: r.importance,
             pinned: r.importance >= 0.9,
+            // One short field each, only when the row has it (no tokens spent on absence).
+            ...(byFromSource(r._source) ? { by: byFromSource(r._source) } : {}),
+            ...(supersedesOf.has(r.id) ? { supersedes: supersedesOf.get(r.id).map((x) => `#${x}`).join(' ') } : {}),
+            ...(supersededBy.has(r.id) ? { superseded_by: supersededBy.get(r.id) } : {}),
+            ...(consolidatedIntoOf(parsedContent) !== undefined ? { consolidated_into: consolidatedIntoOf(parsedContent) } : {}),
             // Ranking internals only on request — they roughly double the per-memory cost and an
             // agent acting on the memory needs what/why/state, not the scorer's arithmetic.
             ...(args?.explain ? {
@@ -966,6 +1170,8 @@ function handleRecall(args) {
             type: axis.mem_type ?? null,
             state: axis.mem_state ?? null,
         },
+        ...(supersededHidden > 0 ? { superseded_hidden: capped(supersededHidden), superseded_hint: 'include_superseded: true to show them' } : {}),
+        ...(consolidatedHidden > 0 ? { consolidated_hidden: capped(consolidatedHidden), consolidated_hint: 'include_consolidated: true to show them (rows folded into a summary; still in the DB)' } : {}),
         memories: memoriesOut,
     });
 }
@@ -990,82 +1196,28 @@ function handleForget(args) {
         const res = db.prepare('DELETE FROM memories WHERE id = ?').run(args.memory_id);
         return JSON.stringify({ ok: true, deleted: res.changes, memory_id: args.memory_id });
     }
-    // Auto-sweep — also respect pin (importance >= 0.9) as protection
-    const rows = db
-        .prepare(`SELECT id, layer, importance, access_count, last_accessed_at, protected, altitude
-              FROM memories
-              WHERE protected = 0 AND importance < 0.9`)
-        .all();
-    const now = Math.floor(Date.now() / 1000);
-    const actions = [];
-    for (const r of rows) {
-        const daysSince = (now - r.last_accessed_at) / 86400;
-        const heat = computeHeat({
-            accessesLast30d: daysSince < 30 ? r.access_count : 0,
-            accessesLast90d: daysSince < 90 ? r.access_count : 0,
-            daysSinceLastAccess: daysSince,
-            totalAccesses: r.access_count,
-            baseImportance: r.importance,
-        });
-        const action = decideForgetting({
-            daysSinceLastAccess: daysSince,
-            importance: r.importance,
-            heatScore: heat.score,
-            protected: r.protected === 1,
-            layer: r.layer,
-            altitude: r.altitude ?? undefined,
-        });
-        if (action !== 'keep')
-            actions.push({ id: r.id, action });
-    }
-    const toDropIds = actions.filter((a) => a.action === 'drop').map((a) => a.id);
-    if (!args.dry_run) {
-        const del = db.prepare('DELETE FROM memories WHERE id = ?');
-        const tx = db.transaction((ids) => { for (const id of ids)
-            del.run(id); });
-        tx(toDropIds);
-    }
-    return JSON.stringify({
-        ok: true,
-        dry_run: !!args.dry_run,
-        scanned: rows.length,
-        to_drop: toDropIds.length,
-        to_compress: actions.filter((a) => a.action === 'compress').length,
-        sample_ids_to_drop: toDropIds.slice(0, 10),
-    });
+    // 0.18.1: the id-less auto-sweep that used to follow here (DELETE every row whose forgetting
+    // score crossed a threshold) is removed. No caller reached it; it is gone so that the only
+    // memory DELETE in the server is the explicit one above.
+    return JSON.stringify({ ok: false, error: 'memory_id required: forget deletes one memory by id; there is no sweep' });
 }
 function handleConsolidate(args) {
     const dryRun = !!args?.dry_run;
     if (dryRun) {
-        // Preview: simulate by running against a transaction we roll back
-        // We don't have a clean "preview" path in lib/consolidate, so do a best-effort
-        // read-only audit: count candidates using the same rules.
-        const now = Math.floor(Date.now() / 1000);
-        const ageCutoff = now - (args.min_age_days ?? 7) * 86400;
-        const candidates = db.prepare(`
-      SELECT m.entity_id, e.name as entity_name, m.layer, COUNT(*) as c
-      FROM memories m
-      JOIN entities e ON e.id = m.entity_id
-      WHERE m.protected = 0
-        AND m.importance < 0.9
-        AND m.layer IN ('context', 'emotion', 'implementation')
-        AND m.created_at <= ?
-      GROUP BY m.entity_id, m.layer
-      HAVING c >= 2
-      ORDER BY c DESC
-    `).all(ageCutoff);
-        const totalReplaced = candidates.reduce((s, c) => s + c.c, 0);
+        // Read-only preview, the same plan `--apply` would act on (0.18.1).
+        const plan = planConsolidate(db, { min_age_days: typeof args?.min_age_days === 'number' ? args.min_age_days : undefined });
         return JSON.stringify({
             ok: true,
             dry_run: true,
-            clusters: candidates.length,
-            memories_replaced_if_run: totalReplaced,
-            preview: candidates.slice(0, 20).map((c) => ({
+            clusters: plan.clusters.length,
+            memories_folded_if_run: plan.wouldFold,
+            deleted_if_run: 0,
+            preview: plan.clusters.slice(0, 20).map((c) => ({
                 entity: c.entity_name,
                 layer: c.layer,
-                count: c.c,
+                count: c.ids.length,
             })),
-            hint: 'Set dry_run=false to actually consolidate.',
+            hint: 'Set dry_run=false to consolidate (originals are kept and marked consolidated_into).',
         });
     }
     const result = runConsolidate(db, {
@@ -1384,6 +1536,9 @@ async function handleRememberUnified(args) {
     }
     // Update mode
     if (args.memory_id) {
+        if (args.supersedes !== undefined && args.supersedes !== null) {
+            return JSON.stringify({ ok: false, rejected: 'supersedes', reason: 'supersedes applies when creating a memory, not when updating one (memory_id). Remember the new decision without memory_id and pass supersedes: <old id>.', saved: false });
+        }
         return handleUpdateMemory(args);
     }
     // Create mode (default). Only content is required; everything an agent used to have to