linksee-memory 0.17.2 → 0.18.0

package/README.md

@@ -21,6 +21,8 @@ A new install has an empty memory, so "how did we solve this before?" finds noth
 
 1. In Claude Code or Codex, say: *"Remember: in this repo we decided to use X, because Y. Use Linksee."*
 2. Open a **new** session — in either one — and ask: *"What did we decide about X? Use Linksee."*
+3. Two repos: record a decision in repo A, then in repo B (e.g. Codex) ask the same. It **does** come back — the memory is per machine, not per repo — labelled `entity: repo-a` and `by: <client>`; `entity_name` on the recall narrows by a part of the entity name (`repo-a` also matches `repo-a-backup`).
+4. Reverse it: `remember` the new decision with `supersedes: <old memory_id>`. `recall` then shows only the new one (`supersedes #<id>`); `include_superseded: true` shows both.
 
 ## What it does not do
 
@@ -100,7 +102,7 @@ an agent can hold without a manual.
 | Tool | What it does |
 |---|---|
 | `recall` | **Start here.** No arguments → the **session brief**: what needs attention, where you are on the Map, open loops, top entities. `query` → search; `path` → a file's edit history with the user intent behind each edit; `where: "<topic>"` → your position on the Current Truth Map + blast radius; `dream: true` → the triage session (North Star, orphaned proposals, distill queue, friction). |
-| `remember` | **Save / update / delete.** `content` is the only required field — entity and layer default to the project you're in. Add `anchor: {}` to also record it as a decision (in Claude Code, re-injected on session start and before a matching Edit/Write/Bash); add `violation_signal` to it so a contradicting edit can be detected. |
+| `remember` | **Save / update / delete.** `content` is the only required field — entity and layer default to the project you're in. Add `anchor: {}` to also record it as a decision (in Claude Code, re-injected on session start and before a matching Edit/Write/Bash); add `violation_signal` to it so a contradicting edit can be detected. `supersedes: <id>` replaces an older memory of the same entity (recall hides the old one). |
 | `read_smart` | **Token-saving file reader** with AST diff caching. Re-read unchanged = ~50 tokens; modified = changed chunks only. |
 | `drift_status` | **"What's drifting right now?"** The truth map: 🔴 drift / 🟡 review / ⚪ held / 🔵 verified / ⚫ unverified, with the evidence for each. `anchor_id` → deep-dive into one decision. |
 | `declare_anchor` | **Record a normative claim** — `decision` / `prohibition` / `constraint` the detector checks against reality, or `proposal`: an option you presented that the user never addressed, parked as a review item. |

package/dist/bin/import-sessions.js

