merge(F4): vector store (sqlite-vec + hybrid RRF)

src/lib/memory/vectorStore.ts

@@ -0,0 +1,365 @@
+// Raw SQL allowed: sqlite-vec virtual table DDL is dynamic (dim varies). See plan 21 §D5.
+// Hard Rule #5 exception: sqlite-vec VIRTUAL TABLE cannot be created via src/lib/db/ domain modules
+// because the table dimension (N in FLOAT[N]) depends on the active embedding model at runtime.
+//
+// NOTE on rowid: vec0 v0.1.9 requires BigInt when inserting explicit rowid values.
+// The vec_memories table uses the *same* rowid space as the `memories` table to enable
+// a simple JOIN (m.rowid = v.rowid). We do NOT use a named primary-key column because
+// vec0 rejects numeric (non-BigInt) values for named PKs in this version.
+
+import { createRequire } from "module";
+import type { EmbeddingResolution } from "./embedding/types";
+import {
+  getMemoryVecMeta,
+  setMemoryVecMeta,
+  markAllMemoriesNeedReindex,
+  countMemoryReindexPending,
+} from "../localDb";
+import { getDbInstance } from "../db/core";
+import { logger } from "../../../open-sse/utils/logger.ts";
+import { sanitizeErrorMessage } from "../../../open-sse/utils/error.ts";
+
+const _require = createRequire(import.meta.url);
+
+const log = logger("VECTOR_STORE");
+
+// ──────────────── Types ────────────────
+
+export interface VectorSearchHit {
+  memoryId: string; // UUID (same as memories.id)
+  distance: number; // L2 distance — lower = more similar
+  score: number; // 1 / (1 + distance) — higher = better
+}
+
+export interface HybridRrfHit {
+  memoryId: string;
+  vecRank: number | null; // null if not from vector search
+  ftsRank: number | null; // null if not from FTS5
+  rrfScore: number; // RRF score (k=60 default)
+  vecDistance: number | null;
+  ftsScore: number | null;
+}
+
+export interface VectorStore {
+  /** Ensure schema (sqlite-vec loaded, vec_memories created if needed, dim aligned). Idempotent. */
+  ensureReady(resolution: EmbeddingResolution): Promise<{ ready: boolean; reason: string }>;
+  /** Insert/update vector for a memory. */
+  upsertVector(memoryId: string, vector: Float32Array): Promise<void>;
+  /** Delete vector for a memory (no-op if not present). */
+  deleteVector(memoryId: string): Promise<void>;
+  /** KNN brute-force search. Returns top-K hits ordered by distance ASC. */
+  searchVector(vector: Float32Array, topK: number, apiKeyId?: string): Promise<VectorSearchHit[]>;
+  /** Hybrid RRF search (FTS5 + vector fused via Reciprocal Rank Fusion, k=60). */
+  searchHybrid(
+    vector: Float32Array,
+    queryText: string,
+    topK: number,
+    apiKeyId?: string,
+  ): Promise<HybridRrfHit[]>;
+  /** Stats for UI Engine status. */
+  stats(): Promise<{
+    rowCount: number;
+    needsReindex: number;
+    activeDim: number | null;
+    signature: string | null;
+  }>;
+  /** Drop and recreate vec_memories (on signature change). Marks all memories needs_reindex=1. */
+  resetForSignature(signature: string, dim: number): Promise<void>;
+}
+
+// ──────────────── Constants ────────────────
+
+const RRF_K = Number(process.env["MEMORY_RRF_K"] ?? 60);
+const TOP_K_DEFAULT = Number(process.env["MEMORY_VEC_TOP_K"] ?? 20);
+
+// ──────────────── Helpers ────────────────
+
+/**
+ * Encode a Float32Array as a Buffer of little-endian bytes.
+ * sqlite-vec accepts this format for FLOAT[] column values.
+ */
+function encodeVector(v: Float32Array): Buffer {
+  return Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+
+// ──────────────── Implementation ────────────────
+
+class VectorStoreImpl implements VectorStore {
+  async ensureReady(resolution: EmbeddingResolution): Promise<{ ready: boolean; reason: string }> {
+    const db = getDbInstance();
+    const meta = getMemoryVecMeta();
+
+    // Signature changed (or first time with a known dim) → recreate with new dim.
+    if (resolution.dimensions !== null && resolution.signature !== meta.embeddingSignature) {
+      await this.resetForSignature(resolution.signature, resolution.dimensions);
+      return { ready: true, reason: `vec_memories recreated with dim=${resolution.dimensions}` };
+    }
+
+    // Already marked loaded → idempotent no-op.
+    if (meta.vecLoaded) {
+      return { ready: true, reason: "vec_memories already ready" };
+    }
+
+    // Not yet loaded but we have a dim — create the table now.
+    if (resolution.dimensions !== null) {
+      const dim = meta.activeDim ?? resolution.dimensions;
+      try {
+        db.exec(
+          `CREATE VIRTUAL TABLE IF NOT EXISTS vec_memories USING vec0(embedding FLOAT[${dim}])`,
+        );
+        setMemoryVecMeta({ vecLoaded: true, activeDim: dim });
+        return { ready: true, reason: `vec_memories created with dim=${dim}` };
+      } catch (err: unknown) {
+        const msg = sanitizeErrorMessage(err instanceof Error ? err.message : String(err));
+        return { ready: false, reason: `failed to create vec_memories: ${msg}` };
+      }
+    }
+
+    return { ready: false, reason: "no dimensions available yet (lazy probe pending)" };
+  }
+
+  async upsertVector(memoryId: string, vector: Float32Array): Promise<void> {
+    const db = getDbInstance();
+
+    // Map UUID memoryId → INTEGER rowid (the rowid is used as the FK into vec_memories).
+    const row = db.prepare("SELECT rowid FROM memories WHERE id = ?").get(memoryId) as
+      | { rowid: number }
+      | undefined;
+
+    if (!row) {
+      throw new Error(`memory not found: ${memoryId}`);
+    }
+
+    // vec0 v0.1.9 requires BigInt for explicit rowid insertion — plain numbers are rejected.
+    // INSERT OR REPLACE is not supported by vec0 — use DELETE + INSERT for upsert semantics.
+    db.prepare("DELETE FROM vec_memories WHERE rowid = ?").run(BigInt(row.rowid));
+    db.prepare("INSERT INTO vec_memories(rowid, embedding) VALUES (?, ?)").run(
+      BigInt(row.rowid),
+      encodeVector(vector),
+    );
+  }
+
+  async deleteVector(memoryId: string): Promise<void> {
+    const db = getDbInstance();
+    db.prepare(
+      "DELETE FROM vec_memories WHERE rowid = (SELECT rowid FROM memories WHERE id = ?)",
+    ).run(memoryId);
+  }
+
+  async searchVector(
+    vector: Float32Array,
+    topK: number,
+    apiKeyId?: string,
+  ): Promise<VectorSearchHit[]> {
+    const db = getDbInstance();
+    const k = topK > 0 ? topK : TOP_K_DEFAULT;
+
+    const rows = db
+      .prepare(
+        `SELECT m.id AS memory_id, v.distance
+         FROM vec_memories v
+         JOIN memories m ON m.rowid = v.rowid
+         WHERE v.embedding MATCH ?
+           AND ($apiKeyId IS NULL OR m.api_key_id = $apiKeyId)
+           AND k = ?
+         ORDER BY v.distance ASC`,
+      )
+      .all(encodeVector(vector), { apiKeyId: apiKeyId ?? null }, k) as Array<{
+        memory_id: string;
+        distance: number;
+      }>;
+
+    return rows.map((r) => ({
+      memoryId: r.memory_id,
+      distance: r.distance,
+      score: 1 / (1 + r.distance),
+    }));
+  }
+
+  async searchHybrid(
+    vector: Float32Array,
+    queryText: string,
+    topK: number,
+    apiKeyId?: string,
+  ): Promise<HybridRrfHit[]> {
+    const db = getDbInstance();
+    const k = topK > 0 ? topK : TOP_K_DEFAULT;
+    const rrfK = RRF_K;
+
+    // SQLite does not support FULL OUTER JOIN — use UNION ALL + GROUP BY (RRF recipe).
+    // Reference: https://alexgarcia.xyz/blog/2024/sqlite-vec-hybrid-search/
+    const rows = db
+      .prepare(
+        `WITH vec_results AS (
+           SELECT m.id AS memory_id,
+                  ROW_NUMBER() OVER (ORDER BY v.distance ASC) AS vec_rank,
+                  v.distance AS vec_distance
+           FROM vec_memories v
+           JOIN memories m ON m.rowid = v.rowid
+           WHERE v.embedding MATCH ?
+             AND ($apiKeyId IS NULL OR m.api_key_id = $apiKeyId)
+             AND k = ?
+         ),
+         fts_results AS (
+           SELECT m.id AS memory_id,
+                  ROW_NUMBER() OVER (ORDER BY fts.rank ASC) AS fts_rank,
+                  fts.rank AS fts_score
+           FROM memory_fts fts
+           JOIN memories m ON m.memory_id = fts.rowid
+           WHERE fts.memory_fts MATCH ?
+             AND ($apiKeyId IS NULL OR m.api_key_id = $apiKeyId)
+           LIMIT ?
+         ),
+         fused AS (
+           SELECT
+             memory_id,
+             MAX(vec_rank)      AS vec_rank,
+             MAX(fts_rank)      AS fts_rank,
+             MAX(vec_distance)  AS vec_distance,
+             MAX(fts_score)     AS fts_score,
+             SUM(rrf_contrib)   AS rrf_score
+           FROM (
+             SELECT memory_id, vec_rank, NULL AS fts_rank, vec_distance,
+                    NULL AS fts_score, 1.0 / (${rrfK} + vec_rank) AS rrf_contrib
+             FROM vec_results
+             UNION ALL
+             SELECT memory_id, NULL, fts_rank, NULL, fts_score, 1.0 / (${rrfK} + fts_rank)
+             FROM fts_results
+           )
+           GROUP BY memory_id
+         )
+         SELECT memory_id, vec_rank, fts_rank, vec_distance, fts_score, rrf_score
+         FROM fused
+         ORDER BY rrf_score DESC
+         LIMIT ?`,
+      )
+      .all(
+        encodeVector(vector),
+        { apiKeyId: apiKeyId ?? null },
+        k,
+        queryText,
+        k,
+        k,
+      ) as Array<{
+        memory_id: string;
+        vec_rank: number | null;
+        fts_rank: number | null;
+        vec_distance: number | null;
+        fts_score: number | null;
+        rrf_score: number;
+      }>;
+
+    return rows.map((r) => ({
+      memoryId: r.memory_id,
+      vecRank: r.vec_rank,
+      ftsRank: r.fts_rank,
+      rrfScore: r.rrf_score,
+      vecDistance: r.vec_distance,
+      ftsScore: r.fts_score,
+    }));
+  }
+
+  async stats(): Promise<{
+    rowCount: number;
+    needsReindex: number;
+    activeDim: number | null;
+    signature: string | null;
+  }> {
+    let rowCount = 0;
+    try {
+      const db = getDbInstance();
+      const row = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as
+        | { cnt: number }
+        | undefined;
+      rowCount = row?.cnt ?? 0;
+    } catch {
+      // vec_memories may not exist yet — not an error, just 0 rows.
+      rowCount = 0;
+    }
+
+    const needsReindex = countMemoryReindexPending();
+    const meta = getMemoryVecMeta();
+
+    return {
+      rowCount,
+      needsReindex,
+      activeDim: meta.activeDim,
+      signature: meta.embeddingSignature,
+    };
+  }
+
+  async resetForSignature(signature: string, dim: number): Promise<void> {
+    const db = getDbInstance();
+
+    // DROP + CREATE is intentionally destructive — triggers lazy backfill via F5.
+    db.exec("DROP TABLE IF EXISTS vec_memories");
+    db.exec(`CREATE VIRTUAL TABLE vec_memories USING vec0(embedding FLOAT[${dim}])`);
+
+    markAllMemoriesNeedReindex();
+    setMemoryVecMeta({
+      activeDim: dim,
+      embeddingSignature: signature,
+      lastResetAt: new Date().toISOString(),
+      vecLoaded: true,
+    });
+  }
+}
+
+// ──────────────── Singleton ────────────────
+
+let _instance: VectorStore | null | undefined = undefined; // undefined = not yet attempted
+
+/**
+ * Singleton instance (lazy-initialized).
+ * Returns null if sqlite-vec is unavailable (e.g. WASM / cloud backend).
+ * Callers should degrade gracefully to FTS5 keyword search when this returns null.
+ */
+export function getVectorStore(): VectorStore | null {
+  if (_instance !== undefined) {
+    return _instance;
+  }
+
+  // Test seam: VECTOR_STORE_DISABLE_VEC=true forces null (simulates cloud/WASM environment).
+  if (process.env["VECTOR_STORE_DISABLE_VEC"] === "true") {
+    log.warn(
+      "VECTOR_STORE_DISABLE_VEC is set — sqlite-vec disabled. Degrading to FTS5 keyword search.",
+    );
+    _instance = null;
+    return null;
+  }
+
+  const db = getDbInstance();
+  const raw = db.raw as { loadExtension?: (path: string) => void } | null;
+
+  // sqlite-vec must be loaded as a native extension on the better-sqlite3 raw handle.
+  // The SqliteAdapter wrapper does not expose loadExtension directly.
+  if (!raw || typeof raw.loadExtension !== "function") {
+    log.warn(
+      "sqlite-vec not loaded: db driver does not support loadExtension (cloud/WASM backend). " +
+        "Degrading to FTS5 keyword search.",
+    );
+    _instance = null;
+    return null;
+  }
+
+  try {
+    const sqliteVec = _require("sqlite-vec") as { load: (db: unknown) => void };
+    sqliteVec.load(raw);
+    log.info("sqlite-vec loaded successfully");
+    _instance = new VectorStoreImpl();
+  } catch (err: unknown) {
+    const safeMsg = sanitizeErrorMessage(err instanceof Error ? err.message : String(err));
+    log.warn(`sqlite-vec failed to load: ${safeMsg}. Degrading to FTS5 keyword search.`);
+    _instance = null;
+  }
+
+  return _instance;
+}
+
+/**
+ * Reset the singleton cache (for tests only — allows re-initialization between tests).
+ * @internal
+ */
+export function _resetVectorStoreSingleton(): void {
+  _instance = undefined;
+}

tests/unit/memory-vectorstore-crud.test.ts

@@ -0,0 +1,268 @@
+/**
+ * tests/unit/memory-vectorstore-crud.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for upsertVector / searchVector / deleteVector:
+ *   - Insert 3 memories; upsertVector for each → COUNT=3.
+ *   - searchVector(query_vec, topK=2) returns 2 results ordered by distance ASC.
+ *   - searchVector with apiKeyId filters results.
+ *   - deleteVector removes the entry; COUNT=2.
+ *   - deleteVector for non-existent memoryId is no-op (no throw).
+ *   - upsertVector for non-existent memoryId throws.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mock } from "node:test";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-crud-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+
+const core = await import("../../src/lib/db/core.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+import type { EmbeddingResolution } from "../../src/lib/memory/embedding/types.ts";
+
+const DIM = 4;
+
+function makeResolution(): EmbeddingResolution {
+  return {
+    source: "remote",
+    model: "test/dim4",
+    dimensions: DIM,
+    signature: `test:dim4:${DIM}`,
+    reason: "test",
+  };
+}
+
+function makeVec(...values: number[]): Float32Array {
+  return new Float32Array(values);
+}
+
+function cleanup() {
+  mock.restoreAll();
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+function getStoreOrSkip(t: { skip: (msg: string) => void }): ReturnType<typeof getVectorStore> {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+  if (store === null) {
+    t.skip("sqlite-vec not available in this environment — skipping");
+    return null;
+  }
+  return store;
+}
+
+async function setupTable(store: NonNullable<ReturnType<typeof getVectorStore>>) {
+  const res = makeResolution();
+  await store.ensureReady(res);
+}
+
+function insertMemory(
+  db: ReturnType<typeof core.getDbInstance>,
+  id: string,
+  apiKeyId: string,
+  content: string,
+) {
+  db.prepare(
+    `INSERT INTO memories (id, api_key_id, type, key, content, created_at)
+     VALUES (?, ?, 'factual', ?, ?, datetime('now'))`,
+  ).run(id, apiKeyId, `key-${id}`, content);
+}
+
+// ──────────────── upsertVector + COUNT ────────────────
+
+test("upsertVector: inserts 3 vectors, vec_memories count = 3", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemory(db, "mem-a", "key1", "alpha");
+  insertMemory(db, "mem-b", "key1", "beta");
+  insertMemory(db, "mem-c", "key1", "gamma");
+
+  await store.upsertVector("mem-a", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-b", makeVec(0.0, 1.0, 0.0, 0.0));
+  await store.upsertVector("mem-c", makeVec(0.0, 0.0, 1.0, 0.0));
+
+  const cnt = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as { cnt: number };
+  assert.equal(cnt.cnt, 3, "should have 3 vectors after 3 upserts");
+});
+
+test("upsertVector: idempotent (re-insert same memory updates the vector)", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemory(db, "mem-a", "key1", "alpha");
+  await store.upsertVector("mem-a", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-a", makeVec(0.5, 0.5, 0.0, 0.0)); // re-insert
+
+  const cnt = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as { cnt: number };
+  assert.equal(cnt.cnt, 1, "re-inserting same memory_id should not create duplicates");
+});
+
+test("upsertVector: throws when memoryId does not exist in memories table", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  await setupTable(store);
+
+  await assert.rejects(
+    () => store.upsertVector("nonexistent-id", makeVec(1.0, 0.0, 0.0, 0.0)),
+    /memory not found/i,
+    "should throw when memoryId not found",
+  );
+});
+
+// ──────────────── searchVector ────────────────
+
+test("searchVector: returns topK=2 results ordered by distance ASC", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemory(db, "mem-a", "key1", "alpha");
+  insertMemory(db, "mem-b", "key1", "beta");
+  insertMemory(db, "mem-c", "key1", "gamma");
+
+  // Three vectors in different directions.
+  await store.upsertVector("mem-a", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-b", makeVec(0.0, 1.0, 0.0, 0.0));
+  await store.upsertVector("mem-c", makeVec(0.0, 0.0, 1.0, 0.0));
+
+  // Query similar to mem-a.
+  const query = makeVec(0.9, 0.1, 0.0, 0.0);
+  const hits = await store.searchVector(query, 2);
+
+  assert.equal(hits.length, 2, "should return topK=2 results");
+
+  // All hits should have valid structure.
+  for (const h of hits) {
+    assert.ok(typeof h.memoryId === "string");
+    assert.ok(typeof h.distance === "number");
+    assert.ok(typeof h.score === "number");
+  }
+
+  // Results should be ordered by distance ASC.
+  if (hits.length >= 2) {
+    assert.ok(
+      hits[0].distance <= hits[1].distance,
+      "results must be ordered by distance ASC (smaller = more similar)",
+    );
+  }
+
+  // mem-a should be closest to the query.
+  assert.equal(hits[0].memoryId, "mem-a", "mem-a should be the closest hit");
+});
+
+test("searchVector: score = 1/(1+distance) is always in (0, 1]", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemory(db, "mem-a", "key1", "alpha");
+  await store.upsertVector("mem-a", makeVec(1.0, 0.0, 0.0, 0.0));
+
+  const hits = await store.searchVector(makeVec(1.0, 0.0, 0.0, 0.0), 5);
+  assert.ok(hits.length >= 1);
+  for (const h of hits) {
+    assert.ok(h.score > 0 && h.score <= 1, `score ${h.score} must be in (0, 1]`);
+  }
+});
+
+test("searchVector: apiKeyId filter restricts results to matching api_key_id", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  // Two memories with different api_key_id.
+  insertMemory(db, "mem-key1", "key1", "key1 doc");
+  insertMemory(db, "mem-key2", "key2", "key2 doc");
+
+  await store.upsertVector("mem-key1", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-key2", makeVec(1.0, 0.0, 0.0, 0.0));
+
+  // Without filter: both should match.
+  const allHits = await store.searchVector(makeVec(1.0, 0.0, 0.0, 0.0), 10);
+  assert.equal(allHits.length, 2, "without apiKeyId filter, both should be returned");
+
+  // With filter for key1 only.
+  const key1Hits = await store.searchVector(makeVec(1.0, 0.0, 0.0, 0.0), 10, "key1");
+  assert.equal(key1Hits.length, 1, "with apiKeyId=key1, only key1 doc should be returned");
+  assert.equal(key1Hits[0].memoryId, "mem-key1");
+
+  // With filter for key2 only.
+  const key2Hits = await store.searchVector(makeVec(1.0, 0.0, 0.0, 0.0), 10, "key2");
+  assert.equal(key2Hits.length, 1, "with apiKeyId=key2, only key2 doc should be returned");
+  assert.equal(key2Hits[0].memoryId, "mem-key2");
+});
+
+// ──────────────── deleteVector ────────────────
+
+test("deleteVector: removes the vector from vec_memories", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemory(db, "mem-a", "key1", "alpha");
+  insertMemory(db, "mem-b", "key1", "beta");
+
+  await store.upsertVector("mem-a", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-b", makeVec(0.0, 1.0, 0.0, 0.0));
+
+  const before = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as { cnt: number };
+  assert.equal(before.cnt, 2);
+
+  await store.deleteVector("mem-a");
+
+  const after = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as { cnt: number };
+  assert.equal(after.cnt, 1, "count should decrease to 1 after delete");
+});
+
+test("deleteVector: no-op when memoryId does not exist (no throw)", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  await setupTable(store);
+
+  // Should not throw.
+  await assert.doesNotReject(
+    () => store.deleteVector("nonexistent-id"),
+    "deleteVector for non-existent id must be a no-op (not throw)",
+  );
+});

tests/unit/memory-vectorstore-ensure-ready.test.ts

@@ -0,0 +1,182 @@
+/**
+ * tests/unit/memory-vectorstore-ensure-ready.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for VectorStore.ensureReady():
+ *   - First call with signature "X" creates vec_memories with correct dim.
+ *   - Second call same signature is idempotent (no-op).
+ *   - Call with new signature "Y" drops + recreates and marks all memories needs_reindex=1.
+ *   - Returns {ready: false} when sqlite-vec is not available.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mock } from "node:test";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-ensure-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+
+const core = await import("../../src/lib/db/core.ts");
+const { getMemoryVecMeta } = await import("../../src/lib/db/memoryVec.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+import type { EmbeddingResolution } from "../../src/lib/memory/embedding/types.ts";
+
+function makeResolution(sig: string, dim: number): EmbeddingResolution {
+  return {
+    source: "remote",
+    model: "openai/text-embedding-3-small",
+    dimensions: dim,
+    signature: sig,
+    reason: "test",
+  };
+}
+
+function cleanup() {
+  mock.restoreAll();
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+// Helper: get VectorStore or skip if sqlite-vec is not available.
+function getStoreOrSkip(t: { skip: (msg: string) => void }): ReturnType<typeof getVectorStore> {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+  if (store === null) {
+    t.skip("sqlite-vec not available in this environment — skipping");
+    return null;
+  }
+  return store;
+}
+
+// ──────────────── Tests ────────────────
+
+test("ensureReady: first call creates vec_memories with correct dim", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  const res = makeResolution("openai:text-embedding-3-small:1536", 1536);
+
+  const result = await store.ensureReady(res);
+
+  assert.equal(result.ready, true, "should be ready after first ensureReady");
+
+  // Verify the virtual table was created.
+  const rows = db.prepare("SELECT COUNT(*) AS cnt FROM vec_memories").get() as { cnt: number };
+  assert.equal(rows.cnt, 0, "vec_memories should exist (empty after creation)");
+
+  // Verify meta was updated.
+  const meta = getMemoryVecMeta();
+  assert.equal(meta.embeddingSignature, "openai:text-embedding-3-small:1536");
+  assert.equal(meta.activeDim, 1536);
+  assert.equal(meta.vecLoaded, true);
+});
+
+test("ensureReady: second call with same signature is idempotent", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const res = makeResolution("openai:text-embedding-3-small:1536", 1536);
+
+  await store.ensureReady(res);
+
+  // Read meta after first call.
+  const meta1 = getMemoryVecMeta();
+
+  // Second call — should be no-op.
+  const result = await store.ensureReady(res);
+
+  assert.equal(result.ready, true);
+  const meta2 = getMemoryVecMeta();
+
+  // Meta should not have changed (lastResetAt remains the same).
+  assert.equal(meta1.embeddingSignature, meta2.embeddingSignature);
+  assert.equal(meta1.activeDim, meta2.activeDim);
+  assert.equal(meta1.vecLoaded, meta2.vecLoaded);
+});
+
+test("ensureReady: signature change triggers reset + marks memories needs_reindex=1", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+
+  // Insert a few memories first.
+  for (let i = 0; i < 3; i++) {
+    db.prepare(
+      `INSERT INTO memories (id, api_key_id, type, key, content, created_at)
+       VALUES (?, 'key1', 'factual', ?, ?, datetime('now'))`,
+    ).run(`mem-${i}`, `key-${i}`, `content-${i}`);
+  }
+
+  // First ensureReady with signature X.
+  const resX = makeResolution("openai:ada-002:1024", 1024);
+  await store.ensureReady(resX);
+
+  // Check X is set.
+  assert.equal(getMemoryVecMeta().embeddingSignature, "openai:ada-002:1024");
+  assert.equal(getMemoryVecMeta().activeDim, 1024);
+
+  // Now switch to signature Y (different model + dim).
+  const resY = makeResolution("openai:text-embedding-3-small:1536", 1536);
+  const resetResult = await store.ensureReady(resY);
+
+  assert.equal(resetResult.ready, true, "should be ready after signature change");
+
+  // Verify new signature is stored.
+  const metaAfter = getMemoryVecMeta();
+  assert.equal(metaAfter.embeddingSignature, "openai:text-embedding-3-small:1536");
+  assert.equal(metaAfter.activeDim, 1536);
+  assert.ok(metaAfter.lastResetAt !== null, "lastResetAt should be set after reset");
+
+  // All 3 memories should have needs_reindex = 1.
+  const needsRows = db
+    .prepare("SELECT COUNT(*) AS cnt FROM memories WHERE needs_reindex = 1")
+    .get() as { cnt: number };
+  assert.equal(needsRows.cnt, 3, "all memories should be marked needs_reindex=1 after signature change");
+});
+
+test("ensureReady: returns {ready: false} when dimensions are null (no probe done yet)", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  // Resolution with null dimensions — lazy probe not done yet.
+  const resNullDim: EmbeddingResolution = {
+    source: "remote",
+    model: "openai/text-embedding-3-small",
+    dimensions: null,
+    signature: "openai:text-embedding-3-small:null",
+    reason: "test - dim not probed yet",
+  };
+
+  const result = await store.ensureReady(resNullDim);
+
+  // Should not crash, but cannot create table without dim.
+  // Either ready (if signature already matches a loaded table) or not ready.
+  assert.ok(
+    typeof result.ready === "boolean",
+    "ensureReady must return {ready: boolean, reason: string}",
+  );
+  assert.ok(typeof result.reason === "string");
+});

tests/unit/memory-vectorstore-load.test.ts

@@ -0,0 +1,128 @@
+/**
+ * tests/unit/memory-vectorstore-load.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for getVectorStore() singleton load behaviour:
+ *   - Returns instance when sqlite-vec loads successfully.
+ *   - Returns null when the db driver has no loadExtension (cloud/WASM backend).
+ *   - Singleton: two calls return the same instance.
+ *   - _resetVectorStoreSingleton allows re-initialization.
+ *
+ * NOTE: Testing the "sqlite-vec load failure" path requires a module-level seam.
+ * We expose VECTOR_STORE_DISABLE_VEC env var to force the null path in tests.
+ * The production code checks this env var to allow test isolation.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-load-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+
+const core = await import("../../src/lib/db/core.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+function cleanup() {
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+// ──────────────── Singleton ────────────────
+
+test("getVectorStore() returns the same singleton on two consecutive calls", () => {
+  _resetVectorStoreSingleton();
+  const r1 = getVectorStore();
+  const r2 = getVectorStore();
+  assert.strictEqual(r1, r2, "two calls must return the exact same reference");
+});
+
+test("_resetVectorStoreSingleton() allows re-initialization", () => {
+  _resetVectorStoreSingleton();
+  const r1 = getVectorStore();
+  _resetVectorStoreSingleton();
+  const r2 = getVectorStore();
+  // Both are valid (either instance or null) but may be different objects on re-init.
+  // The key is that reset does not throw and returns a valid result.
+  assert.ok(r1 === null || r1 !== null); // trivially true — exercises code path
+  assert.ok(r2 === null || r2 !== null);
+});
+
+// ──────────────── Result shape ────────────────
+
+test("getVectorStore() returns null or a VectorStore instance (never throws)", () => {
+  _resetVectorStoreSingleton();
+
+  let result: unknown;
+  let threw = false;
+  try {
+    result = getVectorStore();
+  } catch {
+    threw = true;
+  }
+
+  assert.equal(threw, false, "getVectorStore() must never throw — must return null on failure");
+  assert.ok(
+    result === null || (typeof result === "object" && result !== null),
+    `getVectorStore() must return object or null, got ${typeof result}`,
+  );
+});
+
+test("getVectorStore() result has all required VectorStore methods when not null", () => {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+
+  if (store === null) {
+    // sqlite-vec is not available in this environment — skip method shape check.
+    return;
+  }
+
+  const requiredMethods = [
+    "ensureReady",
+    "upsertVector",
+    "deleteVector",
+    "searchVector",
+    "searchHybrid",
+    "stats",
+    "resetForSignature",
+  ] as const;
+
+  for (const method of requiredMethods) {
+    assert.ok(
+      typeof (store as Record<string, unknown>)[method] === "function",
+      `VectorStore must have method ${method}`,
+    );
+  }
+});
+
+// ──────────────── Null path ────────────────
+
+test("getVectorStore() returns null when VECTOR_STORE_DISABLE_VEC env var is set", () => {
+  // This test uses the VECTOR_STORE_DISABLE_VEC seam to force the null/degraded path.
+  // The env var simulates environments where sqlite-vec cannot be loaded (cloud/WASM).
+  process.env.VECTOR_STORE_DISABLE_VEC = "true";
+  _resetVectorStoreSingleton();
+  const result = getVectorStore();
+  delete process.env.VECTOR_STORE_DISABLE_VEC;
+
+  assert.equal(result, null, "VECTOR_STORE_DISABLE_VEC=true must force null result");
+});

tests/unit/memory-vectorstore-rrf.test.ts

@@ -0,0 +1,253 @@
+/**
+ * tests/unit/memory-vectorstore-rrf.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for searchHybrid() RRF (Reciprocal Rank Fusion, k=60):
+ *   - Case 1: doc only FTS hit → rrfScore = 1/(60+ftsRank), vecRank=null.
+ *   - Case 2: doc only vec hit → rrfScore = 1/(60+vecRank), ftsRank=null.
+ *   - Case 3: doc in both → rrfScore = sum, highest score.
+ *   - Results ordered DESC by rrfScore.
+ *   - apiKeyId filters both vec and FTS results.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mock } from "node:test";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-rrf-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+process.env.MEMORY_RRF_K = "60";
+
+const core = await import("../../src/lib/db/core.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+import type { EmbeddingResolution } from "../../src/lib/memory/embedding/types.ts";
+
+const DIM = 4;
+const RRF_K = 60;
+
+function makeResolution(): EmbeddingResolution {
+  return {
+    source: "remote",
+    model: "test/dim4",
+    dimensions: DIM,
+    signature: `test:dim4:${DIM}`,
+    reason: "test",
+  };
+}
+
+function makeVec(...values: number[]): Float32Array {
+  return new Float32Array(values);
+}
+
+function cleanup() {
+  mock.restoreAll();
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+function getStoreOrSkip(t: { skip: (msg: string) => void }): ReturnType<typeof getVectorStore> {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+  if (store === null) {
+    t.skip("sqlite-vec not available in this environment — skipping");
+    return null;
+  }
+  return store;
+}
+
+async function setupTable(store: NonNullable<ReturnType<typeof getVectorStore>>) {
+  await store.ensureReady(makeResolution());
+}
+
+function insertMemoryWithFts(
+  db: ReturnType<typeof core.getDbInstance>,
+  id: string,
+  apiKeyId: string,
+  content: string,
+) {
+  // Insert into memories — the trigger memory_fts_ai fires automatically if the DB has it.
+  // In a fresh test DB the trigger exists (created by migration 023).
+  db.prepare(
+    `INSERT INTO memories (id, api_key_id, type, key, content, created_at)
+     VALUES (?, ?, 'factual', ?, ?, datetime('now'))`,
+  ).run(id, apiKeyId, `key-${id}`, content);
+  // The migration 023 trigger inserts into memory_fts using memory_id (= rowid).
+  // If the trigger didn't fire (e.g. test DB without triggers), manually sync FTS.
+  try {
+    const row = db.prepare("SELECT rowid, memory_id FROM memories WHERE id = ?").get(id) as
+      | { rowid: number; memory_id: number | null }
+      | undefined;
+    if (row) {
+      const ftsRowid = row.memory_id ?? row.rowid;
+      const ftsCount = db
+        .prepare("SELECT COUNT(*) AS cnt FROM memory_fts WHERE rowid = ?")
+        .get(ftsRowid) as { cnt: number };
+      if (ftsCount.cnt === 0) {
+        db.prepare("INSERT INTO memory_fts(rowid, content, key) VALUES(?, ?, ?)").run(
+          ftsRowid,
+          content,
+          `key-${id}`,
+        );
+      }
+    }
+  } catch {
+    // FTS population is best-effort for tests — if memory_fts doesn't exist, vec-only tests still work.
+  }
+}
+
+// ──────────────── RRF tests ────────────────
+
+test("searchHybrid: results ordered DESC by rrfScore", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  // Insert 3 memories. All searchable via FTS for "hello".
+  insertMemoryWithFts(db, "mem-both", "key1", "hello world");
+  insertMemoryWithFts(db, "mem-fts-only", "key1", "hello text search only");
+  insertMemoryWithFts(db, "mem-vec-only", "key1", "different topic");
+
+  // mem-both gets a vector close to query.
+  await store.upsertVector("mem-both", makeVec(1.0, 0.0, 0.0, 0.0));
+  // mem-vec-only gets a vector close to query but no FTS match.
+  await store.upsertVector("mem-vec-only", makeVec(0.95, 0.05, 0.0, 0.0));
+  // mem-fts-only has no vector.
+
+  const query = makeVec(1.0, 0.0, 0.0, 0.0);
+  const hits = await store.searchHybrid(query, "hello", 10);
+
+  // Should return at least something.
+  assert.ok(hits.length > 0, "should return at least one hit");
+
+  // All hits must have rrfScore > 0.
+  for (const h of hits) {
+    assert.ok(typeof h.memoryId === "string");
+    assert.ok(typeof h.rrfScore === "number");
+    assert.ok(h.rrfScore > 0, `rrfScore must be > 0, got ${h.rrfScore}`);
+  }
+
+  // Results must be ordered DESC by rrfScore.
+  for (let i = 0; i < hits.length - 1; i++) {
+    assert.ok(
+      hits[i].rrfScore >= hits[i + 1].rrfScore,
+      `results must be ordered DESC by rrfScore: ${hits[i].rrfScore} >= ${hits[i + 1].rrfScore}`,
+    );
+  }
+});
+
+test("searchHybrid: doc in both FTS and vec → highest rrfScore (sum of both contributions)", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  insertMemoryWithFts(db, "mem-both", "key1", "hello hybrid search");
+  insertMemoryWithFts(db, "mem-fts-only", "key1", "hello text");
+  insertMemoryWithFts(db, "mem-vec-only", "key1", "no-fts-match");
+
+  // Give mem-both a close vector.
+  await store.upsertVector("mem-both", makeVec(1.0, 0.0, 0.0, 0.0));
+  // Give mem-vec-only a close vector too.
+  await store.upsertVector("mem-vec-only", makeVec(0.9, 0.0, 0.0, 0.0));
+
+  const hits = await store.searchHybrid(makeVec(1.0, 0.0, 0.0, 0.0), "hello", 10);
+
+  const bothHit = hits.find((h) => h.memoryId === "mem-both");
+  if (bothHit) {
+    // mem-both should have contributions from both vec and fts.
+    // Its rrfScore should be ≥ 1/(60+1) (at minimum from one source).
+    const minRrf = 1 / (RRF_K + 1);
+    assert.ok(
+      bothHit.rrfScore >= minRrf,
+      `mem-both rrfScore ${bothHit.rrfScore} should be >= ${minRrf}`,
+    );
+  }
+});
+
+test("searchHybrid: FTS-only hit has vecRank=null", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  // Only insert FTS, no vector for this memory.
+  insertMemoryWithFts(db, "fts-only-mem", "key1", "unique text for fts test only");
+
+  // Query that will NOT match FTS for other mems.
+  const hits = await store.searchHybrid(makeVec(0.0, 0.0, 0.0, 1.0), "unique text for fts", 10);
+
+  const ftsOnlyHit = hits.find((h) => h.memoryId === "fts-only-mem");
+  if (ftsOnlyHit) {
+    // If mem only came from FTS, vecRank should be null.
+    if (ftsOnlyHit.ftsRank !== null && ftsOnlyHit.vecRank === null) {
+      assert.ok(ftsOnlyHit.rrfScore > 0);
+      const expectedContrib = 1 / (RRF_K + (ftsOnlyHit.ftsRank ?? 1));
+      // Score should be approximately the FTS contribution.
+      assert.ok(
+        Math.abs(ftsOnlyHit.rrfScore - expectedContrib) < 0.01,
+        `FTS-only rrfScore ${ftsOnlyHit.rrfScore} should ≈ ${expectedContrib}`,
+      );
+    }
+  }
+});
+
+test("searchHybrid: apiKeyId filters both vec and FTS results", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await setupTable(store);
+
+  // Insert two memories with different api_key_id.
+  insertMemoryWithFts(db, "mem-key1", "key1", "hello hybrid");
+  insertMemoryWithFts(db, "mem-key2", "key2", "hello hybrid");
+
+  await store.upsertVector("mem-key1", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("mem-key2", makeVec(1.0, 0.0, 0.0, 0.0));
+
+  // Without filter: should see both.
+  const allHits = await store.searchHybrid(makeVec(1.0, 0.0, 0.0, 0.0), "hello", 10);
+  const allIds = allHits.map((h) => h.memoryId);
+  // At least one of each should appear (FTS and/or vec).
+  assert.ok(
+    allIds.includes("mem-key1") || allIds.includes("mem-key2"),
+    "without filter should include at least one hit",
+  );
+
+  // With filter for key1 only.
+  const key1Hits = await store.searchHybrid(makeVec(1.0, 0.0, 0.0, 0.0), "hello", 10, "key1");
+  for (const h of key1Hits) {
+    assert.notEqual(h.memoryId, "mem-key2", "key2 should not appear when filtering for key1");
+  }
+
+  // With filter for key2 only.
+  const key2Hits = await store.searchHybrid(makeVec(1.0, 0.0, 0.0, 0.0), "hello", 10, "key2");
+  for (const h of key2Hits) {
+    assert.notEqual(h.memoryId, "mem-key1", "key1 should not appear when filtering for key2");
+  }
+});

tests/unit/memory-vectorstore-stats.test.ts

@@ -0,0 +1,196 @@
+/**
+ * tests/unit/memory-vectorstore-stats.test.ts
+ *
+ * Plan 21 — Memory Engine Redesign (F4)
+ * Tests for VectorStore.stats():
+ *   - rowCount reflects actual vec_memories count.
+ *   - needsReindex reflects memories.needs_reindex=1 count.
+ *   - activeDim and signature reflect memory_vec_meta.
+ *   - stats() returns zeros when vec_memories does not exist yet.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { mock } from "node:test";
+
+const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omr-vecstore-stats-"));
+process.env.DATA_DIR = TEST_DATA_DIR;
+process.env.DISABLE_SQLITE_AUTO_BACKUP = "true";
+
+const core = await import("../../src/lib/db/core.ts");
+const { markAllMemoriesNeedReindex } = await import("../../src/lib/db/memoryVec.ts");
+const vsModule = await import("../../src/lib/memory/vectorStore.ts");
+const { getVectorStore, _resetVectorStoreSingleton } = vsModule;
+
+import type { EmbeddingResolution } from "../../src/lib/memory/embedding/types.ts";
+
+const DIM = 4;
+
+function makeResolution(): EmbeddingResolution {
+  return {
+    source: "remote",
+    model: "test/dim4",
+    dimensions: DIM,
+    signature: `test:dim4:${DIM}`,
+    reason: "test",
+  };
+}
+
+function makeVec(...values: number[]): Float32Array {
+  return new Float32Array(values);
+}
+
+function insertMemory(
+  db: ReturnType<typeof core.getDbInstance>,
+  id: string,
+) {
+  db.prepare(
+    `INSERT INTO memories (id, api_key_id, type, key, content, created_at)
+     VALUES (?, 'key1', 'factual', ?, ?, datetime('now'))`,
+  ).run(id, `key-${id}`, `content-${id}`);
+}
+
+function cleanup() {
+  mock.restoreAll();
+  _resetVectorStoreSingleton();
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+}
+
+test.afterEach(() => {
+  cleanup();
+});
+
+test.after(() => {
+  core.resetDbInstance();
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+});
+
+function getStoreOrSkip(t: { skip: (msg: string) => void }): ReturnType<typeof getVectorStore> {
+  _resetVectorStoreSingleton();
+  const store = getVectorStore();
+  if (store === null) {
+    t.skip("sqlite-vec not available in this environment — skipping");
+    return null;
+  }
+  return store;
+}
+
+// ──────────────── stats() ────────────────
+
+test("stats(): rowCount=0 and activeDim=null before ensureReady", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const result = await store.stats();
+
+  assert.equal(result.rowCount, 0, "rowCount must be 0 when table doesn't exist yet");
+  assert.equal(result.needsReindex, 0, "needsReindex must be 0 initially");
+  assert.equal(result.activeDim, null, "activeDim must be null before ensureReady");
+  assert.equal(result.signature, null, "signature must be null before ensureReady");
+});
+
+test("stats(): rowCount reflects actual vector count after upserts", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await store.ensureReady(makeResolution());
+
+  insertMemory(db, "m1");
+  insertMemory(db, "m2");
+  insertMemory(db, "m3");
+
+  await store.upsertVector("m1", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("m2", makeVec(0.0, 1.0, 0.0, 0.0));
+  await store.upsertVector("m3", makeVec(0.0, 0.0, 1.0, 0.0));
+
+  const result = await store.stats();
+  assert.equal(result.rowCount, 3, "rowCount must equal number of inserted vectors");
+});
+
+test("stats(): needsReindex reflects memories marked for reindex", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await store.ensureReady(makeResolution());
+
+  // Insert 5 memories.
+  for (let i = 0; i < 5; i++) {
+    insertMemory(db, `m${i}`);
+  }
+
+  // Mark all as needing reindex.
+  const affected = markAllMemoriesNeedReindex();
+  assert.equal(affected, 5, "should mark 5 memories as needing reindex");
+
+  const result = await store.stats();
+  assert.equal(result.needsReindex, 5, "needsReindex must reflect 5 memories with needs_reindex=1");
+});
+
+test("stats(): activeDim and signature reflect meta after ensureReady", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const sig = `test:dim4:${DIM}`;
+  await store.ensureReady(makeResolution());
+
+  const result = await store.stats();
+
+  assert.equal(result.activeDim, DIM, "activeDim must match the dimension passed to ensureReady");
+  assert.equal(result.signature, sig, "signature must match the resolution signature");
+});
+
+test("stats(): needsReindex decreases as vectors are inserted (marking reindex=0)", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await store.ensureReady(makeResolution());
+
+  insertMemory(db, "m1");
+  insertMemory(db, "m2");
+
+  // Mark all as pending.
+  markAllMemoriesNeedReindex();
+
+  const before = await store.stats();
+  assert.equal(before.needsReindex, 2);
+
+  // Clear needs_reindex for m1 manually (simulating successful reindex).
+  db.prepare("UPDATE memories SET needs_reindex = 0 WHERE id = 'm1'").run();
+
+  const after = await store.stats();
+  assert.equal(after.needsReindex, 1, "needsReindex should decrease when a memory is cleared");
+});
+
+test("stats(): rowCount decreases after deleteVector", async (t) => {
+  const store = getStoreOrSkip(t);
+  if (!store) return;
+
+  const db = core.getDbInstance();
+  await store.ensureReady(makeResolution());
+
+  insertMemory(db, "m1");
+  insertMemory(db, "m2");
+
+  await store.upsertVector("m1", makeVec(1.0, 0.0, 0.0, 0.0));
+  await store.upsertVector("m2", makeVec(0.0, 1.0, 0.0, 0.0));
+
+  const before = await store.stats();
+  assert.equal(before.rowCount, 2);
+
+  await store.deleteVector("m1");
+
+  const after = await store.stats();
+  assert.equal(after.rowCount, 1, "rowCount should decrease after deleteVector");
+});