midas-memory-mcp 0.0.3

package/dist/memory.js

@@ -0,0 +1,472 @@
+/** Midas core — a faithful TypeScript port of `midas/memory.py`'s shipping behaviour:
+ * recall ranks by relevance × importance × recency with the scale-free parsimony floor
+ * (`minRelevanceRatio` 0.3, measured-safe), optional BM25+RRF hybrid (cached index),
+ * typed belief revision (supersession chains), policy-gated `capture`, budgeted lean
+ * `buildContext` with the dated "Today is …" anchor, and no-LLM selective forgetting. */
+import { randomUUID } from "node:crypto";
+import { BM25 } from "./bm25.js";
+import { cosine, HashingEmbedder } from "./embeddings.js";
+import { contentImportance } from "./importance.js";
+import { InMemoryStore } from "./store.js";
+import { MEMORY_PROVENANCE } from "./types.js";
+export const RECENCY_HALF_LIFE_DAYS = 30.0;
+export const DEFAULT_RECALL_LIMIT = 6;
+export const DURABLE_KINDS = ["fact", "preference", "constraint"];
+// Update/change cues for typed belief revision — same pattern set as the Python module.
+const UPDATE_RE = /\b(actually|instead|now|currently|updated|changed|change|new|replaced|replace|taken over|take over|handed over|hand over|signed off|resigned|stepped down|stepped up|postponed|delayed|moved to|moved from|rescheduled|cancelled|no longer|not anymore|never)\b|\bwas\b.*\bbut now\b/i;
+const SUPERSEDE_STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for", "of", "with", "by", "is",
+    "are", "was", "were", "be", "been", "being", "have", "has", "had", "do", "does", "did", "will",
+    "would", "could", "should", "may", "might", "must", "can", "we", "our", "us", "it", "its",
+    "this", "that", "these", "those", "i", "you", "he", "she", "they", "them",
+]);
+const ENTITY_STOPWORDS = new Set([
+    "project", "user", "client", "team", "ticket", "issue", "task", "feature", "release", "launch",
+    "date", "database", "service", "server", "environment",
+    "january", "february", "march", "april", "may", "june", "july", "august", "september",
+    "october", "november", "december",
+]);
+const PROPER_ENTITY = /\b[A-Z][A-Za-z0-9_-]{2,}\b/g;
+const PROVENANCE_RANK = {
+    planning: 0,
+    observation: 1,
+    action: 2,
+    user_confirmation: 3,
+};
+function contentWords(text) {
+    const out = new Set();
+    for (const w of text.split(/\s+/)) {
+        const lw = w.toLowerCase();
+        if (w.length > 3 && !SUPERSEDE_STOPWORDS.has(lw) && /^[a-z0-9]+$/i.test(w))
+            out.add(lw);
+    }
+    return out;
+}
+function properEntities(text) {
+    const out = new Set();
+    for (const m of text.matchAll(PROPER_ENTITY)) {
+        const lw = m[0].toLowerCase();
+        if (!ENTITY_STOPWORDS.has(lw))
+            out.add(lw);
+    }
+    return out;
+}
+function intersects(a, b) {
+    for (const x of a)
+        if (b.has(x))
+            return true;
+    return false;
+}
+export const DEFAULT_POLICY = {
+    minImportance: 2,
+    acceptKinds: ["note", "chat", "fact", "preference", "constraint", "mission"],
+    dedupThreshold: 0.95,
+};
+export class Memory {
+    store;
+    embedder;
+    wRelevance;
+    wImportance;
+    wRecency;
+    supersede;
+    supersedeThreshold;
+    supersedePool;
+    supersedeMargin;
+    supersedeLowerThreshold;
+    minRelevanceRatio;
+    importanceScorer;
+    policy;
+    now;
+    bm25Cache = null;
+    constructor(opts = {}) {
+        this.store = opts.store ?? new InMemoryStore();
+        this.embedder = opts.embedder ?? new HashingEmbedder();
+        this.wRelevance = opts.wRelevance ?? 1.0;
+        this.wImportance = opts.wImportance ?? 0.3;
+        this.wRecency = opts.wRecency ?? 0.2;
+        this.supersede = opts.supersede ?? false;
+        this.supersedeThreshold = opts.supersedeThreshold ?? 0.55;
+        this.supersedePool = opts.supersedePool ?? 20;
+        this.supersedeMargin = opts.supersedeMargin ?? 0.05;
+        this.supersedeLowerThreshold = opts.supersedeLowerThreshold ?? 0.3;
+        this.minRelevanceRatio = Math.max(0, opts.minRelevanceRatio ?? 0.3);
+        this.importanceScorer = opts.importanceScorer ?? null;
+        this.policy = opts.policy ?? DEFAULT_POLICY;
+        this.now = opts.now ?? (() => Date.now() / 1000);
+    }
+    remember(content, opts = {}) {
+        content = (content ?? "").trim();
+        if (!content)
+            throw new Error("Memory.remember: `content` is required");
+        const embedding = this.embedder.embed(content);
+        const ts = opts.createdAt ?? this.now();
+        const importance = this.deriveImportance(opts.importance ?? null, content);
+        const provenance = opts.provenance ?? "observation";
+        if (!MEMORY_PROVENANCE.includes(provenance)) {
+            throw new Error(`invalid memory provenance '${provenance}'`);
+        }
+        const record = {
+            id: randomUUID(),
+            content,
+            kind: opts.kind ?? "note",
+            importance,
+            source: opts.source ?? null,
+            provenance,
+            actor: opts.actor ?? null,
+            metadata: opts.metadata ?? {},
+            createdAt: ts,
+            updatedAt: ts,
+            embedding,
+            supersededBy: null,
+        };
+        this.store.put(record);
+        if (this.supersede)
+            this.maybeSupersede(record);
+        return record;
+    }
+    capture(content, opts = {}) {
+        content = (content ?? "").trim();
+        if (!content)
+            return { stored: false, reason: "empty content", record: null, importance: 0 };
+        const scorer = this.importanceScorer ?? contentImportance;
+        const importance = clampImportance(scorer(content));
+        const kind = opts.kind ?? "chat";
+        if (!this.policy.acceptKinds.includes(kind)) {
+            return { stored: false, reason: `kind '${kind}' not accepted by policy`, record: null, importance };
+        }
+        if (importance < this.policy.minImportance) {
+            return {
+                stored: false,
+                reason: `below relevance floor (importance ${importance} < ${this.policy.minImportance})`,
+                record: null,
+                importance,
+            };
+        }
+        if (this.policy.dedupThreshold > 0) {
+            const near = this.store.search(this.embedder.embed(content), { limit: 1 });
+            if (near.length && near[0][0] >= this.policy.dedupThreshold) {
+                const existing = near[0][1];
+                const upgraded = this.upgradeProvenance(existing, opts);
+                return {
+                    stored: false,
+                    reason: "near-duplicate of an existing memory" + (upgraded ? " (provenance upgraded)" : ""),
+                    record: existing,
+                    importance,
+                };
+            }
+        }
+        const record = this.remember(content, { ...opts, kind, importance });
+        return { stored: true, reason: "stored", record, importance };
+    }
+    upgradeProvenance(record, opts) {
+        const provenance = opts.provenance ?? "observation";
+        if (PROVENANCE_RANK[provenance] <= PROVENANCE_RANK[record.provenance])
+            return false;
+        record.provenance = provenance;
+        record.actor = opts.actor ?? record.actor;
+        record.source = opts.source ?? record.source;
+        record.metadata = { ...record.metadata, ...(opts.metadata ?? {}) };
+        record.updatedAt = opts.createdAt ?? this.now();
+        this.store.put(record);
+        return true;
+    }
+    deriveImportance(importance, content) {
+        if (importance !== null && importance !== undefined && importance > 0) {
+            return clampImportance(importance);
+        }
+        return clampImportance(this.importanceScorer ? this.importanceScorer(content) : 1);
+    }
+    recall(query, opts = {}) {
+        const limit = opts.limit ?? DEFAULT_RECALL_LIMIT;
+        const qEmb = this.embedder.embed(query);
+        const now = opts.now ?? this.now();
+        const predicate = (r) => {
+            if (opts.kind && r.kind !== opts.kind)
+                return false;
+            if (opts.minImportance != null && r.importance < opts.minImportance)
+                return false;
+            if (opts.metadataFilter) {
+                for (const [k, v] of Object.entries(opts.metadataFilter)) {
+                    if (r.metadata?.[k] !== v)
+                        return false;
+                }
+            }
+            return true;
+        };
+        const pool = opts.pool ?? Math.max(limit * 5, limit);
+        let candidates;
+        let relevanceMap = null;
+        if (opts.hybrid) {
+            [candidates, relevanceMap] = this.hybridCandidates(query, qEmb, pool, predicate);
+        }
+        else {
+            candidates = this.store.search(qEmb, { limit: pool, predicate });
+        }
+        if (this.supersede)
+            candidates = this.resolveCandidates(candidates);
+        if (!candidates.length)
+            return [];
+        const relevances = candidates.map(([cos, r]) => relevanceMap ? relevanceMap.get(r.id) ?? Math.max(0, cos) : Math.max(0, cos));
+        const ratio = opts.minRelevanceRatio ?? this.minRelevanceRatio;
+        const ratioFloor = ratio > 0 && relevances.length ? ratio * Math.max(...relevances) : null;
+        const hits = [];
+        for (let i = 0; i < candidates.length; i++) {
+            const [, record] = candidates[i];
+            const relevance = relevances[i];
+            if (opts.minRelevance != null && relevance < opts.minRelevance)
+                continue;
+            if (ratioFloor !== null && relevance < ratioFloor)
+                continue;
+            const importanceNorm = (record.importance - 1) / 4;
+            const ageDays = Math.max(0, (now - record.updatedAt) / 86_400);
+            const recency = Math.exp(-ageDays / RECENCY_HALF_LIFE_DAYS);
+            hits.push({
+                record,
+                score: this.wRelevance * relevance + this.wImportance * importanceNorm + this.wRecency * recency,
+                relevance,
+                importanceNorm,
+                recency,
+            });
+        }
+        hits.sort((a, b) => b.score - a.score || b.record.updatedAt - a.record.updatedAt);
+        return hits.slice(0, limit);
+    }
+    hybridCandidates(query, qEmb, pool, predicate) {
+        const semantic = this.store.search(qEmb, { limit: pool, predicate });
+        const records = this.store.all().filter(predicate);
+        const allowed = new Map(records.map((r) => [r.id, r]));
+        const bmScores = new Map([...this.bm25Index().scores(query)].filter(([rid]) => allowed.has(rid)));
+        const bmRanked = [...bmScores.keys()].sort((a, b) => bmScores.get(b) - bmScores.get(a));
+        const byId = new Map(semantic.map(([cos, r]) => [r.id, [cos, r]]));
+        for (const rid of bmRanked.slice(0, pool)) {
+            if (!byId.has(rid)) {
+                const rec = allowed.get(rid);
+                const cos = rec.embedding ? cosine(qEmb, rec.embedding) : 0;
+                byId.set(rid, [cos, rec]);
+            }
+        }
+        // Reciprocal-rank fusion (k=60), normalised to [0,1] — same as the Python implementation.
+        const K = 60;
+        const denseRank = new Map(semantic.map(([, r], i) => [r.id, i]));
+        const bmRank = new Map(bmRanked.map((rid, i) => [rid, i]));
+        const raw = new Map();
+        let top = 0;
+        for (const rid of byId.keys()) {
+            const d = denseRank.has(rid) ? 1 / (K + denseRank.get(rid) + 1) : 0;
+            const b = bmRank.has(rid) ? 1 / (K + bmRank.get(rid) + 1) : 0;
+            raw.set(rid, d + b);
+            top = Math.max(top, d + b);
+        }
+        const relevanceMap = new Map();
+        for (const [rid, s] of raw)
+            relevanceMap.set(rid, top > 0 ? s / top : 0);
+        return [[...byId.values()], relevanceMap];
+    }
+    bm25Index() {
+        const version = this.store.version;
+        if (!this.bm25Cache || this.bm25Cache[0] !== version) {
+            this.bm25Cache = [version, new BM25(this.store.all())];
+        }
+        return this.bm25Cache[1];
+    }
+    maybeSupersede(newRecord) {
+        if (!newRecord.embedding)
+            return;
+        if (newRecord.kind === "chat")
+            return; // chat never revises (the safe Python default)
+        const hasCue = UPDATE_RE.test(newRecord.content);
+        const effectiveThreshold = hasCue ? this.supersedeLowerThreshold : this.supersedeThreshold;
+        const candidates = this.store.search(newRecord.embedding, {
+            limit: this.supersedePool,
+            predicate: (r) => r.id !== newRecord.id && r.kind === newRecord.kind,
+        });
+        const byHead = new Map();
+        for (const [score, candidate] of candidates) {
+            if (score < effectiveThreshold)
+                continue;
+            const head = this.resolveHead(candidate);
+            if (head.id === newRecord.id || head.supersededBy !== null)
+                continue;
+            if (normalize(head.content) === normalize(newRecord.content))
+                continue;
+            const ne = properEntities(newRecord.content);
+            const he = properEntities(head.content);
+            if (ne.size && he.size && !intersects(ne, he))
+                continue;
+            if (score < this.supersedeThreshold && !intersects(contentWords(newRecord.content), contentWords(head.content))) {
+                continue;
+            }
+            const prev = byHead.get(head.id);
+            if (!prev || score > prev[0])
+                byHead.set(head.id, [score, head]);
+        }
+        if (!byHead.size)
+            return;
+        const ranked = [...byHead.values()].sort((a, b) => b[0] - a[0]);
+        if (ranked.length > 1 && ranked[0][0] - ranked[1][0] < this.supersedeMargin)
+            return;
+        const head = ranked[0][1];
+        head.supersededBy = newRecord.id;
+        this.store.put(head);
+    }
+    resolveHead(record) {
+        const seen = new Set();
+        let current = record;
+        while (current.supersededBy !== null && !seen.has(current.id)) {
+            seen.add(current.id);
+            const next = this.store.get(current.supersededBy);
+            if (!next)
+                break;
+            current = next;
+        }
+        return current;
+    }
+    resolveCandidates(candidates) {
+        const best = new Map();
+        for (const [score, record] of candidates) {
+            const head = this.resolveHead(record);
+            const prev = best.get(head.id);
+            if (!prev || score > prev[0])
+                best.set(head.id, [score, head]);
+        }
+        return [...best.values()];
+    }
+    buildContext(query, opts = {}) {
+        const budget = opts.tokenBudget ?? 512;
+        const now = opts.now ?? this.now();
+        const hits = this.recall(query, { ...opts, now });
+        let records = hits.map((h) => h.record);
+        if (this.supersede)
+            records = records.filter((r) => this.resolveHead(r).id === r.id);
+        const chosen = [];
+        let used = 0;
+        for (const record of records) {
+            const line = formatRecord(record, { maxChars: opts.maxRecordChars ?? 600, now });
+            const cost = approxTokens(line);
+            if (used + cost > budget)
+                break;
+            chosen.push([record, line, cost]);
+            used += cost;
+        }
+        if (!chosen.length)
+            return { text: "", records: [], tokens: 0 };
+        let body = chosen.map(([, line]) => line).join("\n");
+        if (opts.header !== false) {
+            let head = "# Memory - relevant context (use silently to stay consistent)";
+            head += `\n# Today is ${fmtDate(now)}`;
+            body = head + "\n" + body;
+        }
+        return { text: body, records: chosen.map(([r]) => r), tokens: used };
+    }
+    forget(recordId) {
+        const target = this.store.get(recordId);
+        if (!target)
+            return false;
+        for (const r of this.store.all()) {
+            if (r.supersededBy === recordId) {
+                r.supersededBy = target.supersededBy;
+                this.store.put(r);
+            }
+        }
+        return this.store.delete(recordId);
+    }
+    forgetMatching(query, opts = {}) {
+        const minRelevance = opts.minRelevance ?? 0.5;
+        const hits = this.recall(query, {
+            limit: opts.limit ?? 20,
+            minRelevance,
+            metadataFilter: opts.metadataFilter ?? null,
+        });
+        const matched = hits.filter((h) => h.relevance >= minRelevance).map((h) => h.record);
+        if (!opts.dryRun)
+            for (const r of matched)
+                this.forget(r.id);
+        return matched;
+    }
+    memoryValue(record, now) {
+        now = now ?? this.now();
+        const importanceNorm = (record.importance - 1) / 4;
+        const ageDays = Math.max(0, (now - record.updatedAt) / 86_400);
+        const recency = Math.exp(-ageDays / RECENCY_HALF_LIFE_DAYS);
+        const denom = this.wImportance + this.wRecency;
+        return denom > 0 ? (this.wImportance * importanceNorm + this.wRecency * recency) / denom : 0;
+    }
+    tier(record, now) {
+        now = now ?? this.now();
+        const ageDays = Math.max(0, (now - record.updatedAt) / 86_400);
+        if (ageDays <= 1)
+            return "short";
+        if (ageDays <= 7)
+            return "medium";
+        return "long";
+    }
+    forgetDecayed(opts = {}) {
+        const now = this.now();
+        const records = this.store.all();
+        const pointedTo = new Set(records.map((r) => r.supersededBy).filter((x) => x !== null));
+        const protectImportance = opts.protectImportance ?? 4;
+        const protectedRec = (r) => DURABLE_KINDS.includes(r.kind) ||
+            r.importance >= protectImportance ||
+            r.supersededBy !== null ||
+            pointedTo.has(r.id);
+        const candidates = records.filter((r) => !protectedRec(r));
+        const value = new Map(candidates.map((r) => [r.id, this.memoryValue(r, now)]));
+        candidates.sort((a, b) => value.get(a.id) - value.get(b.id));
+        const toDrop = [];
+        const dropped = new Set();
+        if (opts.minValue != null) {
+            for (const r of candidates) {
+                if (value.get(r.id) < opts.minValue) {
+                    toDrop.push(r.id);
+                    dropped.add(r.id);
+                }
+            }
+        }
+        if (opts.maxRecords != null) {
+            let surviving = records.length - dropped.size;
+            for (const r of candidates) {
+                if (surviving <= opts.maxRecords)
+                    break;
+                if (dropped.has(r.id))
+                    continue;
+                toDrop.push(r.id);
+                dropped.add(r.id);
+                surviving -= 1;
+            }
+        }
+        return toDrop.filter((rid) => this.store.delete(rid));
+    }
+}
+function normalize(text) {
+    return text.split(/\s+/).join(" ").toLowerCase();
+}
+function clampImportance(value) {
+    if (!Number.isFinite(value))
+        return 1;
+    return Math.max(1, Math.min(5, Math.round(value)));
+}
+export function fmtDate(ts) {
+    return new Date(ts * 1000).toISOString().slice(0, 10); // UTC, same as Python
+}
+function relativeAge(createdAt, now) {
+    const days = Math.floor((now - createdAt) / 86_400);
+    if (days <= 0)
+        return "today";
+    if (days < 14)
+        return `${days}d ago`;
+    if (days < 60)
+        return `${Math.floor(days / 7)}w ago`;
+    if (days < 730)
+        return `${Math.floor(days / 30)}mo ago`;
+    return `${Math.floor(days / 365)}y ago`;
+}
+export function formatRecord(record, opts = {}) {
+    let date = fmtDate(record.createdAt);
+    if (opts.now != null)
+        date = `${date}, ${relativeAge(record.createdAt, opts.now)}`;
+    const body = record.content.split(/\s+/).join(" ").slice(0, opts.maxChars ?? 600);
+    return `- [${record.kind} | ${date}] ${body}`;
+}
+export function approxTokens(text) {
+    return Math.max(1, Math.floor(text.split(/\s+/).length * 1.3));
+}

