mcp-super-memory 0.4.8 → 0.5.1

package/dist/memoryGraph.js

@@ -1,20 +1,32 @@
-import { readFile, writeFile, mkdir, appendFile } from "fs/promises";
+import { readFile, writeFile, mkdir, appendFile, rename, copyFile } from "fs/promises";
 import { randomBytes } from "crypto";
 import { join } from "path";
 import { homedir } from "os";
 import { Mutex } from "async-mutex";
-import { embedTextAsync, EMBEDDING_BACKEND } from "./embedding.js";
+import MiniSearch from "minisearch";
+import { embedTextAsync, EMBEDDING_BACKEND, getThresholdProfile } from "./embedding.js";
 const DATA_DIR = process.env.SUPER_MEMORY_DATA_DIR ?? join(homedir(), ".super-memory");
 const GRAPH_FILE = join(DATA_DIR, "graph.json");
 const CONVERSATIONS_DIR = join(DATA_DIR, "conversations");
-const KEY_MERGE_THRESHOLD = 0.85;
-const MEMORY_DEDUP_THRESHOLD = 0.9;
-const KEY_AUTO_LINK_THRESHOLD = 0.5;
-const KEY_RECALL_THRESHOLD = 0.28;
-const CONTENT_RECALL_THRESHOLD = 0.28;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+// Thresholds are calibrated per embedding backend/model (see embedding.ts).
+const _THRESHOLDS = getThresholdProfile();
+const KEY_MERGE_THRESHOLD = _THRESHOLDS.keyMerge;
+const MEMORY_DEDUP_THRESHOLD = _THRESHOLDS.memoryDedup;
+const KEY_AUTO_LINK_THRESHOLD = _THRESHOLDS.keyAutoLink;
+const KEY_RECALL_THRESHOLD = _THRESHOLDS.keyRecall;
+const CONTENT_RECALL_THRESHOLD = _THRESHOLDS.contentRecall;
 const DEPTH_INCREMENT = 0.05;
 const DEPTH_MAX = 1.0;
 const DEPTH_DEEP_THRESHOLD = 0.7;