@@ -79,7 +79,17 @@ async function main() {
     const scanAll = args.includes('--all');
     const sessionFileIdx = args.indexOf('--session-file');
     const sessionFile = sessionFileIdx >= 0 ? args[sessionFileIdx + 1] : null;
-    const projectArgs = args.filter((a, i) => !a.startsWith('--') && (sessionFileIdx < 0 || i !== sessionFileIdx + 1));
+    // --via stop-hook is passed by sync-session (the Claude Code Stop hook). Anything else is a
+    // manual or batch import. Recorded in memories.source next to the session keys (0.18.0).
+    const viaIdx = args.indexOf('--via');
+    const via = viaIdx >= 0 && args[viaIdx + 1] === 'stop-hook' ? 'stop-hook' : 'import';
+    const projectArgs = args.filter((a, i) => !a.startsWith('--')
+        && (sessionFileIdx < 0 || i !== sessionFileIdx + 1)
+        && (viaIdx < 0 || i !== viaIdx + 1));
+    // The session keys are kept as they were: wipeSession and makeDistilledTurnSet find these rows
+    // by the substring `"session_id":"…"` (position does not matter, the exact text does).
+    // Known, not changed here: wipeSession runs outside the re-insert transaction.
+    const sourceJson = (src) => JSON.stringify({ ...src, client: 'claude-code', via });
     // Single-file mode (used by the Stop hook)
     if (sessionFile) {
         const db = dryRun ? null : openDb();
@@ -137,7 +147,7 @@ async function main() {
             for (const m of result.memories) {
                 if (m.source.turn_uuid && distilledTurns.has(m.source.turn_uuid))
                     continue; // distilled rewrite wins
-                const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, JSON.stringify(m.source), m.thread_id ?? null, m.occurred_at ?? Math.floor(Date.now() / 1000));
+                const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, sourceJson(m.source), m.thread_id ?? null, m.occurred_at ?? Math.floor(Date.now() / 1000));
                 memContentToId.set(m.content, Number(res.lastInsertRowid));
                 inserted.memories++;
             }
@@ -263,7 +273,7 @@ async function main() {
                 for (const m of result.memories) {
                     if (m.source.turn_uuid && distilledTurns.has(m.source.turn_uuid))
                         continue; // distilled rewrite wins
-                    const srcJson = JSON.stringify(m.source);
+                    const srcJson = sourceJson(m.source);
                     const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, srcJson, m.thread_id ?? null, m.occurred_at ?? Math.floor(Date.now() / 1000));
                     memContentToId.set(m.content, Number(res.lastInsertRowid));
                     agg.memories_inserted++;

package/dist/bin/sync-session.js

@@ -77,7 +77,7 @@ async function main() {
         log(`transcript missing: ${transcriptPath}`);
         process.exit(0);
     }
-    const r = spawnSync(process.execPath, [importerPath, '--session-file', transcriptPath], {
+    const r = spawnSync(process.execPath, [importerPath, '--session-file', transcriptPath, '--via', 'stop-hook'], {
         encoding: 'utf8',
         timeout: 30000,
     });

package/dist/lib/supersede.d.ts

@@ -0,0 +1,35 @@
+import type Database from 'better-sqlite3';
+export declare const MAX_SUPERSEDES = 20;
+export declare class SupersedeRefused extends Error {
+    readonly memoryId: number | null;
+    readonly reason: string;
+    constructor(memoryId: number | null, reason: string);
+}
+/** Normalize the `supersedes` argument to a de-duplicated list of positive integers, or throw. */
+export declare function parseSupersedesArg(raw: unknown): number[];
+interface OldRow {
+    id: number;
+    entity_id: number;
+    content: string;
+    source: string | null;
+}
+/**
+ * Check every id against the DB. Throws SupersedeRefused on the first id that cannot be
+ * confirmed. Call inside the same transaction as the INSERT so the check and the write agree.
+ */
+export declare function checkSupersedes(db: Database.Database, ids: number[], entityId: number, newId?: number): OldRow[];
+/**
+ * Write the edges (new → old, relation 'supersedes') and mark each old row superseded.
+ * JSON content: state → 'superseded' and superseded_by → newId (same representation the edge
+ * detector and distill triage already use). Plain-text content is left as written; the edge
+ * alone is what recall folds on.
+ */
+export declare function applySupersedes(db: Database.Database, newId: number, rows: OldRow[]): void;
+/** source JSON for a row written through MCP. clientInfo is what the host sent in initialize. */
+export declare function mcpSource(clientInfo: {
+    name?: unknown;
+    version?: unknown;
+} | undefined | null): string;
+/** Short "by" label for recall. Only what the row itself recorded; never inferred. */
+export declare function byFromSource(source: string | null | undefined): string | undefined;
+export {};

package/dist/lib/supersede.js

@@ -0,0 +1,130 @@
+// Reversal and attribution for memories (0.18.0).
+//
+// Two of the four cases an outside developer named (Discussion #16) where decision memory breaks:
+//   1. Reversal — "we decided X" then "no, Y". Before 0.18 nothing wrote a `supersedes` edge, so
+//      recall returned both and ranked by recency/score. Now `remember({ supersedes })` writes the
+//      edge and marks the old row; recall folds it unless asked.
+//   2. Who said it — `memories.source` was never filled from the MCP side. Now each new row
+//      records the client name/version the MCP host sent in `initialize` (self-reported, not proof).
+//
+// Rules (fail-closed): an id that does not exist, the new row itself, a row of another entity,
+// or a row the next session import will rewrite (raw Stop-hook capture) is refused, and nothing
+// is written — no new row, no edge, no state change.
+export const MAX_SUPERSEDES = 20;
+export class SupersedeRefused extends Error {
+    memoryId;
+    reason;
+    constructor(memoryId, reason) {
+        super(reason);
+        this.memoryId = memoryId;
+        this.reason = reason;
+        this.name = 'SupersedeRefused';
+    }
+}
+/** Normalize the `supersedes` argument to a de-duplicated list of positive integers, or throw. */
+export function parseSupersedesArg(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    const list = Array.isArray(raw) ? raw : [raw];
+    if (list.length === 0)
+        return [];
+    if (list.length > MAX_SUPERSEDES) {
+        throw new SupersedeRefused(null, `supersedes takes at most ${MAX_SUPERSEDES} ids (got ${list.length})`);
+    }
+    const out = [];
+    for (const v of list) {
+        const n = typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v.trim()) : v;
+        if (typeof n !== 'number' || !Number.isSafeInteger(n) || n <= 0) {
+            throw new SupersedeRefused(null, `supersedes must be memory ids (positive integers); got ${JSON.stringify(v)}`);
+        }
+        if (!out.includes(n))
+            out.push(n);
+    }
+    return out;
+}
+/**
+ * Check every id against the DB. Throws SupersedeRefused on the first id that cannot be
+ * confirmed. Call inside the same transaction as the INSERT so the check and the write agree.
+ */
+export function checkSupersedes(db, ids, entityId, newId) {
+    const get = db.prepare('SELECT id, entity_id, content, source FROM memories WHERE id = ?');
+    const rows = [];
+    for (const id of ids) {
+        if (newId !== undefined && id === newId)
+            throw new SupersedeRefused(id, `memory #${id} is the memory being written — a memory cannot supersede itself`);
+        const row = get.get(id);
+        if (!row)
+            throw new SupersedeRefused(id, `memory #${id} does not exist`);
+        if (row.entity_id !== entityId) {
+            throw new SupersedeRefused(id, `memory #${id} belongs to another entity (entity_id ${row.entity_id}, this one is ${entityId}) — pass the same entity_name, or remember it under that entity`);
+        }
+        if (isRawSessionCapture(row)) {
+            throw new SupersedeRefused(id, `memory #${id} is a raw capture from a Claude Code session; the next import of that session rewrites it with a new id, so the link would not last. Rewrite it first with remember({ memory_id: ${id}, content: { ..., "distilled": true } }) — distilled rows survive re-import — then supersede it`);
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+/** Raw Stop-hook / batch-import row (source carries a session_id) that has not been distilled. */
+function isRawSessionCapture(row) {
+    if (!row.source)
+        return false;
+    let src;
+    try {
+        src = JSON.parse(row.source);
+    }
+    catch {
+        return false;
+    }
+    if (!src || typeof src !== 'object' || typeof src.session_id !== 'string')
+        return false;
+    try {
+        const c = JSON.parse(row.content);
+        if (c && typeof c === 'object' && (c.distilled === true || c.distilled === 1))
+            return false;
+    }
+    catch { /* plain text → not distilled */ }
+    return true;
+}
+/**
+ * Write the edges (new → old, relation 'supersedes') and mark each old row superseded.
+ * JSON content: state → 'superseded' and superseded_by → newId (same representation the edge
+ * detector and distill triage already use). Plain-text content is left as written; the edge
+ * alone is what recall folds on.
+ */
+export function applySupersedes(db, newId, rows) {
+    const edge = db.prepare(`INSERT OR IGNORE INTO memory_edges (from_memory_id, to_memory_id, relation) VALUES (?, ?, 'supersedes')`);
+    const mark = db.prepare(`UPDATE memories SET content = json_set(content, '$.state', 'superseded', '$.superseded_by', ?)
+      WHERE id = ? AND json_valid(content) AND json_type(content) = 'object'`);
+    for (const r of rows) {
+        edge.run(newId, r.id);
+        mark.run(newId, r.id);
+    }
+}
+// ── Attribution ──────────────────────────────────────────────────────────────
+const clean = (s, max) => String(s ?? '').replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, max);
+/** source JSON for a row written through MCP. clientInfo is what the host sent in initialize. */
+export function mcpSource(clientInfo) {
+    const name = clientInfo ? clean(clientInfo.name, 64) : '';
+    if (!name)
+        return JSON.stringify({ client: 'unknown', via: 'mcp' });
+    const version = clientInfo ? clean(clientInfo.version, 32) : '';
+    return JSON.stringify(version ? { client: name, version, via: 'mcp' } : { client: name, via: 'mcp' });
+}
+/** Short "by" label for recall. Only what the row itself recorded; never inferred. */
+export function byFromSource(source) {
+    if (!source)
+        return undefined;
+    try {
+        const s = JSON.parse(source);
+        if (s && typeof s === 'object') {
+            if (typeof s.client === 'string' && s.client)
+                return s.client;
+            if (typeof s.origin === 'string' && s.origin)
+                return s.origin;
+        }
+    }
+    catch { /* legacy plain-text source */ }
+    return undefined;
+}
+//# sourceMappingURL=supersede.js.map

package/dist/mcp/server.js

@@ -27,6 +27,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';
@@ -202,6 +203,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 +231,7 @@ 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).' },
                 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 +508,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 +529,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 +556,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 +741,22 @@ 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'))`;
+function appendSupersededFilter(sql, mode) {
+    if (mode === 'exclude')
+        return sql + ` AND NOT ${SUPERSEDED_SQL}`;
+    if (mode === 'only')
+        return sql + ` AND ${SUPERSEDED_SQL}`;
+    return sql;
+}
+function runFtsQuery(query, layer, limit, axis, sup = 'include') {
     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 +769,17 @@ function runFtsQuery(query, layer, limit, axis) {
     }
     if (axis)
         sql = appendAxisFilters(sql, params, axis);
+    sql = appendSupersededFilter(sql, sup);
     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, sup = 'include') {
     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 +795,7 @@ function runLikeQuery(query, entityName, layer, limit, axis) {
     }
     if (axis)
         sql = appendAxisFilters(sql, params, axis);
+    sql = appendSupersededFilter(sql, sup);
     if (query && !entityName) {
         sql += ' AND (e.name LIKE ? OR m.content LIKE ?)';
         params.push(`%${query}%`, `%${query}%`);
@@ -750,9 +872,29 @@ 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';
+    const sup = showSuperseded ? 'include' : 'exclude';
+    const HIDDEN_COUNT_CAP = 1000;
+    let supersededHidden = 0;
+    if (!showSuperseded) {
+        const hiddenIds = new Set();
+        if (canUseFts) {
+            for (const r of runFtsQuery(ftsQuery, layer, HIDDEN_COUNT_CAP, axis, 'only'))
+                hiddenIds.add(r.id);
+            for (const r of runLikeQuery(args.query, undefined, layer, HIDDEN_COUNT_CAP, axis, 'only'))
+                hiddenIds.add(r.id);
+        }
+        else {
+            for (const r of runLikeQuery(args.query, args.entity_name, layer, HIDDEN_COUNT_CAP, axis, 'only'))
+                hiddenIds.add(r.id);
+        }
+        supersededHidden = hiddenIds.size;
+    }
     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, sup);
+        const likeRows = runLikeQuery(args.query, undefined, layer, fetchLimit, axis, sup);
         const seen = new Map();
         for (const r of ftsRows)
             seen.set(r.id, { ...r, _via: 'fts' });
@@ -773,7 +915,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, sup).map((r) => ({ ...r, _via: 'like' }));
         searchMethod = 'like';
     }
     const useFts = searchMethod !== 'like';
@@ -868,8 +1010,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 +1083,10 @@ 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) } : {}),
             // 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 +1131,7 @@ function handleRecall(args) {
             type: axis.mem_type ?? null,
             state: axis.mem_state ?? null,
         },