package/dist/policy.d.ts

@@ -0,0 +1,5 @@
+/** The injected agent policy and capture parameters — verbatim the same text the Python MCP
+ * server injects (token-lean: 198 approx tokens), so behaviour is identical across servers. */
+import type { MemoryPolicy } from "./memory.js";
+export declare const AGENT_MEMORY_INSTRUCTIONS: string;
+export declare function policySummary(policy: MemoryPolicy): string;

package/dist/policy.js

@@ -0,0 +1,19 @@
+export const AGENT_MEMORY_INSTRUCTIONS = "Use Midas memory on every task. It is local, source-traceable, and uses no LLM at ingest/query.\n\n" +
+    "1) RECALL FIRST. Call `build_context` with the user's goal; use the returned facts silently. Use " +
+    "`recall`/`inspect_memory` only when you need audit details.\n\n" +
+    "2) CAPTURE DURABLE SIGNAL. Call `capture` for reusable facts, decisions, preferences, constraints, " +
+    "corrections, and completed actions. Skip pure small talk. Midas scores, dedups, and rejects trivia, " +
+    "so capture can be brief and does not need an LLM. Set kind/provenance accurately; use " +
+    'provenance="user_confirmation" only for explicit user confirmation.\n\n' +
+    "3) GUARD ACTIONS. Memory may guide planning, but before external/destructive actions based on memory, " +
+    "call `check_memory_use`. If it is not allowed, ask the user to confirm in this turn.\n\n" +
+    "4) FORGET ON REQUEST. Use `forget_matching` as a dry-run first, show matches, then repeat with " +
+    "dry_run=false after confirmation.\n\n" +
+    "Midas stores verbatim source records and bounds memory automatically; compact context is for cheap " +
+    "reader prompts, audit tools are for traceability.";
+export function policySummary(policy) {
+    return (`keep items scoring importance >= ${policy.minImportance}/5, ` +
+        `kinds ${JSON.stringify(policy.acceptKinds)}, ` +
+        `skip near-duplicates (cosine >= ${policy.dedupThreshold}); ` +
+        "guard external/destructive actions to user_confirmation provenance");
+}