+const RRF_K = 60;
+const BM25_RESULT_DEPTH = 50;
+const DENSE_RESULT_DEPTH = 50;
+const LINK_WEIGHT_DEFAULT = 1.0;
+const LINK_WEIGHT_MIN = 0.1;
+const LINK_WEIGHT_MAX = 3.0;
+const LINK_REINFORCE_AMOUNT = 0.1;
+const LINK_DECAY_RATE = 0.005;
 // ── Vector math ──
 function cosineSim(a, b) {
     let dot = 0, normA = 0, normB = 0;
@@ -35,6 +47,18 @@ function batchCosineSim(query, matrix) {
 function uid() {
     return randomBytes(6).toString("hex");
 }
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isNodeError(err) {
+    return err instanceof Error && "code" in err;
+}
+function conversationPath(sessionId) {
+    if (!SESSION_ID_PATTERN.test(sessionId)) {
+        throw new Error("Invalid session_id. Use 1-128 characters: letters, numbers, dot, underscore, or hyphen.");
+    }
+    return join(CONVERSATIONS_DIR, `${sessionId}.jsonl`);
+}
 export function sanitizeKeys(keys) {
     let arr;
     if (typeof keys === "string") {
@@ -65,26 +89,51 @@ export class MemoryGraph {
     _storedDim = null;
     _lock = new Mutex();
     _dirty = false;
-    static HOP_DECAY = 0.5;
+    _bm25;
+    constructor() {
+        this._bm25 = new MiniSearch({
+            fields: ["content"],
+            storeFields: [],
+            idField: "id",
+            tokenize: (text) => text
+                .toLowerCase()
+                .split(/[\s\p{P}]+/u)
+                .filter((t) => t.length >= 1),
+            processTerm: (term) => (term.length < 1 ? false : term.toLowerCase()),
+        });
+    }
+    static HOP_DECAY = 0.3;
     static TIME_HALF_LIFE = 30 * 24 * 3600;
     get linkCount() {
         return Object.values(this._keyToMems).reduce((sum, mids) => sum + mids.size, 0);
     }
-    _link(keyId, memId) {
+    _link(keyId, memId, weight = LINK_WEIGHT_DEFAULT) {
         if (!this._keyToMems[keyId])
-            this._keyToMems[keyId] = new Set();
-        this._keyToMems[keyId].add(memId);
+            this._keyToMems[keyId] = new Map();
+        if (!this._keyToMems[keyId].has(memId)) {
+            this._keyToMems[keyId].set(memId, weight);
+        }
         if (!this._memToKeys[memId])
-            this._memToKeys[memId] = new Set();
-        this._memToKeys[memId].add(keyId);
+            this._memToKeys[memId] = new Map();
+        if (!this._memToKeys[memId].has(keyId)) {
+            this._memToKeys[memId].set(keyId, weight);
+        }
     }
     _hasLink(keyId, memId) {
         return this._keyToMems[keyId]?.has(memId) ?? false;
     }
+    _getLinkWeight(keyId, memId) {
+        return this._keyToMems[keyId]?.get(memId) ?? LINK_WEIGHT_DEFAULT;
+    }
+    _setLinkWeight(keyId, memId, weight) {
+        const clamped = Math.max(LINK_WEIGHT_MIN, Math.min(LINK_WEIGHT_MAX, weight));
+        this._keyToMems[keyId]?.set(memId, clamped);
+        this._memToKeys[memId]?.set(keyId, clamped);
+    }
     _unlinkMemory(memId) {
         const kids = this._memToKeys[memId];
         if (kids) {
-            for (const kid of kids) {
+            for (const kid of kids.keys()) {
                 const mems = this._keyToMems[kid];
                 if (mems) {
                     mems.delete(memId);
@@ -95,6 +144,34 @@ export class MemoryGraph {
             delete this._memToKeys[memId];
         }
     }
+    _validMemoryLinks(links, selfId) {
+        if (!Array.isArray(links))
+            return [];
+        const seen = new Set();
+        const valid = [];
+        for (const linkedId of links) {
+            if (typeof linkedId !== "string")
+                continue;
+            if (linkedId === selfId || seen.has(linkedId))
+                continue;
+            if (!(linkedId in this.memories))
+                continue;
+            seen.add(linkedId);
+            valid.push(linkedId);
+        }
+        return valid;
+    }
+    _removeMemoryReferences(memoryIds) {
+        const deleted = new Set(memoryIds);
+        for (const [mid, mem] of Object.entries(this.memories)) {
+            mem.links = this._validMemoryLinks(mem.links, mid).filter((linkedId) => !deleted.has(linkedId));
+        }
+    }
+    _pruneDanglingExplicitLinks() {
+        for (const [mid, mem] of Object.entries(this.memories)) {
+            mem.links = this._validMemoryLinks(mem.links, mid);
+        }
+    }
     _pruneOrphanKeys() {
         for (const kid of Object.keys(this.keys)) {
             const mems = this._keyToMems[kid];
@@ -111,9 +188,58 @@ export class MemoryGraph {
         if (dim !== this._storedDim) {
             throw new Error(`Embedding dimension mismatch: existing data uses ${this._storedDim}-dim, ` +
                 `current backend (${EMBEDDING_BACKEND}) produces ${dim}-dim.\n` +
-                `To switch backends, delete ~/.super-memory/graph.json first.`);
+                `Restart the server to auto-migrate (re-embeds all data with the current ` +
+                `backend, preserving content), or set SUPER_MEMORY_AUTO_MIGRATE=false to opt out.`);
         }
     }
+    // Recover from an embedding-backend/dimension change instead of bricking.
+    // Switching backends (e.g. OpenAI 1536-dim → local 768/1024-dim) used to make
+    // every recall/remember throw forever. Here we detect the mismatch on load and
+    // re-embed all keys and memories with the current backend — content, links,
+    // depth, and access history are preserved. Disable with SUPER_MEMORY_AUTO_MIGRATE=false.
+    async _ensureEmbeddingDim() {
+        if (this._storedDim === null)
+            return;
+        let probeDim;
+        try {
+            probeDim = (await embedTextAsync("dimension probe")).length;
+        }
+        catch (err) {
+            console.error(`[graph] could not probe embedding dimension: ${errorMessage(err)}`);
+            return;
+        }
+        if (probeDim === this._storedDim)
+            return;
+        if (process.env.SUPER_MEMORY_AUTO_MIGRATE === "false") {
+            console.error(`[graph] WARNING: stored embeddings are ${this._storedDim}-dim but the current ` +
+                `backend (${EMBEDDING_BACKEND}) produces ${probeDim}-dim. Auto-migration is ` +
+                `disabled — recall/remember will fail until the original backend is restored.`);
+            return;
+        }
+        await this._migrateEmbeddings(probeDim);
+    }
+    async _migrateEmbeddings(newDim) {
+        const nKeys = Object.keys(this.keys).length;
+        const nMems = Object.keys(this.memories).length;
+        console.error(`[graph] embedding dimension changed ${this._storedDim} -> ${newDim}. Re-embedding ` +
+            `${nKeys} keys + ${nMems} memories with the current backend (${EMBEDDING_BACKEND}); ` +
+            `content and links are preserved. This is a one-time migration.`);
+        try {
+            await copyFile(GRAPH_FILE, `${GRAPH_FILE}.bak.${this._storedDim}d`);
+        }
+        catch (err) {
+            console.error(`[graph] pre-migration backup failed (continuing): ${errorMessage(err)}`);
+        }
+        for (const mem of Object.values(this.memories)) {
+            mem.embedding = await embedTextAsync(mem.content, "passage");
+        }
+        for (const key of Object.values(this.keys)) {
+            key.embedding = await embedTextAsync(key.concept, "passage");
+        }
+        this._storedDim = newDim;
+        await this.save();
+        console.error(`[graph] migration complete: now ${newDim}-dim (backup saved as graph.json.bak).`);
+    }
     _isExpired(mem) {
         return mem.ttl != null && Date.now() / 1000 > mem.ttl;
     }
@@ -156,15 +282,24 @@ export class MemoryGraph {
         const sims = batchCosineSim(embedding, matrix);
         for (let i = 0; i < keyIds.length; i++) {
             if (sims[i] >= KEY_AUTO_LINK_THRESHOLD && !this._hasLink(keyIds[i], memId)) {
-                this._link(keyIds[i], memId);
+                this._link(keyIds[i], memId, sims[i]);
             }
         }
     }
+    _rebuildBm25Index() {
+        this._bm25.removeAll();
+        const docs = Object.entries(this.memories)
+            .filter(([mid]) => !(mid in this._supersededBy))
+            .filter(([, mem]) => !this._isExpired(mem))
+            .map(([mid, mem]) => ({ id: mid, content: mem.content }));
+        if (docs.length > 0)
+            this._bm25.addAll(docs);
+    }
     getKeysForMemory(memId) {
         const kids = this._memToKeys[memId];
         if (!kids)
             return [];
-        return [...kids]
+        return [...kids.keys()]
             .filter((kid) => kid in this.keys)
             .map((kid) => this.keys[kid].concept);
     }
@@ -175,8 +310,10 @@ export class MemoryGraph {
             const text = await readFile(GRAPH_FILE, "utf-8");
             raw = JSON.parse(text);
         }
-        catch {
-            return;
+        catch (err) {
+            if (isNodeError(err) && err.code === "ENOENT")
+                return;
+            throw new Error(`Failed to load memory graph at ${GRAPH_FILE}: ${errorMessage(err)}`);
         }
         for (const [kid, k] of Object.entries(raw.keys ?? {})) {
             this.keys[kid] = k;
@@ -193,6 +330,9 @@ export class MemoryGraph {
                 supersedes: null,
             };
             const mem = { ...defaults, ...m };
+            mem.links = Array.isArray(mem.links)
+                ? mem.links.filter((linkedId) => typeof linkedId === "string")
+                : [];
             if (!mem.embedding || mem.embedding.length === 0) {
                 mem.embedding = await embedTextAsync(mem.content);
             }
@@ -203,13 +343,18 @@ export class MemoryGraph {
             this._storedDim = firstMem.embedding.length;
         }
         for (const lnk of raw.links ?? []) {
-            this._link(lnk.key_id, lnk.memory_id);
+            if (lnk.key_id in this.keys && lnk.memory_id in this.memories) {
+                this._link(lnk.key_id, lnk.memory_id, lnk.weight ?? LINK_WEIGHT_DEFAULT);
+            }
         }
+        this._pruneDanglingExplicitLinks();
         for (const [mid, mem] of Object.entries(this.memories)) {
             if (mem.supersedes) {
                 this._supersededBy[mem.supersedes] = mid;
             }
         }
+        await this._ensureEmbeddingDim();
+        this._rebuildBm25Index();
         console.error(`[graph] loaded ${Object.keys(this.keys).length} keys, ` +
             `${Object.keys(this.memories).length} memories, ${this.linkCount} links`);
     }
@@ -217,8 +362,8 @@ export class MemoryGraph {
         await mkdir(DATA_DIR, { recursive: true });
         const links = [];
         for (const [kid, mids] of Object.entries(this._keyToMems)) {
-            for (const mid of mids) {
-                links.push({ key_id: kid, memory_id: mid });
+            for (const [mid, weight] of mids) {
+                links.push({ key_id: kid, memory_id: mid, weight });
             }
         }
         const data = {
@@ -226,7 +371,9 @@ export class MemoryGraph {
             memories: this.memories,
             links,
         };
-        await writeFile(GRAPH_FILE, JSON.stringify(data, null, 2), "utf-8");
+        const tmp = GRAPH_FILE + ".tmp";
+        await writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+        await rename(tmp, GRAPH_FILE);
         this._dirty = false;
     }
     markDirty() {
@@ -295,7 +442,7 @@ export class MemoryGraph {
             resultMid = mid;
             const now = Date.now() / 1000;
             const expiresAt = options.ttlSeconds != null ? now + options.ttlSeconds : null;
-            const validLinks = (options.relatedTo ?? []).filter((lid) => lid in this.memories);
+            const validLinks = this._validMemoryLinks(options.relatedTo ?? [], mid);
             this.memories[mid] = {
                 id: mid,
                 content,
@@ -319,6 +466,7 @@ export class MemoryGraph {
                     this._link(kid, mid);
             }
             this._autoLinkKeys(mid, embedding);
+            this._bm25.add({ id: mid, content });
             await this.save();
         });
         return [resultMid, false];
@@ -332,19 +480,25 @@ export class MemoryGraph {
                 throw new Error(`Memory ${oldId} not found`);
             }
             const old = this.memories[oldId];
-            // Chain cleanup: keep depth max 1 (new → old; grandparent deleted)
+            // Chain cleanup: keep depth max 1 (new -> old; grandparent deleted)
             const grandparentId = old.supersedes;
             if (grandparentId && grandparentId in this.memories) {
                 delete this.memories[grandparentId];
                 this._unlinkMemory(grandparentId);
+                this._removeMemoryReferences([grandparentId]);
                 delete this._supersededBy[grandparentId];
                 this._pruneOrphanKeys();
+                try {
+                    this._bm25.discard(grandparentId);
+                }
+                catch { /* already removed */ }
             }
             const mid = uid();
             resultMid = mid;
             const now = Date.now() / 1000;
             const ns = options.namespace ?? old.namespace;
-            const validLinks = (options.relatedTo ?? []).filter((lid) => lid in this.memories);
+            const nextLinks = options.relatedTo === undefined ? old.links : options.relatedTo;
+            const validLinks = this._validMemoryLinks(nextLinks ?? [], mid);
             this.memories[mid] = {
                 id: mid,
                 content: newContent,
@@ -359,12 +513,17 @@ export class MemoryGraph {
                 ttl: old.ttl,
                 links: validLinks,
             };
+            this._bm25.add({ id: mid, content: newContent });
             // Weaken old memory depth
             old.depth =
                 old.depth >= DEPTH_DEEP_THRESHOLD
                     ? old.depth * 0.8
                     : old.depth * 0.3;
             this._supersededBy[oldId] = mid;
+            try {
+                this._bm25.discard(oldId);
+            }
+            catch { /* already removed */ }
             const keyConcepts = options.keyConcepts;
             if (keyConcepts && keyConcepts.length > 0) {
                 const sanitized = sanitizeKeys(keyConcepts);
@@ -376,9 +535,9 @@ export class MemoryGraph {
                 }
             }
             else {
-                // Copy old links (snapshot to avoid mutation during iteration)
-                for (const kid of [...(this._memToKeys[oldId] ?? new Set())]) {
-                    this._link(kid, mid);
+                // Copy old links with weights (snapshot to avoid mutation during iteration)
+                for (const [kid, w] of [...(this._memToKeys[oldId] ?? new Map())]) {
+                    this._link(kid, mid, w);
                 }
             }
             this._autoLinkKeys(mid, newEmbedding);
@@ -390,12 +549,11 @@ export class MemoryGraph {
     async recall(query, topK = 5, namespace, expand = false) {
         if (Object.keys(this.memories).length === 0)
             return [];
-        const qEmb = await embedTextAsync(query); // outside lock
+        const qEmb = await embedTextAsync(query, "query"); // outside lock
         this._checkDim(qEmb);
         const results = [];
         await this._lock.runExclusive(async () => {
             const queryLower = query.toLowerCase().trim();
-            const memScores = {};
             const memMatchedKeys = {};
             const memHop = {};
             const skip = (mid) => {
@@ -410,7 +568,15 @@ export class MemoryGraph {
                     return true;
                 return false;
             };
-            // ── Path A: Key batch matching → links → memories ──
+            // ── BM25 sparse search ──
+            const bm25Ranked = [];
+            const bm25Results = this._bm25.search(query, { fuzzy: 0.2, prefix: true });
+            for (const r of bm25Results.slice(0, BM25_RESULT_DEPTH)) {
+                if (!skip(r.id))
+                    bm25Ranked.push({ id: r.id, score: r.score });
+            }
+            // ── Dense Path A: Key batch matching ──
+            const denseScores = {};
             const keyIds = Object.keys(this.keys);
             const keySims = keyIds.length > 0
                 ? batchCosineSim(qEmb, keyIds.map((kid) => this.keys[kid].embedding))
@@ -431,21 +597,19 @@ export class MemoryGraph {
             keyScores.sort((a, b) => b[0] - a[0]);
             for (const [keySim, kid] of keyScores.slice(0, 10)) {
                 const idf = this._keyIdf(kid);
-                for (const memId of this._keyToMems[kid] ?? new Set()) {
+                for (const memId of this._keyToMems[kid]?.keys() ?? []) {
                     if (skip(memId))
                         continue;
-                    const mem = this.memories[memId];
-                    const depthFactor = 0.9 + mem.depth * 0.1;
-                    const tf = this._timeFactor(mem);
-                    const score = keySim * idf * depthFactor * tf;
-                    memScores[memId] = (memScores[memId] ?? 0) + score;
+                    const lw = this._getLinkWeight(kid, memId);
+                    const score = keySim * idf * lw;
+                    denseScores[memId] = (denseScores[memId] ?? 0) + score;
                     if (!memMatchedKeys[memId])
                         memMatchedKeys[memId] = [];
                     memMatchedKeys[memId].push(this.keys[kid].concept);
                     memHop[memId] = 1;
                 }
             }
-            // ── Path B: Content batch direct matching ──
+            // ── Dense Path B: Content batch direct matching ──
             const memIds = Object.keys(this.memories);
             if (memIds.length > 0) {
                 const contentSims = batchCosineSim(qEmb, memIds.map((mid) => this.memories[mid].embedding));
@@ -455,15 +619,12 @@ export class MemoryGraph {
                         continue;
                     const cSim = contentSims[i];
                     if (cSim >= CONTENT_RECALL_THRESHOLD) {
-                        const mem = this.memories[mid];
-                        const depthFactor = 0.9 + mem.depth * 0.1;
-                        const tf = this._timeFactor(mem);
-                        const contentScore = cSim * depthFactor * tf * 0.8;
-                        if (mid in memScores) {
-                            memScores[mid] += contentScore * 0.2;
+                        const contentScore = cSim * 0.8;
+                        if (mid in denseScores) {
+                            denseScores[mid] += contentScore * 0.2;
                         }
                         else {
-                            memScores[mid] = contentScore;
+                            denseScores[mid] = contentScore;
                         }
                         if (!memMatchedKeys[mid])
                             memMatchedKeys[mid] = [];
@@ -473,18 +634,70 @@ export class MemoryGraph {
                     }
                 }
             }
+            // ── Build dense ranked list ──
+            const denseRanked = Object.entries(denseScores)
+                .sort(([, a], [, b]) => b - a)
+                .slice(0, DENSE_RESULT_DEPTH)
+                .map(([id, score]) => ({ id, score }));
+            // ── RRF fusion ──
+            const memScores = {};
+            for (let rank = 0; rank < bm25Ranked.length; rank++) {
+                const mid = bm25Ranked[rank].id;
+                memScores[mid] = (memScores[mid] ?? 0) + 1 / (RRF_K + rank + 1);
+                if (!memMatchedKeys[mid])
+                    memMatchedKeys[mid] = [];
+                if (!memMatchedKeys[mid].includes("(bm25)"))
+                    memMatchedKeys[mid].push("(bm25)");
+                if (!(mid in memHop))
+                    memHop[mid] = 1;
+            }
+            for (let rank = 0; rank < denseRanked.length; rank++) {
+                const mid = denseRanked[rank].id;
+                memScores[mid] = (memScores[mid] ?? 0) + 1 / (RRF_K + rank + 1);
+            }
+            // ── Lexical exact-key boost ──
+            // RRF flattens score magnitude, so a memory whose key the query names
+            // *literally* ranks no higher than one that merely shares fuzzy content
+            // similarity — and with compressed embeddings (e.g. e5) the dense key
+            // signal can't break that tie on its own. Give memories an additive bonus
+            // when the query literally contains one of their key concepts, so an exact
+            // concept hit outranks same-language content noise. IDF-weighted so hub
+            // keys don't dominate; on the same RRF scale (~one top-rank contribution).
+            for (const [, kid] of keyScores) {
+                const concept = this.keys[kid]?.concept;
+                if (!concept || concept.length < 2)
+                    continue;
+                if (!queryLower.includes(concept.toLowerCase()))
+                    continue;
+                const bonus = (1 / (RRF_K + 1)) * this._keyIdf(kid);
+                for (const memId of this._keyToMems[kid]?.keys() ?? []) {
+                    if (skip(memId))
+                        continue;
+                    memScores[memId] = (memScores[memId] ?? 0) + bonus;
+                }
+            }
+            // ── Apply depth/time modulation to fused scores ──
+            for (const mid of Object.keys(memScores)) {
+                const mem = this.memories[mid];
+                if (!mem)
+                    continue;
+                const depthFactor = 0.9 + mem.depth * 0.1;
+                const tf = this._timeFactor(mem);
+                memScores[mid] *= depthFactor * tf;
+            }
             // ── 2-hop: via shared keys ──
             for (const mid of Object.keys(memScores)) {
                 const hop1Score = memScores[mid];
-                for (const kid of this._memToKeys[mid] ?? new Set()) {
+                for (const kid of this._memToKeys[mid]?.keys() ?? []) {
                     if (!(kid in this.keys))
                         continue;
                     const concept = this.keys[kid].concept;
                     const idf = this._keyIdf(kid);
-                    for (const otherMid of this._keyToMems[kid] ?? new Set()) {
+                    for (const otherMid of this._keyToMems[kid]?.keys() ?? []) {
                         if (otherMid === mid || skip(otherMid))
                             continue;
-                        const hop2Score = hop1Score * MemoryGraph.HOP_DECAY * idf;
+                        const lw = this._getLinkWeight(kid, otherMid);
+                        const hop2Score = hop1Score * MemoryGraph.HOP_DECAY * idf * lw;
                         memScores[otherMid] = (memScores[otherMid] ?? 0) + hop2Score;
                         if (!memMatchedKeys[otherMid])
                             memMatchedKeys[otherMid] = [];
@@ -500,7 +713,12 @@ export class MemoryGraph {
                 const memObj = this.memories[mid];
                 if (!memObj)
                     continue;
-                for (const linkedId of memObj.links) {
+                const linkedIds = new Set(memObj.links);
+                for (const [otherMid, otherMem] of Object.entries(this.memories)) {
+                    if (otherMem.links.includes(mid))
+                        linkedIds.add(otherMid);
+                }
+                for (const linkedId of linkedIds) {
                     if (linkedId === mid || skip(linkedId))
                         continue;
                     const linkScore = hop1Score * MemoryGraph.HOP_DECAY;
@@ -544,6 +762,31 @@ export class MemoryGraph {
                     links: mem.links,
                 });
             }
+            // ── Hebbian link reinforcement / decay ──
+            const returnedSet = new Set(ranked.map(([mid]) => mid));
+            const matchedKeyIds = new Set(keyScores.slice(0, 10).map(([, kid]) => kid));
+            // Strengthen ONLY the links that actually fired for this query (matched
+            // key → returned memory). Reinforcing a returned memory's *other* keys
+            // would let an unrelated association grow every time that memory surfaces
+            // for a different key, slowly polluting the graph. This mirrors the decay
+            // side, which is already scoped to matched keys.
+            for (const [mid] of ranked) {
+                for (const kid of this._memToKeys[mid]?.keys() ?? []) {
+                    if (!matchedKeyIds.has(kid))
+                        continue;
+                    this._setLinkWeight(kid, mid, this._getLinkWeight(kid, mid) + LINK_REINFORCE_AMOUNT);
+                }
+            }
+            // Weaken: explored but not returned
+            for (const [, kid] of keyScores.slice(0, 10)) {
+                for (const [memId, cw] of this._keyToMems[kid] ?? new Map()) {
+                    if (skip(memId))
+                        continue;
+                    if (!returnedSet.has(memId)) {
+                        this._setLinkWeight(kid, memId, cw - LINK_DECAY_RATE);
+                    }
+                }
+            }
             this.markDirty();
         });
         await this.flush(); // outside lock
@@ -555,9 +798,9 @@ export class MemoryGraph {
             return [];
         const related = {};
         // Key-sharing
-        for (const kid of this._memToKeys[memoryId] ?? new Set()) {
+        for (const kid of this._memToKeys[memoryId]?.keys() ?? []) {
             const concept = this.keys[kid]?.concept ?? "?";
-            for (const mid of this._keyToMems[kid] ?? new Set()) {
+            for (const mid of this._keyToMems[kid]?.keys() ?? []) {
                 if (mid === memoryId || !(mid in this.memories))
                     continue;
                 const mem = this.memories[mid];
@@ -583,7 +826,7 @@ export class MemoryGraph {
             if (!(linkedId in this.memories) || linkedId === memoryId)
                 continue;
             const mem = this.memories[linkedId];
-            if (this._isExpired(mem))
+            if (this._isExpired(mem) || linkedId in this._supersededBy)
                 continue;
             if (!related[linkedId]) {
                 related[linkedId] = {
@@ -603,7 +846,7 @@ export class MemoryGraph {
         }
         // Reverse links (←)
         for (const [mid, mem] of Object.entries(this.memories)) {
-            if (mid === memoryId || this._isExpired(mem))
+            if (mid === memoryId || this._isExpired(mem) || mid in this._supersededBy)
                 continue;
             if (mem.links.includes(memoryId)) {
                 if (!related[mid]) {
@@ -629,7 +872,12 @@ export class MemoryGraph {
                 return false;
             delete this.memories[memoryId];
             this._unlinkMemory(memoryId);
+            this._removeMemoryReferences([memoryId]);
             this._pruneOrphanKeys();
+            try {
+                this._bm25.discard(memoryId);
+            }
+            catch { /* already removed */ }
             delete this._supersededBy[memoryId];
             for (const [oldId, newId] of Object.entries(this._supersededBy)) {
                 if (newId === memoryId)
@@ -673,12 +921,17 @@ export class MemoryGraph {
             for (const mid of expired) {
                 delete this.memories[mid];
                 this._unlinkMemory(mid);
+                try {
+                    this._bm25.discard(mid);
+                }
+                catch { /* already removed */ }
                 delete this._supersededBy[mid];
                 for (const [oldId, newId] of Object.entries(this._supersededBy)) {
                     if (newId === mid)
                         delete this._supersededBy[oldId];
                 }
             }
+            this._removeMemoryReferences(expired);
             this._pruneOrphanKeys();
             if (expired.length > 0)
                 await this.save();
@@ -689,7 +942,7 @@ export class MemoryGraph {
 // ── Conversation store ──
 export async function saveTurn(sessionId, role, content) {
     await mkdir(CONVERSATIONS_DIR, { recursive: true });
-    const path = join(CONVERSATIONS_DIR, `${sessionId}.jsonl`);
+    const path = conversationPath(sessionId);
     let turn = 0;
     try {
         const text = await readFile(path, "utf-8");
@@ -708,7 +961,7 @@ export async function saveTurn(sessionId, role, content) {
     return turn;
 }
 export async function loadConversation(sessionId, turn) {
-    const path = join(CONVERSATIONS_DIR, `${sessionId}.jsonl`);
+    const path = conversationPath(sessionId);
     let text;
     try {
         text = await readFile(path, "utf-8");
@@ -716,10 +969,17 @@ export async function loadConversation(sessionId, turn) {
     catch {
         return [];
     }
-    const lines = text
-        .split("\n")
-        .filter((l) => l.trim())
-        .map((l) => JSON.parse(l));
+    const lines = [];
+    text.split("\n").forEach((line, idx) => {
+        if (!line.trim())
+            return;
+        try {
+            lines.push(JSON.parse(line));
+        }
+        catch (err) {
+            throw new Error(`Invalid conversation log ${sessionId} at line ${idx + 1}: ${errorMessage(err)}`);
+        }
+    });
     if (turn != null) {
         const start = Math.max(0, turn - 2);
         const end = Math.min(lines.length, turn + 3);