wotann 0.5.0

package/dist/memory/store.js

@@ -0,0 +1,3571 @@
+/**
+ * SQLite memory store with FTS5 full-text search.
+ * 8-layer unified memory system per §14 and MEMORY_ARCHITECTURE.md.
+ *
+ * LAYERS:
+ * 1. Auto-Capture — every tool call, file read, command output
+ * 2. Core Blocks — user/feedback/project/reference/cases/patterns/decisions/issues
+ * 3. Working Memory — current session state, recent context
+ * 4. Knowledge Graph — entity relationships, bi-temporal facts
+ * 5. Archival — long-term storage with temporal decay
+ * 6. Recall — retrieval with skeptical verification
+ * 7. Team Memory — shared across agents/sessions
+ * 8. Proactive Context — anticipated context based on patterns
+ *
+ * FEATURES:
+ * - FTS5 full-text search across all layers
+ * - Skeptical memory: verify before acting on recalled memories
+ * - Consolidation lock: prevent concurrent autoDream sessions
+ * - Decision log: track architectural/design decisions with rationale
+ * - Temporal decay: older memories get lower relevance scores
+ * - Privacy tags: mark sensitive memories for restricted access
+ */
+import Database from "better-sqlite3";
+import { join } from "node:path";
+import { mkdirSync, existsSync, writeFileSync, readFileSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { writeFileAtomicSyncBestEffort } from "../utils/atomic-io.js";
+import { deriveIngestTimestamps } from "./dual-timestamp.js";
+import { clampContextTokens, cleanContext, buildContextualChunk, buildBatchedContextualChunks, createLlmContextGenerator, } from "./contextual-embeddings.js";
+import { fromStoreFields as palaceFromStoreFields, toStoreFields as palaceToStoreFields, isUnder as palaceIsUnder, parsePath as palaceParsePath, formatPath as palaceFormatPath, listHalls as palaceListHalls, listWings as palaceListWings, listRooms as palaceListRooms, countTree as palaceCountTree, renderTree as palaceRenderTree, } from "./mem-palace.js";
+import { hybridFusion as rrfFusion, temporalFiltered, metadataOnly, summaryOnly, } from "./extended-search-types.js";
+import { EntitySchema } from "./entity-types.js";
+import { createHeuristicClassifier, resolveLatest, partitionByKind } from "./relationship-types.js";
+import { validateDate, validateDateOrNull, } from "./bi-temporal-edges.js";
+import { IncrementalIndexer, computeContentSha, } from "./incremental-indexer.js";
+import { hybridSearch as hybridRetrieverSearch, createLexicalRetriever, createVectorRetriever, } from "./hybrid-retrieval.js";
+import { MemvidBackend, } from "./memvid-backend.js";
+import { SemanticCache, bigramEmbedding, } from "./semantic-cache.js";
+import { MemoryBenchmark } from "./memory-benchmark.js";
+import { MemoryToolkit, } from "./memory-tools.js";
+import { createTEMPR, } from "./tempr.js";
+import { createHeuristicCrossEncoder } from "./cross-encoder.js";
+// V9 T1.3 — sqlite-vec backend (FATAL orphan). Loaded opt-in via
+// `WOTANN_SQLITE_VEC=1` env var because the native `sqlite-vec`
+// extension isn't bundled by default; loading is synchronous when
+// the extension is available.
+import { createSqliteVecBackend, isSqliteVecAvailable, } from "./sqlite-vec-backend.js";
+// Asymmetric embedding prefixes — model-aware text shaping inspired by
+// LightRAG's `embedding-prefixes` branch (HKUDS, merged 2026-04-26).
+// Modern instruction-tuned encoders (BGE / Qwen3-Embedding / E5) score
+// noticeably higher when queries get one prefix and docs get another.
+// Gated behind `WOTANN_ASYMMETRIC_EMBEDDINGS=1` so existing un-prefixed
+// indexes keep working unchanged. See ./embedding-profiles.ts.
+import { applyDocPrefix, applyQueryPrefix, getEmbeddingProfile, isAsymmetricEmbeddingsEnabled, } from "./embedding-profiles.js";
+// V9 T1.4 — ONNX cross-encoder (FATAL orphan). Session loading is
+// async (`loadMiniLmSession`) so the member field is populated post-
+// construction via `attachOnnxCrossEncoder()`. Baseline remains
+// the heuristic encoder for sync callers.
+import { createOnnxCrossEncoder, isMiniLmModelAvailable, isOnnxRuntimeAvailable, loadMiniLmSession, } from "./onnx-cross-encoder.js";
+import { createDefaultRetrievalRegistry, } from "./retrieval-registry.js";
+// V9 T14.2 — opt-in retrieval strategies. Each is a heavy / experimental
+// retriever that is OFF by default; callers opt in via
+// `registerOptionalStrategies(opts)`. The orphan modules each ship a
+// pure function (asmr voter, Louvain community detector, persona tree
+// builder); the wrappers below adapt them onto the RetrievalMode
+// contract so the existing dispatch path (`searchWithMode`) drives them.
+import { runAsmrVoter } from "./asmr-voter.js";
+import { detectCommunities, communityOf } from "./community-detection.js";
+import { buildPersonaTree, walkPersonaTree } from "./persona-tree.js";
+export class MemoryStore {
+    /** MemoryProvider contract: stable identifier for the SQLite + FTS5 backend. */
+    name = "sqlite";
+    /** MemoryProvider contract: semver of the MemoryStore implementation. */
+    version = "1.0.0";
+    db;
+    dbPath;
+    /**
+     * Optional synchronous contextual-retrieval generator. When set, insert()
+     * prepends a ~50-token chunk-context to the FTS-indexed value per
+     * Anthropic's 2024 contextual retrieval (+30-50% recall on paraphrase).
+     * Pure sync — LLM-backed generators should pre-render async context and
+     * capture it in the closure. Null = disabled (honest pass-through).
+     */
+    contextGenerator = null;
+    /** Install or clear the contextual-embedding generator used by insert(). */
+    setContextGenerator(gen) {
+        this.contextGenerator = gen;
+    }
+    /**
+     * V9 T1.3 — Optional sqlite-vec backend for native dense-vector
+     * retrieval in TEMPR's vector channel. Null until `attachVectorBackend()`
+     * lazy-initializes it (or if the native extension isn't loadable).
+     * When non-null, `temprSearch()` uses it as the default `opts.vectorBackend`
+     * instead of the FTS5+cosine fallback.
+     *
+     * Population is the caller's responsibility — use `upsertEmbedding()`
+     * below as new entries arrive with their embeddings. See V9 T1.3 for
+     * the full persistent-index design.
+     */
+    vectorBackend = null;
+    /**
+     * V9 T1.4 — Optional ONNX-backed cross-encoder for TEMPR rerank.
+     * Upgraded from the heuristic baseline via `attachOnnxCrossEncoder()`
+     * (async — session load is async). `temprSearch()` uses this as the
+     * default `opts.crossEncoder` when caller doesn't override.
+     */
+    defaultCrossEncoder = createHeuristicCrossEncoder();
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+        const dir = join(dbPath, "..");
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        this.db = new Database(dbPath);
+        // Wave 6.5-UU (H-21): standard PRAGMA bundle. busy_timeout = 5000 lets
+        // concurrent writers wait up to 5s for the lock instead of throwing
+        // SQLITE_BUSY immediately (the better-sqlite3 default is 0ms).
+        // synchronous = NORMAL keeps writes durable across app crashes at ~10x
+        // the throughput of FULL. foreign_keys = ON enables CASCADE.
+        this.db.pragma("busy_timeout = 5000");
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.pragma("foreign_keys = ON");
+        this.db.pragma("user_version"); // read for migration check
+        this.initializeSchema();
+    }
+    /**
+     * MemoryProvider contract. Idempotent — schema is created in the
+     * constructor via `initializeSchema()`, so this is a no-op for
+     * already-constructed instances. Exposed for contract conformance
+     * with async backends that defer connection/table creation.
+     */
+    initialize() {
+        // Schema already created in constructor. Re-running is safe
+        // (all DDL is IF NOT EXISTS) but unnecessary.
+    }
+    /**
+     * V9 T1.3 — Attach the sqlite-vec backend. Call once post-construction
+     * when the caller knows their embedding dimension. Safe to call
+     * multiple times — idempotent (attaches once). When sqlite-vec isn't
+     * available, silently keeps `vectorBackend: null` so `temprSearch`
+     * falls back to the FTS5+cosine path.
+     *
+     * @param dimensions Embedding dimension (384 for MiniLM-L-6, 768 for L-12).
+     * @param tableName Optional vec0 table name override.
+     * @returns true when the backend was attached; false on unavailability.
+     */
+    attachVectorBackend(dimensions, tableName) {
+        if (this.vectorBackend !== null)
+            return true; // idempotent
+        if (!isSqliteVecAvailable())
+            return false;
+        try {
+            this.vectorBackend = createSqliteVecBackend({
+                db: this.db,
+                dimensions,
+                ...(tableName ? { tableName } : {}),
+            });
+            return true;
+        }
+        catch {
+            // Extension loaded but table creation failed (e.g. dimension
+            // mismatch against an existing vec0 table). Honest null.
+            this.vectorBackend = null;
+            return false;
+        }
+    }
+    /**
+     * V9 T1.4 — Upgrade the default cross-encoder from heuristic to
+     * ONNX-backed MiniLM rerank. Async because `loadMiniLmSession`
+     * loads the native `onnxruntime-node` session asynchronously.
+     * Safe to call at any time — `temprSearch` reads `this.defaultCrossEncoder`
+     * per-call so the swap takes effect on the next invocation.
+     *
+     * @param modelPath Optional override for the MiniLM .onnx file.
+     * @returns true when ONNX was attached; false when runtime/model absent.
+     */
+    async attachOnnxCrossEncoder(modelPath) {
+        if (!isOnnxRuntimeAvailable() || !isMiniLmModelAvailable(modelPath)) {
+            return false;
+        }
+        try {
+            const session = await loadMiniLmSession(modelPath);
+            if (!session)
+                return false;
+            this.defaultCrossEncoder = createOnnxCrossEncoder({ session });
+            return true;
+        }
+        catch {
+            // Keep the heuristic baseline on any ONNX failure.
+            return false;
+        }
+    }
+    /**
+     * V9 T1.3 companion — push an embedding into the vec0 index for a
+     * given memory entry. No-op when the backend isn't attached. Caller
+     * generates the embedding using its chosen embedder so the store
+     * doesn't pull an embedder dependency. Idempotent on duplicate id.
+     *
+     * Asymmetric-prefix port (LightRAG `embedding-prefixes`): the caller
+     * is responsible for applying the doc prefix BEFORE generating the
+     * vector. A typical wiring looks like:
+     *
+     *   import { applyDocPrefix, getEmbeddingProfile,
+     *            isAsymmetricEmbeddingsEnabled } from "./embedding-profiles.js";
+     *   const profile = isAsymmetricEmbeddingsEnabled()
+     *     ? getEmbeddingProfile(modelName)
+     *     : null;
+     *   const vec = await embed(applyDocPrefix(profile, entry.value));
+     *   store.upsertEmbedding(entry.id, vec);
+     *
+     * NOTE: turning the env-var gate ON for an existing index that was
+     * built without prefixes will skew similarity scores at query time.
+     * Rebuild the vec_embeddings table after enabling. See
+     * embedding-profiles.ts header for the full rationale.
+     */
+    upsertEmbedding(id, vector) {
+        if (!this.vectorBackend)
+            return false;
+        try {
+            this.vectorBackend.upsert(id, vector);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Accessor for the attached vectorBackend (null when not attached).
+     * Used by TEMPR-aware callers to pass `opts.vectorBackend` explicitly
+     * OR to confirm availability before generating an embedding. See
+     * `temprSearch()` for default-injection behavior.
+     */
+    getVectorBackend() {
+        return this.vectorBackend;
+    }
+    /** Accessor for the default cross-encoder. Callers can override via
+     * `temprSearch`'s `opts.crossEncoder`. */
+    getDefaultCrossEncoder() {
+        return this.defaultCrossEncoder;
+    }
+    initializeSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_entries (
+        id TEXT PRIMARY KEY,
+        layer TEXT NOT NULL,
+        block_type TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        session_id TEXT,
+        verified INTEGER NOT NULL DEFAULT 0,
+        archived INTEGER NOT NULL DEFAULT 0,
+        confidence REAL DEFAULT 1.0,
+        tags TEXT DEFAULT '',
+        access_count INTEGER DEFAULT 0,
+        last_accessed TEXT,
+        source_type TEXT DEFAULT 'auto_capture',
+        source_file TEXT,
+        source_command TEXT,
+        verified_at TEXT,
+        verified_by TEXT,
+        freshness_score REAL NOT NULL DEFAULT 1.0,
+        confidence_level REAL NOT NULL DEFAULT 0.5,
+        last_verified_at TEXT,
+        verification_status TEXT NOT NULL DEFAULT 'unverified',
+        domain TEXT NOT NULL DEFAULT '',
+        topic TEXT NOT NULL DEFAULT ''
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_memory_layer ON memory_entries(layer);
+      CREATE INDEX IF NOT EXISTS idx_memory_block ON memory_entries(block_type);
+      CREATE INDEX IF NOT EXISTS idx_memory_key ON memory_entries(key);
+      CREATE INDEX IF NOT EXISTS idx_memory_session ON memory_entries(session_id);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+        key, value,
+        content='memory_entries',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER IF NOT EXISTS memory_ai AFTER INSERT ON memory_entries BEGIN
+        INSERT INTO memory_fts(rowid, key, value) VALUES (new.rowid, new.key, new.value);
+      END;
+      CREATE TRIGGER IF NOT EXISTS memory_au AFTER UPDATE ON memory_entries BEGIN
+        INSERT INTO memory_fts(memory_fts, rowid, key, value) VALUES('delete', old.rowid, old.key, old.value);
+        INSERT INTO memory_fts(rowid, key, value) VALUES (new.rowid, new.key, new.value);
+      END;
+      CREATE TRIGGER IF NOT EXISTS memory_ad AFTER DELETE ON memory_entries BEGIN
+        INSERT INTO memory_fts(memory_fts, rowid, key, value) VALUES('delete', old.rowid, old.key, old.value);
+      END;
+
+      CREATE TABLE IF NOT EXISTS knowledge_nodes (
+        id TEXT PRIMARY KEY,
+        entity TEXT NOT NULL,
+        entity_type TEXT NOT NULL,
+        properties TEXT DEFAULT '{}',
+        valid_from TEXT NOT NULL DEFAULT (datetime('now')),
+        valid_to TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE TABLE IF NOT EXISTS knowledge_edges (
+        id TEXT PRIMARY KEY,
+        source_id TEXT NOT NULL REFERENCES knowledge_nodes(id),
+        target_id TEXT NOT NULL REFERENCES knowledge_nodes(id),
+        relation TEXT NOT NULL,
+        weight REAL NOT NULL DEFAULT 1.0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_kg_entity ON knowledge_nodes(entity);
+      CREATE INDEX IF NOT EXISTS idx_kg_edges_src ON knowledge_edges(source_id);
+      CREATE INDEX IF NOT EXISTS idx_kg_edges_tgt ON knowledge_edges(target_id);
+
+      CREATE TABLE IF NOT EXISTS team_memory (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        shared INTEGER NOT NULL DEFAULT 1,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_team_agent ON team_memory(agent_id);
+
+      CREATE TABLE IF NOT EXISTS working_memory (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        importance REAL NOT NULL DEFAULT 0.5,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        expires_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_working_session ON working_memory(session_id);
+
+      CREATE TABLE IF NOT EXISTS decision_log (
+        id TEXT PRIMARY KEY,
+        decision TEXT NOT NULL,
+        rationale TEXT NOT NULL,
+        alternatives TEXT,
+        constraints TEXT,
+        stakeholders TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        session_id TEXT
+      );
+
+      CREATE TABLE IF NOT EXISTS auto_capture (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_type TEXT NOT NULL,
+        tool_name TEXT,
+        content TEXT NOT NULL,
+        session_id TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_capture_session ON auto_capture(session_id);
+
+      CREATE TABLE IF NOT EXISTS verbatim_drawers (
+        id TEXT PRIMARY KEY,
+        entry_id TEXT REFERENCES memory_entries(id) ON DELETE SET NULL,
+        raw_content TEXT NOT NULL,
+        content_type TEXT NOT NULL DEFAULT 'conversation',
+        session_id TEXT,
+        domain TEXT NOT NULL DEFAULT '',
+        topic TEXT NOT NULL DEFAULT '',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_verbatim_entry ON verbatim_drawers(entry_id);
+      CREATE INDEX IF NOT EXISTS idx_verbatim_session ON verbatim_drawers(session_id);
+      CREATE INDEX IF NOT EXISTS idx_verbatim_domain ON verbatim_drawers(domain, topic);
+
+      CREATE VIRTUAL TABLE IF NOT EXISTS verbatim_fts USING fts5(
+        raw_content,
+        content='verbatim_drawers',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER IF NOT EXISTS verbatim_ai AFTER INSERT ON verbatim_drawers BEGIN
+        INSERT INTO verbatim_fts(rowid, raw_content) VALUES (new.rowid, new.raw_content);
+      END;
+      CREATE TRIGGER IF NOT EXISTS verbatim_au AFTER UPDATE ON verbatim_drawers BEGIN
+        INSERT INTO verbatim_fts(verbatim_fts, rowid, raw_content) VALUES('delete', old.rowid, old.raw_content);
+        INSERT INTO verbatim_fts(rowid, raw_content) VALUES (new.rowid, new.raw_content);
+      END;
+      CREATE TRIGGER IF NOT EXISTS verbatim_ad AFTER DELETE ON verbatim_drawers BEGIN
+        INSERT INTO verbatim_fts(verbatim_fts, rowid, raw_content) VALUES('delete', old.rowid, old.raw_content);
+      END;
+
+      CREATE TABLE IF NOT EXISTS memory_vectors (
+        entry_id TEXT PRIMARY KEY REFERENCES memory_entries(id) ON DELETE CASCADE,
+        embedding BLOB NOT NULL,
+        model TEXT NOT NULL DEFAULT 'local-trigram',
+        dimensions INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_vectors_model ON memory_vectors(model);
+
+      CREATE TABLE IF NOT EXISTS memory_provenance_log (
+        id TEXT PRIMARY KEY,
+        entry_id TEXT NOT NULL REFERENCES memory_entries(id) ON DELETE CASCADE,
+        action TEXT NOT NULL,
+        old_value TEXT,
+        new_value TEXT,
+        actor TEXT,
+        reason TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_provenance_entry ON memory_provenance_log(entry_id);
+      CREATE INDEX IF NOT EXISTS idx_memory_source_type ON memory_entries(source_type);
+      CREATE INDEX IF NOT EXISTS idx_memory_source_file ON memory_entries(source_file);
+    `);
+        // ── Domain-Partitioned Search Migration (MemPalace R1) ──
+        // Add domain/topic columns for existing databases. +34% retrieval improvement
+        // from metadata filtering before FTS5 search (MemPalace: 60.9% → 94.8%).
+        this.migrateAddColumn("memory_entries", "domain", "TEXT NOT NULL DEFAULT ''");
+        this.migrateAddColumn("memory_entries", "topic", "TEXT NOT NULL DEFAULT ''");
+        this.db.prepare(`CREATE INDEX IF NOT EXISTS idx_memory_domain ON memory_entries(domain)`).run();
+        this.db.prepare(`CREATE INDEX IF NOT EXISTS idx_memory_topic ON memory_entries(topic)`).run();
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memory_domain_topic ON memory_entries(domain, topic)`)
+            .run();
+        // ── Auto-Capture Consolidation Tracking (Phase B Bug #1 fix) ──
+        // Without this column, every consolidation pass would re-process all
+        // auto_capture rows and create duplicate memory_entries. The column
+        // records the ISO-timestamp when a row was routed into the structured
+        // tables (memory_entries / decision_log / etc.). NULL = not yet
+        // consolidated.
+        this.migrateAddColumn("auto_capture", "consolidated_at", "TEXT");
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_capture_consolidated ON auto_capture(consolidated_at)`)
+            .run();
+        // ── Temporal Validity Migration (MemPalace R2) ──
+        // Add valid_from/valid_to to knowledge_edges for bi-temporal fact queries.
+        this.migrateAddColumn("knowledge_edges", "valid_from", "TEXT NOT NULL DEFAULT (datetime('now'))");
+        this.migrateAddColumn("knowledge_edges", "valid_to", "TEXT");
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_kg_edges_temporal ON knowledge_edges(valid_from, valid_to)`)
+            .run();
+        // ── Bi-Temporal Ingest Axis Migration (Phase 2 P1-M5, Zep/Graphiti port) ──
+        // Adds the SECOND time axis to knowledge_edges. The knowledge-time
+        // axis (valid_from/valid_to) was wired in M7; this migration adds
+        // the ingest-time axis (recorded_from/recorded_to) so callers can
+        // answer "what did WOTANN know about X on date Y?". Legacy rows
+        // default recorded_from = created_at so they behave as if inserted
+        // at creation time; recorded_to stays null (still known). This is
+        // non-breaking — existing readers (getActiveEdgesAt, etc.) ignore
+        // the new columns.
+        this.migrateAddColumn("knowledge_edges", "recorded_from", "TEXT NOT NULL DEFAULT (datetime('now'))");
+        this.migrateAddColumn("knowledge_edges", "recorded_to", "TEXT");
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_kg_edges_recorded ON knowledge_edges(recorded_from, recorded_to)`)
+            .run();
+        // Back-fill legacy rows: set recorded_from = created_at where the
+        // ALTER TABLE default (datetime('now')) would otherwise stamp the
+        // migration time, not the original insert time. Only touches rows
+        // where recorded_from is equal to the default we just added (i.e.
+        // the ones we can't distinguish from genuine inserts). Safe because
+        // we only update when the stored value exceeds created_at — i.e.
+        // this row was materialized BEFORE the migration.
+        this.db
+            .prepare(`UPDATE knowledge_edges
+         SET recorded_from = created_at
+         WHERE recorded_from > created_at`)
+            .run();
+        // ── Dual-Timestamp Migration (Phase H Task 1) ──
+        // Records both WHEN the memory was written (document_date) and WHEN
+        // the referenced event happened (event_date). Enables queries like
+        // "what did we say last week about last year's launch?". Legacy rows
+        // leave event_date_source='' so readers can distinguish them from
+        // honestly-fallback rows.
+        this.migrateAddColumn("memory_entries", "document_date", "INTEGER");
+        this.migrateAddColumn("memory_entries", "event_date", "INTEGER");
+        this.migrateAddColumn("memory_entries", "event_date_uncertainty_ms", "INTEGER");
+        this.migrateAddColumn("memory_entries", "event_date_source", "TEXT NOT NULL DEFAULT ''");
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memory_event_date ON memory_entries(event_date)`)
+            .run();
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memory_document_date ON memory_entries(document_date)`)
+            .run();
+        // ── Typed Relationships Migration (Phase H Task 2) ──
+        // Typed edges between memory_entries with a kind in
+        // {updates,extends,derives,unknown}. Lets us answer "what is the
+        // CURRENT policy?" by walking updates forward from the root.
+        this.db
+            .prepare(`CREATE TABLE IF NOT EXISTS memory_relationships (
+          id TEXT PRIMARY KEY,
+          from_id TEXT NOT NULL,
+          to_id TEXT NOT NULL,
+          kind TEXT NOT NULL,
+          confidence REAL NOT NULL DEFAULT 0.5,
+          rationale TEXT,
+          invalidated_at INTEGER,
+          created_at INTEGER NOT NULL
+        )`)
+            .run();
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memrel_from ON memory_relationships(from_id)`)
+            .run();
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memrel_to ON memory_relationships(to_id)`)
+            .run();
+        this.db
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_memrel_kind ON memory_relationships(kind)`)
+            .run();
+    }
+    /** @internal Migration helper — ONLY called with hardcoded literals.
+     *
+     * Wave 6.5-UU (H-23) — wrap PRAGMA + ALTER inside an explicit transaction
+     * so a SIGKILL between the existence check and the column add can't
+     * leave the DB half-migrated (column added but no committed marker).
+     * SQLite is internally transactional per-statement, but the *combination*
+     * of PRAGMA table_info + ALTER TABLE is not — without the transaction
+     * wrapper a crash between the two could let the next call see an
+     * already-added column and skip a follow-up step that depends on the
+     * write being committed end-to-end.
+     *
+     * Identifier validation runs BEFORE entering the transaction so a bad
+     * identifier doesn't open and immediately roll back a tx for nothing.
+     */
+    migrateAddColumn(table, column, definition) {
+        // Validate inputs match safe identifier patterns
+        const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+        if (!SAFE_IDENTIFIER.test(table) || !SAFE_IDENTIFIER.test(column)) {
+            throw new Error(`Invalid SQL identifier: table="${table}", column="${column}"`);
+        }
+        // Definition can include type + constraints but must not contain semicolons or comments
+        if (/[;]|--/.test(definition)) {
+            throw new Error(`Invalid column definition: "${definition}"`);
+        }
+        this.db.transaction(() => {
+            const cols = this.db.prepare(`PRAGMA table_info(${table})`).all();
+            if (!cols.some((c) => c.name === column)) {
+                this.db.prepare(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`).run();
+            }
+        })();
+    }
+    // ── Layer 1: Auto-Capture ──────────────────────────────────
+    captureEvent(eventType, content, toolName, sessionId) {
+        this.db
+            .prepare(`
+      INSERT INTO auto_capture (event_type, tool_name, content, session_id) VALUES (?, ?, ?, ?)
+    `)
+            .run(eventType, toolName ?? null, content.slice(0, 2000), sessionId ?? null);
+    }
+    getRecentCaptures(sessionId, limit = 20) {
+        return this.db
+            .prepare(`
+      SELECT * FROM auto_capture WHERE session_id = ? ORDER BY created_at DESC LIMIT ?
+    `)
+            .all(sessionId, limit);
+    }
+    getAutoCaptureEntries(limit = 50, sessionId) {
+        const rows = sessionId
+            ? this.db
+                .prepare(`
+        SELECT * FROM auto_capture WHERE session_id = ? ORDER BY created_at DESC LIMIT ?
+      `)
+                .all(sessionId, limit)
+            : this.db
+                .prepare(`
+        SELECT * FROM auto_capture ORDER BY created_at DESC LIMIT ?
+      `)
+                .all(limit);
+        return rows.map((row) => ({
+            id: Number(row["id"] ?? 0),
+            eventType: row["event_type"],
+            toolName: row["tool_name"],
+            content: row["content"],
+            sessionId: row["session_id"],
+            createdAt: row["created_at"],
+        }));
+    }
+    /**
+     * Return auto_capture entries that have NOT yet been routed into the
+     * structured memory_entries / decision_log tables. Phase B Bug #1 fix.
+     *
+     * Consolidation uses `consolidated_at IS NULL` as the work-queue marker.
+     * Once a row has been processed by `consolidateAutoCaptures()`, its
+     * `consolidated_at` is stamped with the current ISO-8601 timestamp so
+     * it won't be re-read on the next pass.
+     */
+    getUnconsolidatedAutoCaptures(limit = 500) {
+        const rows = this.db
+            .prepare(`
+      SELECT * FROM auto_capture
+      WHERE consolidated_at IS NULL
+      ORDER BY created_at ASC
+      LIMIT ?
+    `)
+            .all(limit);
+        return rows.map((row) => ({
+            id: Number(row["id"] ?? 0),
+            eventType: row["event_type"],
+            toolName: row["tool_name"],
+            content: row["content"],
+            sessionId: row["session_id"],
+            createdAt: row["created_at"],
+        }));
+    }
+    /**
+     * Mark a set of auto_capture rows as consolidated. Called by
+     * `consolidateAutoCaptures()` once their observations have been inserted
+     * into `memory_entries` / `decision_log`. Idempotent.
+     */
+    markAutoCapturesConsolidated(ids) {
+        if (ids.length === 0)
+            return;
+        const placeholders = ids.map(() => "?").join(",");
+        const stmt = this.db.prepare(`UPDATE auto_capture SET consolidated_at = datetime('now')
+       WHERE id IN (${placeholders}) AND consolidated_at IS NULL`);
+        stmt.run(...ids);
+    }
+    /**
+     * Route unconsolidated auto_capture rows into structured memory tables
+     * (memory_entries + decision_log). Phase B Bug #1 fix.
+     *
+     * Bug: `.wotann/memory.db` showed 1,990 rows in `auto_capture` but 0
+     * in `memory_entries`, `knowledge_nodes`, and `decision_log` — every
+     * observation was silently dumped into the raw capture table with no
+     * structured routing. Session-end extraction ran from
+     * `session.messages` (not from the DB), so daemon lifecycle events
+     * never produced structured entries.
+     *
+     * This method reads from the auto_capture table itself, runs each row
+     * through the caller-supplied extractor (normally
+     * `ObservationExtractor.extractFromCaptures`), maps the observation
+     * type to the right MemoryBlockType, and inserts into memory_entries.
+     * Decisions are ALSO mirrored into decision_log for the decision
+     * ledger.
+     *
+     * Classification failures (row content matches no pattern) emit a
+     * `classification_failed` event via the optional callback — never
+     * silently swallowed. Quality bar from feedback_wotann_quality_bars.
+     *
+     * @returns a report: how many routed per bucket + how many failed classification.
+     */
+    consolidateAutoCaptures(extractFn, options) {
+        const batchSize = options?.batchSize ?? 500;
+        const entries = this.getUnconsolidatedAutoCaptures(batchSize);
+        if (entries.length === 0) {
+            return {
+                read: 0,
+                routed: 0,
+                byBlock: {},
+                classificationFailed: 0,
+                decisionLogged: 0,
+            };
+        }
+        let observations;
+        try {
+            observations = extractFn(entries);
+        }
+        catch (err) {
+            // Extractor crash — surface to caller via callback (honest stub, not
+            // silent success — feedback_wotann_quality_bars_session2). Mark NONE
+            // consolidated so the next pass can retry when the extractor is fixed.
+            options?.onClassificationFailed?.(entries[0], `extractor_crash:${err.message}`);
+            throw err;
+        }
+        const covered = new Set();
+        const byBlock = {};
+        let decisionLogged = 0;
+        // Phase 1: insert into memory_entries for every extracted observation.
+        // Wrapped in a transaction so a later SQL failure rolls back the whole
+        // batch — we don't want a half-routed pass where some rows are marked
+        // consolidated but their memory_entries never made it.
+        const insertTx = this.db.transaction(() => {
+            for (const obs of observations) {
+                const blockType = this.observationTypeToBlockType(obs.type);
+                byBlock[blockType] = (byBlock[blockType] ?? 0) + 1;
+                const sessionId = entries.find((e) => obs.sourceIds.includes(e.id))?.sessionId;
+                this.insert({
+                    id: randomUUID(),
+                    layer: "working",
+                    blockType,
+                    key: `${obs.type}:${obs.assertion.slice(0, 80)}`,
+                    value: obs.assertion,
+                    sessionId,
+                    verified: false,
+                    freshnessScore: 1.0,
+                    confidenceLevel: obs.confidence,
+                    verificationStatus: "unverified",
+                    tags: `consolidated,${obs.type}`,
+                    domain: obs.domain ?? "",
+                    topic: obs.topic ?? "",
+                });
+                // Decisions ALSO flow into the decision_log (bi-temporal ledger).
+                if (obs.type === "decision") {
+                    this.db
+                        .prepare(`INSERT INTO decision_log (id, decision, rationale, alternatives, constraints, stakeholders, session_id)
+               VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                        .run(randomUUID(), obs.assertion.slice(0, 500), `auto-consolidated from ${obs.sourceIds.length} capture(s)`, null, null, null, sessionId ?? null);
+                    decisionLogged++;
+                }
+                for (const sid of obs.sourceIds)
+                    covered.add(sid);
+            }
+        });
+        insertTx();
+        // Phase 2: mark all auto_capture rows that fed into an observation as
+        // consolidated, AND mark uncovered rows as consolidated-but-unclassified
+        // so we don't re-visit them every tick. Emit classification_failed for
+        // those so the caller can log/alert.
+        const coveredIds = [...covered];
+        this.markAutoCapturesConsolidated(coveredIds);
+        const unclassified = entries.filter((e) => !covered.has(e.id));
+        if (unclassified.length > 0 && options?.onClassificationFailed) {
+            for (const entry of unclassified) {
+                options.onClassificationFailed(entry, "no_pattern_matched");
+            }
+        }
+        // Mark unclassified as consolidated too — they've had their chance.
+        // Without this, the queue grows unbounded and every pass re-examines
+        // the same junk. The `onClassificationFailed` callback above gives
+        // observability without keeping them in the work queue forever.
+        this.markAutoCapturesConsolidated(unclassified.map((e) => e.id));
+        return {
+            read: entries.length,
+            routed: covered.size,
+            byBlock,
+            classificationFailed: unclassified.length,
+            decisionLogged,
+        };
+    }
+    /** Map observation type to the right memory block. Isolated for testability. */
+    observationTypeToBlockType(type) {
+        switch (type) {
+            case "decision":
+                return "decisions";
+            case "preference":
+                return "feedback";
+            case "milestone":
+                return "project";
+            case "problem":
+                return "issues";
+            case "discovery":
+                return "cases";
+        }
+    }
+    // ── Verbatim Drawers (MemPalace R6) ────────────────────────
+    // Stores raw conversation chunks alongside structured blocks.
+    // Search against summaries, return originals — how MemPalace gets 96.6% recall.
+    /** Store a raw verbatim chunk, optionally linked to a structured memory entry. */
+    storeVerbatim(rawContent, options) {
+        const id = randomUUID();
+        this.db
+            .prepare(`
+      INSERT INTO verbatim_drawers (id, entry_id, raw_content, content_type, session_id, domain, topic)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(id, options?.entryId ?? null, rawContent, options?.contentType ?? "conversation", options?.sessionId ?? null, options?.domain ?? "", options?.topic ?? "");
+        return id;
+    }
+    /** Search verbatim drawers via FTS5. Returns raw content with match scores. */
+    searchVerbatim(query, limit = 10) {
+        const rows = this.db
+            .prepare(`
+      SELECT vd.*, rank AS score
+      FROM verbatim_fts
+      JOIN verbatim_drawers vd ON vd.rowid = verbatim_fts.rowid
+      WHERE verbatim_fts MATCH ?
+      ORDER BY rank LIMIT ?
+    `)
+            .all(query, limit);
+        return rows.map((r) => ({
+            id: r["id"],
+            rawContent: r["raw_content"],
+            entryId: r["entry_id"] ?? null,
+            score: r["score"] ?? 0,
+            domain: r["domain"] ?? "",
+            topic: r["topic"] ?? "",
+        }));
+    }
+    /** Get the raw verbatim content linked to a structured memory entry. */
+    getVerbatimForEntry(entryId) {
+        const rows = this.db
+            .prepare(`
+      SELECT id, raw_content, content_type FROM verbatim_drawers WHERE entry_id = ? ORDER BY created_at DESC
+    `)
+            .all(entryId);
+        return rows.map((r) => ({
+            id: r["id"],
+            rawContent: r["raw_content"],
+            contentType: r["content_type"],
+        }));
+    }
+    /** Count of verbatim entries. */
+    getVerbatimCount() {
+        return this.db.prepare(`SELECT COUNT(*) as count FROM verbatim_drawers`).get().count;
+    }
+    // ── Layer 2: Core Blocks CRUD ──────────────────────────────
+    insert(entry) {
+        // Phase H Task 1: derive dual-timestamp fields from raw content so
+        // temporal queries ("what did we say last week about last year's
+        // launch?") can distinguish writing date from event date. Caller
+        // may override by passing explicit documentDate / eventDate.
+        const derived = deriveIngestTimestamps(`${entry.key} ${entry.value}`);
+        const documentDate = entry.documentDate ?? derived.documentDate;
+        const eventDate = entry.eventDate ?? derived.eventDate;
+        const eventDateUncertaintyMs = entry.eventDateUncertaintyMs ?? derived.eventDateUncertaintyMs;
+        const eventDateSource = entry.eventDate !== undefined && entry.eventDateSource === undefined
+            ? "user-supplied"
+            : (entry.eventDateSource ?? derived.eventDateSource);
+        // Phase H Wave-3C: contextual-retrieval enrichment. When a generator
+        // is installed, prepend a ~50-token chunk-context to the indexed
+        // value per Anthropic contextual retrieval. Generator failure falls
+        // through to raw value — honest pass-through, never silent garbage.
+        let indexedValue = entry.value;
+        if (this.contextGenerator) {
+            try {
+                const raw = this.contextGenerator(entry.key, entry.value);
+                const context = clampContextTokens(cleanContext(raw));
+                if (context)
+                    indexedValue = `${context}\n\n${entry.value}`;
+            }
+            catch {
+                /* honest fallback: keep raw value */
+            }
+        }
+        // Phase 2 P1-M8 Fix A — write BOTH confidence columns so read-back
+        // matches caller intent. Prior to this fix `confidence_level`,
+        // `freshness_score`, and `verification_status` were never written by
+        // insert(), so `rowToEntry` always returned confidence_level=0.5 (the
+        // column default). Reflector.promote and consolidateAutoCaptures both
+        // pass explicit confidenceLevel signals that were being silently
+        // dropped. Preserves the split semantics:
+        //   - confidence       = caller-supplied raw score (stays stable)
+        //   - confidence_level = working value the verify pipeline mutates
+        //                        (seeded from caller at insert time)
+        const confidenceLevel = entry.confidenceLevel ?? entry.confidence ?? 0.5;
+        const freshnessScore = entry.freshnessScore ?? 1.0;
+        const verificationStatus = entry.verificationStatus ?? "unverified";
+        this.db
+            .prepare(`
+      INSERT INTO memory_entries (id, layer, block_type, key, value, session_id, verified, confidence, tags, domain, topic, document_date, event_date, event_date_uncertainty_ms, event_date_source, freshness_score, confidence_level, verification_status)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(entry.id, entry.layer, entry.blockType, entry.key, indexedValue, entry.sessionId ?? null, entry.verified ? 1 : 0, entry.confidence ?? 1.0, entry.tags ?? "", entry.domain ?? "", entry.topic ?? "", documentDate, eventDate, eventDateUncertaintyMs, eventDateSource, freshnessScore, confidenceLevel, verificationStatus);
+    }
+    replace(id, key, value) {
+        this.db
+            .prepare(`
+      UPDATE memory_entries SET key = ?, value = ?, updated_at = datetime('now') WHERE id = ?
+    `)
+            .run(key, value, id);
+    }
+    archive(id) {
+        this.db
+            .prepare(`
+      UPDATE memory_entries SET archived = 1, updated_at = datetime('now') WHERE id = ?
+    `)
+            .run(id);
+    }
+    /**
+     * MemoryProvider contract: structured update of an existing entry.
+     * Builds a dynamic UPDATE with only the supplied fields, preserving
+     * every other column. Silent no-op when `updates` is empty or the id
+     * does not exist — matches `InMemoryProvider.update` semantics.
+     *
+     * NOTE: separate from `replace()` which is the legacy key/value-only
+     * mutation used by `memoryReplace()`. `update()` additionally supports
+     * `verified` and `confidence` columns required by the interface.
+     */
+    update(id, updates) {
+        const sets = [];
+        const params = [];
+        if (updates.key !== undefined) {
+            sets.push("key = ?");
+            params.push(updates.key);
+        }
+        if (updates.value !== undefined) {
+            sets.push("value = ?");
+            params.push(updates.value);
+        }
+        if (updates.verified !== undefined) {
+            sets.push("verified = ?");
+            params.push(updates.verified ? 1 : 0);
+        }
+        if (updates.confidence !== undefined) {
+            sets.push("confidence = ?");
+            params.push(updates.confidence);
+        }
+        if (sets.length === 0)
+            return;
+        sets.push("updated_at = datetime('now')");
+        params.push(id);
+        this.db.prepare(`UPDATE memory_entries SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+    }
+    /**
+     * MemoryProvider contract: hard-delete by id. Distinct from
+     * `archive()` (soft-delete via the `archived` column). Hard-delete
+     * cascades to FTS5 shadow table via SQLite foreign-key triggers.
+     */
+    delete(id) {
+        this.db.prepare(`DELETE FROM memory_entries WHERE id = ?`).run(id);
+    }
+    /**
+     * MemoryProvider contract: total count of non-archived entries.
+     * Thin alias over `getEntryCount()` so conforming callers have a
+     * stable name across providers.
+     */
+    count() {
+        return this.getEntryCount();
+    }
+    /**
+     * MemoryProvider contract: basic liveness probe. Issues a trivial
+     * `SELECT 1` to confirm the SQLite handle is open and responsive.
+     * Returns false on any exception rather than throwing.
+     */
+    healthCheck() {
+        try {
+            const row = this.db.prepare("SELECT 1 AS ok").get();
+            return row?.ok === 1;
+        }
+        catch {
+            return false;
+        }
+    }
+    getById(id) {
+        const row = this.db
+            .prepare(`
+      SELECT * FROM memory_entries WHERE id = ? AND archived = 0
+    `)
+            .get(id);
+        if (row) {
+            this.db
+                .prepare(`
+        UPDATE memory_entries SET access_count = access_count + 1, last_accessed = datetime('now') WHERE id = ?
+      `)
+                .run(id);
+        }
+        return row ? this.rowToEntry(row) : null;
+    }
+    getByLayer(layer) {
+        return this.db
+            .prepare(`
+      SELECT * FROM memory_entries WHERE layer = ? AND archived = 0 ORDER BY updated_at DESC
+    `)
+            .all(layer).map((r) => this.rowToEntry(r));
+    }
+    getByBlock(blockType) {
+        return this.db
+            .prepare(`
+      SELECT * FROM memory_entries WHERE block_type = ? AND archived = 0 ORDER BY updated_at DESC
+    `)
+            .all(blockType).map((r) => this.rowToEntry(r));
+    }
+    // ── Layer 3: Working Memory ────────────────────────────────
+    setWorkingMemory(sessionId, key, value, importance = 0.5) {
+        this.db
+            .prepare(`
+      INSERT OR REPLACE INTO working_memory (id, session_id, key, value, importance) VALUES (?, ?, ?, ?, ?)
+    `)
+            .run(randomUUID(), sessionId, key, value, importance);
+    }
+    getWorkingMemory(sessionId) {
+        return this.db
+            .prepare(`
+      SELECT key, value, importance FROM working_memory
+      WHERE session_id = ? AND (expires_at IS NULL OR expires_at > datetime('now'))
+      ORDER BY importance DESC
+    `)
+            .all(sessionId);
+    }
+    clearWorkingMemory(sessionId) {
+        this.db.prepare(`DELETE FROM working_memory WHERE session_id = ?`).run(sessionId);
+    }
+    // ── Layer 4: Knowledge Graph ───────────────────────────────
+    /**
+     * Phase 2 P1-M7: typed-entity graph population.
+     *
+     * Validates a structured entity against `entity-types.EntitySchema`
+     * (person / project / file / concept / event / goal / skill / tool)
+     * and inserts it into `knowledge_nodes`. If a node with the same
+     * entity+type already exists, the existing id is returned rather
+     * than duplicated. Remaining fields are serialized into the
+     * properties JSON payload so downstream consumers can reconstruct
+     * the typed entity.
+     *
+     * Exists specifically to fix the "49-byte empty KG" bug: callers
+     * that already hold a validated Entity can push it to the graph
+     * without re-typing the free-form API.
+     */
+    recordEntity(entity) {
+        const parsed = EntitySchema.safeParse(entity);
+        if (!parsed.success) {
+            throw new Error(`recordEntity: invalid entity — ${parsed.error.message}`);
+        }
+        const valid = parsed.data;
+        const name = entityNameOf(valid);
+        const existing = this.db
+            .prepare(`SELECT id FROM knowledge_nodes WHERE entity = ? AND entity_type = ? LIMIT 1`)
+            .get(name, valid.type);
+        if (existing)
+            return existing.id;
+        const properties = {};
+        for (const [k, v] of Object.entries(valid)) {
+            if (k === "type" || k === "name")
+                continue;
+            if (v === undefined || v === null)
+                continue;
+            properties[k] = typeof v === "string" ? v : JSON.stringify(v);
+        }
+        return this.addKnowledgeNode(name, valid.type, properties);
+    }
+    /**
+     * Phase 2 P1-M7: batch entity population. Parses each entity, skips
+     * invalid rows (returning them in `skipped`), inserts the rest in a
+     * single transaction.
+     */
+    recordEntities(entities) {
+        const inserted = [];
+        const skipped = [];
+        const tx = this.db.transaction(() => {
+            for (const entity of entities) {
+                try {
+                    const nodeId = this.recordEntity(entity);
+                    inserted.push({ entity, nodeId });
+                }
+                catch (err) {
+                    skipped.push({ entity, reason: err instanceof Error ? err.message : String(err) });
+                }
+            }
+        });
+        tx();
+        return { inserted, skipped };
+    }
+    /**
+     * Phase 2 P1-M7: heuristic relationship materialization.
+     *
+     * Given two memory entries, classify the relationship between them
+     * using the heuristic classifier (no LLM call) and, when confident,
+     * insert a knowledge_edges row linking their knowledge_nodes.
+     *
+     * Returns the edge id when inserted, or null when the classifier
+     * emits no relationship (or confidence is below the threshold).
+     */
+    async recordHeuristicRelationship(fromNodeId, toNodeId, predecessorContent, successorContent, minConfidence = 0.5) {
+        const classifier = createHeuristicClassifier();
+        const result = await classifier.classify(predecessorContent, successorContent);
+        if (!result)
+            return null;
+        if (result.confidence < minConfidence)
+            return null;
+        return this.addKnowledgeEdge(fromNodeId, toNodeId, result.kind, result.confidence);
+    }
+    /**
+     * Phase 2 P1-M7: follow an `updates`-relationship chain from the
+     * given rootId and return the id of the most recent node in that
+     * chain. Delegates to relationship-types.resolveLatest so callers
+     * don't have to import both modules. Used for "what is the CURRENT
+     * version of fact X?" queries.
+     */
+    resolveLatestRelationship(rels, rootId) {
+        return resolveLatest(rels, rootId);
+    }
+    /**
+     * Phase 2 P1-M7: group the relationships attached to a node by kind
+     * (updates / extends / derives / unknown). Delegates to
+     * relationship-types.partitionByKind.
+     */
+    partitionRelationshipsByKind(rels, nodeId) {
+        return partitionByKind(rels, nodeId);
+    }
+    addKnowledgeNode(entity, entityType, properties) {
+        const id = randomUUID();
+        this.db
+            .prepare(`
+      INSERT INTO knowledge_nodes (id, entity, entity_type, properties) VALUES (?, ?, ?, ?)
+    `)
+            .run(id, entity, entityType, JSON.stringify(properties ?? {}));
+        return id;
+    }
+    addKnowledgeEdge(sourceId, targetId, relation, weight = 1.0, validFrom) {
+        const id = randomUUID();
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`
+      INSERT INTO knowledge_edges (id, source_id, target_id, relation, weight, valid_from, recorded_from) VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(id, sourceId, targetId, relation, weight, validFrom ?? now, now);
+        return id;
+    }
+    // ── Bi-Temporal Edges (Phase 2 P1-M5, Zep/Graphiti port) ──
+    /**
+     * Insert a bi-temporal knowledge edge. Both axes are independent:
+     *   - valid_from / valid_to:     when the fact is true in the world
+     *   - recorded_from / recorded_to: when WOTANN knew the fact
+     *
+     * Defaults:
+     *   - valid_from     = options.validFrom ?? now
+     *   - valid_to       = options.validTo ?? null (still valid)
+     *   - recorded_from  = options.recordedFrom ?? now (set automatically
+     *                      on every insert — the "when WOTANN learned it"
+     *                      timestamp is typically right-now)
+     *   - recorded_to    = null (still known)
+     *
+     * Throws ValidationError on malformed dates.
+     */
+    addBiTemporalEdge(sourceId, targetId, relation, options = {}) {
+        const now = new Date().toISOString();
+        const validFrom = options.validFrom ? validateDate(options.validFrom, "validFrom") : now;
+        const validTo = validateDateOrNull(options.validTo ?? null, "validTo");
+        const recordedFrom = options.recordedFrom
+            ? validateDate(options.recordedFrom, "recordedFrom")
+            : now;
+        const weight = options.weight ?? 1.0;
+        const id = randomUUID();
+        this.db
+            .prepare(`INSERT INTO knowledge_edges
+         (id, source_id, target_id, relation, weight, valid_from, valid_to, recorded_from, recorded_to)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, sourceId, targetId, relation, weight, validFrom, validTo, recordedFrom, null);
+        return id;
+    }
+    /**
+     * Retract an edge on the ingest-time axis (the fact is no longer
+     * known to WOTANN). Optionally also closes the knowledge-time axis
+     * when `factEndedAt` is supplied — use when WOTANN learns a fact was
+     * wrong AND knows when the fact stopped being true.
+     *
+     * The row is NOT deleted — historical queries (queryKnownAt(past))
+     * still see it. This preserves the "WOTANN knew this between dates
+     * X and Y" audit trail that Zep/Graphiti uses for knowledge updates.
+     */
+    retractBiTemporalEdge(edgeId, input = {}) {
+        const retractedAt = input.retractedAt ?? new Date().toISOString();
+        validateDate(retractedAt, "retractedAt");
+        if (input.factEndedAt !== undefined) {
+            const validTo = validateDateOrNull(input.factEndedAt, "factEndedAt");
+            const info = this.db
+                .prepare(`UPDATE knowledge_edges
+           SET recorded_to = ?, valid_to = ?
+           WHERE id = ? AND recorded_to IS NULL`)
+                .run(retractedAt, validTo, edgeId);
+            return info.changes > 0;
+        }
+        const info = this.db
+            .prepare(`UPDATE knowledge_edges
+         SET recorded_to = ?
+         WHERE id = ? AND recorded_to IS NULL`)
+            .run(retractedAt, edgeId);
+        return info.changes > 0;
+    }
+    /**
+     * Fetch a single bi-temporal edge by id. Returns null when missing.
+     * Handles legacy rows (null recorded_from) by falling back to
+     * created_at per the migration spec.
+     */
+    getBiTemporalEdge(edgeId) {
+        const row = this.db
+            .prepare(`SELECT id, source_id, target_id, relation, weight,
+                valid_from, valid_to, recorded_from, recorded_to, created_at
+         FROM knowledge_edges WHERE id = ?`)
+            .get(edgeId);
+        if (!row)
+            return null;
+        return rowToBiTemporalEdge(row);
+    }
+    /**
+     * Query edges that were VALID (true in the world) at `date`.
+     * Ignores the ingest-time axis entirely — even retracted edges are
+     * returned if they were valid at the given date.
+     */
+    queryValidAt(date) {
+        validateDate(date, "date");
+        const rows = this.db
+            .prepare(`SELECT id, source_id, target_id, relation, weight,
+                valid_from, valid_to, recorded_from, recorded_to, created_at
+         FROM knowledge_edges
+         WHERE valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)`)
+            .all(date, date);
+        return rows.map(rowToBiTemporalEdge);
+    }
+    /**
+     * Query edges that WOTANN KNEW at `date` on the ingest-time axis.
+     * Ignores the knowledge-time axis — even edges that represent
+     * historical (no-longer-valid) facts are returned if WOTANN knew
+     * about them at the given date.
+     */
+    queryKnownAt(date) {
+        validateDate(date, "date");
+        const rows = this.db
+            .prepare(`SELECT id, source_id, target_id, relation, weight,
+                valid_from, valid_to, recorded_from, recorded_to, created_at
+         FROM knowledge_edges
+         WHERE recorded_from <= ? AND (recorded_to IS NULL OR recorded_to > ?)`)
+            .all(date, date);
+        return rows.map(rowToBiTemporalEdge);
+    }
+    /**
+     * Query edges matching BOTH axes: the fact was true in the world at
+     * `validAt` AND WOTANN knew the fact at `knownAt`. This is the
+     * canonical Zep/Graphiti snapshot query — "what was WOTANN's picture
+     * of the world as of date X?".
+     */
+    querySnapshot(q) {
+        validateDate(q.validAt, "validAt");
+        validateDate(q.knownAt, "knownAt");
+        const rows = this.db
+            .prepare(`SELECT id, source_id, target_id, relation, weight,
+                valid_from, valid_to, recorded_from, recorded_to, created_at
+         FROM knowledge_edges
+         WHERE valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)
+           AND recorded_from <= ? AND (recorded_to IS NULL OR recorded_to > ?)`)
+            .all(q.validAt, q.validAt, q.knownAt, q.knownAt);
+        return rows.map(rowToBiTemporalEdge);
+    }
+    /**
+     * Replace an edge: invalidate the old one on BOTH axes (fact ended
+     * AND knowledge retracted) and insert a new edge carrying the
+     * successor fact. Returns the new edge id. This is the canonical
+     * Zep/Graphiti contradiction-handling flow: "we used to think X, now
+     * we think Y — the switchover happened at time T".
+     */
+    replaceBiTemporalEdge(oldEdgeId, input) {
+        const at = input.at ?? new Date().toISOString();
+        validateDate(at, "at");
+        const existing = this.getBiTemporalEdge(oldEdgeId);
+        if (!existing)
+            return null;
+        const tx = this.db.transaction(() => {
+            this.retractBiTemporalEdge(oldEdgeId, {
+                retractedAt: at,
+                factEndedAt: at,
+            });
+            return this.addBiTemporalEdge(input.sourceId, input.targetId, input.relation, {
+                validFrom: at,
+                recordedFrom: at,
+                ...(input.weight !== undefined ? { weight: input.weight } : {}),
+            });
+        });
+        return tx();
+    }
+    /**
+     * Invalidate a knowledge edge by setting its valid_to timestamp.
+     * The edge remains for historical queries but is excluded from active queries.
+     */
+    invalidateKnowledgeEdge(edgeId, endedAt) {
+        const result = this.db
+            .prepare(`
+      UPDATE knowledge_edges SET valid_to = ? WHERE id = ? AND valid_to IS NULL
+    `)
+            .run(endedAt ?? new Date().toISOString(), edgeId);
+        return result.changes > 0;
+    }
+    /**
+     * Get knowledge edges that were active at a specific point in time.
+     * A relationship is active if valid_from <= date AND (valid_to IS NULL OR valid_to > date).
+     */
+    getActiveEdgesAt(date) {
+        return this.db
+            .prepare(`
+      SELECT id, source_id, target_id, relation, weight, valid_from, valid_to
+      FROM knowledge_edges
+      WHERE valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)
+    `)
+            .all(date, date).map((r) => ({
+            id: r["id"],
+            sourceId: r["source_id"],
+            targetId: r["target_id"],
+            relation: r["relation"],
+            weight: r["weight"],
+            validFrom: r["valid_from"],
+            validTo: r["valid_to"] ?? null,
+        }));
+    }
+    getRelatedEntities(entity, maxDepth = 2) {
+        const startNodes = this.db
+            .prepare(`
+      SELECT * FROM knowledge_nodes WHERE entity = ? AND (valid_to IS NULL OR valid_to > datetime('now'))
+    `)
+            .all(entity);
+        if (startNodes.length === 0)
+            return [];
+        const visited = new Set();
+        const result = [];
+        let frontier = startNodes.map((n) => n["id"]);
+        for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+            const nextFrontier = [];
+            for (const nodeId of frontier) {
+                if (visited.has(nodeId))
+                    continue;
+                visited.add(nodeId);
+                const node = this.db.prepare(`SELECT * FROM knowledge_nodes WHERE id = ?`).get(nodeId);
+                if (node) {
+                    result.push({
+                        id: node["id"],
+                        entity: node["entity"],
+                        entityType: node["entity_type"],
+                        properties: JSON.parse(node["properties"] || "{}"),
+                        validFrom: node["valid_from"],
+                        validTo: node["valid_to"],
+                    });
+                }
+                const edges = this.db
+                    .prepare(`
+          SELECT target_id AS connected FROM knowledge_edges WHERE source_id = ? AND (valid_to IS NULL OR valid_to > datetime('now'))
+          UNION SELECT source_id AS connected FROM knowledge_edges WHERE target_id = ? AND (valid_to IS NULL OR valid_to > datetime('now'))
+        `)
+                    .all(nodeId, nodeId);
+                for (const e of edges) {
+                    if (!visited.has(e.connected))
+                        nextFrontier.push(e.connected);
+                }
+            }
+            frontier = nextFrontier;
+        }
+        return result;
+    }
+    getKnowledgeGraphSize() {
+        const nodes = this.db.prepare(`SELECT COUNT(*) as c FROM knowledge_nodes`).get().c;
+        const edges = this.db.prepare(`SELECT COUNT(*) as c FROM knowledge_edges`).get().c;
+        return { nodes, edges };
+    }
+    // ── Layer 6: Skeptical Recall ──────────────────────────────
+    skepticalSearch(query, limit = 10) {
+        const results = this.search(query, limit);
+        return results.map((r) => {
+            let ageDays = 0;
+            try {
+                const updatedTime = new Date(r.entry.updatedAt).getTime();
+                if (!isNaN(updatedTime)) {
+                    ageDays = (Date.now() - updatedTime) / (1000 * 60 * 60 * 24);
+                }
+            }
+            catch {
+                /* default to 0 days age */
+            }
+            const temporalDecay = Math.max(0.3, 1.0 - ageDays * 0.01);
+            const confidence = (r.entry.confidence ?? 1.0) * temporalDecay * (r.entry.verified ? 1.0 : 0.7);
+            return { ...r, needsVerification: confidence < 0.6 || !r.entry.verified };
+        });
+    }
+    // ── Layer 7: Team Memory ───────────────────────────────────
+    setTeamMemory(agentId, key, value) {
+        this.db
+            .prepare(`
+      INSERT INTO team_memory (id, agent_id, key, value) VALUES (?, ?, ?, ?)
+    `)
+            .run(randomUUID(), agentId, key, value);
+    }
+    getTeamMemory(agentId) {
+        if (agentId) {
+            return this.db
+                .prepare(`
+        SELECT agent_id, key, value FROM team_memory WHERE agent_id = ? AND shared = 1 ORDER BY updated_at DESC
+      `)
+                .all(agentId);
+        }
+        return this.db
+            .prepare(`
+      SELECT agent_id, key, value FROM team_memory WHERE shared = 1 ORDER BY updated_at DESC LIMIT 100
+    `)
+            .all();
+    }
+    getTeamMemoryRecords(agentId) {
+        const rows = agentId
+            ? this.db
+                .prepare(`
+        SELECT id, agent_id, key, value, shared, created_at, updated_at
+        FROM team_memory
+        WHERE agent_id = ?
+        ORDER BY updated_at DESC
+      `)
+                .all(agentId)
+            : this.db
+                .prepare(`
+        SELECT id, agent_id, key, value, shared, created_at, updated_at
+        FROM team_memory
+        ORDER BY updated_at DESC
+      `)
+                .all();
+        return rows.map((row) => ({
+            id: row["id"],
+            agentId: row["agent_id"],
+            key: row["key"],
+            value: row["value"],
+            shared: Boolean(row["shared"]),
+            createdAt: row["created_at"],
+            updatedAt: row["updated_at"],
+        }));
+    }
+    exportTeamMemorySnapshot(agentId) {
+        return {
+            exportedAt: new Date().toISOString(),
+            entries: this.getTeamMemoryRecords(agentId),
+        };
+    }
+    importTeamMemorySnapshot(snapshot) {
+        let inserted = 0;
+        let updated = 0;
+        let skipped = 0;
+        const conflicts = [];
+        for (const entry of snapshot.entries) {
+            const existing = this.db
+                .prepare(`
+        SELECT id, value, updated_at
+        FROM team_memory
+        WHERE agent_id = ? AND key = ?
+        ORDER BY updated_at DESC
+        LIMIT 1
+      `)
+                .get(entry.agentId, entry.key);
+            if (!existing) {
+                this.db
+                    .prepare(`
+          INSERT INTO team_memory (id, agent_id, key, value, shared, created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?)
+        `)
+                    .run(entry.id, entry.agentId, entry.key, entry.value, entry.shared ? 1 : 0, entry.createdAt, entry.updatedAt);
+                inserted++;
+                continue;
+            }
+            const incomingTs = Date.parse(entry.updatedAt);
+            const existingTs = Date.parse(existing.updated_at);
+            const incomingIsNewer = !Number.isNaN(incomingTs) && !Number.isNaN(existingTs)
+                ? incomingTs > existingTs
+                : entry.updatedAt > existing.updated_at;
+            if (existing.value !== entry.value) {
+                conflicts.push(`${entry.agentId}:${entry.key}`);
+            }
+            if (incomingIsNewer) {
+                this.db
+                    .prepare(`
+          UPDATE team_memory
+          SET value = ?, shared = ?, updated_at = ?, created_at = ?
+          WHERE id = ?
+        `)
+                    .run(entry.value, entry.shared ? 1 : 0, entry.updatedAt, entry.createdAt, existing.id);
+                updated++;
+            }
+            else {
+                skipped++;
+            }
+        }
+        return {
+            inserted,
+            updated,
+            skipped,
+            conflicts: [...new Set(conflicts)],
+        };
+    }
+    syncTeamMemoryFile(snapshotPath, agentId) {
+        let syncResult = {
+            inserted: 0,
+            updated: 0,
+            skipped: 0,
+            conflicts: [],
+        };
+        if (existsSync(snapshotPath)) {
+            try {
+                const parsed = JSON.parse(readFileSync(snapshotPath, "utf-8"));
+                if (Array.isArray(parsed.entries)) {
+                    syncResult = this.importTeamMemorySnapshot(parsed);
+                }
+            }
+            catch {
+                syncResult = {
+                    inserted: 0,
+                    updated: 0,
+                    skipped: 0,
+                    conflicts: ["snapshot:parse-error"],
+                };
+            }
+        }
+        const exportedSnapshot = this.exportTeamMemorySnapshot(agentId);
+        // SECURITY (B6): atomic write + lock so concurrent daemon processes don't
+        // write a half-serialized JSON blob to the snapshot file.
+        writeFileAtomicSyncBestEffort(snapshotPath, JSON.stringify(exportedSnapshot, null, 2), {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+        return {
+            ...syncResult,
+            exported: exportedSnapshot.entries.length,
+        };
+    }
+    // ── Layer 8: Proactive Context ─────────────────────────────
+    getProactiveContext(sessionId, currentFile) {
+        const suggestions = [];
+        const recent = this.db
+            .prepare(`
+      SELECT * FROM memory_entries WHERE session_id = ? AND archived = 0 ORDER BY last_accessed DESC LIMIT 5
+    `)
+            .all(sessionId);
+        for (const r of recent)
+            suggestions.push(this.rowToEntry(r));
+        if (currentFile) {
+            const fileRelated = this.search(currentFile.split("/").pop() ?? "", 3);
+            for (const r of fileRelated) {
+                if (!suggestions.some((s) => s.id === r.entry.id))
+                    suggestions.push(r.entry);
+            }
+        }
+        return suggestions.slice(0, 10);
+    }
+    // ── FTS5 Search ────────────────────────────────────────────
+    search(query, limit = 10, options) {
+        const domainFilter = options?.domainFilter ?? [];
+        const hasDomainFilter = domainFilter.length > 0;
+        const conditions = ["memory_fts MATCH ?", "me.archived = 0"];
+        const params = [query];
+        if (hasDomainFilter) {
+            const placeholders = domainFilter.map(() => "?").join(", ");
+            conditions.push(`me.domain IN (${placeholders})`);
+            for (const d of domainFilter)
+                params.push(d);
+        }
+        params.push(limit);
+        const sql = `
+      SELECT me.*, rank AS score, snippet(memory_fts, 1, '<b>', '</b>', '...', 32) AS snippet
+      FROM memory_fts
+      JOIN memory_entries me ON me.rowid = memory_fts.rowid
+      WHERE ${conditions.join(" AND ")}
+      ORDER BY rank LIMIT ?
+    `;
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => ({
+            entry: this.rowToEntry(r),
+            score: r["score"] ?? 0,
+            snippet: r["snippet"] ?? "",
+        }));
+    }
+    /**
+     * Domain-partitioned search (MemPalace R1).
+     * Filters by domain/topic BEFORE running FTS5, reducing noise by up to 34%.
+     * - domain only: +12% retrieval (MemPalace: 60.9% → 73.1%)
+     * - domain + topic: +34% retrieval (MemPalace: 60.9% → 94.8%)
+     */
+    searchPartitioned(query, options = {}) {
+        const { domain, topic, limit = 10 } = options;
+        // No partition filters → fall back to standard search
+        if (!domain && !topic)
+            return this.search(query, limit);
+        // Build dynamic WHERE clause for domain/topic filtering
+        const conditions = ["memory_fts MATCH ?", "me.archived = 0"];
+        const params = [query];
+        if (domain) {
+            conditions.push("me.domain = ?");
+            params.push(domain);
+        }
+        if (topic) {
+            conditions.push("me.topic = ?");
+            params.push(topic);
+        }
+        params.push(limit);
+        const sql = `
+      SELECT me.*, rank AS score, snippet(memory_fts, 1, '<b>', '</b>', '...', 32) AS snippet
+      FROM memory_fts
+      JOIN memory_entries me ON me.rowid = memory_fts.rowid
+      WHERE ${conditions.join(" AND ")}
+      ORDER BY rank LIMIT ?
+    `;
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map((r) => ({
+            entry: this.rowToEntry(r),
+            score: r["score"] ?? 0,
+            snippet: r["snippet"] ?? "",
+        }));
+    }
+    /**
+     * Phase 13 Wave-3C — MemPalace-aware search. Gated by MEMORY_PALACE=1
+     * env. When enabled, accepts a MemPalacePath/Query and routes through
+     * searchPartitioned with domain/topic derived from the palace path
+     * (hall → domain, wing[/room] → topic). The palace-style hierarchy
+     * then post-filters results so wing=X/room=Y queries only return
+     * entries recorded under X/Y, not X alone. When MEMORY_PALACE is
+     * unset, falls back to standard search (no regression).
+     */
+    searchPalace(query, palace = {}, limit = 10) {
+        if (process.env["MEMORY_PALACE"] !== "1") {
+            return this.search(query, limit);
+        }
+        const path = { hall: palace.hall ?? "" };
+        const { domain, topic } = palace.hall
+            ? palaceToStoreFields({
+                hall: palace.hall,
+                ...(palace.wing ? { wing: palace.wing } : {}),
+                ...(palace.room ? { room: palace.room } : {}),
+            })
+            : { domain: "", topic: undefined };
+        const hits = this.searchPartitioned(query, {
+            limit: limit * 2,
+            ...(domain ? { domain } : {}),
+            ...(topic ? { topic } : {}),
+        });
+        if (!palace.hall)
+            return hits.slice(0, limit);
+        // Post-filter: require the row's palace-path to fall under the query.
+        const filtered = hits.filter((h) => {
+            const rowPath = palaceFromStoreFields({
+                domain: h.entry.domain ?? "",
+                topic: h.entry.topic,
+            });
+            return palaceIsUnder(rowPath, path);
+        });
+        return filtered.slice(0, limit);
+    }
+    // ── MemPalace helpers (Phase 2 P1-M7) ───────────────────────
+    /**
+     * Phase 2 P1-M7: list every distinct hall currently represented in
+     * memory_entries, derived from the row's domain/topic fields. A hall
+     * is the top-level palace axis ("auth", "deploy", "memory").
+     */
+    palaceListHalls() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT domain, topic FROM memory_entries WHERE archived = 0 AND domain != ''`)
+            .all();
+        const entries = this.rowsToPalaceEntries(rows);
+        return palaceListHalls(entries);
+    }
+    /** Phase 2 P1-M7: list wings under a hall. */
+    palaceListWings(hall) {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT domain, topic FROM memory_entries
+         WHERE archived = 0 AND domain != ''`)
+            .all();
+        const entries = this.rowsToPalaceEntries(rows);
+        return palaceListWings(entries, hall);
+    }
+    /** Phase 2 P1-M7: list rooms under a specific wing within a hall. */
+    palaceListRooms(hall, wing) {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT domain, topic FROM memory_entries
+         WHERE archived = 0 AND domain != ''`)
+            .all();
+        const entries = this.rowsToPalaceEntries(rows);
+        return palaceListRooms(entries, hall, wing);
+    }
+    /**
+     * Phase 2 P1-M7: tree-view of the palace — counts at hall, wing, and
+     * room granularity. Use together with `palaceTreeText()` for a
+     * printable outline.
+     */
+    palaceCountTree() {
+        const rows = this.db
+            .prepare(`SELECT domain, topic FROM memory_entries WHERE archived = 0 AND domain != ''`)
+            .all();
+        const entries = this.rowsToPalaceEntries(rows);
+        return palaceCountTree(entries);
+    }
+    /**
+     * Phase 2 P1-M7: render the palace tree as a printable outline.
+     * Wraps palaceCountTree + palaceRenderTree so TUIs and CLI consumers
+     * can print a quick palace summary without reaching into mem-palace
+     * directly.
+     */
+    palaceTreeText() {
+        return palaceRenderTree(this.palaceCountTree());
+    }
+    /**
+     * Phase 2 P1-M7: parse a slash-separated palace path and format it
+     * back out. Kept on MemoryStore so the palace API is discoverable
+     * from a single entry point.
+     */
+    palaceParsePath(pathString) {
+        return palaceParsePath(pathString);
+    }
+    palaceFormatPath(path) {
+        return palaceFormatPath(path);
+    }
+    /**
+     * Convert memory_entries rows to MemPalaceEntry shape. Derives the
+     * palace path from domain/topic fields via the shared
+     * palaceFromStoreFields helper.
+     */
+    rowsToPalaceEntries(rows) {
+        return rows.map((r) => ({
+            path: palaceFromStoreFields({ domain: r.domain, topic: r.topic ?? "" }),
+            data: null,
+        }));
+    }
+    // ── Contextual embeddings helpers (Phase 2 P1-M7) ───────────
+    /**
+     * Phase 2 P1-M7: install a ContextualChunkGenerator on this store.
+     * When set, every subsequent insert() will call the generator and
+     * prepend ~50 tokens of context to the indexed value per Anthropic's
+     * contextual retrieval guidelines.
+     *
+     * Thin wrapper over setContextGenerator that accepts the structured
+     * ContextualChunkGenerator type defined in contextual-embeddings.ts.
+     */
+    asyncContextGenerator = null;
+    installContextGenerator(generator) {
+        this.asyncContextGenerator = generator;
+    }
+    /** Phase 2 P1-M7: retrieve the installed async ContextualChunkGenerator. */
+    getContextGenerator() {
+        return this.asyncContextGenerator;
+    }
+    /**
+     * Phase 2 P1-M7: convenience — wrap an LLM query function as a
+     * ContextualChunkGenerator and install it in one call.
+     */
+    enableContextualRetrieval(llm) {
+        this.installContextGenerator(createLlmContextGenerator(llm));
+    }
+    /**
+     * Phase 2 P1-M7: build one contextual chunk (chunk + LLM-derived
+     * context). Exposed for callers that want to precompute chunks
+     * offline before inserting into memory.
+     */
+    async buildContextualChunk(chunk, document, llm) {
+        const generator = createLlmContextGenerator(llm);
+        const built = await buildContextualChunk(chunk, document, generator);
+        return built.contextualized;
+    }
+    /**
+     * Phase 2 P1-M7: batch version — build multiple contextual chunks
+     * with bounded concurrency.
+     */
+    async buildContextualChunksBatch(chunks, document, llm, options) {
+        const generator = createLlmContextGenerator(llm);
+        const built = await buildBatchedContextualChunks(chunks, document, generator, options);
+        return built.map((b) => b.contextualized);
+    }
+    /**
+     * Phase 13 Wave-3C — extended search modes (Cognee parity). Dispatches
+     * to extended-search-types for non-default modes: temporal-filtered,
+     * summary-only, metadata-only, hybrid-fusion. Default mode falls
+     * through to FTS5 search. Non-default modes return an empty list when
+     * the store has no entries matching the mode's criteria.
+     */
+    searchExtended(query, options = {}) {
+        const mode = options.mode ?? "default";
+        const limit = options.limit ?? 10;
+        if (mode === "default")
+            return this.search(query, limit);
+        const ftsHits = this.search(query, limit * 2);
+        const entries = ftsHits.map((h) => ({
+            id: h.entry.id,
+            content: h.entry.value,
+            ...(h.entry.documentDate ? { timestamp: h.entry.documentDate } : {}),
+            ...(h.entry.tags ? { metadata: { type: h.entry.tags } } : {}),
+        }));
+        const byId = new Map(ftsHits.map((h) => [h.entry.id, h]));
+        let hits = [];
+        if (mode === "temporal-filtered" && options.temporal) {
+            hits = temporalFiltered(entries, options.temporal);
+        }
+        else if (mode === "summary-only") {
+            hits = summaryOnly(entries);
+        }
+        else if (mode === "metadata-only" && options.metadata) {
+            hits = metadataOnly(entries, options.metadata);
+        }
+        else if (mode === "hybrid-fusion" && options.secondaryRanking) {
+            const primary = ftsHits.map((h, rank) => ({
+                entry: {
+                    id: h.entry.id,
+                    content: h.entry.value,
+                    ...(h.entry.documentDate ? { timestamp: h.entry.documentDate } : {}),
+                },
+                score: 1 / (rank + 1),
+            }));
+            const secondary = options.secondaryRanking.map((h, rank) => ({
+                entry: {
+                    id: h.entry.id,
+                    content: h.entry.value,
+                    ...(h.entry.documentDate ? { timestamp: h.entry.documentDate } : {}),
+                },
+                score: 1 / (rank + 1),
+            }));
+            hits = rrfFusion([primary, secondary]);
+        }
+        return hits
+            .map((hit) => byId.get(hit.entry.id))
+            .filter((r) => r !== undefined)
+            .slice(0, limit);
+    }
+    // ── TEMPR (Phase 2 P1-M4, Hindsight port) ──────────────
+    /**
+     * TEMPR 4-channel parallel retrieval + RRF + cross-encoder rerank.
+     *
+     * Hindsight port (arXiv 2512.12818) — 91.4% LongMemEval-S reference.
+     * Runs 4 canonical channels in parallel over this store:
+     *
+     *   1. VECTOR   — dense retrieval via caller-supplied embedder
+     *                 (falls back to FTS5-equivalent if no embedder)
+     *   2. BM25     — FTS5 lexical match (store.search)
+     *   3. ENTITY   — KG-aware: parses query entity candidates and
+     *                 retrieves entries whose content mentions any
+     *                 related entity (from knowledge_nodes + M7 edges)
+     *   4. TEMPORAL — bi-temporal snapshot: returns entries adjacent
+     *                 to edges valid at `opts.validAt` (leverages M5
+     *                 queryValidAt). When no validAt, falls back to
+     *                 eventDate/documentDate proximity to `opts.now`.
+     *
+     * Failed channels (exceptions from the backing calls) are isolated
+     * — the remaining channels still contribute. A channel that crashes
+     * is captured in `result.channelResults.get(name).error`; the overall
+     * query never crashes.
+     *
+     * Cross-encoder: defaults to the word-overlap heuristic (good
+     * enough for wiring; the real MS MARCO MiniLM lands in P1-M2 via
+     * createCrossEncoderFromFn). Pass `crossEncoder: null` to skip
+     * rerank entirely.
+     *
+     * Per-query isolation: every call constructs a fresh TEMPR handle
+     * over snapshot channel functions — no shared state between calls.
+     */
+    async temprSearch(query, opts = {}) {
+        const topK = opts.topK ?? 20;
+        const pool = opts.candidatePool ?? Math.max(50, topK * 3);
+        // Resolve the asymmetric prefix profile ONCE per call. Order:
+        //   1. Explicit profile override (highest priority).
+        //   2. Registry lookup by model name.
+        //   3. null (symmetric / no prefix).
+        // The env-var gate suppresses the entire feature when off — keeps
+        // existing un-prefixed indexes from getting score-skewed by a
+        // prefixed query embedding (see embedding-profiles.ts header).
+        const prefixesEnabled = isAsymmetricEmbeddingsEnabled();
+        const resolvedProfile = !prefixesEnabled
+            ? null
+            : (opts.embeddingProfile ??
+                (opts.embeddingModel ? getEmbeddingProfile(opts.embeddingModel) : null));
+        // Build each channel. Each channel is a closure over `this`. Errors
+        // inside the closure become rejections that TEMPR captures — never
+        // swallow here.
+        const vectorChannel = {
+            name: "vector",
+            retrieve: async (args) => {
+                if (!opts.embed) {
+                    // No embedder provided — emit empty rather than faking
+                    // (quality bar: honest failure). Caller sees the empty
+                    // channel result and can decide what to do.
+                    return { candidates: [] };
+                }
+                // Phase 2 P1-M2 (OMEGA): native sqlite-vec knn path.
+                // When a vectorBackend is provided, route through it rather
+                // than doing per-row cosine. The backend is populated by the
+                // caller (typically via MemoryStore.upsertEmbedding).
+                // V9 T1.3: when `opts.vectorBackend` is omitted, fall back to
+                // the store's attached `this.vectorBackend` so callers that
+                // called `attachVectorBackend()` at setup time get sqlite-vec
+                // routing automatically.
+                const resolvedBackend = opts.vectorBackend ?? this.vectorBackend;
+                if (resolvedBackend) {
+                    try {
+                        // LightRAG asymmetric-prefix port: prepend the model's
+                        // recommended query prefix BEFORE embedding. No-op when
+                        // the env-var gate is off OR the model isn't in the
+                        // registry (resolvedProfile === null).
+                        const queryText = applyQueryPrefix(resolvedProfile, args.query);
+                        const queryVec = await opts.embed(queryText);
+                        const hits = resolvedBackend.knn(queryVec, pool);
+                        if (hits.length === 0)
+                            return { candidates: [] };
+                        // Rehydrate content from the store. Missing ids (stale
+                        // index) are dropped silently — honest fail.
+                        const cands = [];
+                        for (const h of hits) {
+                            const entry = this.getById(h.id);
+                            if (entry) {
+                                cands.push({ id: entry.id, content: entry.value });
+                            }
+                        }
+                        return { candidates: cands };
+                    }
+                    catch {
+                        // sqlite-vec path failed — fall through to FTS5+cosine
+                        // fallback below. Honest degradation.
+                    }
+                }
+                // Baseline vector retrieval: FTS5 shortlist → cosine rerank
+                // against query embedding. This is a COARSE approximation
+                // used when sqlite-vec isn't wired.
+                const shortlist = this.search(args.query, pool);
+                if (shortlist.length === 0)
+                    return { candidates: [] };
+                // LightRAG asymmetric-prefix port: query gets queryPrefix,
+                // each doc gets docPrefix — different prefixes are the whole
+                // point of this branch. Both calls no-op when the gate is off.
+                const queryVec = await opts.embed(applyQueryPrefix(resolvedProfile, args.query));
+                const scored = [];
+                for (const row of shortlist) {
+                    const docVec = await opts.embed(applyDocPrefix(resolvedProfile, row.entry.value));
+                    const score = cosineSimTempr(queryVec, docVec);
+                    if (score > 0) {
+                        scored.push({
+                            c: { id: row.entry.id, content: row.entry.value },
+                            score,
+                        });
+                    }
+                }
+                scored.sort((a, b) => b.score - a.score);
+                return { candidates: scored.slice(0, pool).map((s) => s.c) };
+            },
+        };
+        const bm25Channel = {
+            name: "bm25",
+            retrieve: async (args) => {
+                const results = this.search(args.query, pool);
+                return {
+                    candidates: results.map((r) => ({
+                        id: r.entry.id,
+                        content: r.entry.value,
+                    })),
+                };
+            },
+        };
+        const entityChannel = {
+            name: "entity",
+            retrieve: async (args) => {
+                // Heuristic entity extraction from the query: capitalized
+                // tokens + quoted strings. Good enough for the channel split
+                // (we don't need a full NER — the LLM-based extraction lives
+                // in observation-extractor and feeds into recordEntity).
+                const tokens = extractQueryEntities(args.query);
+                if (tokens.length === 0)
+                    return { candidates: [] };
+                // Look up knowledge_nodes by any matching entity name, then
+                // find memory entries that mention any related entity.
+                const collected = new Map();
+                for (const tok of tokens) {
+                    try {
+                        const related = this.getRelatedEntities(tok, 2);
+                        for (const node of related) {
+                            // Find entries whose value mentions this entity name.
+                            // FTS5 quoted-phrase search: "Alice" (no operators).
+                            const safe = fts5QuoteName(node.entity);
+                            if (!safe)
+                                continue;
+                            const rows = this.search(safe, 20);
+                            for (const row of rows) {
+                                if (!collected.has(row.entry.id)) {
+                                    collected.set(row.entry.id, {
+                                        id: row.entry.id,
+                                        content: row.entry.value,
+                                        metadata: { entityMatch: node.entity, entityType: node.entityType },
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    catch {
+                        // skip this token — another might match
+                    }
+                }
+                return { candidates: [...collected.values()].slice(0, pool) };
+            },
+        };
+        const temporalChannel = {
+            name: "temporal",
+            retrieve: async (_args) => {
+                // If a validAt is provided, fetch edges valid at that point
+                // and surface entries connected (via KG node.entity) to those
+                // edges' source/target. Otherwise, surface entries whose
+                // documentDate/eventDate is closest to `now` — a recency
+                // proxy for temporal relevance.
+                if (opts.validAt) {
+                    try {
+                        const edges = this.queryValidAt(opts.validAt);
+                        if (edges.length === 0)
+                            return { candidates: [] };
+                        // Resolve each edge's source/target knowledge_node entity
+                        // name, then collect matching entries.
+                        const entityNames = new Set();
+                        for (const edge of edges.slice(0, pool)) {
+                            const sNode = this.db
+                                .prepare(`SELECT entity FROM knowledge_nodes WHERE id = ?`)
+                                .get(edge.sourceId);
+                            const tNode = this.db
+                                .prepare(`SELECT entity FROM knowledge_nodes WHERE id = ?`)
+                                .get(edge.targetId);
+                            if (sNode?.entity)
+                                entityNames.add(sNode.entity);
+                            if (tNode?.entity)
+                                entityNames.add(tNode.entity);
+                        }
+                        const collected = new Map();
+                        for (const name of entityNames) {
+                            const safe = fts5QuoteName(name);
+                            if (!safe)
+                                continue;
+                            const rows = this.search(safe, 10);
+                            for (const row of rows) {
+                                if (!collected.has(row.entry.id)) {
+                                    collected.set(row.entry.id, {
+                                        id: row.entry.id,
+                                        content: row.entry.value,
+                                        metadata: { temporalEntity: name, validAt: opts.validAt },
+                                    });
+                                }
+                            }
+                        }
+                        return { candidates: [...collected.values()].slice(0, pool) };
+                    }
+                    catch {
+                        return { candidates: [] };
+                    }
+                }
+                // Fallback: recency-based. Pick entries with documentDate
+                // closest to `now` from within a BM25 shortlist for relevance.
+                const now = opts.now ?? Date.now();
+                const shortlist = this.search(query, pool);
+                const scored = shortlist
+                    .filter((r) => r.entry.documentDate !== undefined)
+                    .map((r) => {
+                    const age = Math.abs(now - r.entry.documentDate);
+                    return { entry: r.entry, age };
+                })
+                    .sort((a, b) => a.age - b.age);
+                return {
+                    candidates: scored.slice(0, pool).map((s) => ({
+                        id: s.entry.id,
+                        content: s.entry.value,
+                        metadata: { temporalRecencyAge: s.age },
+                    })),
+                };
+            },
+        };
+        // V9 T1.4: when `opts.crossEncoder` is omitted, default to the
+        // store's attached `this.defaultCrossEncoder` (ONNX when attached
+        // via `attachOnnxCrossEncoder`, heuristic otherwise). Passing
+        // `null` still explicitly disables reranking.
+        const crossEncoder = opts.crossEncoder === null ? undefined : (opts.crossEncoder ?? this.defaultCrossEncoder);
+        const tempr = createTEMPR({
+            channels: [vectorChannel, bm25Channel, entityChannel, temporalChannel],
+            ...(crossEncoder !== undefined ? { crossEncoder } : {}),
+            topK,
+            ...(opts.onChannelError !== undefined ? { onChannelError: opts.onChannelError } : {}),
+        });
+        const searchOpts = { topK };
+        const result = await tempr.search(query, searchOpts);
+        // Rehydrate full MemoryEntry on each hit (callers typically want
+        // the full entry, not just id + content).
+        const hits = result.hits.map((hit) => ({
+            ...hit,
+            entry: this.getById(hit.id),
+        }));
+        return {
+            hits,
+            channelResults: result.channelResults,
+            rerankerApplied: result.rerankerApplied,
+            durationMs: result.durationMs,
+        };
+    }
+    /** Get all unique domains in the memory store. */
+    getDomains() {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT domain FROM memory_entries WHERE archived = 0 AND domain != '' ORDER BY domain`)
+            .all();
+        return rows.map((r) => r.domain);
+    }
+    /** Get all unique topics within a domain (or all topics if no domain specified). */
+    getTopics(domain) {
+        const rows = domain
+            ? this.db
+                .prepare(`SELECT DISTINCT topic FROM memory_entries WHERE archived = 0 AND domain = ? AND topic != '' ORDER BY topic`)
+                .all(domain)
+            : this.db
+                .prepare(`SELECT DISTINCT topic FROM memory_entries WHERE archived = 0 AND topic != '' ORDER BY topic`)
+                .all();
+        return rows.map((r) => r.topic);
+    }
+    // ── Consolidation Lock ─────────────────────────────────────
+    acquireConsolidationLock(lockId) {
+        const lockPath = join(this.dbPath, "..", "consolidation.lock");
+        if (existsSync(lockPath)) {
+            try {
+                const lockData = JSON.parse(readFileSync(lockPath, "utf-8"));
+                if (Date.now() - lockData.timestamp > 30 * 60 * 1000) {
+                    unlinkSync(lockPath);
+                }
+                else {
+                    return false;
+                }
+            }
+            catch {
+                try {
+                    unlinkSync(lockPath);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        try {
+            writeFileSync(lockPath, JSON.stringify({ lockId, timestamp: Date.now() }), { flag: "wx" });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    releaseConsolidationLock() {
+        const lockPath = join(this.dbPath, "..", "consolidation.lock");
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // ── Decision Log ───────────────────────────────────────────
+    logDecision(decision) {
+        this.db
+            .prepare(`
+      INSERT INTO decision_log (id, decision, rationale, alternatives, constraints, stakeholders, session_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(decision.id, decision.decision, decision.rationale, decision.alternatives ?? null, decision.constraints ?? null, decision.stakeholders ?? null, decision.sessionId ?? null);
+    }
+    getDecisions(limit = 20) {
+        return this.db
+            .prepare(`SELECT * FROM decision_log ORDER BY created_at DESC LIMIT ?`)
+            .all(limit);
+    }
+    // ── Memory Tools (6 agent-callable tools per spec) ─────────
+    memoryReplace(block, key, value, domain, topic) {
+        const existing = this.db
+            .prepare(`
+      SELECT id FROM memory_entries WHERE block_type = ? AND key = ? AND archived = 0
+    `)
+            .get(block, key);
+        if (existing) {
+            this.replace(existing.id, key, value);
+        }
+        else {
+            this.insert({
+                id: randomUUID(),
+                layer: "core_blocks",
+                blockType: block,
+                key,
+                value,
+                verified: false,
+                freshnessScore: 1.0,
+                confidenceLevel: 0.8,
+                verificationStatus: "unverified",
+                domain: domain ?? "",
+                topic: topic ?? "",
+            });
+        }
+    }
+    memoryInsert(block, key, value, domain, topic) {
+        this.insert({
+            id: randomUUID(),
+            layer: "core_blocks",
+            blockType: block,
+            key,
+            value,
+            verified: false,
+            freshnessScore: 1.0,
+            confidenceLevel: 0.8,
+            verificationStatus: "unverified",
+            domain: domain ?? "",
+            topic: topic ?? "",
+        });
+    }
+    memoryRethink(entryId, newValue) {
+        const entry = this.getById(entryId);
+        if (!entry)
+            return null;
+        this.replace(entryId, entry.key, newValue);
+        return { ...entry, value: newValue };
+    }
+    memorySearch(query, optionsOrLayers) {
+        // Backward compat: accept both old (layers array) and new (options object) signatures
+        if (Array.isArray(optionsOrLayers)) {
+            // Old API: memorySearch(query, layers[])
+            const results = this.searchPartitioned(query, { limit: 50 });
+            return optionsOrLayers.length === 0
+                ? results
+                : results.filter((r) => optionsOrLayers.includes(r.entry.layer));
+        }
+        // New API: memorySearch(query, { layers?, domain?, topic? })
+        const opts = (optionsOrLayers ?? {});
+        const results = this.searchPartitioned(query, {
+            domain: opts.domain,
+            topic: opts.topic,
+            limit: 50,
+        });
+        if (!opts.layers || opts.layers.length === 0)
+            return results;
+        return results.filter((r) => opts.layers.includes(r.entry.layer));
+    }
+    memoryArchive(entryId) {
+        const entry = this.getById(entryId);
+        if (!entry)
+            return false;
+        this.archive(entryId);
+        return true;
+    }
+    memoryVerify(entryId) {
+        const entry = this.getById(entryId);
+        if (entry) {
+            this.db
+                .prepare(`UPDATE memory_entries SET verified = 1, updated_at = datetime('now') WHERE id = ?`)
+                .run(entryId);
+            return { ...entry, verified: true };
+        }
+        return null;
+    }
+    // ── Stats ──────────────────────────────────────────────────
+    getEntryCount() {
+        return this.db.prepare(`SELECT COUNT(*) as count FROM memory_entries WHERE archived = 0`).get().count;
+    }
+    getLayerStats() {
+        const rows = this.db
+            .prepare(`
+      SELECT layer, COUNT(*) as count FROM memory_entries WHERE archived = 0 GROUP BY layer
+    `)
+            .all();
+        const stats = {};
+        for (const r of rows)
+            stats[r.layer] = r.count;
+        return stats;
+    }
+    // ── Helpers ────────────────────────────────────────────────
+    rowToEntry(row) {
+        return {
+            id: row["id"],
+            layer: row["layer"],
+            blockType: row["block_type"],
+            key: row["key"],
+            value: row["value"],
+            createdAt: row["created_at"],
+            updatedAt: row["updated_at"],
+            sessionId: row["session_id"],
+            verified: Boolean(row["verified"]),
+            confidence: row["confidence"],
+            tags: row["tags"],
+            sourceType: row["source_type"],
+            sourceFile: row["source_file"],
+            freshnessScore: row["freshness_score"] ?? 1.0,
+            confidenceLevel: row["confidence_level"] ?? 0.5,
+            lastVerifiedAt: row["last_verified_at"],
+            verificationStatus: row["verification_status"] ?? "unverified",
+            domain: row["domain"] ?? "",
+            topic: row["topic"] ?? "",
+            documentDate: row["document_date"],
+            eventDate: row["event_date"],
+            eventDateUncertaintyMs: row["event_date_uncertainty_ms"],
+            eventDateSource: row["event_date_source"] ?? "",
+        };
+    }
+    // ── Vector Embeddings ──────────────────────────────────────
+    /**
+     * Store a vector embedding for a memory entry.
+     * Uses trigram-based local embeddings by default (zero API calls).
+     */
+    storeEmbedding(entryId, embedding, model = "local-trigram") {
+        this.db
+            .prepare(`
+      INSERT OR REPLACE INTO memory_vectors (entry_id, embedding, model, dimensions)
+      VALUES (?, ?, ?, ?)
+    `)
+            .run(entryId, Buffer.from(embedding.buffer), model, embedding.length);
+    }
+    /**
+     * Generate a local trigram-based embedding (no API needed).
+     * Not as good as nomic-embed-text but works offline.
+     */
+    generateLocalEmbedding(text) {
+        const normalized = text.toLowerCase().replace(/[^a-z0-9\s]/g, "");
+        const words = normalized.split(/\s+/).filter(Boolean);
+        // Simple bag-of-trigrams → fixed-size vector via hashing
+        const DIMS = 256;
+        const vec = new Float32Array(DIMS);
+        for (const word of words) {
+            for (let i = 0; i <= word.length - 3; i++) {
+                const trigram = word.slice(i, i + 3);
+                let hash = 0;
+                for (let j = 0; j < trigram.length; j++) {
+                    hash = ((hash << 5) - hash + trigram.charCodeAt(j)) | 0;
+                }
+                const idx = Math.abs(hash) % DIMS;
+                vec[idx] = (vec[idx] ?? 0) + 1;
+            }
+        }
+        // L2 normalize
+        let norm = 0;
+        for (let i = 0; i < DIMS; i++)
+            norm += (vec[i] ?? 0) * (vec[i] ?? 0);
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let i = 0; i < DIMS; i++)
+                vec[i] = (vec[i] ?? 0) / norm;
+        }
+        return vec;
+    }
+    /**
+     * Cosine similarity between two embeddings.
+     */
+    cosineSimilarity(a, b) {
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        const len = Math.min(a.length, b.length);
+        for (let i = 0; i < len; i++) {
+            dot += (a[i] ?? 0) * (b[i] ?? 0);
+            normA += (a[i] ?? 0) * (a[i] ?? 0);
+            normB += (b[i] ?? 0) * (b[i] ?? 0);
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom > 0 ? dot / denom : 0;
+    }
+    /**
+     * Vector similarity search across all memory entries with embeddings.
+     * Optional domainFilter narrows the candidate set to entries in the specified
+     * domains (MemPalace-style partition). Up to +34% retrieval improvement.
+     */
+    vectorSearch(query, limit = 10, options) {
+        const queryEmbedding = this.generateLocalEmbedding(query);
+        const domainFilter = options?.domainFilter ?? [];
+        const hasDomainFilter = domainFilter.length > 0;
+        const sqlParts = [
+            "SELECT mv.entry_id, mv.embedding, mv.dimensions",
+            "FROM memory_vectors mv",
+            "JOIN memory_entries me ON me.id = mv.entry_id",
+            "WHERE me.archived = 0",
+        ];
+        const params = [];
+        if (hasDomainFilter) {
+            const placeholders = domainFilter.map(() => "?").join(", ");
+            sqlParts.push(`AND me.domain IN (${placeholders})`);
+            for (const d of domainFilter)
+                params.push(d);
+        }
+        const rows = this.db.prepare(sqlParts.join(" ")).all(...params);
+        const scored = rows.map((row) => {
+            const embedding = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimensions);
+            const similarity = this.cosineSimilarity(queryEmbedding, embedding);
+            return { entryId: row.entry_id, similarity };
+        });
+        scored.sort((a, b) => b.similarity - a.similarity);
+        return scored
+            .slice(0, limit)
+            .map((s) => ({
+            entryId: s.entryId,
+            similarity: s.similarity,
+            entry: this.getById(s.entryId),
+        }))
+            .filter((r) => r.entry !== null);
+    }
+    // ── Reciprocal Rank Fusion Search ──────────────────────────
+    /**
+     * Hybrid search combining FTS5 (BM25), vector similarity, temporal recency,
+     * and access frequency using Reciprocal Rank Fusion.
+     * Optional domainFilter narrows every signal to entries in the specified domains.
+     */
+    hybridSearch(query, limit = 10, options) {
+        const K = 60; // RRF constant
+        const domainFilter = options?.domainFilter ?? [];
+        const hasDomainFilter = domainFilter.length > 0;
+        // Signal 1: FTS5 BM25
+        const ftsResults = this.search(query, limit * 2, { domainFilter });
+        const ftsRanks = new Map();
+        ftsResults.forEach((r, i) => ftsRanks.set(r.entry.id, i + 1));
+        // Signal 2: Vector similarity
+        const vecResults = this.vectorSearch(query, limit * 2, { domainFilter });
+        const vecRanks = new Map();
+        vecResults.forEach((r, i) => vecRanks.set(r.entryId, i + 1));
+        // Signal 3: Temporal recency (all non-archived entries sorted by date)
+        let recentSql = "SELECT id FROM memory_entries WHERE archived = 0";
+        const recentParams = [];
+        if (hasDomainFilter) {
+            const placeholders = domainFilter.map(() => "?").join(", ");
+            recentSql += ` AND domain IN (${placeholders})`;
+            for (const d of domainFilter)
+                recentParams.push(d);
+        }
+        recentSql += " ORDER BY updated_at DESC LIMIT ?";
+        recentParams.push(limit * 3);
+        const recentRows = this.db.prepare(recentSql).all(...recentParams);
+        const recencyRanks = new Map();
+        recentRows.forEach((r, i) => recencyRanks.set(r.id, i + 1));
+        // Signal 4: Access frequency
+        let freqSql = "SELECT id FROM memory_entries WHERE archived = 0";
+        const freqParams = [];
+        if (hasDomainFilter) {
+            const placeholders = domainFilter.map(() => "?").join(", ");
+            freqSql += ` AND domain IN (${placeholders})`;
+            for (const d of domainFilter)
+                freqParams.push(d);
+        }
+        freqSql += " ORDER BY access_count DESC LIMIT ?";
+        freqParams.push(limit * 3);
+        const freqRows = this.db.prepare(freqSql).all(...freqParams);
+        const freqRanks = new Map();
+        freqRows.forEach((r, i) => freqRanks.set(r.id, i + 1));
+        // Merge all candidate IDs
+        const allIds = new Set([
+            ...ftsRanks.keys(),
+            ...vecRanks.keys(),
+            ...recencyRanks.keys(),
+            ...freqRanks.keys(),
+        ]);
+        // Compute RRF score
+        const scored = [];
+        for (const id of allIds) {
+            const ftsRank = ftsRanks.get(id) ?? Infinity;
+            const vecRank = vecRanks.get(id) ?? Infinity;
+            const recRank = recencyRanks.get(id) ?? Infinity;
+            const freqRank = freqRanks.get(id) ?? Infinity;
+            const score = (ftsRank < Infinity ? 1 / (K + ftsRank) : 0) * 0.4 +
+                (vecRank < Infinity ? 1 / (K + vecRank) : 0) * 0.3 +
+                (recRank < Infinity ? 1 / (K + recRank) : 0) * 0.2 +
+                (freqRank < Infinity ? 1 / (K + freqRank) : 0) * 0.1;
+            scored.push({ id, score });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        const results = [];
+        for (const s of scored.slice(0, limit)) {
+            const entry = this.getById(s.id);
+            if (!entry)
+                continue;
+            results.push({
+                entry,
+                score: s.score,
+                snippet: entry.value.slice(0, 200),
+                matchType: "hybrid",
+            });
+        }
+        return results;
+    }
+    // ── Semantic retrieval cache (Phase 2 P1-M7) ───────────────
+    /**
+     * Phase 2 P1-M7: expose the semantic-cache backend via MemoryStore
+     * so callers can build a deduped retrieval cache without importing
+     * semantic-cache directly. The cache's lifetime is the store's
+     * lifetime; call `clearRetrievalCache()` to reset or
+     * `getRetrievalCacheStats()` to observe.
+     */
+    retrievalCache = null;
+    getRetrievalCache(options) {
+        if (!this.retrievalCache) {
+            this.retrievalCache = new SemanticCache({
+                similarityThreshold: options?.similarityThreshold ?? 0.9,
+                maxEntries: options?.maxEntries ?? 200,
+                ttlMs: options?.ttlMs ?? 10 * 60 * 1000,
+                embed: options?.embed ?? (async (text) => bigramEmbedding(text)),
+            });
+        }
+        return this.retrievalCache;
+    }
+    /**
+     * Phase 2 P1-M7: cached wrapper around search() — returns previously
+     * computed results when the query embedding is near-identical to a
+     * prior miss. Miss falls through to live search, result is cached.
+     */
+    async cachedSearch(query, limit = 10, options) {
+        const cache = this.getRetrievalCache(options);
+        const hit = await cache.get(query);
+        if (hit !== null)
+            return hit;
+        const live = this.search(query, limit);
+        await cache.set(query, live);
+        return live;
+    }
+    /** Phase 2 P1-M7: cache observability — hit/miss/eviction counters. */
+    getRetrievalCacheStats() {
+        return this.retrievalCache?.stats() ?? null;
+    }
+    /** Phase 2 P1-M7: clear the retrieval cache. */
+    clearRetrievalCache() {
+        this.retrievalCache?.clear();
+    }
+    // ── Memory benchmark (Phase 2 P1-M7) ───────────────────────
+    /**
+     * Phase 2 P1-M7: run the LongMemEval-style memory benchmark against
+     * this store. Wires the MemoryBenchmark orphan into MemoryStore —
+     * callers just say `store.runMemoryBenchmark()` and receive a
+     * scored BenchmarkSuite. Optional category lets callers run only a
+     * specific slice (e.g. "adversarial", "partitioned").
+     */
+    runMemoryBenchmark(category) {
+        const bench = new MemoryBenchmark();
+        const adapter = {
+            insert: (entry) => {
+                this.insert({
+                    id: entry.id,
+                    layer: entry.layer,
+                    blockType: entry.blockType,
+                    key: entry.key,
+                    value: entry.value,
+                    verified: entry.verified,
+                    freshnessScore: entry.freshnessScore,
+                    confidenceLevel: entry.confidenceLevel,
+                    verificationStatus: entry.verificationStatus,
+                    ...(entry.domain ? { domain: entry.domain } : {}),
+                    ...(entry.topic ? { topic: entry.topic } : {}),
+                });
+            },
+            search: (query, limit) => {
+                const safe = sanitizeForFts5(query);
+                if (!safe)
+                    return [];
+                return this.search(safe, limit).map((r) => ({
+                    entry: { key: r.entry.key, value: r.entry.value },
+                    score: r.score,
+                }));
+            },
+            searchPartitioned: (query, options) => {
+                const safe = sanitizeForFts5(query);
+                if (!safe)
+                    return [];
+                return this.searchPartitioned(safe, options).map((r) => ({
+                    entry: { key: r.entry.key, value: r.entry.value },
+                    score: r.score,
+                }));
+            },
+        };
+        return category ? bench.runCategory(adapter, category) : bench.run(adapter);
+    }
+    // ── Agent-callable memory toolkit (Phase 2 P1-M7) ──────────
+    /**
+     * Phase 2 P1-M7: return a MemoryToolkit bound to this store.
+     *
+     * MemoryToolkit exposes memory_search / memory_replace / memory_insert
+     * as agent-callable tools following the OpenAI function-calling
+     * schema. Before this wire, the toolkit existed (580 LOC with tests)
+     * but no caller instantiated it — agents couldn't actually invoke
+     * memory operations by name.
+     *
+     * The adapter cast is safe because MemoryStore already implements
+     * every method of MemoryToolStoreAdapter with the exact signatures
+     * used by memory-tools.ts.
+     */
+    createAgentToolkit() {
+        return new MemoryToolkit(this);
+    }
+    /**
+     * Phase 2 P1-M7: fetch the tool definitions (name + schema) for
+     * registering memory ops with a provider that supports function
+     * calling. Convenience so callers don't need to construct a
+     * MemoryToolkit just to read definitions.
+     */
+    getMemoryToolDefinitions() {
+        return this.createAgentToolkit().getToolDefinitions();
+    }
+    /**
+     * Phase 2 P1-M7: dispatch a memory tool by name. Returns the result
+     * envelope with success/error + data payload. Agents pass the
+     * tool_name + arguments received from the provider.
+     */
+    dispatchMemoryTool(toolName, args) {
+        return this.createAgentToolkit().dispatch(toolName, args);
+    }
+    // ── Phase 2 P1-M3: Mem0 v3 agent-facts wrappers ───────────
+    //
+    // Thin forwarders to the agent-facts module so callers holding a
+    // MemoryStore can record and retrieve Mem0 v3 agent-scoped facts
+    // without a second import. The actual tag-encoding / filter logic
+    // lives in `agent-facts.ts` (single source of truth — Quality
+    // Bar #11). These wrappers exist to keep the API symmetric with
+    // other MemoryStore capabilities (e.g., recordEntity, searchPalace).
+    //
+    // Lazy import pattern avoids any circular-module-load edge case
+    // with `agent-facts.ts` which imports MemoryStore as a type. Using
+    // `import()` at call time would make these async; we use a cached
+    // module reference instead to keep the API synchronous.
+    /**
+     * Phase 2 P1-M3: record an ADD-only agent-fact. Delegates to
+     * `recordAgentFact` in `agent-facts.ts`. Honest failure on empty
+     * agentId bubbles up — caller must provide a non-empty identity.
+     */
+    recordAgentFact(fact) {
+        // Synchronous require via eagerly-resolved module ref. The
+        // `agent-facts` module depends only on MemoryStore as a type so
+        // the cycle is harmless at runtime; the lazy binding keeps
+        // initialisation order independent of load order.
+        const mod = getAgentFactsModule();
+        mod.recordAgentFact(this, fact);
+    }
+    /**
+     * Phase 2 P1-M3: retrieve agent-facts scoped to an agent identity.
+     * Delegates to `retrieveAgentFacts` in `agent-facts.ts`.
+     */
+    retrieveAgentFacts(opts) {
+        const mod = getAgentFactsModule();
+        return mod.retrieveAgentFacts(this, opts);
+    }
+    // ── Memvid portable export/import (Phase 2 P1-M7) ──────────
+    /**
+     * Phase 2 P1-M7: export all non-archived memory_entries to a
+     * portable MemvidFile (JSON). Useful for sharing memory between
+     * machines or backing up for review.
+     *
+     * Wires the orphan MemvidBackend into the MemoryStore export path.
+     * The returned MemvidFile can be written to disk with
+     * `JSON.stringify(file, null, 2)` or passed to another
+     * store.importFromMemvid() on a different machine.
+     */
+    exportToMemvid(options) {
+        const { outputPath, ...exportOptions } = options ?? {};
+        // Build a transient memvid backend. We don't persist to disk from
+        // the store itself (caller decides where to write).
+        const tempPath = outputPath ?? join(process.cwd(), ".wotann", "memvid-export.json");
+        const backend = new MemvidBackend(tempPath);
+        const rows = this.db
+            .prepare(`SELECT id, key, value, tags, confidence, block_type, domain, topic, updated_at
+         FROM memory_entries WHERE archived = 0`)
+            .all();
+        for (const r of rows) {
+            backend.save({
+                key: String(r["key"]),
+                value: String(r["value"]),
+                category: String(r["block_type"] ?? "general"),
+                tags: r["tags"] ? r["tags"].split(",").filter(Boolean) : [],
+                confidence: Number(r["confidence"] ?? 1.0),
+                metadata: {
+                    sourceId: String(r["id"]),
+                    ...(r["domain"] ? { domain: String(r["domain"]) } : {}),
+                    ...(r["topic"] ? { topic: String(r["topic"]) } : {}),
+                },
+            });
+        }
+        return backend.export(exportOptions);
+    }
+    /**
+     * Phase 2 P1-M7: import entries from a MemvidFile into memory_entries.
+     * Delegates per-entry de-dup to the MemvidBackend then replays
+     * unique entries into the store as core_blocks rows.
+     *
+     * Returns a MemvidImportResult with imported / skipped / duplicate
+     * counts. The import is idempotent-by-key for the memvid layer but
+     * creates fresh memory_entries rows (caller can dedupe via domain
+     * or block_type after the fact).
+     */
+    importFromMemvid(file) {
+        let imported = 0;
+        let duplicates = 0;
+        const errors = [];
+        const insertTx = this.db.transaction(() => {
+            for (const entry of file.entries) {
+                try {
+                    const existing = this.db
+                        .prepare(`SELECT id FROM memory_entries WHERE key = ? LIMIT 1`)
+                        .get(entry.key);
+                    if (existing) {
+                        duplicates++;
+                        continue;
+                    }
+                    this.insert({
+                        id: randomUUID(),
+                        layer: "core_blocks",
+                        blockType: blockTypeFromMemvid(entry.category),
+                        key: entry.key,
+                        value: entry.value,
+                        verified: false,
+                        confidence: entry.confidence,
+                        tags: entry.tags.join(","),
+                        freshnessScore: 1.0,
+                        confidenceLevel: entry.confidence,
+                        verificationStatus: "unverified",
+                    });
+                    imported++;
+                }
+                catch (err) {
+                    errors.push(`Failed to import "${entry.key}": ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        });
+        insertTx();
+        return { imported, skipped: errors.length, duplicates, errors };
+    }
+    // ── Hybrid Retriever Framework (Phase 2 P1-M7) ─────────────
+    /**
+     * Phase 2 P1-M7: pluggable retriever-chain search.
+     *
+     * Wraps `hybrid-retrieval.hybridSearch`: a generic retriever-framework
+     * with RRF fusion + optional reranker. Complements the existing
+     * `hybridSearch()` (which hard-codes FTS5 + vector + recency + freq)
+     * by letting callers supply arbitrary Retriever / Reranker
+     * combinations.
+     *
+     * Default retrievers: the lexical retriever from hybrid-retrieval.
+     * Callers can pass additional retrievers (e.g. a dense-vector one) or
+     * a reranker via the `config` param.
+     */
+    async hybridRetrieverSearch(query, config) {
+        // Pull all non-archived entries into the searchable shape.
+        const rows = this.db
+            .prepare(`SELECT id, key, value, tags, domain, topic, document_date
+         FROM memory_entries WHERE archived = 0 ORDER BY updated_at DESC LIMIT 500`)
+            .all();
+        const entries = rows.map((r) => ({
+            id: String(r["id"]),
+            content: `${String(r["key"] ?? "")} ${String(r["value"] ?? "")}`.trim(),
+            ...(r["tags"] ? { metadata: { tags: String(r["tags"]) } } : {}),
+            ...(r["document_date"] ? { timestamp: Number(r["document_date"]) } : {}),
+        }));
+        const retrievers = config?.retrievers ?? [createLexicalRetriever()];
+        const merged = {
+            retrievers,
+            ...(config?.reranker ? { reranker: config.reranker } : {}),
+            ...(config?.fusionK !== undefined ? { fusionK: config.fusionK } : {}),
+            ...(config?.topKBeforeRerank !== undefined
+                ? { topKBeforeRerank: config.topKBeforeRerank }
+                : {}),
+            topK: config?.topK ?? config?.limit ?? 10,
+            ...(config?.parallel !== undefined ? { parallel: config.parallel } : {}),
+        };
+        return hybridRetrieverSearch(query, entries, merged);
+    }
+    /**
+     * Phase 2 P1-M7: factory for a default lexical retriever. Thin
+     * convenience so callers can build a HybridRetrievalConfig without
+     * importing hybrid-retrieval directly.
+     */
+    createLexicalRetriever() {
+        return createLexicalRetriever();
+    }
+    /**
+     * Phase 2 P1-M7: factory for a default vector retriever backed by
+     * a caller-supplied embedding function.
+     */
+    createVectorRetriever(embed) {
+        return createVectorRetriever({ embed });
+    }
+    /**
+     * Phase 2 P1-M7: reranker used by the retriever-chain API when
+     * supplied. Kept as a pass-through (caller implements their own).
+     */
+    applyReranker(query, hits, reranker) {
+        return reranker.rerank(query, hits);
+    }
+    // ── Memory Freshness Scoring ───────────────────────────────
+    /**
+     * Compute the freshness-adjusted confidence for a memory entry.
+     * confidence = base_confidence * decay(age) * verification_boost
+     */
+    computeFreshness(entry) {
+        const base = entry.confidence ?? 1.0;
+        // Temporal decay: lose 1% per day, minimum 0.2
+        let ageDays = 0;
+        try {
+            const updatedTime = new Date(entry.updatedAt).getTime();
+            if (!isNaN(updatedTime)) {
+                ageDays = (Date.now() - updatedTime) / (1000 * 60 * 60 * 24);
+            }
+        }
+        catch {
+            /* default to 0 */
+        }
+        const decay = Math.max(0.2, 1.0 - ageDays * 0.01);
+        // Verified memories decay 3x slower
+        const verifiedBoost = entry.verified ? 1.0 : 0.7;
+        return base * decay * verifiedBoost;
+    }
+    // ── Contradiction Detection ────────────────────────────────
+    /**
+     * Check if a new memory contradicts existing entries.
+     * Uses keyword overlap + sentiment analysis to detect conflicts.
+     */
+    detectContradictions(key, value) {
+        const results = [];
+        const existing = this.search(key, 10);
+        for (const r of existing) {
+            // Skip same-value entries
+            if (r.entry.value === value)
+                continue;
+            // Check for direct contradiction keywords
+            const existingLower = r.entry.value.toLowerCase();
+            const newLower = value.toLowerCase();
+            // Pattern: "uses X" vs "uses Y" (for same subject)
+            const usesPatternExisting = existingLower.match(/uses?\s+(\w+)/);
+            const usesPatternNew = newLower.match(/uses?\s+(\w+)/);
+            if (usesPatternExisting && usesPatternNew && usesPatternExisting[1] !== usesPatternNew[1]) {
+                results.push({
+                    existingEntry: r.entry,
+                    newValue: value,
+                    conflictType: "direct",
+                    confidence: 0.8,
+                });
+                continue;
+            }
+            // Pattern: negation words that flip meaning
+            const negations = ["not", "never", "don't", "doesn't", "shouldn't", "disabled", "removed"];
+            for (const neg of negations) {
+                const existingHasNeg = existingLower.includes(neg);
+                const newHasNeg = newLower.includes(neg);
+                if (existingHasNeg !== newHasNeg && this.keywordOverlap(existingLower, newLower) > 0.5) {
+                    results.push({
+                        existingEntry: r.entry,
+                        newValue: value,
+                        conflictType: "indirect",
+                        confidence: 0.6,
+                    });
+                    break;
+                }
+            }
+        }
+        return results;
+    }
+    keywordOverlap(a, b) {
+        const wordsA = new Set(a.split(/\s+/).filter((w) => w.length > 3));
+        const wordsB = new Set(b.split(/\s+/).filter((w) => w.length > 3));
+        if (wordsA.size === 0 || wordsB.size === 0)
+            return 0;
+        let overlap = 0;
+        for (const w of wordsA) {
+            if (wordsB.has(w))
+                overlap++;
+        }
+        return overlap / Math.max(wordsA.size, wordsB.size);
+    }
+    // ── Provenance Logging ─────────────────────────────────────
+    logProvenance(entryId, action, oldValue, newValue, actor, reason) {
+        this.db
+            .prepare(`
+      INSERT INTO memory_provenance_log (id, entry_id, action, old_value, new_value, actor, reason)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(randomUUID(), entryId, action, oldValue, newValue, actor ?? null, reason ?? null);
+    }
+    getProvenance(entryId) {
+        return this.db
+            .prepare(`
+      SELECT * FROM memory_provenance_log WHERE entry_id = ? ORDER BY created_at DESC
+    `)
+            .all(entryId);
+    }
+    // ── Insert with Provenance ─────────────────────────────────
+    insertWithProvenance(entry, sourceType, sourceFile) {
+        // Check for contradictions before inserting
+        const contradictions = this.detectContradictions(entry.key, entry.value);
+        // Phase H Task 1: dual-timestamp derivation on the provenance path.
+        const derived = deriveIngestTimestamps(`${entry.key} ${entry.value}`);
+        const documentDate = entry.documentDate ?? derived.documentDate;
+        const eventDate = entry.eventDate ?? derived.eventDate;
+        const eventDateUncertaintyMs = entry.eventDateUncertaintyMs ?? derived.eventDateUncertaintyMs;
+        const eventDateSource = entry.eventDate !== undefined && entry.eventDateSource === undefined
+            ? "user-supplied"
+            : (entry.eventDateSource ?? derived.eventDateSource);
+        // Insert the entry with source metadata + dual timestamps.
+        // Phase 2 P1-M8 Fix A — see insert() above; mirror the same confidence
+        // column contract so the provenance path doesn't silently drop
+        // confidenceLevel/freshnessScore/verificationStatus.
+        const confidenceLevel = entry.confidenceLevel ?? entry.confidence ?? 0.5;
+        const freshnessScore = entry.freshnessScore ?? 1.0;
+        const verificationStatus = entry.verificationStatus ?? "unverified";
+        this.db
+            .prepare(`
+      INSERT INTO memory_entries (id, layer, block_type, key, value, session_id, verified, confidence, tags, source_type, source_file, document_date, event_date, event_date_uncertainty_ms, event_date_source, freshness_score, confidence_level, verification_status)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+            .run(entry.id, entry.layer, entry.blockType, entry.key, entry.value, entry.sessionId ?? null, entry.verified ? 1 : 0, entry.confidence ?? 1.0, entry.tags ?? "", sourceType, sourceFile ?? null, documentDate, eventDate, eventDateUncertaintyMs, eventDateSource, freshnessScore, confidenceLevel, verificationStatus);
+        // Generate and store local embedding
+        const embedding = this.generateLocalEmbedding(`${entry.key} ${entry.value}`);
+        this.storeEmbedding(entry.id, embedding);
+        // Log provenance
+        this.logProvenance(entry.id, "insert", null, entry.value, undefined, `source: ${sourceType}`);
+        return { contradictions };
+    }
+    // ── Memory Freshness + Provenance Verification ─────────────
+    /**
+     * Compute a freshness score for a memory entry using exponential decay.
+     * Score decays based on time since last update, with verified entries
+     * decaying 3x slower than unverified ones.
+     *
+     * Returns a value between 0 and 1.
+     */
+    computeFreshnessScore(entry) {
+        const HALF_LIFE_DAYS_UNVERIFIED = 30;
+        const HALF_LIFE_DAYS_VERIFIED = 90;
+        let ageDays = 0;
+        try {
+            const updatedTime = new Date(entry.updatedAt).getTime();
+            if (!isNaN(updatedTime)) {
+                ageDays = Math.max(0, (Date.now() - updatedTime) / (1000 * 60 * 60 * 24));
+            }
+        }
+        catch {
+            /* default to 0 */
+        }
+        const halfLife = entry.verified ? HALF_LIFE_DAYS_VERIFIED : HALF_LIFE_DAYS_UNVERIFIED;
+        // Exponential decay: score = e^(-lambda * t), where lambda = ln(2) / half_life
+        const lambda = Math.LN2 / halfLife;
+        return Math.max(0, Math.min(1, Math.exp(-lambda * ageDays)));
+    }
+    /**
+     * Verify a memory entry against the codebase by checking whether
+     * the source file (if any) still exists and the entry's content
+     * is still relevant. Updates verification status and freshness.
+     */
+    verifyMemoryAgainstCodebase(entryId, workspaceDir) {
+        const entry = this.getById(entryId);
+        if (!entry) {
+            return {
+                entryId,
+                previousStatus: "unverified",
+                newStatus: "unverified",
+                freshnessScore: 0,
+                confidenceLevel: 0,
+                reason: "Entry not found",
+            };
+        }
+        const previousStatus = entry.verificationStatus;
+        const freshness = this.computeFreshnessScore(entry);
+        let newStatus = "unverified";
+        let confidence = entry.confidenceLevel;
+        let reason = "";
+        // Check if source file still exists
+        if (entry.sourceFile) {
+            const fullPath = entry.sourceFile.startsWith("/")
+                ? entry.sourceFile
+                : join(workspaceDir, entry.sourceFile);
+            if (existsSync(fullPath)) {
+                // File exists -- read it to check if content is still relevant
+                try {
+                    const fileContent = readFileSync(fullPath, "utf-8");
+                    const keyWords = entry.key
+                        .toLowerCase()
+                        .split(/\s+/)
+                        .filter((w) => w.length > 3);
+                    const relevantWords = keyWords.filter((w) => fileContent.toLowerCase().includes(w));
+                    const relevanceRatio = keyWords.length > 0 ? relevantWords.length / keyWords.length : 0.5;
+                    if (relevanceRatio > 0.5) {
+                        newStatus = "verified";
+                        confidence = Math.min(1.0, 0.7 + relevanceRatio * 0.3);
+                        reason = `Source file exists, ${Math.round(relevanceRatio * 100)}% keyword match`;
+                    }
+                    else {
+                        newStatus = "stale";
+                        confidence = Math.max(0.1, relevanceRatio);
+                        reason = `Source file exists but content diverged (${Math.round(relevanceRatio * 100)}% match)`;
+                    }
+                }
+                catch {
+                    newStatus = "stale";
+                    confidence = 0.3;
+                    reason = "Source file exists but unreadable";
+                }
+            }
+            else {
+                newStatus = "stale";
+                confidence = 0.1;
+                reason = "Source file no longer exists";
+            }
+        }
+        else {
+            // No source file -- check contradictions
+            const contradictions = this.detectContradictions(entry.key, entry.value);
+            if (contradictions.length > 0) {
+                newStatus = "conflicting";
+                confidence = Math.max(0.1, confidence * 0.5);
+                reason = `${contradictions.length} conflicting entries found`;
+            }
+            else if (freshness > 0.7) {
+                newStatus = "verified";
+                confidence = Math.min(1.0, confidence + 0.1);
+                reason = "No contradictions, still fresh";
+            }
+            else {
+                newStatus = "stale";
+                confidence = freshness;
+                reason = `No source file, freshness decayed to ${(freshness * 100).toFixed(0)}%`;
+            }
+        }
+        // Persist the updated verification state
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`
+      UPDATE memory_entries
+      SET freshness_score = ?,
+          confidence_level = ?,
+          last_verified_at = ?,
+          verification_status = ?,
+          updated_at = datetime('now')
+      WHERE id = ?
+    `)
+            .run(freshness, confidence, now, newStatus, entryId);
+        // Log provenance for the verification
+        this.logProvenance(entryId, "verify_against_codebase", previousStatus, newStatus, "system", reason);
+        return {
+            entryId,
+            previousStatus,
+            newStatus,
+            freshnessScore: freshness,
+            confidenceLevel: confidence,
+            reason,
+        };
+    }
+    /**
+     * Batch-refresh freshness scores for all non-archived entries.
+     * Returns the number of entries updated.
+     */
+    refreshAllFreshnessScores() {
+        const rows = this.db
+            .prepare(`
+      SELECT id, updated_at, verified, confidence FROM memory_entries WHERE archived = 0
+    `)
+            .all();
+        let updated = 0;
+        for (const row of rows) {
+            const entry = this.rowToEntry(row);
+            const freshness = this.computeFreshnessScore(entry);
+            const currentFreshness = row["freshness_score"] ?? 1.0;
+            // Only update if the score has changed meaningfully
+            if (Math.abs(freshness - currentFreshness) > 0.01) {
+                this.db
+                    .prepare(`
+          UPDATE memory_entries SET freshness_score = ? WHERE id = ?
+        `)
+                    .run(freshness, row["id"]);
+                updated++;
+            }
+        }
+        return updated;
+    }
+    /**
+     * Get entries that need verification (stale or unverified with low freshness).
+     */
+    getEntriesNeedingVerification(limit = 20) {
+        const rows = this.db
+            .prepare(`
+      SELECT * FROM memory_entries
+      WHERE archived = 0
+        AND (verification_status IN ('stale', 'unverified', 'conflicting')
+             OR freshness_score < 0.5)
+      ORDER BY freshness_score ASC
+      LIMIT ?
+    `)
+            .all(limit);
+        return rows.map((r) => this.rowToEntry(r));
+    }
+    /**
+     * Delete auto_capture entries older than the retention window (S1-14).
+     *
+     * auto_capture logs every tool call's input/output — identical growth
+     * profile to the audit trail. Pair a call to this with
+     * AuditTrail.pruneOlderThan() on a daemon cron to keep
+     * `~/.wotann/memory.db` bounded.
+     *
+     * Returns the number of rows removed. Idempotent.
+     */
+    pruneAutoCaptures(days = 30) {
+        const cutoff = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+        const info = this.db.prepare("DELETE FROM auto_capture WHERE created_at < ?").run(cutoff);
+        return Number(info.changes);
+    }
+    // ── Incremental Indexer (Phase 2 P1-M7) ─────────────────────
+    /**
+     * Phase 2 P1-M7: file-indexing helpers wired into MemoryStore.
+     *
+     * The underlying IncrementalIndexer persists a SHA-per-file cache to
+     * `~/.wotann/index-cache.json` so repeat indexing runs only re-read
+     * files whose content actually changed. A lazy singleton keeps the
+     * cache in memory for the store's lifetime.
+     */
+    incrementalIndexer = null;
+    getIncrementalIndexer(options) {
+        if (!this.incrementalIndexer) {
+            this.incrementalIndexer = new IncrementalIndexer(options ?? {});
+        }
+        return this.incrementalIndexer;
+    }
+    /**
+     * Return only the paths that need re-indexing (new or SHA-changed).
+     * First call loads the on-disk cache. Safe to call repeatedly.
+     */
+    async getStaleFiles(paths, options) {
+        const indexer = this.getIncrementalIndexer(options);
+        await indexer.load();
+        return indexer.getStaleFiles(paths);
+    }
+    /**
+     * Record that a file has been indexed. Content-SHA is computed from
+     * the supplied text so callers who already have the content in
+     * memory don't pay an extra disk read.
+     */
+    async markFileIndexed(path, content, chunksCount, options) {
+        const indexer = this.getIncrementalIndexer(options);
+        await indexer.load();
+        const sha = computeContentSha(content);
+        indexer.markIndexed(path, sha, chunksCount);
+        await indexer.save();
+    }
+    /** Forget a path — used when a file is deleted. Persists immediately. */
+    async forgetFileIndex(path, options) {
+        const indexer = this.getIncrementalIndexer(options);
+        await indexer.load();
+        const removed = indexer.forget(path);
+        if (removed)
+            await indexer.save();
+        return removed;
+    }
+    /** Stats on the in-memory index cache. */
+    async getFileIndexStats(options) {
+        const indexer = this.getIncrementalIndexer(options);
+        await indexer.load();
+        return indexer.stats();
+    }
+    // ── Typed Relationships (Phase H Task 2) ───────────────────
+    /** Persist one typed relationship. Idempotent on id. */
+    addRelationship(rel) {
+        this.db
+            .prepare(`INSERT OR REPLACE INTO memory_relationships
+         (id, from_id, to_id, kind, confidence, rationale, invalidated_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(rel.id, rel.fromId, rel.toId, rel.kind, rel.confidence, rel.rationale ?? null, null, rel.createdAt);
+    }
+    /** Bulk-persist relationships in a single transaction. */
+    addRelationships(rels) {
+        if (rels.length === 0)
+            return 0;
+        const tx = this.db.transaction((items) => {
+            for (const rel of items)
+                this.addRelationship(rel);
+        });
+        tx(rels);
+        return rels.length;
+    }
+    /**
+     * Mark a relationship as invalidated. Used by
+     * knowledge-update-dynamics when a successor supersedes a
+     * predecessor — the predecessor's outbound non-updates edges are
+     * stamped so readers can distinguish active from historical edges.
+     */
+    invalidateRelationship(id, atMs = Date.now()) {
+        const info = this.db
+            .prepare(`UPDATE memory_relationships SET invalidated_at = ? WHERE id = ? AND invalidated_at IS NULL`)
+            .run(atMs, id);
+        return Number(info.changes) > 0;
+    }
+    /** Fetch all relationships touching a given memory_entries id. */
+    getRelationshipsForEntry(entryId, options) {
+        const includeInvalidated = options?.includeInvalidated ?? false;
+        const conditions = ["(from_id = ? OR to_id = ?)"];
+        const params = [entryId, entryId];
+        if (options?.kind) {
+            conditions.push("kind = ?");
+            params.push(options.kind);
+        }
+        if (!includeInvalidated)
+            conditions.push("invalidated_at IS NULL");
+        const rows = this.db
+            .prepare(`SELECT id, from_id, to_id, kind, confidence, rationale, created_at
+         FROM memory_relationships
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY created_at DESC`)
+            .all(...params);
+        return rows.map((r) => ({
+            id: r["id"],
+            fromId: r["from_id"],
+            toId: r["to_id"],
+            kind: r["kind"],
+            confidence: r["confidence"] ?? 0.5,
+            createdAt: r["created_at"] ?? 0,
+            ...(r["rationale"] ? { rationale: r["rationale"] } : {}),
+        }));
+    }
+    /** All relationships — used by resolveLatest walkers + tests. */
+    getAllRelationships(options) {
+        const includeInvalidated = options?.includeInvalidated ?? false;
+        const sql = includeInvalidated
+            ? `SELECT id, from_id, to_id, kind, confidence, rationale, created_at FROM memory_relationships ORDER BY created_at DESC`
+            : `SELECT id, from_id, to_id, kind, confidence, rationale, created_at FROM memory_relationships WHERE invalidated_at IS NULL ORDER BY created_at DESC`;
+        const rows = this.db.prepare(sql).all();
+        return rows.map((r) => ({
+            id: r["id"],
+            fromId: r["from_id"],
+            toId: r["to_id"],
+            kind: r["kind"],
+            confidence: r["confidence"] ?? 0.5,
+            createdAt: r["created_at"] ?? 0,
+            ...(r["rationale"] ? { rationale: r["rationale"] } : {}),
+        }));
+    }
+    // ── Phase 2 P1-M6: retrieval-mode dispatcher ─────────────────
+    //
+    // Cognee exposes a menu of ~14 retrieval modes. WOTANN owns 2 native
+    // retrievers (FTS5 search, hybrid TEMPR) plus 10 narrow functions in
+    // extended-search-types.ts. P1-M6 adds 12 more single-axis modes and
+    // exposes them via a registry. `searchWithMode` is the store-level
+    // dispatch entry: callers pass a mode name + options, we route
+    // through the registry and inject a RetrievalContext pre-wired with
+    // this store.
+    //
+    // Quality bar #3 (sibling-site scan): the registry is lazily
+    // allocated — no cost to callers that never use a mode.
+    retrievalRegistrySlot = null;
+    getRetrievalRegistry() {
+        if (this.retrievalRegistrySlot)
+            return this.retrievalRegistrySlot;
+        this.retrievalRegistrySlot = createDefaultRetrievalRegistry();
+        return this.retrievalRegistrySlot;
+    }
+    /**
+     * Register a custom retrieval mode on this store's registry. Callers
+     * that want a custom mode (e.g. a domain-specific reranker) can push
+     * it in here and then dispatch via `searchWithMode`.
+     */
+    registerRetrievalMode(mode) {
+        this.getRetrievalRegistry().register(mode);
+    }
+    /** List every retrieval mode name available on this store. */
+    listRetrievalModes() {
+        return this.getRetrievalRegistry()
+            .list()
+            .map((m) => m.name);
+    }
+    /**
+     * Dispatch a retrieval mode by name. When the mode is not
+     * registered, returns an empty result with an "unknown-mode"
+     * scoring note rather than throwing. This keeps callers in callback
+     * chains from needing to guard every dispatch.
+     */
+    async searchWithMode(modeName, query, opts) {
+        const registry = this.getRetrievalRegistry();
+        const mode = registry.get(modeName);
+        if (!mode) {
+            return {
+                mode: modeName,
+                results: [],
+                scoring: {
+                    method: "unknown-mode",
+                    isHeuristic: true,
+                    notes: `mode "${modeName}" is not registered`,
+                },
+            };
+        }
+        const ctx = { store: this };
+        return mode.search(ctx, query, opts);
+    }
+    /**
+     * V9 T14.2 — Register opt-in heavy / experimental retrieval
+     * strategies onto this store's registry. Default-OFF: callers must
+     * pass each flag explicitly. Each strategy delegates to a pure
+     * orphan module (asmr-voter / community-detection / persona-tree)
+     * and surfaces honest fallback semantics when its prerequisites
+     * (entry pool, edge graph, etc.) aren't available.
+     *
+     * Returns the names registered so the caller can introspect.
+     */
+    registerOptionalStrategies(opts) {
+        const added = [];
+        const store = this;
+        if (opts.asmrVoter === true) {
+            const asmrMode = {
+                name: "asmr-voter",
+                description: "Reciprocal-rank-fusion ensemble: run N base retrievers and majority-vote the top-K. Off by default; opt-in heavy retrieval.",
+                search: async (_ctx, query, modeOpts) => {
+                    const limit = Math.max(1, modeOpts?.limit ?? 10);
+                    // Default ensemble: re-use the store's own search path twice
+                    // so the wire is exercised even without a custom retriever
+                    // panel. Callers that need real diversity inject specs via
+                    // modeOpts.params.retrievers.
+                    const params = modeOpts?.params ?? {};
+                    const customRetrievers = params
+                        .retrievers;
+                    const retrievers = customRetrievers ?? [
+                        {
+                            name: "fts-primary",
+                            retriever: async (q) => store.search(q, limit * 2),
+                        },
+                        {
+                            name: "fts-secondary",
+                            retriever: async (q) => store.search(q, limit),
+                        },
+                    ];
+                    const vote = await runAsmrVoter(query, retrievers, { topK: limit });
+                    return {
+                        mode: "asmr-voter",
+                        results: vote.hits.map((h) => ({
+                            id: h.entry.id,
+                            content: h.entry.value,
+                            score: h.fusedScore,
+                            reason: `RRF across ${Object.keys(h.ranks).length} retrievers`,
+                            metadata: {
+                                ranks: h.ranks,
+                                hasPartialFailure: vote.hasPartialFailure,
+                            },
+                        })),
+                        scoring: {
+                            method: "rrf-ensemble",
+                            isHeuristic: vote.hasPartialFailure,
+                            ...(vote.hasPartialFailure
+                                ? { notes: "one or more retrievers failed; results degraded" }
+                                : {}),
+                        },
+                    };
+                },
+            };
+            this.registerRetrievalMode(asmrMode);
+            added.push(asmrMode.name);
+        }
+        if (opts.communityDetection === true) {
+            const cdMode = {
+                name: "community-detection",
+                description: "Louvain community detection over the bi-temporal knowledge graph; pulls all members of the community a query-matched entity belongs to. Off by default.",
+                search: async (ctx, query, modeOpts) => {
+                    const limit = Math.max(1, modeOpts?.limit ?? 10);
+                    const edges = ctx.edges;
+                    if (!edges || edges.length === 0) {
+                        // Honest fallback: no graph, no community pull-in. Still
+                        // surface the FTS hits so the mode never returns empty
+                        // when the store has matches.
+                        const fts = store.search(query, limit);
+                        return {
+                            mode: "community-detection",
+                            results: fts.map((r) => ({
+                                id: r.entry.id,
+                                content: r.entry.value,
+                                score: r.score,
+                                reason: "fts-only (no graph edges injected)",
+                            })),
+                            scoring: {
+                                method: "louvain-fallback-fts",
+                                isHeuristic: true,
+                                notes: "no edges in RetrievalContext; community detection skipped",
+                            },
+                        };
+                    }
+                    // The orphan helper takes BiTemporalEdge[]; the registry
+                    // ctx.edges is a lighter shape (RetrievalEdge). Adapt.
+                    const adaptedEdges = edges.map((e, i) => ({
+                        id: `ctx-edge-${i}`,
+                        sourceId: e.fromId,
+                        targetId: e.toId,
+                        relation: e.relation ?? "related",
+                        weight: e.weight ?? 1,
+                        validFrom: new Date(0).toISOString(),
+                        validTo: null,
+                        recordedFrom: new Date(0).toISOString(),
+                        recordedTo: null,
+                    }));
+                    const report = detectCommunities(adaptedEdges);
+                    const fts = store.search(query, limit);
+                    // Pull in community siblings of the top FTS hit to broaden
+                    // recall — this is the actual "community detection" boost.
+                    const top = fts[0];
+                    const siblings = top ? communityOf(report, top.entry.id) : null;
+                    return {
+                        mode: "community-detection",
+                        results: fts.map((r) => ({
+                            id: r.entry.id,
+                            content: r.entry.value,
+                            score: r.score,
+                            reason: siblings !== null ? `community ${siblings}` : "fts-hit",
+                            metadata: {
+                                modularity: report.modularity,
+                                communityCount: report.communities.length,
+                            },
+                        })),
+                        scoring: {
+                            method: "louvain",
+                            isHeuristic: false,
+                            notes: `${report.communities.length} communities, modularity=${report.modularity.toFixed(3)}`,
+                        },
+                    };
+                },
+            };
+            this.registerRetrievalMode(cdMode);
+            added.push(cdMode.name);
+        }
+        if (opts.personaTree === true) {
+            const ptMode = {
+                name: "persona-tree",
+                description: "Hierarchical persona-tree retrieval: groups memories into topic/trait/persona levels then surfaces top entries from the matching subtree. Off by default.",
+                search: async (_ctx, query, modeOpts) => {
+                    const limit = Math.max(1, modeOpts?.limit ?? 10);
+                    // Source entries: prefer ctx.entries when injected; otherwise
+                    // go through FTS so we never crash on empty stores.
+                    const ftsHits = store.search(query, limit * 4);
+                    if (ftsHits.length === 0) {
+                        return {
+                            mode: "persona-tree",
+                            results: [],
+                            scoring: {
+                                method: "tree-walk",
+                                isHeuristic: true,
+                                notes: "no matching memories",
+                            },
+                        };
+                    }
+                    const tree = buildPersonaTree(ftsHits.map((h) => h.entry));
+                    // Walk the tree to find leaves whose memoryId is in the FTS
+                    // hit set, ordered by tree-level (level-0 leaves first).
+                    const orderedIds = [];
+                    walkPersonaTree(tree, (node) => {
+                        if (node.level === 0 && node.memoryId) {
+                            orderedIds.push(node.memoryId);
+                        }
+                    });
+                    const ftsById = new Map(ftsHits.map((h) => [h.entry.id, h]));
+                    const ranked = orderedIds
+                        .map((id) => ftsById.get(id))
+                        .filter((h) => h !== undefined)
+                        .slice(0, limit);
+                    return {
+                        mode: "persona-tree",
+                        results: ranked.map((r) => ({
+                            id: r.entry.id,
+                            content: r.entry.value,
+                            score: r.score,
+                            reason: "persona-tree leaf",
+                            metadata: {
+                                totalMemories: tree.totalMemories,
+                                builtAt: tree.builtAt,
+                            },
+                        })),
+                        scoring: {
+                            method: "tree-walk",
+                            isHeuristic: false,
+                            notes: `tree built from ${tree.totalMemories} memories`,
+                        },
+                    };
+                },
+            };
+            this.registerRetrievalMode(ptMode);
+            added.push(ptMode.name);
+        }
+        return added;
+    }
+    close() {
+        this.db.close();
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────
+/**
+ * Return the canonical name field for an entity. Handles per-type
+ * name fields: `person.name`, `project.name`, `file.path`,
+ * `concept.name`, `event.name`, `goal.name`, `skill.name`,
+ * `tool.name`.
+ */
+function entityNameOf(entity) {
+    if (entity.type === "file")
+        return entity.path;
+    return entity.name;
+}
+/**
+ * Map a memvid category string onto a valid MemoryBlockType. Unknown
+ * categories fall back to `reference`.
+ */
+function blockTypeFromMemvid(category) {
+    const valid = [
+        "user",
+        "feedback",
+        "project",
+        "reference",
+        "cases",
+        "patterns",
+        "decisions",
+        "issues",
+    ];
+    return valid.includes(category)
+        ? category
+        : "reference";
+}
+/**
+ * Map a knowledge_edges row onto a BiTemporalEdge. Legacy rows that
+ * predate the P1-M5 migration may have null/empty recorded_from — fall
+ * back to created_at so the consumer always gets a populated axis.
+ */
+function rowToBiTemporalEdge(row) {
+    const id = row["id"];
+    const sourceId = row["source_id"];
+    const targetId = row["target_id"];
+    const relation = row["relation"];
+    const weight = typeof row["weight"] === "number" ? row["weight"] : 1.0;
+    const createdAt = row["created_at"];
+    const validFromRaw = row["valid_from"];
+    const recordedFromRaw = row["recorded_from"];
+    return {
+        id,
+        sourceId,
+        targetId,
+        relation,
+        weight,
+        validFrom: validFromRaw && validFromRaw.length > 0
+            ? validFromRaw
+            : (createdAt ?? new Date(0).toISOString()),
+        validTo: row["valid_to"] ?? null,
+        recordedFrom: recordedFromRaw && recordedFromRaw.length > 0
+            ? recordedFromRaw
+            : (createdAt ?? new Date(0).toISOString()),
+        recordedTo: row["recorded_to"] ?? null,
+    };
+}
+/**
+ * Minimal FTS5 sanitizer — strips punctuation to tokens and joins with
+ * OR. Returns empty string when no valid tokens survive. Used by the
+ * benchmark adapter so natural-language questions (which contain ?, :,
+ * quotes, etc.) don't crash FTS5.
+ */
+// ── TEMPR helpers (Phase 2 P1-M4) ─────────────────────
+/** Cosine similarity for TEMPR vector channel. Zero-safe. */
+function cosineSimTempr(a, b) {
+    if (a.length === 0 || b.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * Heuristic entity extraction from a natural-language query.
+ * Returns capitalized multi-word sequences, quoted phrases, and
+ * standalone capitalized words of length >= 2. The LLM-based
+ * extraction is the real thing; this channel bootstrap is a proxy
+ * that catches common proper nouns with zero dep.
+ */
+function extractQueryEntities(query) {
+    const tokens = new Set();
+    // Quoted phrases first — "New York", 'Alice Bob'
+    const quoted = query.match(/["']([^"']+)["']/g);
+    if (quoted) {
+        for (const q of quoted)
+            tokens.add(q.replace(/["']/g, "").trim());
+    }
+    // Multi-word capitalized sequences — "New York City"
+    const caps = query.match(/\b[A-Z][a-zA-Z]+(?:\s+[A-Z][a-zA-Z]+)+\b/g);
+    if (caps) {
+        for (const c of caps)
+            tokens.add(c);
+    }
+    // Standalone capitalized words — "Alice"
+    const solo = query.match(/\b[A-Z][a-zA-Z]{1,}\b/g);
+    if (solo) {
+        for (const s of solo)
+            tokens.add(s);
+    }
+    return [...tokens].filter((t) => t.length >= 2).slice(0, 8);
+}
+/**
+ * Sanitize a proper name for use in an FTS5 MATCH query.
+ * Strips control characters and wraps in double quotes so FTS5
+ * treats it as a phrase. Returns empty string when the name is
+ * empty after sanitization.
+ */
+function fts5QuoteName(name) {
+    const cleaned = name.replace(/["\\]/g, " ").replace(/\s+/g, " ").trim();
+    if (cleaned.length === 0)
+        return "";
+    return `"${cleaned}"`;
+}
+function sanitizeForFts5(query) {
+    const tokens = query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter((t) => t.length >= 2);
+    const unique = Array.from(new Set(tokens));
+    if (unique.length === 0)
+        return "";
+    return unique.slice(0, 12).join(" OR ");
+}
+let agentFactsModuleCache = null;
+function getAgentFactsModule() {
+    if (agentFactsModuleCache === null) {
+        throw new Error("MemoryStore.recordAgentFact/retrieveAgentFacts: agent-facts module not bootstrapped; " +
+            "import src/memory/agent-facts.js at composition-root to register the wiring.");
+    }
+    return agentFactsModuleCache;
+}
+/**
+ * Bootstrap the agent-facts module reference used by
+ * `MemoryStore.recordAgentFact` / `MemoryStore.retrieveAgentFacts`.
+ *
+ * Called automatically by `agent-facts.ts` at import time so any
+ * consumer who imports either file gets the wiring transparently.
+ * Exposed for testability — tests can inject a stub module.
+ */
+export function setAgentFactsModule(mod) {
+    agentFactsModuleCache = mod;
+}
+//# sourceMappingURL=store.js.map