package/dist/store.d.ts

@@ -0,0 +1,35 @@
+import type { MemoryRecord } from "./types.js";
+export type Predicate = (record: MemoryRecord) => boolean;
+export declare class InMemoryStore {
+    protected records: Map<string, MemoryRecord>;
+    /** Monotonic change counter — lets Memory cache derived indexes (BM25) cheaply. */
+    version: number;
+    put(record: MemoryRecord): void;
+    get(recordId: string): MemoryRecord | null;
+    delete(recordId: string): boolean;
+    all(): MemoryRecord[];
+    clear(): void;
+    search(embedding: Float32Array, opts: {
+        limit: number;
+        predicate?: Predicate;
+    }): Array<[number, MemoryRecord]>;
+}
+export declare class SQLiteStore extends InMemoryStore {
+    private db;
+    private dataVersion;
+    constructor(path: string);
+    private currentDataVersion;
+    /** Reload the mirror when ANOTHER connection (e.g. the Python server) wrote the file. */
+    private refreshIfStale;
+    private load;
+    put(record: MemoryRecord): void;
+    get(recordId: string): MemoryRecord | null;
+    all(): MemoryRecord[];
+    search(embedding: Float32Array, opts: {
+        limit: number;
+        predicate?: Predicate;
+    }): Array<[number, MemoryRecord]>;
+    delete(recordId: string): boolean;
+    clear(): void;
+    close(): void;
+}

