@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/src/memory/MemoryStore.ts

@@ -1,321 +1,216 @@
 /**
  * MemoryStore – persistent key-value fact store and weight checkpoint helper.
  *
- * Uses IndexedDB with a dedicated 'ssmjs' database containing two object stores:
- *   - 'facts'   : MemoryEntry records keyed by the fact key string
- *   - 'weights' : a single ArrayBuffer keyed by `weightsKey`
+ * Persistence is delegated to a narrow {@link FactStoragePort} (M01) fronted by
+ * a {@link ScopedFactRepository} unit-of-work layer (M02–M06):
+ *   - Browser default: IndexedDB via {@link IdbStorageAdapter}; every write
+ *     resolves only after the transaction commits (M02).
+ *   - Node.js: pass `storage: await NodeFileStorageAdapter.open(path)` for real
+ *     durable storage. fake-indexeddb via `idbFactory` remains supported for
+ *     TESTS, but is never durable and is not presented as such.
+ *   - Facts live in an explicit {@link MemoryScope} partition (default: the
+ *     unbound, never-connected scope) with durable revisions, operation
+ *     identity, provenance and — when `sync: true` — a journaled tombstone
+ *     trail that caps/TTL will not sacrifice (M03/M04/M06).
+ *
+ * Recall ranking and its derived embedding/index caches live in
+ * {@link SemanticRecall}; the public shapes in `./types.ts`.
  *
  * Weight save/load is delegated to the SSMRuntime passed to saveWeights/loadWeights.
  */
 