+        ...(supersededHidden > 0 ? { superseded_hidden: supersededHidden >= HIDDEN_COUNT_CAP ? `${HIDDEN_COUNT_CAP}+` : supersededHidden, superseded_hint: 'include_superseded: true to show them' } : {}),
         memories: memoriesOut,
     });
 }
@@ -1384,6 +1550,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

package/dist/skill/SKILL.md

@@ -155,7 +155,7 @@ open → decided → in_progress → done
 |---|---|---|
 | `affects` | string[] | File paths or areas this touches. Critical for future `recall_file` accuracy |
 | `next_action` | string / null | What should happen next. Null if done/completed |
-| `supersedes_id` | number / null | Memory ID this replaces (builds pivot chains) |
+| `supersedes_id` | number / null | Memory ID this replaces. Content only — the link that recall acts on is the `remember` argument `supersedes: <id>` (0.18.0) |
 | `prior_belief` | string | What we used to think (for learnings — enables belief-update tracking) |
 | `evidence_refs` | object[] | Links to evidence: `{"type": "session"|"file"|"url", "id": "...", "label": "..."}`. Store as REFERENCES, never inline the full content |
 
@@ -435,7 +435,7 @@ User: "Let's switch to Stripe for payments"
    → Look for: type="decision", state="decided" memories on the same topic
 2. If past decision found:
    a. Tell user: "Previously we decided <X> because <reason>. Override?"
-   b. If user confirms override → use supersedes_id to link to old decision
+   b. If user confirms override → `remember({ content, supersedes: <old memory_id> })` (recall then hides the old decision)
    c. If user says "oh right, keep it" → no new memory needed, proceed
 3. If no past decision found → proceed to record (see Case E below)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "mcpName": "io.github.michielinksee/linksee-memory",
   "description": "Hand a project over — to your next session, to Cursor/Codex/Gemini, to your successor — with the reasons attached. Local-first memory MCP for coding agents: decisions re-injected before the agent acts, drift detection across every project you run. One SQLite file, nothing leaves your machine.",
   "type": "module",