package/dist/store.js

@@ -0,0 +1,159 @@
+/** Stores — `InMemoryStore` (exact cosine scan) and `SQLiteStore` (node:sqlite persistence).
+ *
+ * SQLiteStore uses the SAME table schema and float32-blob encoding as the Python
+ * `midas/sqlite_store.py`, and the same `PRAGMA data_version` staleness probe — so a TypeScript
+ * MCP server and a Python one can share a single memory file, live, in both directions. */
+import { DatabaseSync } from "node:sqlite";
+import { cosine } from "./embeddings.js";
+export class InMemoryStore {
+    records = new Map();
+    /** Monotonic change counter — lets Memory cache derived indexes (BM25) cheaply. */
+    version = 0;
+    put(record) {
+        this.records.set(record.id, record);
+        this.version += 1;
+    }
+    get(recordId) {
+        return this.records.get(recordId) ?? null;
+    }
+    delete(recordId) {
+        const existed = this.records.delete(recordId);
+        if (existed)
+            this.version += 1;
+        return existed;
+    }
+    all() {
+        return [...this.records.values()];
+    }
+    clear() {
+        this.records.clear();
+        this.version += 1;
+    }
+    search(embedding, opts) {
+        const scored = [];
+        for (const r of this.records.values()) {
+            if (r.embedding === null)
+                continue;
+            if (opts.predicate && !opts.predicate(r))
+                continue;
+            scored.push([cosine(embedding, r.embedding), r]);
+        }
+        scored.sort((a, b) => b[0] - a[0]);
+        return scored.slice(0, opts.limit);
+    }
+}
+export class SQLiteStore extends InMemoryStore {
+    db;
+    dataVersion;
+    constructor(path) {
+        super();
+        this.db = new DatabaseSync(path);
+        this.db.exec("PRAGMA journal_mode=WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        importance INTEGER NOT NULL,
+        source TEXT,
+        provenance TEXT NOT NULL DEFAULT 'observation',
+        actor TEXT,
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        created_at REAL NOT NULL,
+        updated_at REAL NOT NULL,
+        superseded_by TEXT,
+        embedding BLOB
+      )
+    `);
+        this.load();
+        this.dataVersion = this.currentDataVersion();
+    }
+    currentDataVersion() {
+        const row = this.db.prepare("PRAGMA data_version").get();
+        return Number(row.data_version);
+    }
+    /** Reload the mirror when ANOTHER connection (e.g. the Python server) wrote the file. */
+    refreshIfStale() {
+        const v = this.currentDataVersion();
+        if (v === this.dataVersion)
+            return;
+        this.dataVersion = v;
+        this.records.clear();
+        this.version += 1;
+        this.load();
+    }
+    load() {
+        const rows = this.db
+            .prepare("SELECT id, content, kind, importance, source, provenance, actor, metadata_json, " +
+            "created_at, updated_at, superseded_by, embedding FROM memories")
+            .all();
+        for (const row of rows) {
+            super.put(rowToRecord(row));
+        }
+    }
+    put(record) {
+        this.refreshIfStale();
+        super.put(record);
+        const blob = record.embedding
+            ? new Uint8Array(record.embedding.buffer.slice(0), record.embedding.byteOffset, record.embedding.byteLength)
+            : null;
+        this.db
+            .prepare(`INSERT INTO memories (id, content, kind, importance, source, provenance, actor,
+                               metadata_json, created_at, updated_at, superseded_by, embedding)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           content=excluded.content, kind=excluded.kind, importance=excluded.importance,
+           source=excluded.source, provenance=excluded.provenance, actor=excluded.actor,
+           metadata_json=excluded.metadata_json,
+           created_at=excluded.created_at, updated_at=excluded.updated_at,
+           superseded_by=excluded.superseded_by, embedding=excluded.embedding`)
+            .run(record.id, record.content, record.kind, record.importance, record.source, record.provenance, record.actor, JSON.stringify(record.metadata ?? {}), record.createdAt, record.updatedAt, record.supersededBy, blob);
+    }
+    get(recordId) {
+        this.refreshIfStale();
+        return super.get(recordId);
+    }
+    all() {
+        this.refreshIfStale();
+        return super.all();
+    }
+    search(embedding, opts) {
+        this.refreshIfStale();
+        return super.search(embedding, opts);
+    }
+    delete(recordId) {
+        this.refreshIfStale();
+        const existed = super.delete(recordId);
+        if (existed)
+            this.db.prepare("DELETE FROM memories WHERE id = ?").run(recordId);
+        return existed;
+    }
+    clear() {
+        super.clear();
+        this.db.exec("DELETE FROM memories");
+    }
+    close() {
+        this.db.close();
+    }
+}
+function rowToRecord(row) {
+    let embedding = null;
+    if (row.embedding && row.embedding.byteLength >= 4) {
+        const bytes = new Uint8Array(row.embedding); // copy → aligned buffer
+        embedding = new Float32Array(bytes.buffer, 0, Math.floor(bytes.byteLength / 4));
+    }
+    return {
+        id: row.id,
+        content: row.content,
+        kind: row.kind,
+        importance: row.importance,
+        source: row.source,
+        provenance: (row.provenance || "observation"),
+        actor: row.actor,
+        metadata: row.metadata_json ? JSON.parse(row.metadata_json) : {},
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        supersededBy: row.superseded_by,
+        embedding,
+    };
+}