-import { SSMError } from '../errors/SSMError.js';
-import { tokenize, jaccardSimilarity } from '../similarity/index.js';
-import { hybridRetrieve, denseSearch, HnswIndex, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
-
-export type FactType = 'text' | 'json' | 'number' | 'boolean';
-
-export interface MemoryEntry {
-    key        : string;
-    content    : string;
-    timestamp  : number;
-    /**
-     * Monotonic write sequence, used only to break `timestamp` ties so that
-     * ordering stays deterministic when several entries are written within the
-     * same millisecond (Date.now() resolution). Higher = written later.
-     * Optional for backward compatibility with entries persisted/imported
-     * before this field existed (those sort as seq 0).
-     */
-    seq?       : number;
-    /** Optional time-to-live in milliseconds. */
-    ttlMs?     : number;
-    /** Semantic type of the stored value. Default: 'text'. */
-    type?      : FactType;
-    /** Tags for grouping and filtering. */
-    tags?      : string[];
-    /** Importance weight in the range 0–1. Default: 0.5. */
-    importance?: number;
-}
-
-/**
- * Which ranker produced a recall ordering. Matches the vocabulary the gateway's
- * Evermind recall/validate surfaces already report, so a host can render one chip
- * ("Semantic recall" / "Lexical recall (fallback)") regardless of which layer
- * answered.
- */
-export type RecallMethod = 'embedding' | 'lexical';
-
-/** A recalled entry with its relevance score (higher = closer). */
-export interface ScoredMemory {
-    entry: MemoryEntry;
-    score: number;
-}
-
-/** A ranked recall: the hits plus the ranker that ordered them. */
-export interface RankedRecall {
-    hits: ScoredMemory[];
-    method: RecallMethod;
-}
-
-export interface RememberOptions {
-    /** Override the store-level defaultTtlMs for this entry. */
-    ttlMs?     : number;
-    type?      : FactType;
-    tags?      : string[];
-    importance?: number;
-}
-
-export interface MemoryStoreOptions {
-    /** IndexedDB database name. Default: 'ssmjs'. */
-    dbName?       : string;
-    /** Key used for weight storage within the 'weights' object store. Default: 'ssmjs-weights'. */
-    weightsKey?   : string;
-    /**
-     * IDBFactory to use instead of the global `indexedDB`.
-     * Use this in Node.js environments with fake-indexeddb:
-     *   import { IDBFactory } from 'fake-indexeddb';
-     *   const idbFactory = new IDBFactory();
-     */
-    idbFactory?   : IDBFactory;
-    /**
-     * Default TTL applied to new entries when no per-entry ttlMs is provided.
-     * Entries with an expired TTL are filtered from recallAll() and related methods.
-     */
-    defaultTtlMs? : number;
-    /**
-     * Fact count at/above which semantic recall switches from an exact O(N)
-     * cosine scan to an O(log N) HNSW ANN index. Default 256 — small stores stay
-     * exact (simpler + faster), large stores stay fast. (EVM-1)
-     */
-    annThreshold? : number;
-    /**
-     * Hard cap on stored facts. When set, each write evicts the lowest-value
-     * entries (expired first, then lowest importance, then oldest) so the store
-     * stays bounded. Unset = unbounded (legacy). (EVM-7)
-     */
-    maxEntries?   : number;
-    /**
-     * Max content→embedding vectors held in the LRU recall cache. Default 2000.
-     * (EVM-8 — bounded LRU instead of clear-on-overflow.)
-     */
-    embedCacheMax?: number;
-}
-
-const FACTS_STORE   = 'facts';
-const WEIGHTS_STORE = 'weights';
-const DB_VERSION    = 1;
-
-/**
- * Process-wide monotonic counter stamped onto each remembered entry. Strictly
- * increasing per write regardless of store instance, so it reliably breaks
- * `timestamp` ties (same-millisecond writes) in newest-first ordering.
- */
-let _writeSeq = 0;
-
-// Minimal interface to avoid importing SSMRuntime (circular dep)
-interface SaveLoadRuntime {
-    save(opts?: { storage: 'indexedDB'; key: string }): Promise<void>;
-    load(opts?: { key: string }): Promise<boolean>;
-}
-
-// Forward-declared to avoid circular dependency at import time
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type SSMRuntimeRef = any;
+import type { HybridRetrieveOptions } from '../retrieval/index.js';
+import { IdbStorageAdapter } from '../storage/idbAdapter.js';
+import { ScopedFactRepository } from '../storage/ScopedFactRepository.js';
+import {
+    MemoryStorageError,
+    type ConsistencyNote,
+    type FactProvenance,
+    type FactStoragePort,
+    type MemoryScope,
+    type StoredFactRecord,
+    type TombstoneRecord,
+    type JournalEntry,
+} from '../storage/types.js';
+import { SemanticRecall } from './SemanticRecall.js';
+import { isExpired, liveEntries, rememberInput, toEntry, toImportRecord } from './records.js';
+import { TtlSweeper } from './ttlSweeper.js';
+import type {
+    MemoryEntry,
+    MemoryStoreOptions,
+    RankedRecall,
+    RememberOptions,
+    SaveLoadRuntime,
+    ScoredMemory,
+    SSMRuntimeRef,
+} from './types.js';
+
+export type {
+    FactType,
+    MemoryEntry,
+    MemoryStoreOptions,
+    RankedRecall,
+    RecallMethod,
+    RememberOptions,
+    ScoredMemory,
+} from './types.js';
 
 /** Max content→embedding vectors retained (LRU-evicted past this). (EVM-8) */
 const EMBED_CACHE_MAX = 2000;
 
 export class MemoryStore {
-    private readonly _dbName     : string;
     private readonly _weightsKey : string;
-    private readonly _idb        : IDBFactory | undefined;
     private readonly _defaultTtl : number | undefined;
-    private readonly _annThreshold : number;
     private readonly _maxEntries : number | undefined;
-    private readonly _embedCacheMax : number;
-    private _db: IDBDatabase | null = null;
-    private _sweepTimer: ReturnType<typeof setInterval> | null = null;
-    /** Content → L2-normalised embedding cache, used by recallSimilar. */
-    private readonly _embedCache = new Map<string, Float32Array>();
-    /** Runtime whose embeddings populate `_embedCache`; a change invalidates it. */
-    private _embedRuntime: unknown = null;
-
-    // ── Persistent dense index (EVM-1b) ────────────────────────────────────────
-    // Fact embeddings keyed by `${key}@${seq}` so an EDIT (seq bump) is a new key
-    // and an unchanged fact is never re-embedded. The HNSW index is derived from
-    // these vectors and reused across recalls until the fact set changes — so
-    // steady-state recall is O(1) query-embed + O(log N) search, not O(N) embed.
-    private readonly _denseVectors = new Map<string, Float32Array>();
-    private _denseIndex: HnswIndex | null = null;
-    /** Signature of the fact set the current index was built from. */
-    private _denseSig = '';
-    /** Identity of the runtime whose embeddings populated the vectors. */
-    private _denseRuntime: unknown = null;
+    private readonly _scope: MemoryScope;
+    /** The unit-of-work layer every durable operation flows through. */
+    readonly repository: ScopedFactRepository;
+    private readonly _storage: FactStoragePort;
+    /** Cross-context subscription, opened on the first operation (see `_ready`). */
+    private _unsubscribe: (() => void) | undefined;
+    private _subscribed = false;
+    private readonly _sweeper = new TtlSweeper();
+    /** Ranking + its embedding / dense-index caches (EVM-1, EVM-1b, EVM-8). */
+    private readonly _recall: SemanticRecall;
+    /**
+     * Last store generation observed from a FOREIGN context (another tab,
+     * window or process). Monotonic, in-memory only; lets readers notice
+     * cross-context writes without a storage round-trip per recall (M05).
+     */
+    private _foreignRevision = 0;
 
     constructor(opts: MemoryStoreOptions = {}) {
-        this._dbName     = opts.dbName     ?? 'ssmjs';
         this._weightsKey = opts.weightsKey ?? 'ssmjs-weights';
-        this._idb        = opts.idbFactory;
         this._defaultTtl = opts.defaultTtlMs;
-        this._annThreshold = opts.annThreshold ?? 256;
         this._maxEntries = opts.maxEntries;
-        this._embedCacheMax = opts.embedCacheMax ?? EMBED_CACHE_MAX;
+        this._recall = new SemanticRecall({
+            annThreshold : opts.annThreshold ?? 256,
+            embedCacheMax: opts.embedCacheMax ?? EMBED_CACHE_MAX,
+            // Opt-in floor: 0 keeps recall returning its best hits, as it always did.
+            minRelevance : opts.minRelevance ?? 0,
+        });
+        this._scope = opts.scope ? { ...opts.scope } : {};
+        this._storage = opts.storage ?? new IdbStorageAdapter(opts.dbName ?? 'ssmjs', {
+            idbFactory: opts.idbFactory,
+            contextId : opts.contextId,
+        });
+        this.repository = new ScopedFactRepository(this._storage, {
+            syncEnabled: opts.sync ?? false,
+            contextId  : opts.contextId,
+        });
     }
 
-    // ── Internal DB open ──────────────────────────────────────────────────────
-
-    private _open(): Promise<IDBDatabase> {
-        if (this._db) return Promise.resolve(this._db);
-
-        return new Promise((resolve, reject) => {
-            const factory = this._idb ?? (typeof indexedDB !== 'undefined' ? indexedDB : undefined);
-            if (!factory) {
-                reject(new SSMError(
-                    'MEMORY_UNAVAILABLE',
-                    'IndexedDB is not available in this environment. Pass an idbFactory option (e.g. from fake-indexeddb) for Node.js support.',
-                ));
-                return;
-            }
-
-            const req = factory.open(this._dbName, DB_VERSION);
-
-            req.onupgradeneeded = (e) => {
-                const db = (e.target as IDBOpenDBRequest).result;
-                if (!db.objectStoreNames.contains(FACTS_STORE)) {
-                    db.createObjectStore(FACTS_STORE, { keyPath: 'key' });
-                }
-                if (!db.objectStoreNames.contains(WEIGHTS_STORE)) {
-                    db.createObjectStore(WEIGHTS_STORE);
-                }
-            };
-
-            req.onsuccess = () => {
-                this._db = req.result;
-                resolve(req.result);
-            };
-            /* istanbul ignore next -- IDB open onerror fires only on storage faults; not reproducible with fake-indexeddb */
-            req.onerror = () => reject(new SSMError(
-                'MEMORY_UNAVAILABLE',
-                `Failed to open IndexedDB "${this._dbName}": ${req.error?.message ?? 'unknown'}`,
-                req.error,
-            ));
-        });
+    /**
+     * Cross-context invalidation (M05): a sibling tab/window/process that
+     * commits against the same storage invalidates this instance's derived
+     * caches. Subscribed lazily on the first operation: before it there are no
+     * caches to invalidate, and an eager subscription opened a global
+     * BroadcastChannel in the constructor that kept Node processes alive.
+     */
+    private _ready(): void {
+        if (this._subscribed) return;
+        this._subscribed = true;
+        this._unsubscribe = this.repository.subscribe((note) => this._onForeignChange(note));
     }
 
-    // ── TTL helpers ───────────────────────────────────────────────────────────
+    /** The scope partition this store is bound to (never widened implicitly). */
+    get scope(): MemoryScope {
+        return { ...this._scope };
+    }
+
+    /** The durable storage backend kind in use ('indexedDB' | 'node-file'). */
+    get storageKind(): FactStoragePort['kind'] {
+        return this._storage.kind;
+    }
+
+    /**
+     * Best-effort in-memory token that changes when another context writes to
+     * this store's database. Readers (e.g. EvermindCognition's recall cache)
+     * can fold it into their cache key so cross-context writes invalidate
+     * without a storage hit per recall.
+     */
+    get foreignRevision(): number {
+        return this._foreignRevision;
+    }
 
-    private _isExpired(entry: MemoryEntry): boolean {
-        if (entry.ttlMs == null) return false;
-        return Date.now() > entry.timestamp + entry.ttlMs;
+    private _onForeignChange(note: ConsistencyNote): void {
+        if (note.revision <= this._foreignRevision) return;
+        this._foreignRevision = note.revision;
+        // Derived caches describe a fact set another context just changed.
+        this._recall.invalidate();
     }
 
     // ── Semantic facts ────────────────────────────────────────────────────────
 
-    /** Stores or overwrites a fact. */
+    /**
+     * Stores or overwrites a fact. Resolves only after the underlying
+     * transaction commits durably (M02); the fact, its provenance and its sync
+     * journal entry commit atomically.
+     */
     async remember(key: string, content: string, opts?: RememberOptions): Promise<void> {
-        const db = await this._open();
-        const entry: MemoryEntry = {
-            key,
-            content,
-            timestamp  : Date.now(),
-            seq        : ++_writeSeq,
-            ttlMs      : opts?.ttlMs ?? this._defaultTtl,
-            type       : opts?.type,
-            tags       : opts?.tags,
-            importance : opts?.importance,
-        };
-
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        await requestToPromise(tx.objectStore(FACTS_STORE).put(entry), `Failed to store fact "${key}"`, () => undefined);
-        // EVM-7: keep the store bounded — evict lowest-value entries past the cap.
-        if (this._maxEntries != null) await this._enforceCap();
+        this._ready();
+        await this.repository.remember(this._scope, key, rememberInput(content, opts, this._defaultTtl));
+        // EVM-7: keep the store bounded — evict lowest-value SYNCED entries past
+        // the cap; unsynced knowledge is never sacrificed to a cache cap (M06).
+        if (this._maxEntries != null) {
+            await this.repository.evictForCap(this._scope, this._maxEntries, isExpired);
+        }
     }
 
     /**
-     * Evicts the lowest-value entries until at most `maxEntries` remain. Eviction
-     * priority (removed first): expired → lowest importance → oldest. No-op when
-     * no cap is set or the store is under it. (EVM-7)
+     * Compare-and-set write (M04/M05): commits only if the record's current
+     * revision equals `expectedRevision` (`null` asserts the key is absent).
+     * Throws a MemoryStorageError otherwise (`code` 'MEMORY_CONFLICT',
+     * `storageCode` 'STORAGE_CONFLICT'; see `isStorageConflict`) — callers reconcile
+     * (re-read, re-evaluate evidence) instead of blindly overwriting a
+     * concurrent writer. Returns the committed entry.
      */
-    private async _enforceCap(): Promise<void> {
-        if (this._maxEntries == null) return;
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        const all = await requestToPromise(
-            tx.objectStore(FACTS_STORE).getAll() as IDBRequest<MemoryEntry[]>,
-            'Failed to scan facts for cap',
-            (r) => r,
-        );
-        if (all.length <= this._maxEntries) return;
-
-        // Ascending sort = worst first: expired (0) before live (1), then lower
-        // importance, then older timestamp, then lower write sequence.
-        const rank = (e: MemoryEntry): [number, number, number, number] =>
-            [this._isExpired(e) ? 0 : 1, e.importance ?? 0.5, e.timestamp, e.seq ?? 0];
-        const sorted = [...all].sort((a, b) => {
-            const ra = rank(a), rb = rank(b);
-            for (let i = 0; i < ra.length; i++) {
-                if (ra[i] !== rb[i]) return ra[i]! - rb[i]!;
-            }
-            return 0;
+    async rememberCas(key: string, content: string, expectedRevision: number | null, opts?: RememberOptions): Promise<MemoryEntry> {
+        this._ready();
+        const { record } = await this.repository.remember(this._scope, key, {
+            ...rememberInput(content, opts, this._defaultTtl),
+            expectedRevision,
         });
-        const victims = sorted.slice(0, all.length - this._maxEntries);
-        await Promise.all(victims.map((e) => this.forget(e.key)));
+        return toEntry(record);
+    }
+
+    /** Fetches an entry WITH its durable revision, for CAS-based reconciliation. */
+    async recallVersioned(key: string): Promise<MemoryEntry | undefined> {
+        return this.recall(key);
     }
 
     /**
-     * Starts a background timer that periodically hard-deletes expired entries —
+     * Starts a background timer that periodically deletes expired entries —
      * TTL is otherwise only evaluated lazily on read, so an idle store would keep
      * dead entries forever. Idempotent; pair with {@link stopTtlSweeper}. (EVM-7)
+     *
+     * With sync enabled each expiry is a scoped deletion (tombstone + journal),
+     * not a silent drop (M06).
      */
     startTtlSweeper(intervalMs: number): void {
-        if (this._sweepTimer) return;
-        const timer = setInterval(() => { void this.purgeExpired(); }, intervalMs);
-        // Don't keep a Node process alive just for the sweeper.
-        const maybeUnref = timer as unknown as { unref?: () => void };
-        /* istanbul ignore else -- unref exists in Node; absent in the browser */
-        if (typeof maybeUnref.unref === 'function') {
-            maybeUnref.unref();
-        }
-        this._sweepTimer = timer;
+        this._sweeper.start(intervalMs, () => this.purgeExpired());
     }
 
     /** Stops the background TTL sweeper started by {@link startTtlSweeper}. */
     stopTtlSweeper(): void {
-        if (this._sweepTimer) {
-            clearInterval(this._sweepTimer);
-            this._sweepTimer = null;
-        }
+        this._sweeper.stop();
     }
 
     /**
-     * Retrieves a fact by key.
+     * Retrieves a fact by key from this store's scope partition.
      * Returns `undefined` if the key does not exist or the entry has expired.
      */
     async recall(key: string): Promise<MemoryEntry | undefined> {
-        const db = await this._open();
-
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        return requestToPromise(
-            tx.objectStore(FACTS_STORE).get(key) as IDBRequest<MemoryEntry | undefined>,
-            `Failed to recall fact "${key}"`,
-            (entry) => (entry && this._isExpired(entry) ? undefined : entry),
-        );
+        this._ready();
+        const record = await this.repository.get(this._scope, key);
+        if (!record || isExpired(record)) return undefined;
+        return toEntry(record);
     }
 
-    /** Returns all non-expired stored facts, newest first. */
+    /** Returns all non-expired stored facts in this store's scope, newest first. */
     async recallAll(): Promise<MemoryEntry[]> {
-        const db = await this._open();
-
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        return requestToPromise(
-            tx.objectStore(FACTS_STORE).getAll() as IDBRequest<MemoryEntry[]>,
-            'Failed to recall all facts',
-            (entries) => entries
-                .filter(e => !this._isExpired(e))
-                // Newest first; break same-millisecond ties by write sequence so
-                // ordering is deterministic (IndexedDB getAll() returns key order,
-                // which would otherwise surface same-ms writes oldest-first).
-                .sort((a, b) => b.timestamp - a.timestamp || (b.seq ?? 0) - (a.seq ?? 0)),
-        );
+        this._ready();
+        return liveEntries(await this.repository.getAll(this._scope));
     }
 
     /**
@@ -329,23 +224,19 @@ export class MemoryStore {
 
     /**
      * Returns all non-expired entries that contain the given tag.
+     * Looks the tag up on the facts `byTag` index when the storage adapter has
+     * one; a full scan is used only when that index is missing.
      */
     async recallByTag(tag: string): Promise<MemoryEntry[]> {
-        const all = await this.recallAll();
-        return all.filter(e => e.tags?.includes(tag) ?? false);
+        this._ready();
+        return liveEntries(await this.repository.getByTag(this._scope, tag));
     }
 
     /**
-     * Finds the top-K semantically similar entries to `query`.
-     *
-     * When `runtime` exposes an `embed()` method (the SSMRuntime does), similarity
-     * is computed as cosine distance between SSM hidden-state embeddings — i.e. the
-     * memory layer uses the very model it is attached to, and recall quality
-     * improves automatically as that model is adapted/distilled. Embeddings are
-     * cached per content string to avoid recomputing across calls.
-     *
-     * If no embedding-capable runtime is provided, or embedding fails for any
-     * reason, it transparently falls back to Jaccard word-overlap similarity.
+     * Finds the top-K semantically similar entries to `query`: cosine over the
+     * attached SSM runtime's embeddings (so recall improves as that model is
+     * adapted), or Jaccard word overlap when no runtime can embed. See
+     * {@link SemanticRecall}.
      */
     async recallSimilar(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<MemoryEntry[]> {
         return (await this.recallSimilarScored(query, topK, runtime)).map(s => s.entry);
@@ -357,52 +248,15 @@ export class MemoryStore {
      * so callers can rank/threshold by TRUE similarity instead of list position.
      * {@link recallSimilar} is the score-dropping convenience wrapper over this.
      */
-    async recallSimilarScored(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<Array<{ entry: MemoryEntry; score: number }>> {
-        const all = await this.recallAll();
-        if (all.length === 0) return [];
-
-        // ── Preferred path: SSM-embedding cosine similarity ───────────────────
-        if (runtime != null && typeof runtime.embed === 'function') {
-            const queryVec = await this._embedWithCache(runtime, query);
-            if (queryVec) {
-                // EVM-1b: sync the persistent vector store + index (embeds only the
-                // delta), then query it — no per-call re-embed of every fact.
-                const synced = await this._syncDense(runtime, all);
-                if (synced) {
-                    const hits = synced.index
-                        // EVM-1: above the threshold, query the persistent HNSW (O(log N)).
-                        ? synced.index.search(queryVec, topK)
-                        // Below it, an exact scan over the (already-embedded) vectors.
-                        : denseSearch(queryVec, synced.items, topK, this._annThreshold);
-                    return hits
-                        .map(h => { const entry = synced.byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
-                        .filter((e): e is { entry: MemoryEntry; score: number } => !!e);
-                }
-            }
-            // Any failure falls through to the Jaccard path below.
-        }
-
-        // ── Fallback: Jaccard word-overlap similarity ─────────────────────────
-        const queryTokens = new Set(tokenize(query));
-        const scored = all.map(entry => {
-            const entryTokens = new Set(tokenize(entry.content));
-            const score       = jaccardSimilarity(queryTokens, entryTokens);
-            return { entry, score };
-        });
-
-        scored.sort((a, b) => b.score - a.score);
-        return scored.slice(0, topK);
+    async recallSimilarScored(query: string, topK: number, runtime?: SSMRuntimeRef): Promise<ScoredMemory[]> {
+        return this._recall.similar(await this.recallAll(), query, topK, runtime);
     }
 
     /**
-     * Hybrid recall: fuses dense (SSM-embedding cosine) and sparse (BM25 lexical)
-     * rankings via Reciprocal Rank Fusion, then applies an MMR diversity rerank.
-     *
-     * This is the production RAG retrieval path — it catches both semantic matches
-     * (embeddings) and exact-token matches (BM25 — identifiers, codes, rare names)
-     * that cosine-only `recallSimilar` misses, and avoids returning near-duplicate
-     * facts. Degrades to BM25-only when no embedding-capable runtime is available,
-     * so it is always strictly at least as good as the lexical fallback.
+     * Hybrid recall: dense (SSM-embedding cosine) and sparse (BM25) rankings
+     * fused by Reciprocal Rank Fusion, then an MMR diversity rerank — catches
+     * exact-token matches cosine misses, and degrades to BM25 alone without a
+     * runtime. The production RAG path.
      */
     async recallHybrid(
         query: string,
@@ -414,19 +268,10 @@ export class MemoryStore {
     }
 
     /**
-     * The hybrid retrieval path with its evidence attached: each hit's fused score,
-     * plus WHICH ranker produced the ordering.
-     *
-     * {@link recallHybrid} is the convenience wrapper that throws both away, so
-     * there is exactly one implementation of the blend — and it is the shared
-     * `hybridRetrieve` → `reciprocalRankFusion` primitive, never a second hand-
-     * rolled mix of cosine and word overlap.
-     *
-     * `method` is honest rather than aspirational: `'embedding'` means the query
-     * really did embed and the dense ranking really did participate in the fusion;
-     * `'lexical'` means no model was available (or embedding failed) and the
-     * ordering is BM25 alone. Callers surface it so a user can tell semantic
-     * recall from the fallback instead of guessing.
+     * {@link recallHybrid} with its evidence: each hit's fused score, and WHICH
+     * ranker produced the ordering — `'embedding'` only when the query and the
+     * candidates really embedded, `'lexical'` when the ordering is BM25 alone.
+     * One blend implementation: the shared `hybridRetrieve` primitive.
      */
     async recallRanked(
         query: string,
@@ -434,218 +279,102 @@ export class MemoryStore {
         runtime?: SSMRuntimeRef,
         opts?: HybridRetrieveOptions,
     ): Promise<RankedRecall> {
-        const all = await this.recallAll();
-        if (all.length === 0) return { hits: [], method: 'lexical' };
-
-        // Embed candidates + query where a runtime is available; null vectors are
-        // fine — hybridRetrieve degrades that candidate to BM25-only.
-        const canEmbed = runtime != null && typeof runtime.embed === 'function';
-        const queryVec = canEmbed ? (await this._embedWithCache(runtime, query)) ?? undefined : undefined;
-
-        const candidates: RetrievalCandidate[] = [];
-        for (const entry of all) {
-            const vector = queryVec ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
-            candidates.push({ id: entry.key, text: entry.content, vector });
-        }
-
-        // The dense ranking only exists when the query embedded AND at least one
-        // candidate did — anything less is a lexical ordering wearing a label.
-        const dense = !!queryVec && candidates.some(c => !!c.vector);
-        const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, annThreshold: this._annThreshold, ...opts });
-        const byKey = new Map(all.map(e => [e.key, e]));
-        return {
-            hits: hits
-                .map(h => { const entry = byKey.get(h.id); return entry ? { entry, score: h.score } : null; })
-                .filter((h): h is ScoredMemory => !!h),
-            method: dense ? 'embedding' : 'lexical',
-        };
+        return this._recall.ranked(await this.recallAll(), query, topK, runtime, opts);
     }
 
     /**
-     * Returns a cached embedding for `text`, computing it via `runtime.embed()`
-     * on a cache miss. Returns `null` (never throws) when embedding is
-     * unavailable so callers can fall back to lexical similarity.
+     * Deletes all entries whose TTL has expired. With sync enabled each expiry
+     * commits a tombstone + journal entry in the same transaction, so expiries
+     * propagate instead of resurrecting from a replica (M06).
+     * @returns The number of entries deleted.
      */
-    private async _embedWithCache(runtime: SSMRuntimeRef, text: string): Promise<Float32Array | null> {
-        // Embeddings are model-specific: if the runtime instance changed, the cached
-        // vectors are from a different model and must be dropped. (EVM-1b)
-        if (runtime !== this._embedRuntime) {
-            this._embedCache.clear();
-            this._embedRuntime = runtime;
-        }
-        const cached = this._embedCache.get(text);
-        if (cached) {
-            // LRU touch: re-insert so this entry becomes most-recently-used. (EVM-8)
-            this._embedCache.delete(text);
-            this._embedCache.set(text, cached);
-            return cached;
-        }
-        try {
-            const vec = await runtime.embed(text);
-            if (vec instanceof Float32Array && vec.length > 0) {
-                // EVM-8: bound cache growth by evicting the LEAST-recently-used entry
-                // (Map keeps insertion order; the first key is the LRU), instead of
-                // dumping the whole cache on every overflow.
-                if (this._embedCache.size >= this._embedCacheMax) {
-                    const lru = this._embedCache.keys().next().value;
-                    if (lru !== undefined) this._embedCache.delete(lru);
-                }
-                this._embedCache.set(text, vec);
-                return vec;
-            }
-        } catch {
-            // Embedding unavailable (no GPU, destroyed runtime, etc.) — signal fallback.
-        }
-        return null;
+    async purgeExpired(): Promise<number> {
+        this._ready();
+        return this.repository.purgeExpired(this._scope, isExpired);
     }
 
     /**
-     * Synchronise the persistent dense vector store + HNSW index to `all` (EVM-1b).
-     * Embeds ONLY new/changed facts (keyed by `key@seq`), prunes removed ones, and
-     * rebuilds the index only when the fact set actually changed — so a read-heavy
-     * workload reuses both the embeddings and the index across recalls. Returns
-     * `null` (caller falls back to lexical) if any embedding is unavailable, or
-     * resets everything when the runtime identity changes (embeddings are
-     * model-specific).
+     * Deletes a single fact. No-op if key does not exist. With sync enabled the
+     * delete is a durable tombstone + journal entry committed atomically (M04).
      */
-    private async _syncDense(
-        runtime: SSMRuntimeRef,
-        all: MemoryEntry[],
-    ): Promise<{ byKey: Map<string, MemoryEntry>; items: Array<{ id: string; vector: Float32Array }>; index: HnswIndex | null } | null> {
-        if (runtime !== this._denseRuntime) {
-            this._denseVectors.clear();
-            this._denseIndex = null;
-            this._denseSig = '';
-            this._denseRuntime = runtime;
-        }
+    async forget(key: string): Promise<void> {
+        this._ready();
+        await this.repository.forget(this._scope, key);
+    }
 
-        const vkeyOf = (e: MemoryEntry): string => `${e.key}@${e.seq ?? 0}`;
-        const currentVkeys = new Set<string>();
-        let sig = `${all.length}`;
-        for (const e of all) { const k = vkeyOf(e); currentVkeys.add(k); sig += '|' + k; }
-
-        const byKey = new Map<string, MemoryEntry>();
-        const items: Array<{ id: string; vector: Float32Array }> = [];
-        for (const entry of all) {
-            const vk = vkeyOf(entry);
-            let vec = this._denseVectors.get(vk);
-            if (!vec) {
-                const v = await this._embedWithCache(runtime, entry.content);
-                if (!v) return null; // embedding failed → lexical fallback
-                vec = v;
-                this._denseVectors.set(vk, vec);
-            }
-            items.push({ id: entry.key, vector: vec });
-            byKey.set(entry.key, entry);
-        }
+    /** Deletes all facts in this store's scope. Does not affect saved weights. */
+    async clear(): Promise<void> {
+        // Drop the persistent dense index/vectors too (EVM-1b) — they describe a
+        // fact set that no longer exists.
+        this._ready();
+        this._recall.resetDense();
+        await this.repository.clear(this._scope);
+    }
 
-        // Drop vectors for facts that are gone or were edited (stale vkeys).
-        if (this._denseVectors.size > currentVkeys.size) {
-            for (const k of this._denseVectors.keys()) {
-                if (!currentVkeys.has(k)) this._denseVectors.delete(k);
-            }
-        }
+    // ── Sync protocol surface (M04) ───────────────────────────────────────────
 
-        // Maintain the ANN index only above the threshold; (re)build it only when
-        // the fact set changed (no embedding involved — purely in-memory).
-        if (all.length >= this._annThreshold) {
-            if (sig !== this._denseSig || this._denseIndex === null) {
-                const index = new HnswIndex();
-                for (const it of items) index.add(it.id, it.vector);
-                this._denseIndex = index;
-            }
-        } else {
-            this._denseIndex = null;
-        }
-        this._denseSig = sig;
-        return { byKey, items, index: this._denseIndex };
+    /** Operations not yet acknowledged by sync — the pending knowledge set. */
+    async pendingOps(): Promise<JournalEntry[]> {
+        return this.repository.pendingOps();
+    }
+
+    /** Delete tombstones in this store's scope (or all scopes when omitted). */
+    async tombstones(scope?: MemoryScope): Promise<TombstoneRecord[]> {
+        return this.repository.tombstones(scope);
     }
 
     /**
-     * Hard-deletes all entries whose TTL has expired.
-     * @returns The number of entries deleted.
+     * Acknowledges that the given operations reached the sync target. Their
+     * facts/tombstones stop being `pendingSync`, so retention may touch them
+     * again. Retention NEVER touches unacknowledged knowledge (M06).
      */
-    async purgeExpired(): Promise<number> {
-        const db = await this._open();
-
-        // Load all raw entries (including expired ones) to check each
-        const tx = db.transaction(FACTS_STORE, 'readonly');
-        const all = await requestToPromise(
-            tx.objectStore(FACTS_STORE).getAll() as IDBRequest<MemoryEntry[]>,
-            'Failed to scan facts for purge',
-            (r) => r,
-        );
-
-        const expired = all.filter(e => this._isExpired(e));
-        if (expired.length === 0) return 0;
-
-        await Promise.all(expired.map(e => this.forget(e.key)));
-        return expired.length;
+    async markSynced(opIds: string[]): Promise<void> {
+        await this.repository.markSynced(opIds);
     }
 
-    /** Deletes a single fact. No-op if key does not exist. */
-    async forget(key: string): Promise<void> {
-        const db = await this._open();
-
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).delete(key), `Failed to forget fact "${key}"`, () => undefined);
+    /** The current durable store generation. */
+    async revision(): Promise<number> {
+        return this.repository.revision();
     }
 
-    /** Deletes all facts. Does not affect saved weights. */
-    async clear(): Promise<void> {
-        const db = await this._open();
-        // Drop the persistent dense index/vectors too (EVM-1b) — they describe a
-        // fact set that no longer exists.
-        this._denseVectors.clear();
-        this._denseIndex = null;
-        this._denseSig = '';
-
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).clear(), 'Failed to clear facts', () => undefined);
+    /** Releases cross-context subscriptions and the underlying connection. */
+    close(): void {
+        this.stopTtlSweeper();
+        this._unsubscribe?.();
+        this._unsubscribe = undefined;
+        this._storage.close?.();
     }
 
     // ── Cross-session memory merge ────────────────────────────────────────────
 
     /**
      * Returns all non-expired facts as a plain array for export.
-     * Suitable for serialisation and import into another MemoryStore instance.
+     * Scope, revision and provenance travel with each entry (M03).
      */
     async exportAll(): Promise<MemoryEntry[]> {
         return this.recallAll();
     }
 
     /**
-     * Imports entries from an external array.
+     * Imports entries from an external array INTO this store's scope partition.
+     * Source timestamps, sequences, tags, importance, TTL and provenance are
+     * preserved — import never rewrites source time (M06).
      *
      * - `'merge'`     : only writes an entry if no existing entry with the same
      *                   key exists, or if the incoming entry has a newer timestamp.
      * - `'overwrite'` : writes all entries unconditionally.
      */
-    async importAll(entries: MemoryEntry[], strategy: 'merge' | 'overwrite'): Promise<void> {
-        for (const entry of entries) {
-            if (strategy === 'overwrite') {
-                await this._putRaw(entry);
-            } else {
-                const existing = await this.recall(entry.key);
-                if (existing == null || entry.timestamp > existing.timestamp) {
-                    await this._putRaw(entry);
-                }
-            }
-        }
-    }
-
-    /** Writes a raw MemoryEntry directly (preserves original timestamp / metadata). */
-    private async _putRaw(entry: MemoryEntry): Promise<void> {
-        const db = await this._open();
-        const tx = db.transaction(FACTS_STORE, 'readwrite');
-        return requestToPromise(tx.objectStore(FACTS_STORE).put(entry), `Failed to import fact "${entry.key}"`, () => undefined);
+    async importAll(entries: MemoryEntry[], strategy: 'merge' | 'overwrite', importedFrom?: string): Promise<void> {
+        this._ready();
+        const records = entries.map((e) => toImportRecord(e, this._scope));
+        await this.repository.importRecords(this._scope, records, strategy, importedFrom);
     }
 
     // ── Weight persistence ────────────────────────────────────────────────────
 
     /**
      * Saves SSM weights via `runtime.save()`.
-     * The weights are stored under `weightsKey` in this store's IndexedDB,
+     * The weights are stored under `weightsKey` in the session's IndexedDB,
      * separate from MambaSession's own key.
      */
     async saveWeights(runtime: SaveLoadRuntime): Promise<void> {
@@ -661,27 +390,18 @@ export class MemoryStore {
     }
 }
 
-// ── IndexedDB helper ──────────────────────────────────────────────────────────
-
-/**
- * Wires an IDBRequest to a promise: resolves with `map(result)` on success,
- * rejects with a normalised MEMORY_UNAVAILABLE error on failure. Extracted so
- * the success/error wiring lives in one place instead of being duplicated across
- * every store method.
- *
- * The onerror branch fires only on IndexedDB storage faults (quota exceeded,
- * disk failure, corruption), which the in-memory fake-indexeddb used in tests
- * cannot reproduce — hence the istanbul ignore on that single line.
- */
-function requestToPromise<R, T>(req: IDBRequest<R>, failMsg: string, map: (result: R) => T): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-        req.onsuccess = () => resolve(map(req.result));
-        /* istanbul ignore next -- IDB storage-fault path; not reproducible with fake-indexeddb */
-        req.onerror = () => reject(new SSMError(
-            'MEMORY_UNAVAILABLE',
-            `${failMsg}: ${req.error?.message ?? 'unknown'}`,
-            req.error ?? undefined,
-        ));
-    });
-}
-
+// Re-export the storage seam so consumers reach it through the store's module.
+export {
+    IdbStorageAdapter,
+    ScopedFactRepository,
+    MemoryStorageError,
+};
+export type {
+    ConsistencyNote,
+    FactProvenance,
+    FactStoragePort,
+    JournalEntry,
+    MemoryScope,
+    StoredFactRecord,
+    TombstoneRecord,
+};