@wrongstack/vector-memory 1.0.2 → 1.0.4

package/dist/index.js

@@ -14,796 +14,357 @@ var VectorMemoryProviderUnavailableError = class extends VectorMemoryError {
   }
 };
 
-// src/transformers-provider.ts
-var DEFAULT_VECTOR_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
-var DEFAULT_VECTOR_DIMENSIONS = 384;
-var DEFAULT_VECTOR_DTYPE = "q8";
-var TransformersEmbeddingProvider = class {
-  id;
-  dimensions;
-  modelId;
-  cacheDir;
-  dtype;
-  device;
-  batchSize;
-  maxChars;
-  allowRemote;
-  extractor;
-  loadPromise;
-  constructor(opts = {}) {
-    this.modelId = opts.modelId ?? DEFAULT_VECTOR_MODEL_ID;
-    this.cacheDir = opts.cacheDir;
-    this.dtype = opts.dtype ?? DEFAULT_VECTOR_DTYPE;
-    this.device = opts.device ?? "cpu";
-    this.batchSize = opts.batchSize ?? 16;
-    this.maxChars = opts.maxChars ?? 2048;
-    this.allowRemote = opts.allowRemoteModels ?? true;
-    this.dimensions = DEFAULT_VECTOR_DIMENSIONS;
-    this.id = `transformers-js:${this.modelId}:${this.dtype}`;
+// src/sage-event-mirror.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getSageSurface } from "@wrongstack/sage";
+function subscribeVectorMemoryToSage(opts) {
+  const { store, memoryStore } = opts;
+  const log = opts.logger;
+  if (opts.enabled === false) {
+    return { dispose: () => void 0 };
   }
-  /**
-   * Synchronous capability check. Returns false when the optional
-   * `@huggingface/transformers` dependency is not installed.
-   *
-   * NOTE: this probes via dynamic import and caches the result, but does
-   * NOT load the model itself — model loading is deferred to `embed()`.
-   */
-  async isAvailable() {
+  const surface = getSageSurface(memoryStore);
+  if (!surface) {
+    log?.debug?.("vector-memory mirror disabled: memory store exposes no SAGE surface");
+    return { dispose: () => void 0 };
+  }
+  const events = memoryStore.events;
+  if (!events) {
+    log?.debug?.("vector-memory mirror disabled: memory store has no event bus");
+    return { dispose: () => void 0 };
+  }
+  const fetch = async (memoryId) => {
     try {
-      await this.loadModule();
-      return true;
-    } catch {
-      return false;
+      return await surface.getSage(memoryId);
+    } catch (err) {
+      log?.warn?.(`vector-memory mirror fetch failed for ${memoryId}: ${errMsg(err)}`);
+      return null;
     }
-  }
-  async embed(texts) {
-    if (texts.length === 0) return [];
-    const extractor = await this.getExtractor();
-    const prepared = texts.map((t) => this.prepare(t));
-    const batches = [];
-    for (let i = 0; i < prepared.length; i += this.batchSize) {
-      batches.push(prepared.slice(i, i + this.batchSize));
+  };
+  const mirror = async (memoryId) => {
+    const memory = await fetch(memoryId);
+    if (!memory) return;
+    if (memory.scope === "session") return;
+    try {
+      const existing = store.findBySageId(memoryId);
+      if (existing) await store.forget(existing.id);
+      await store.remember({
+        text: memory.text,
+        ...memory.summary ? { summary: memory.summary } : {},
+        tags: memory.tags ?? [],
+        scope: "project",
+        kind: "note",
+        metadata: {
+          source: "sage",
+          sageId: memory.id,
+          sageKind: memory.kind,
+          sageScope: memory.scope,
+          importance: memory.importance,
+          confidence: memory.confidence
+        }
+      });
+    } catch (err) {
+      log?.warn?.(`vector-memory mirror remember failed for ${memoryId}: ${errMsg(err)}`);
     }
-    const results = [];
-    for (const batch of batches) {
-      const out = await extractor(batch, { pooling: "mean", normalize: true });
-      results.push(...this.tensorToVectors(out, batch.length));
+  };
+  const forgetMirror = async (memoryId) => {
+    try {
+      const existing = store.findBySageId(memoryId);
+      if (existing) await store.forget(existing.id);
+    } catch (err) {
+      log?.warn?.(`vector-memory mirror forget failed for ${memoryId}: ${errMsg(err)}`);
     }
-    return results;
-  }
-  /** Truncate + normalize text before embedding. */
-  prepare(text) {
-    if (!text) return "";
-    const normalized = text.normalize("NFKC").trim();
-    return normalized.length > this.maxChars ? normalized.slice(0, this.maxChars) : normalized;
-  }
-  tensorToVectors(out, batchSize) {
-    if (typeof out.tolist === "function") {
-      const nested = out.tolist();
-      if (Array.isArray(nested) && Array.isArray(nested[0])) {
-        return nested.map((row) => Float32Array.from(row));
-      }
-      return [Float32Array.from(nested)];
+  };
+  const offAccepted = events.onPattern("memory.accepted", (_event, payload) => {
+    const memoryId = payload?.memoryId;
+    if (typeof memoryId !== "string") return;
+    void mirror(memoryId);
+  });
+  const offRecovered = events.onPattern("memory.recovered", (_event, payload) => {
+    const memoryId = payload?.memoryId;
+    if (typeof memoryId !== "string") return;
+    void mirror(memoryId);
+  });
+  const offUpdated = events.onPattern("memory.updated", (_event, payload) => {
+    const memoryId = payload?.memoryId;
+    if (typeof memoryId !== "string") return;
+    const status = payload?.status;
+    if (status === "deleted") return;
+    void mirror(memoryId);
+  });
+  const offDeleted = events.onPattern("memory.deleted", (_event, payload) => {
+    const memoryId = payload?.memoryId;
+    if (typeof memoryId !== "string") return;
+    void forgetMirror(memoryId);
+  });
+  return {
+    dispose: () => {
+      offAccepted();
+      offRecovered();
+      offUpdated();
+      offDeleted();
     }
-    const flat = out.data;
-    if (flat instanceof Float32Array) {
-      if (batchSize === 1) return [flat];
-      const dim = flat.length / batchSize;
-      const vectors = [];
-      for (let i = 0; i < batchSize; i++) {
-        vectors.push(Float32Array.from(flat.subarray(i * dim, (i + 1) * dim)));
+  };
+}
+async function forgetStaleSageMirrors(store, memoryStore, logger, options) {
+  const surface = getSageSurface(memoryStore);
+  if (!surface) return { scanned: 0, removed: 0 };
+  let scanned = 0;
+  let removed = 0;
+  const PAGE = Math.max(1, options?.pageSize ?? 500);
+  let after;
+  for (; ; ) {
+    const page = store.list(after ? { limit: PAGE, after } : { limit: PAGE });
+    if (page.length === 0) break;
+    const last = page[page.length - 1];
+    after = { updatedAt: last.updatedAt, id: last.id };
+    for (const entry of page) {
+      scanned++;
+      const sageId = entry.metadata?.sageId;
+      if (typeof sageId !== "string") continue;
+      try {
+        const memory = await surface.getSage(sageId);
+        if (memory !== null && memory.status !== "deleted") continue;
+        await store.forget(entry.id);
+        removed++;
+      } catch (err) {
+        logger?.warn?.(`vector-memory stale-mirror sweep failed for ${sageId}: ${errMsg(err)}`);
       }
-      return vectors;
-    }
-    if (Array.isArray(flat) && Array.isArray(flat[0])) {
-      return flat.map((row) => Float32Array.from(row));
     }
-    if (Array.isArray(flat)) {
-      return [Float32Array.from(flat)];
+    if (page.length < PAGE) break;
+  }
+  return { scanned, removed };
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+var SAGE_SWEEP_MARKER_FILENAME = "sage-mirror-sweep.json";
+var DEFAULT_SWEEP_INTERVAL_MS = 60 * 6e4;
+async function sweepStaleSageMirrors(opts) {
+  const markerPath2 = path.join(opts.store.directory, SAGE_SWEEP_MARKER_FILENAME);
+  const interval = opts.minIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+  if (!opts.force) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(markerPath2, "utf8"));
+      const at = typeof raw.at === "string" ? Date.parse(raw.at) : Number.NaN;
+      if (Number.isFinite(at) && Date.now() - at < interval) {
+        return { swept: false, reason: "throttled" };
+      }
+    } catch {
     }
-    throw new Error("TransformersEmbeddingProvider: unexpected pipeline output shape");
   }
-  async getExtractor() {
-    if (this.extractor) return this.extractor;
-    if (!this.loadPromise) this.loadPromise = this.loadExtractor();
-    this.extractor = await this.loadPromise;
-    return this.extractor;
+  try {
+    fs.writeFileSync(markerPath2, JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
+  } catch {
   }
-  async loadExtractor() {
-    const mod = await this.loadModule();
-    if (this.cacheDir) mod.env.cacheDir = this.cacheDir;
-    mod.env.allowRemoteModels = this.allowRemote;
-    if (!this.allowRemote) mod.env.localModelPath = this.cacheDir ?? "";
-    const pipe = await mod.pipeline("feature-extraction", this.modelId, {
-      dtype: this.dtype,
-      device: this.device
-    });
-    return pipe;
+  try {
+    const result = await forgetStaleSageMirrors(opts.store, opts.memoryStore, opts.logger);
+    opts.logger?.debug?.(
+      `vector-memory stale-mirror sweep: scanned=${result.scanned} removed=${result.removed}`
+    );
+    return { swept: true, ...result };
+  } catch (err) {
+    opts.logger?.warn?.(`vector-memory stale-mirror sweep failed: ${errMsg(err)}`);
+    return { swept: false, reason: errMsg(err) };
   }
-  async loadModule() {
+}
+
+// src/sage-fusion.ts
+var DEFAULT_RRF_K = 60;
+var DEFAULT_VECTOR_WEIGHT = 0.3;
+function lexicalRankScore(index, total) {
+  if (total <= 1) return 1;
+  return 1 - index / Math.max(1, total - 1);
+}
+async function fuseWithVectorMemory(query, lexical, options = {}) {
+  const weight = clamp01(options.vectorWeight ?? DEFAULT_VECTOR_WEIGHT);
+  const k = options.rrfK ?? DEFAULT_RRF_K;
+  const limit = options.limit ?? 25;
+  let vectorHits = [];
+  if (options.vectorHits) {
+    vectorHits = [...options.vectorHits];
+  } else if (options.store) {
     try {
-      return await import("@huggingface/transformers");
-    } catch (err) {
-      throw new VectorMemoryProviderUnavailableError(
-        "@huggingface/transformers is not installed. Install it (pnpm add @huggingface/transformers) or wire a fallback EmbeddingProvider.",
-        err
-      );
+      vectorHits = await options.store.search(query, {
+        ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
+        limit: Math.max(limit * 2, 50)
+      });
+    } catch {
+      vectorHits = [];
     }
   }
-};
-
-// src/schema.ts
-var VECTOR_SCHEMA_VERSION = 2;
-var VECTOR_PROVIDER_KEY = "active_provider_id";
-var VECTOR_DIMENSIONS_KEY = "active_provider_dimensions";
-function initVectorSchema(db) {
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA synchronous = NORMAL");
-  db.exec("PRAGMA busy_timeout = 30000");
-  db.exec("PRAGMA temp_store = MEMORY");
-  db.exec("PRAGMA foreign_keys = ON");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS schema_meta (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL
-    );
-  `);
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS entries (
-      id TEXT PRIMARY KEY,
-      text TEXT NOT NULL,
-      summary TEXT,
-      metadata TEXT NOT NULL DEFAULT '{}',
-      tags TEXT NOT NULL DEFAULT '[]',
-      scope TEXT NOT NULL DEFAULT 'project',
-      kind TEXT NOT NULL DEFAULT 'note',
-      content_hash TEXT NOT NULL,
-      created_at TEXT NOT NULL,
-      updated_at TEXT NOT NULL
-    );
-  `);
-  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_scope ON entries(scope)");
-  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_kind ON entries(kind)");
-  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_hash ON entries(content_hash)");
-  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_updated ON entries(updated_at DESC)");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS vectors (
-      entry_id TEXT NOT NULL,
-      provider_id TEXT NOT NULL,
-      dimensions INTEGER NOT NULL,
-      vector BLOB NOT NULL,
-      created_at TEXT NOT NULL,
-      PRIMARY KEY (entry_id, provider_id),
-      FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
-    );
-  `);
-  db.exec("CREATE INDEX IF NOT EXISTS idx_vectors_provider ON vectors(provider_id)");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS embedding_cache (
-      content_hash TEXT NOT NULL,
-      provider_id TEXT NOT NULL,
-      dimensions INTEGER NOT NULL,
-      vector BLOB NOT NULL,
-      text TEXT NOT NULL,
-      created_at TEXT NOT NULL,
-      last_used_at TEXT NOT NULL,
-      use_count INTEGER NOT NULL DEFAULT 0,
-      PRIMARY KEY (content_hash, provider_id, dimensions)
-    );
-  `);
-  db.exec("CREATE INDEX IF NOT EXISTS idx_cache_last_used ON embedding_cache(last_used_at)");
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
-      id UNINDEXED, text, tags, content='entries', content_rowid='rowid'
-    );
-  `);
-  db.exec(`
-    CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
-      INSERT INTO entries_fts(rowid, text, tags)
-      VALUES (new.rowid, new.text, new.tags);
-    END;
-  `);
-  db.exec(`
-    CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
-      INSERT INTO entries_fts(entries_fts, rowid, text, tags)
-      VALUES('delete', old.rowid, old.text, old.tags);
-    END;
-  `);
-  db.exec(`
-    CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
-      INSERT INTO entries_fts(entries_fts, rowid, text, tags)
-      VALUES('delete', old.rowid, old.text, old.tags);
-      INSERT INTO entries_fts(rowid, text, tags)
-      VALUES (new.rowid, new.text, new.tags);
-    END;
-  `);
-}
-function upsertEmbeddingCache(db, row) {
-  db.prepare(
-    `INSERT INTO embedding_cache
-       (content_hash, provider_id, dimensions, vector, text, created_at, last_used_at, use_count)
-     VALUES (?, ?, ?, ?, ?, ?, ?, 1)
-     ON CONFLICT(content_hash, provider_id, dimensions) DO UPDATE SET
-       last_used_at = excluded.last_used_at,
-       use_count = embedding_cache.use_count + 1,
-       vector = excluded.vector`
-  ).run(row.contentHash, row.providerId, row.dimensions, row.vector, row.text, row.now, row.now);
-}
-function lookupEmbeddingCache(db, contentHash, providerId, dimensions, now) {
-  const row = db.prepare(
-    `SELECT vector FROM embedding_cache
-        WHERE content_hash = ? AND provider_id = ? AND dimensions = ?
-        LIMIT 1`
-  ).get(contentHash, providerId, dimensions);
-  if (!row) return void 0;
-  try {
-    db.prepare(
-      `UPDATE embedding_cache SET last_used_at = ?, use_count = use_count + 1
-        WHERE content_hash = ? AND provider_id = ? AND dimensions = ?`
-    ).run(now, contentHash, providerId, dimensions);
-  } catch {
+  const sageById = /* @__PURE__ */ new Map();
+  for (const memory of lexical) sageById.set(memory.id, memory);
+  const lexicalRanked = lexical.map((memory, index) => ({
+    memory,
+    rankScore: lexicalRankScore(index, lexical.length),
+    lexicalScore: lexicalRankScore(index, lexical.length)
+  }));
+  const vectorRanked = [];
+  const seenVectorSageIds = /* @__PURE__ */ new Set();
+  for (let i = 0; i < vectorHits.length; i++) {
+    const hit = vectorHits[i];
+    const sageId = hit.entry.metadata?.["sageId"];
+    if (typeof sageId !== "string" || seenVectorSageIds.has(sageId)) continue;
+    const memory = sageById.get(sageId);
+    if (!memory) continue;
+    seenVectorSageIds.add(sageId);
+    vectorRanked.push({ memory, vectorScore: hit.score });
   }
-  return decodeVector(row.vector);
-}
-function encodeVector(vec) {
-  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
-}
-function decodeVector(buf) {
-  if (buf.byteLength % 4 !== 0) {
-    throw new Error(
-      `decodeVector: invalid vector byteLength ${buf.byteLength} (must be a multiple of 4)`
-    );
+  const fused = /* @__PURE__ */ new Map();
+  for (let i = 0; i < lexicalRanked.length; i++) {
+    const c = lexicalRanked[i];
+    const rrf = (1 - weight) * (1 / (k + i + 1));
+    fused.set(c.memory.id, {
+      memory: c.memory,
+      vectorScore: null,
+      lexicalScore: c.lexicalScore,
+      finalScore: rrf,
+      source: "lexical"
+    });
   }
-  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
-  const copy = new Float32Array(buf.byteLength / 4);
-  for (let i = 0; i < copy.length; i++) {
-    copy[i] = view.getFloat32(i * 4, true);
+  for (let i = 0; i < vectorRanked.length; i++) {
+    const v = vectorRanked[i];
+    const rrf = weight * (1 / (k + i + 1));
+    const existing = fused.get(v.memory.id);
+    if (existing) {
+      existing.finalScore += rrf;
+      existing.vectorScore = v.vectorScore;
+      existing.source = "both";
+    }
   }
-  return copy;
-}
-
-// src/store.ts
-import { createHash, randomUUID } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { withFileLock } from "@wrongstack/core/utils";
-import { loadRuntimeDatabaseSync } from "@wrongstack/persistence";
-import { cosineSimilarity, HashingEmbeddingProvider } from "@wrongstack/sage";
-var DEFAULT_SEARCH_LIMIT = 10;
-function normalizeLimit(limit) {
-  if (limit === void 0 || !Number.isFinite(limit)) return DEFAULT_SEARCH_LIMIT;
-  const floored = Math.floor(limit);
-  return floored < 1 ? DEFAULT_SEARCH_LIMIT : floored;
+  const out = Array.from(fused.values());
+  out.sort((a, b) => b.finalScore - a.finalScore);
+  return out.slice(0, limit);
 }
-var DEFAULT_DIRECTORY = ".wrongstack/vector-memory";
-var DEFAULT_FILENAME = "vector-memory.db";
-var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
-var CACHE_EVICT_BATCH = 256;
-var VectorMemoryStore = class _VectorMemoryStore {
-  db;
-  dbPath;
-  rootDir;
-  provider;
-  closed = false;
-  constructor(opts) {
-    if (!opts.provider) throw new Error("VectorMemoryStore: provider is required");
-    if (!opts.projectRoot) throw new Error("VectorMemoryStore: projectRoot is required");
-    this.provider = opts.provider;
-    const dir = opts.directory ?? DEFAULT_DIRECTORY;
-    const filename = opts.filename ?? DEFAULT_FILENAME;
-    if (path.isAbsolute(dir)) {
-      throw new Error("Vector memory directory must be project-relative.");
+function asVectorRecallProvider(store) {
+  return {
+    async search(query, opts) {
+      const hits = await store.search(query, {
+        limit: opts.limit,
+        ...opts.threshold !== void 0 ? { threshold: opts.threshold } : {}
+      });
+      return hits.map((h) => ({
+        id: h.entry.id,
+        score: h.score,
+        text: h.entry.text,
+        ...h.entry.summary ? { summary: h.entry.summary } : {},
+        tags: h.entry.tags,
+        ...h.entry.metadata ? { metadata: h.entry.metadata } : {}
+      }));
     }
-    const rootDir = path.resolve(opts.projectRoot, dir);
-    const rel = path.relative(path.resolve(opts.projectRoot), rootDir);
-    if (rel.startsWith("..") || path.isAbsolute(rel)) {
-      throw new Error("Vector memory directory must stay inside the project root.");
+  };
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return DEFAULT_VECTOR_WEIGHT;
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+// src/sage-port-wrapper.ts
+import {
+  augmentLexicalWithVectorRecall,
+  isSageVisibleForSearch,
+  SAGE_RETRIEVAL_CAPABILITY,
+  SAGE_SURFACE_CAPABILITY
+} from "@wrongstack/sage";
+function asVectorRecallProviderAdapter(store) {
+  return {
+    async search(query, opts) {
+      const hits = await store.search(query, {
+        limit: opts.limit,
+        ...opts.threshold !== void 0 ? { threshold: opts.threshold } : {}
+      });
+      return hits.map((h) => ({
+        id: h.entry.id,
+        score: h.score,
+        text: h.entry.text,
+        ...h.entry.summary ? { summary: h.entry.summary } : {},
+        tags: h.entry.tags,
+        ...h.entry.metadata ? { metadata: h.entry.metadata } : {}
+      }));
     }
-    fs.mkdirSync(rootDir, { recursive: true });
-    this.rootDir = rootDir;
-    this.dbPath = path.join(rootDir, filename);
-    const Database = loadRuntimeDatabaseSync();
-    this.db = new Database(this.dbPath);
-    initVectorSchema(this.db);
-    this.recordActiveProvider();
-  }
-  /**
-   * Absolute path of the store's data directory (the resolved
-   * `opts.directory`, default `.wrongstack/vector-memory`). Hosts use this
-   * to place sidecar state (e.g. the first-boot SAGE sync marker) next to
-   * the db instead of re-deriving the path and drifting from it.
-   */
-  get directory() {
-    return this.rootDir;
-  }
-  /**
-   * Absolute path of the SQLite database file. Hosts use this to take a
-   * file-level lock that covers all mutating operations (see
-   * `withFileLock(this.dbPath + '.lock', …)`).
-   */
-  get databasePath() {
-    return this.dbPath;
-  }
-  /** The lockfile path used to serialize mutating operations. */
-  get lockPath() {
-    return `${this.dbPath}.lock`;
-  }
-  get activeProviderId() {
-    const row = this.db.prepare("SELECT value FROM schema_meta WHERE key = ?").get(VECTOR_PROVIDER_KEY);
-    return row?.value ?? this.provider.id;
-  }
-  recordActiveProvider() {
-    this.db.exec("BEGIN");
-    try {
-      this.db.prepare(
-        `INSERT INTO schema_meta (key, value) VALUES (?, ?)
-           ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-      ).run(VECTOR_PROVIDER_KEY, this.provider.id);
-      this.db.prepare(
-        `INSERT INTO schema_meta (key, value) VALUES (?, ?)
-           ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-      ).run(VECTOR_DIMENSIONS_KEY, String(this.provider.dimensions));
-      this.db.exec("COMMIT");
-    } catch (e) {
-      this.db.exec("ROLLBACK");
-      throw e;
-    }
-  }
-  static contentHash(text) {
-    return createHash("sha256").update(text.normalize("NFKC").trim()).digest("hex");
-  }
-  /**
-   * Look up a vector for `text` in the provider-level embedding cache.
-   * Cache hit returns the cached vector (no ONNX pass). Miss returns
-   * `undefined`.
-   */
-  cachedVector(text, now) {
-    return lookupEmbeddingCache(
-      this.db,
-      _VectorMemoryStore.contentHash(text),
-      this.provider.id,
-      this.provider.dimensions,
-      now
-    );
-  }
-  /** Persist `vec` for `text` to the embedding cache. */
-  cacheVector(text, vec, now) {
-    upsertEmbeddingCache(this.db, {
-      contentHash: _VectorMemoryStore.contentHash(text),
-      providerId: this.provider.id,
-      dimensions: vec.length,
-      vector: encodeVector(vec),
-      text,
-      now
-    });
-  }
-  /**
-   * Embed `text`, hitting the provider-level cache first. Cache miss falls
-   * through to the configured provider and writes the result back. Returns
-   * `undefined` when the provider fails — the caller can persist the entry
-   * without a vector (fail-open).
-   */
-  async embedWithCache(text) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const cached = this.cachedVector(text, now);
-    if (cached) return cached;
-    try {
-      const result = await this.provider.embed([text]);
-      const vec = result[0];
-      if (vec) this.cacheVector(text, vec, now);
-      return vec;
-    } catch {
-      return void 0;
-    }
-  }
-  /**
-   * Look up an existing entry by `content_hash`. Returns `undefined` when
-   * the entry is not present. Used by `remember()` to make writes idempotent
-   * and by `syncFromSage()` to skip already-indexed SAGE memories.
-   */
-  findByContentHash(contentHash) {
-    this.assertOpen();
-    const row = this.db.prepare("SELECT * FROM entries WHERE content_hash = ? LIMIT 1").get(contentHash);
-    if (!row) return void 0;
-    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(row.id);
-    return this.rowToEntry(row, vectorRow);
-  }
-  /**
-   * Look up the entry mirroring a given SAGE memory id (i.e. the entry
-   * whose `metadata.sageId` equals `sageId`). Returns `undefined` when
-   * no such entry exists. Used by the event-driven mirror to delete
-   * vector entries on SAGE delete events (the emitter knows the SAGE
-   * id, not the vector entry id).
-   *
-   * Index lookup is `json_extract(metadata, '$.sageId')` — the metadata
-   * column is the JSON blob `syncFromSage` writes, so this avoids a
-   * full table scan.
-   */
-  findBySageId(sageId) {
-    this.assertOpen();
-    const row = this.db.prepare(
-      `SELECT * FROM entries
-          WHERE json_extract(metadata, '$.sageId') = ?
-          ORDER BY updated_at DESC
-          LIMIT 1`
-    ).get(sageId);
-    if (!row) return void 0;
-    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(row.id);
-    return this.rowToEntry(row, vectorRow);
-  }
-  /**
-   * Persist a new entry. Idempotent: if an entry with the same
-   * `content_hash` already exists, that entry is returned unchanged
-   * instead of inserting a duplicate. Mutating ops are wrapped in
-   * `withFileLock` so two processes cannot race the dedup check.
-   */
-  async remember(input) {
-    this.assertOpen();
-    if (!input.text || input.text.trim().length === 0) {
-      throw new Error("VectorMemoryStore.remember: text must be non-empty");
-    }
-    return withFileLock(this.lockPath, () => this.rememberUnlocked(input), {
-      timeoutMs: DEFAULT_LOCK_TIMEOUT_MS
-    });
-  }
-  async rememberUnlocked(input) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const contentHash = _VectorMemoryStore.contentHash(input.text);
-    const existing = this.findByContentHash(contentHash);
-    if (existing) return existing;
-    const metadata = input.metadata ?? {};
-    const tags = input.tags ?? [];
-    const scope = input.scope ?? "project";
-    const kind = input.kind ?? "note";
-    const id = randomUUID();
-    const vector = await this.embedWithCache(input.text);
-    const providerId = vector ? this.provider.id : void 0;
-    this.db.exec("BEGIN");
-    try {
-      this.db.prepare(
-        `INSERT INTO entries
-            (id, text, summary, metadata, tags, scope, kind, content_hash, created_at, updated_at)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
-      ).run(
-        id,
-        input.text,
-        input.summary ?? null,
-        JSON.stringify(metadata),
-        JSON.stringify(tags),
-        scope,
-        kind,
-        contentHash,
-        now,
-        now
-      );
-      if (vector && providerId) {
-        this.db.prepare(
-          `INSERT INTO vectors (entry_id, provider_id, dimensions, vector, created_at)
-             VALUES (?, ?, ?, ?, ?)
-             ON CONFLICT(entry_id, provider_id) DO UPDATE SET
-               vector = excluded.vector,
-               dimensions = excluded.dimensions,
-               created_at = excluded.created_at`
-        ).run(id, providerId, vector.length, encodeVector(vector), now);
-      }
-      this.db.exec("COMMIT");
-    } catch (e) {
-      this.db.exec("ROLLBACK");
-      throw e;
-    }
-    const result = {
-      id,
-      text: input.text,
-      summary: input.summary ?? void 0,
-      metadata,
-      tags,
-      scope,
-      kind,
-      contentHash,
-      createdAt: now,
-      updatedAt: now,
-      providerId: providerId ?? "",
-      dimensions: vector?.length ?? 0
-    };
-    if (vector) result.vector = vector;
-    return result;
-  }
-  get(id) {
-    this.assertOpen();
-    const row = this.db.prepare("SELECT * FROM entries WHERE id = ?").get(id);
-    if (!row) return void 0;
-    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(id);
-    return this.rowToEntry(row, vectorRow);
-  }
-  /** Hard-delete an entry by id. Wrapped in `withFileLock` for cross-process safety. */
-  async forget(id) {
-    this.assertOpen();
-    return withFileLock(
-      this.lockPath,
-      async () => {
-        this.db.exec("BEGIN");
-        try {
-          const info = this.db.prepare("DELETE FROM entries WHERE id = ?").run(id);
-          this.db.exec("COMMIT");
-          return info.changes > 0;
-        } catch (e) {
-          this.db.exec("ROLLBACK");
-          throw e;
-        }
-      },
-      { timeoutMs: DEFAULT_LOCK_TIMEOUT_MS }
-    );
-  }
-  async search(query, opts = {}) {
-    this.assertOpen();
-    const limit = normalizeLimit(opts.limit);
-    const threshold = opts.threshold ?? 0;
-    const includeVectors = opts.includeVectors === true;
-    if (typeof query !== "string" || query.trim().length === 0) return [];
-    const queryVec = await this.embedWithCache(query);
-    if (!queryVec || queryVec.length === 0) return [];
-    const providerId = this.provider.id;
-    const dimensions = this.provider.dimensions;
-    const filters = ["v.provider_id = ?", "v.dimensions = ?"];
-    const params = [providerId, dimensions];
-    if (opts.scope !== void 0) {
-      filters.push("e.scope = ?");
-      params.push(opts.scope);
-    }
-    if (opts.kind !== void 0) {
-      filters.push("e.kind = ?");
-      params.push(opts.kind);
-    }
-    const scanRows = this.db.prepare(
-      `SELECT e.id AS id, v.vector AS vec_blob
-           FROM entries e
-           JOIN vectors v ON v.entry_id = e.id
-          WHERE ${filters.join(" AND ")}`
-    ).all(...params);
-    const top = [];
-    for (const row of scanRows) {
-      const vec = decodeVector(row.vec_blob);
-      const raw = cosineSimilarity(queryVec, vec);
-      const score = Math.max(0, Math.min(1, raw));
-      if (!Number.isFinite(score) || score < threshold) continue;
-      if (top.length >= limit && score <= (top[top.length - 1]?.score ?? 0)) continue;
-      let at = top.length;
-      while (at > 0 && (top[at - 1]?.score ?? 0) < score) at--;
-      top.splice(at, 0, { id: row.id, score, vector: vec });
-      if (top.length > limit) top.length = limit;
-    }
-    if (top.length === 0) return [];
-    const placeholders = top.map(() => "?").join(",");
-    const hydrated = this.db.prepare(
-      `SELECT id, text, summary, metadata, tags, scope, kind,
-                content_hash, created_at, updated_at
-           FROM entries WHERE id IN (${placeholders})`
-    ).all(...top.map((t) => t.id));
-    const entryById = /* @__PURE__ */ new Map();
-    for (const row of hydrated) {
-      entryById.set(row.id, this.rowToEntry(row));
-    }
-    const scored = [];
-    for (const candidate of top) {
-      const entry = entryById.get(candidate.id);
-      if (!entry) continue;
-      const hit = { entry, score: candidate.score, providerId };
-      if (includeVectors) hit.vector = candidate.vector;
-      scored.push(hit);
-    }
-    return scored;
-  }
-  /**
-   * Page through entries, newest first.
-   *
-   * Ordering is `(updated_at, id)` DESC — `updated_at` alone is not unique, so
-   * without the id tiebreak two entries written in the same millisecond can
-   * swap places between calls and a paging caller silently skips one.
-   *
-   * Pagination is keyset (`after`), not offset, because the only caller that
-   * pages is `forgetStaleSageMirrors`, which *deletes as it walks*. Under
-   * `OFFSET` every deletion shifts the remaining rows left and the next page
-   * skips exactly as many entries as were removed. Keyset is immune: it
-   * resumes from a position, and the rows a deletion removes are ones the
-   * sweep has already passed.
-   */
-  list(opts = {}) {
-    this.assertOpen();
-    const where = [];
-    const params = [];
-    if (opts.scope !== void 0) {
-      where.push("scope = ?");
-      params.push(opts.scope);
-    }
-    if (opts.kind !== void 0) {
-      where.push("kind = ?");
-      params.push(opts.kind);
-    }
-    if (opts.after) {
-      where.push("(updated_at < ? OR (updated_at = ? AND id < ?))");
-      params.push(opts.after.updatedAt, opts.after.updatedAt, opts.after.id);
-    }
-    const sql = `SELECT * FROM entries ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
-                 ORDER BY updated_at DESC, id DESC LIMIT ?`;
-    params.push(opts.limit ?? 100);
-    const rows = this.db.prepare(sql).all(...params);
-    return rows.map((r) => this.rowToEntry(r));
-  }
-  async reindexAll() {
-    this.assertOpen();
-    return withFileLock(
-      this.lockPath,
-      async () => {
-        const rows = this.db.prepare("SELECT id, text FROM entries").all();
-        let processed = 0;
-        let errors = 0;
-        for (const row of rows) {
-          try {
-            const result = await this.provider.embed([row.text]);
-            const v = result[0];
-            if (!v) {
-              errors++;
-              continue;
-            }
-            const now = (/* @__PURE__ */ new Date()).toISOString();
-            this.db.prepare(
-              `INSERT INTO vectors (entry_id, provider_id, dimensions, vector, created_at)
-                 VALUES (?, ?, ?, ?, ?)
-                 ON CONFLICT(entry_id, provider_id) DO UPDATE SET
-                   vector = excluded.vector,
-                   dimensions = excluded.dimensions,
-                   created_at = excluded.created_at`
-            ).run(row.id, this.provider.id, v.length, encodeVector(v), now);
-            this.cacheVector(row.text, v, now);
-            processed++;
-          } catch {
-            errors++;
-          }
-        }
-        return { processed, errors };
-      },
-      { timeoutMs: 6e4 }
-    );
-  }
-  stats() {
-    this.assertOpen();
-    const entryCount = this.db.prepare("SELECT COUNT(*) AS n FROM entries").get().n;
-    const vectorCount = this.db.prepare("SELECT COUNT(*) AS n FROM vectors").get().n;
-    const providerRows = this.db.prepare("SELECT DISTINCT provider_id FROM vectors").all();
-    return {
-      entries: entryCount,
-      vectors: vectorCount,
-      providers: providerRows.map((r) => r.provider_id),
-      modelAvailable: true,
-      modelId: this.provider.id,
-      dimensions: this.provider.dimensions
-    };
-  }
-  /**
-   * Embedding-cache diagnostics — entries, hit/miss counters, oldest entry.
-   * Useful for the WebUI's vector-memory panel and for diagnosing the
-   * "why is search slow?" question.
-   */
-  cacheStats() {
-    this.assertOpen();
-    const entries = this.db.prepare("SELECT COUNT(*) AS n FROM embedding_cache").get().n;
-    const providers = this.db.prepare("SELECT COUNT(DISTINCT provider_id) AS n FROM embedding_cache").get().n;
-    const totalUseCount = this.db.prepare("SELECT COALESCE(SUM(use_count), 0) AS n FROM embedding_cache").get().n;
-    const oldest = this.db.prepare("SELECT MIN(last_used_at) AS t FROM embedding_cache").get();
-    return {
-      entries,
-      providers,
-      totalUseCount,
-      oldestLastUsedAt: oldest?.t ?? null
-    };
-  }
-  /**
-   * LRU-evict the embedding cache down to `keepMostRecent` rows. The
-   * `embedding_cache` table is independent of `entries`, so a sweep here
-   * only removes cached vectors — never stored entries. Called by hosts
-   * that want to bound cache growth on long-lived processes.
-   */
-  async evictCache(keepMostRecent) {
-    this.assertOpen();
-    if (keepMostRecent < 0) {
-      throw new Error("evictCache: keepMostRecent must be >= 0");
-    }
-    return withFileLock(
-      this.lockPath,
-      async () => {
-        const total = this.db.prepare("SELECT COUNT(*) AS n FROM embedding_cache").get().n;
-        if (total <= keepMostRecent) return { removed: 0 };
-        const toRemove = total - keepMostRecent;
-        const stmt = this.db.prepare(
-          `DELETE FROM embedding_cache
-            WHERE content_hash IN (
-              SELECT content_hash FROM embedding_cache
-               ORDER BY last_used_at ASC
-               LIMIT ?
-            )`
-        );
-        const info = stmt.run(Math.min(toRemove, CACHE_EVICT_BATCH));
-        return { removed: Number(info.changes) };
-      },
-      { timeoutMs: DEFAULT_LOCK_TIMEOUT_MS }
+  };
+}
+function wrapMemoryPortWithVectorRecall(port, options) {
+  const recall = options.vectorRecall ?? asVectorRecallProviderAdapter(options.store);
+  const materializeFor = (searchOpts) => async (sageId) => {
+    const surface = port.getCapability(SAGE_SURFACE_CAPABILITY);
+    if (!surface?.getSage) return void 0;
+    const memory = await surface.getSage(sageId);
+    if (!memory) return void 0;
+    return isSageVisibleForSearch(memory, searchOpts) ? memory : void 0;
+  };
+  const fusionOptions = (searchOpts) => ({
+    vectorRecall: recall,
+    materializeVectorOnly: materializeFor(searchOpts),
+    ...options.weight !== void 0 ? { vectorWeight: options.weight } : {},
+    ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
+    ...options.vectorOnlyThreshold !== void 0 ? { vectorOnlyThreshold: options.vectorOnlyThreshold } : {},
+    ...options.maxMaterializations !== void 0 ? { maxMaterializations: options.maxMaterializations } : {},
+    ...searchOpts?.limit !== void 0 ? { limit: searchOpts.limit } : {}
+  });
+  const callerOwnsFusion = (searchOpts) => Boolean(searchOpts?.vectorRecall);
+  const wrapSearchSage = (original) => async (query, searchOpts) => {
+    const opts = searchOpts;
+    const lexical = await original(query, searchOpts);
+    if (callerOwnsFusion(opts)) return lexical;
+    const fused = await augmentLexicalWithVectorRecall(query, lexical, fusionOptions(opts));
+    return fused.map((hit) => hit.memory);
+  };
+  const wrapSearchWithBreakdown = (original) => async (query, searchOpts) => {
+    const opts = searchOpts;
+    const lexicalHits = await original(query, searchOpts);
+    if (callerOwnsFusion(opts)) return lexicalHits;
+    return augmentLexicalWithVectorRecall(
+      query,
+      lexicalHits.map((hit) => hit.memory),
+      fusionOptions(opts)
     );
-  }
-  close() {
-    if (this.closed) return;
-    this.closed = true;
-    this.db.close();
-  }
-  assertOpen() {
-    if (this.closed) throw new Error("VectorMemoryStore is closed");
-  }
-  rowToEntry(row, vectorRow) {
-    const summaryValue = row.summary;
-    const entry = {
-      id: row.id,
-      text: row.text,
-      summary: summaryValue ?? void 0,
-      metadata: safeParseJson(row.metadata, {}),
-      tags: safeParseJson(row.tags, []),
-      scope: row.scope,
-      kind: row.kind,
-      contentHash: row.content_hash,
-      createdAt: row.created_at,
-      updatedAt: row.updated_at,
-      providerId: vectorRow?.provider_id ?? "",
-      dimensions: vectorRow?.dimensions ?? 0
-    };
-    if (vectorRow?.vector) {
-      entry.vector = decodeVector(vectorRow.vector);
+  };
+  const wrapped = Object.create(
+    Object.getPrototypeOf(port),
+    Object.getOwnPropertyDescriptors(port)
+  );
+  wrapped.getCapability = (capability) => {
+    if (capability.id === SAGE_RETRIEVAL_CAPABILITY.id) {
+      const original = port.getCapability(capability);
+      if (!original) return void 0;
+      return {
+        ...original,
+        searchSage: wrapSearchSage(original.searchSage),
+        ...original.searchSageWithBreakdown ? {
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
+            original.searchSageWithBreakdown
+          )
+        } : {}
+      };
     }
-    return entry;
-  }
-  async syncFromSage(sage) {
-    this.assertOpen();
-    const memories = await sage.listActiveMemories({ limit: Number.POSITIVE_INFINITY });
-    let indexed = 0;
-    let skipped = 0;
-    let failed = 0;
-    const errors = [];
-    for (const memory of memories) {
-      try {
-        const hash = _VectorMemoryStore.contentHash(memory.text);
-        const existing = this.findByContentHash(hash);
-        if (existing) {
-          skipped++;
-          continue;
-        }
-        await this.rememberUnlocked({
-          text: memory.text,
-          summary: memory.summary ?? void 0,
-          metadata: { source: "sage", sageId: memory.id, ...memory.metadata ?? {} },
-          tags: memory.tags ?? [],
-          scope: "project",
-          kind: "note"
-        });
-        indexed++;
-      } catch (err) {
-        failed++;
-        errors.push({ memoryId: memory.id, message: errMsg(err) });
-      }
+    if (capability.id === SAGE_SURFACE_CAPABILITY.id) {
+      const original = port.getCapability(capability);
+      if (!original) return void 0;
+      return {
+        ...original,
+        searchSage: wrapSearchSage(original.searchSage),
+        ...original.searchSageWithBreakdown ? {
+          searchSageWithBreakdown: wrapSearchWithBreakdown(
+            original.searchSageWithBreakdown
+          )
+        } : {}
+      };
     }
-    return { scanned: memories.length, indexed, skipped, failed, errors };
-  }
-};
-function fallbackHashingProvider(dimensions) {
-  return new HashingEmbeddingProvider({ dimensions });
-}
-function safeParseJson(value, fallback) {
-  if (typeof value !== "string") return fallback;
-  try {
-    return JSON.parse(value);
-  } catch {
-    return fallback;
-  }
-}
-function errMsg(err) {
-  return err instanceof Error ? err.message : String(err);
+    return port.getCapability(capability);
+  };
+  return wrapped;
 }
 
+// src/sage-sync.ts
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+import { getSageSurface as getSageSurface2 } from "@wrongstack/sage";
+
 // src/sage-sync-source.ts
 var DEFAULT_PAGE_SIZE = 500;
 var HARD_FLOOR_PAGE = 1;
@@ -840,7 +401,7 @@ function createSageSurfaceSyncSource(sage, opts = {}) {
             }
           });
         }
-        if (!page.nextCursor || rows.length === 0) break;
+        if (!page.nextCursor) break;
         if (rows.length === 0) {
           noProgressPages++;
           if (noProgressPages > 3) break;
@@ -858,9 +419,6 @@ function clamp(value, min, max) {
 }
 
 // src/sage-sync.ts
-import { getSageSurface } from "@wrongstack/sage";
-import * as fs2 from "node:fs";
-import * as path2 from "node:path";
 var SAGE_SYNC_MARKER_FILENAME = "sage-sync.complete.json";
 var RUNNING_STALE_MS = 10 * 60 * 1e3;
 async function startFirstBootSageSync(opts) {
@@ -901,7 +459,7 @@ async function startFirstBootSageSync(opts) {
         return { synced: false, reason: "provider-unavailable" };
       }
     }
-    const surface = getSageSurface(memoryStore);
+    const surface = getSageSurface2(memoryStore);
     if (!surface) {
       log?.debug?.("vector-memory sage sync skipped: memory store exposes no SAGE surface");
       return { synced: false, reason: "no-sage-surface" };
@@ -1033,613 +591,1049 @@ function counts(report) {
   };
 }
 
-// src/tools.ts
-function createVectorMemoryTools(store) {
-  return [
-    vectorMemoryRememberTool(store),
-    vectorMemorySearchTool(store),
-    vectorMemoryStatsTool(store),
-    vectorMemoryForgetTool(store)
-  ];
+// src/schema.ts
+var VECTOR_SCHEMA_VERSION = 2;
+var VECTOR_PROVIDER_KEY = "active_provider_id";
+var VECTOR_DIMENSIONS_KEY = "active_provider_dimensions";
+function initVectorSchema(db) {
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA synchronous = NORMAL");
+  db.exec("PRAGMA busy_timeout = 30000");
+  db.exec("PRAGMA temp_store = MEMORY");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS entries (
+      id TEXT PRIMARY KEY,
+      text TEXT NOT NULL,
+      summary TEXT,
+      metadata TEXT NOT NULL DEFAULT '{}',
+      tags TEXT NOT NULL DEFAULT '[]',
+      scope TEXT NOT NULL DEFAULT 'project',
+      kind TEXT NOT NULL DEFAULT 'note',
+      content_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_scope ON entries(scope)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_kind ON entries(kind)");
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_hash ON entries(content_hash)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_entries_updated ON entries(updated_at DESC)");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS vectors (
+      entry_id TEXT NOT NULL,
+      provider_id TEXT NOT NULL,
+      dimensions INTEGER NOT NULL,
+      vector BLOB NOT NULL,
+      created_at TEXT NOT NULL,
+      PRIMARY KEY (entry_id, provider_id),
+      FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
+    );
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_vectors_provider ON vectors(provider_id)");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS embedding_cache (
+      content_hash TEXT NOT NULL,
+      provider_id TEXT NOT NULL,
+      dimensions INTEGER NOT NULL,
+      vector BLOB NOT NULL,
+      text TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      last_used_at TEXT NOT NULL,
+      use_count INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (content_hash, provider_id, dimensions)
+    );
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_cache_last_used ON embedding_cache(last_used_at)");
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+      id UNINDEXED, text, tags, content='entries', content_rowid='rowid'
+    );
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+      INSERT INTO entries_fts(rowid, text, tags)
+      VALUES (new.rowid, new.text, new.tags);
+    END;
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+      INSERT INTO entries_fts(entries_fts, rowid, text, tags)
+      VALUES('delete', old.rowid, old.text, old.tags);
+    END;
+  `);
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+      INSERT INTO entries_fts(entries_fts, rowid, text, tags)
+      VALUES('delete', old.rowid, old.text, old.tags);
+      INSERT INTO entries_fts(rowid, text, tags)
+      VALUES (new.rowid, new.text, new.tags);
+    END;
+  `);
 }
-function vectorMemoryRememberTool(store) {
-  return {
-    name: "vector_memory_remember",
-    category: "Memory",
-    description: "Persist a piece of knowledge into the local vector memory store. The text is embedded with the active embedding provider (transformers.js when available, otherwise the sage hashing provider). Returns the new entry id and whether an embedding was stored.",
-    usageHint: "Store text you want to find later by *meaning*, not just exact keywords. Embeddings happen locally \u2014 no project text leaves the machine.",
-    permission: "confirm",
-    mutating: true,
-    riskTier: "standard",
-    timeoutMs: 5e3,
-    capabilities: ["memory.write"],
-    icon: "settings",
-    inputSchema: {
-      type: "object",
-      properties: {
-        text: { type: "string", minLength: 1, description: "The text to embed and store." },
-        summary: { type: "string", description: "Optional short label." },
-        tags: {
-          type: "array",
-          items: { type: "string" },
-          description: "Optional tags for later filtering."
-        },
-        scope: {
-          type: "string",
-          enum: ["project", "user", "session"],
-          description: "Visibility scope. Defaults to `project`."
-        },
-        kind: {
-          type: "string",
-          enum: ["note", "fact", "summary", "snippet", "link"],
-          description: "Entry kind. Defaults to `note`."
-        },
-        metadata: {
-          type: "object",
-          additionalProperties: true,
-          description: "Free-form metadata persisted as JSON."
-        }
-      },
-      required: ["text"],
-      additionalProperties: false
-    },
-    execute: async (input) => {
-      const entry = await store.remember(input);
-      return { id: entry.id, hasVector: entry.vector !== void 0 };
-    }
-  };
+function upsertEmbeddingCache(db, row) {
+  db.prepare(
+    `INSERT INTO embedding_cache
+       (content_hash, provider_id, dimensions, vector, text, created_at, last_used_at, use_count)
+     VALUES (?, ?, ?, ?, ?, ?, ?, 1)
+     ON CONFLICT(content_hash, provider_id, dimensions) DO UPDATE SET
+       last_used_at = excluded.last_used_at,
+       use_count = embedding_cache.use_count + 1,
+       vector = excluded.vector`
+  ).run(row.contentHash, row.providerId, row.dimensions, row.vector, row.text, row.now, row.now);
 }
-function vectorMemorySearchTool(store) {
-  return {
-    name: "vector_memory_search",
-    category: "Memory",
-    description: "Semantic search over the vector memory store. Embeds the query with the active provider and returns the top-k entries ranked by cosine similarity. Returns an empty list when the embedding provider is unavailable \u2014 callers should fall back to lexical search.",
-    usageHint: "Use when you want results ranked by meaning. Pairs well with sage `memory_search` for keyword precision.",
-    permission: "auto",
-    mutating: false,
-    riskTier: "safe",
-    timeoutMs: 5e3,
-    capabilities: ["memory.read"],
-    icon: "search",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", minLength: 1, description: "The natural-language query." },
-        limit: {
-          type: "number",
-          minimum: 1,
-          maximum: 100,
-          description: "Max results (default 10)."
-        },
-        threshold: {
-          type: "number",
-          minimum: 0,
-          maximum: 1,
-          description: "Minimum cosine similarity. Results below the floor are dropped."
-        },
-        scope: {
-          type: "string",
-          enum: ["project", "user", "session"],
-          description: "Restrict to a scope."
-        },
-        kind: {
-          type: "string",
-          enum: ["note", "fact", "summary", "snippet", "link"],
-          description: "Restrict to a kind."
-        }
-      },
-      required: ["query"],
-      additionalProperties: false
-    },
-    execute: async (input) => {
-      const hits = await store.search(input.query, {
-        limit: input.limit !== void 0 ? input.limit : void 0,
-        threshold: input.threshold !== void 0 ? input.threshold : void 0,
-        scope: input.scope,
-        kind: input.kind
+function lookupEmbeddingCache(db, contentHash, providerId, dimensions, now) {
+  const row = db.prepare(
+    `SELECT vector FROM embedding_cache
+        WHERE content_hash = ? AND provider_id = ? AND dimensions = ?
+        LIMIT 1`
+  ).get(contentHash, providerId, dimensions);
+  if (!row) return void 0;
+  try {
+    db.prepare(
+      `UPDATE embedding_cache SET last_used_at = ?, use_count = use_count + 1
+        WHERE content_hash = ? AND provider_id = ? AND dimensions = ?`
+    ).run(now, contentHash, providerId, dimensions);
+  } catch {
+  }
+  return decodeVector(row.vector);
+}
+function encodeVector(vec) {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+function decodeVector(buf) {
+  if (buf.byteLength % 4 !== 0) {
+    throw new Error(
+      `decodeVector: invalid vector byteLength ${buf.byteLength} (must be a multiple of 4)`
+    );
+  }
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const copy = new Float32Array(buf.byteLength / 4);
+  for (let i = 0; i < copy.length; i++) {
+    copy[i] = view.getFloat32(i * 4, true);
+  }
+  return copy;
+}
+
+// src/search-race.ts
+function previewText(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + "\u2026";
+}
+async function runSearchRace(query, lexical, vectorStore, options = {}) {
+  const limit = options.limit ?? 20;
+  const threshold = options.threshold ?? 0;
+  let vectorHits = [];
+  try {
+    vectorHits = await vectorStore.search(query, {
+      limit,
+      ...threshold > 0 ? { threshold } : {}
+    });
+  } catch {
+    vectorHits = [];
+  }
+  const lexicalOnly = [];
+  const vectorOnly = [];
+  const overlap = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  const lexicalCapped = lexical.slice(0, limit);
+  for (let i = 0; i < lexicalCapped.length; i++) {
+    const mem = lexicalCapped[i];
+    const score = lexicalCapped.length <= 1 ? 1 : 1 - i / Math.max(1, lexicalCapped.length - 1);
+    const id = mem.id;
+    seenIds.add(id);
+    overlap.push({
+      id,
+      lexicalScore: score,
+      vectorScore: null,
+      // patched below when a vector hit carries this id
+      preview: previewText(mem.text, 140)
+    });
+  }
+  const overlapById = /* @__PURE__ */ new Map();
+  for (const row of overlap) overlapById.set(row.id, row);
+  for (const hit of vectorHits) {
+    const sageId = hit.entry.metadata?.["sageId"];
+    if (typeof sageId !== "string") continue;
+    const existing = overlapById.get(sageId);
+    if (existing) {
+      if (existing.vectorScore === null) {
+        existing.vectorScore = hit.score;
+      }
+      continue;
+    }
+    if (seenIds.has(sageId)) continue;
+    seenIds.add(sageId);
+    vectorOnly.push({
+      id: sageId,
+      lexicalScore: null,
+      vectorScore: hit.score,
+      preview: previewText(hit.entry.text, 140)
+    });
+  }
+  const finalOverlap = [];
+  for (const row of overlap) {
+    if (row.vectorScore === null) {
+      lexicalOnly.push({
+        id: row.id,
+        lexicalScore: row.lexicalScore,
+        vectorScore: null,
+        preview: row.preview
       });
-      return {
-        hits: hits.map((h) => ({
-          id: h.entry.id,
-          score: h.score,
-          text: h.entry.text,
-          summary: h.entry.summary ?? void 0,
-          tags: h.entry.tags
-        }))
-      };
+    } else {
+      finalOverlap.push(row);
     }
-  };
-}
-function vectorMemoryStatsTool(store) {
-  return {
-    name: "vector_memory_stats",
-    category: "Memory",
-    description: "Return counts, providers, and dimensions for the local vector memory store.",
-    usageHint: "Cheap diagnostic \u2014 safe to call any time.",
-    permission: "auto",
-    mutating: false,
-    riskTier: "safe",
-    timeoutMs: 1e3,
-    capabilities: ["memory.read"],
-    icon: "search",
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    },
-    execute: async () => store.stats()
-  };
-}
-function vectorMemoryForgetTool(store) {
+  }
+  const lexicalCount = lexicalOnly.length + finalOverlap.length;
+  const vectorCount = vectorOnly.length + finalOverlap.length;
+  const denom = Math.max(lexicalCount, vectorCount, 1);
   return {
-    name: "vector_memory_forget",
-    category: "Memory",
-    description: "Remove an entry (and its vector) from the vector memory store.",
-    usageHint: "Hard delete \u2014 no soft-delete tombstone. Use `vector_memory_search` to find the id first if you only have text.",
-    permission: "confirm",
-    mutating: true,
-    riskTier: "standard",
-    timeoutMs: 1e3,
-    capabilities: ["memory.write"],
-    icon: "settings",
-    inputSchema: {
-      type: "object",
-      properties: {
-        id: {
-          type: "string",
-          minLength: 1,
-          description: "Entry id returned by `vector_memory_remember`."
-        }
-      },
-      required: ["id"],
-      additionalProperties: false
-    },
-    execute: async (input) => ({ removed: await store.forget(input.id) })
+    query,
+    lexicalOnly,
+    vectorOnly,
+    overlap: finalOverlap,
+    metrics: {
+      lexicalCount,
+      vectorCount,
+      overlapCount: finalOverlap.length,
+      lexicalOnlyRatio: lexicalCount === 0 ? 0 : lexicalOnly.length / lexicalCount,
+      vectorOnlyRatio: vectorCount === 0 ? 0 : vectorOnly.length / vectorCount,
+      agreementRatio: finalOverlap.length / denom
+    }
   };
 }
 
-// src/sage-fusion.ts
-var DEFAULT_RRF_K = 60;
-var DEFAULT_VECTOR_WEIGHT = 0.3;
-function lexicalRankScore(index, total) {
-  if (total <= 1) return 1;
-  return 1 - index / Math.max(1, total - 1);
+// src/store.ts
+import { createHash, randomUUID } from "node:crypto";
+import * as fs3 from "node:fs";
+import * as path3 from "node:path";
+import { withFileLock } from "@wrongstack/core/utils";
+import { loadRuntimeDatabaseSync } from "@wrongstack/persistence";
+import { cosineSimilarity, HashingEmbeddingProvider } from "@wrongstack/sage";
+var DEFAULT_SEARCH_LIMIT = 10;
+function normalizeLimit(limit) {
+  if (limit === void 0 || !Number.isFinite(limit)) return DEFAULT_SEARCH_LIMIT;
+  const floored = Math.floor(limit);
+  return floored < 1 ? DEFAULT_SEARCH_LIMIT : floored;
 }
-async function fuseWithVectorMemory(query, lexical, options = {}) {
-  const weight = clamp01(options.vectorWeight ?? DEFAULT_VECTOR_WEIGHT);
-  const k = options.rrfK ?? DEFAULT_RRF_K;
-  const limit = options.limit ?? 25;
-  const vectorOnlyThreshold = options.vectorOnlyThreshold ?? 0;
-  let vectorHits = [];
-  if (options.vectorHits) {
-    vectorHits = [...options.vectorHits];
-  } else if (options.store) {
+var DEFAULT_DIRECTORY = ".wrongstack/vector-memory";
+var DEFAULT_FILENAME = "vector-memory.db";
+var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
+var CACHE_EVICT_BATCH = 256;
+var VectorMemoryStore = class _VectorMemoryStore {
+  db;
+  dbPath;
+  rootDir;
+  provider;
+  closed = false;
+  constructor(opts) {
+    if (!opts.provider) throw new Error("VectorMemoryStore: provider is required");
+    if (!opts.projectRoot) throw new Error("VectorMemoryStore: projectRoot is required");
+    this.provider = opts.provider;
+    const dir = opts.directory ?? DEFAULT_DIRECTORY;
+    const filename = opts.filename ?? DEFAULT_FILENAME;
+    if (path3.isAbsolute(dir)) {
+      throw new Error("Vector memory directory must be project-relative.");
+    }
+    const rootDir = path3.resolve(opts.projectRoot, dir);
+    const rel = path3.relative(path3.resolve(opts.projectRoot), rootDir);
+    if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+      throw new Error("Vector memory directory must stay inside the project root.");
+    }
+    fs3.mkdirSync(rootDir, { recursive: true });
+    this.rootDir = rootDir;
+    this.dbPath = path3.join(rootDir, filename);
+    const Database = loadRuntimeDatabaseSync();
+    this.db = new Database(this.dbPath);
+    initVectorSchema(this.db);
+    this.recordActiveProvider();
+  }
+  /**
+   * Absolute path of the store's data directory (the resolved
+   * `opts.directory`, default `.wrongstack/vector-memory`). Hosts use this
+   * to place sidecar state (e.g. the first-boot SAGE sync marker) next to
+   * the db instead of re-deriving the path and drifting from it.
+   */
+  get directory() {
+    return this.rootDir;
+  }
+  /**
+   * Absolute path of the SQLite database file. Hosts use this to take a
+   * file-level lock that covers all mutating operations (see
+   * `withFileLock(this.dbPath + '.lock', …)`).
+   */
+  get databasePath() {
+    return this.dbPath;
+  }
+  /** The lockfile path used to serialize mutating operations. */
+  get lockPath() {
+    return `${this.dbPath}.lock`;
+  }
+  get activeProviderId() {
+    const row = this.db.prepare("SELECT value FROM schema_meta WHERE key = ?").get(VECTOR_PROVIDER_KEY);
+    return row?.value ?? this.provider.id;
+  }
+  recordActiveProvider() {
+    this.db.exec("BEGIN");
     try {
-      vectorHits = await options.store.search(query, {
-        ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
-        limit: Math.max(limit * 2, 50)
-      });
+      this.db.prepare(
+        `INSERT INTO schema_meta (key, value) VALUES (?, ?)
+           ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      ).run(VECTOR_PROVIDER_KEY, this.provider.id);
+      this.db.prepare(
+        `INSERT INTO schema_meta (key, value) VALUES (?, ?)
+           ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+      ).run(VECTOR_DIMENSIONS_KEY, String(this.provider.dimensions));
+      this.db.exec("COMMIT");
+    } catch (e) {
+      this.db.exec("ROLLBACK");
+      throw e;
+    }
+  }
+  static contentHash(text) {
+    return createHash("sha256").update(text.normalize("NFKC").trim()).digest("hex");
+  }
+  /**
+   * Look up a vector for `text` in the provider-level embedding cache.
+   * Cache hit returns the cached vector (no ONNX pass). Miss returns
+   * `undefined`.
+   */
+  cachedVector(text, now) {
+    return lookupEmbeddingCache(
+      this.db,
+      _VectorMemoryStore.contentHash(text),
+      this.provider.id,
+      this.provider.dimensions,
+      now
+    );
+  }
+  /** Persist `vec` for `text` to the embedding cache. */
+  cacheVector(text, vec, now) {
+    upsertEmbeddingCache(this.db, {
+      contentHash: _VectorMemoryStore.contentHash(text),
+      providerId: this.provider.id,
+      dimensions: vec.length,
+      vector: encodeVector(vec),
+      text,
+      now
+    });
+  }
+  /**
+   * Embed `text`, hitting the provider-level cache first. Cache miss falls
+   * through to the configured provider and writes the result back. Returns
+   * `undefined` when the provider fails — the caller can persist the entry
+   * without a vector (fail-open).
+   */
+  async embedWithCache(text) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const cached = this.cachedVector(text, now);
+    if (cached) return cached;
+    try {
+      const result = await this.provider.embed([text]);
+      const vec = result[0];
+      if (vec) this.cacheVector(text, vec, now);
+      return vec;
     } catch {
-      vectorHits = [];
+      return void 0;
     }
   }
-  const sageById = /* @__PURE__ */ new Map();
-  for (const memory of lexical) sageById.set(memory.id, memory);
-  const lexicalRanked = lexical.map((memory, index) => ({
-    memory,
-    rankScore: lexicalRankScore(index, lexical.length),
-    lexicalScore: lexicalRankScore(index, lexical.length)
-  }));
-  const vectorRanked = [];
-  const seenVectorSageIds = /* @__PURE__ */ new Set();
-  for (let i = 0; i < vectorHits.length; i++) {
-    const hit = vectorHits[i];
-    const sageId = hit.entry.metadata?.["sageId"];
-    if (typeof sageId !== "string" || seenVectorSageIds.has(sageId)) continue;
-    const memory = sageById.get(sageId);
-    if (!memory) continue;
-    seenVectorSageIds.add(sageId);
-    vectorRanked.push({ memory, vectorScore: hit.score });
+  /**
+   * Look up an existing entry by `content_hash`. Returns `undefined` when
+   * the entry is not present. Used by `remember()` to make writes idempotent
+   * and by `syncFromSage()` to skip already-indexed SAGE memories.
+   */
+  findByContentHash(contentHash) {
+    this.assertOpen();
+    const row = this.db.prepare("SELECT * FROM entries WHERE content_hash = ? LIMIT 1").get(contentHash);
+    if (!row) return void 0;
+    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(row.id);
+    return this.rowToEntry(row, vectorRow);
   }
-  const fused = /* @__PURE__ */ new Map();
-  for (let i = 0; i < lexicalRanked.length; i++) {
-    const c = lexicalRanked[i];
-    const rrf = (1 - weight) * (1 / (k + i + 1));
-    fused.set(c.memory.id, {
-      memory: c.memory,
-      vectorScore: null,
-      lexicalScore: c.lexicalScore,
-      finalScore: rrf,
-      source: "lexical"
+  /**
+   * Look up the entry mirroring a given SAGE memory id (i.e. the entry
+   * whose `metadata.sageId` equals `sageId`). Returns `undefined` when
+   * no such entry exists. Used by the event-driven mirror to delete
+   * vector entries on SAGE delete events (the emitter knows the SAGE
+   * id, not the vector entry id).
+   *
+   * Index lookup is `json_extract(metadata, '$.sageId')` — the metadata
+   * column is the JSON blob `syncFromSage` writes, so this avoids a
+   * full table scan.
+   */
+  findBySageId(sageId) {
+    this.assertOpen();
+    const row = this.db.prepare(
+      `SELECT * FROM entries
+          WHERE json_extract(metadata, '$.sageId') = ?
+          ORDER BY updated_at DESC
+          LIMIT 1`
+    ).get(sageId);
+    if (!row) return void 0;
+    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(row.id);
+    return this.rowToEntry(row, vectorRow);
+  }
+  /**
+   * Persist a new entry. Idempotent: if an entry with the same
+   * `content_hash` already exists, that entry is returned unchanged
+   * instead of inserting a duplicate. Mutating ops are wrapped in
+   * `withFileLock` so two processes cannot race the dedup check.
+   */
+  async remember(input) {
+    this.assertOpen();
+    if (!input.text || input.text.trim().length === 0) {
+      throw new Error("VectorMemoryStore.remember: text must be non-empty");
+    }
+    return withFileLock(this.lockPath, () => this.rememberUnlocked(input), {
+      timeoutMs: DEFAULT_LOCK_TIMEOUT_MS
     });
   }
-  for (let i = 0; i < vectorRanked.length; i++) {
-    const v = vectorRanked[i];
-    const rrf = weight * (1 / (k + i + 1));
-    const existing = fused.get(v.memory.id);
-    if (existing) {
-      existing.finalScore += rrf;
-      existing.vectorScore = v.vectorScore;
-      existing.source = "both";
-    } else if (v.vectorScore >= vectorOnlyThreshold) {
-      fused.set(v.memory.id, {
-        memory: v.memory,
-        vectorScore: v.vectorScore,
-        lexicalScore: null,
-        finalScore: rrf,
-        source: "vector"
-      });
+  async rememberUnlocked(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const contentHash = _VectorMemoryStore.contentHash(input.text);
+    const existing = this.findByContentHash(contentHash);
+    if (existing) return existing;
+    const metadata = input.metadata ?? {};
+    const tags = input.tags ?? [];
+    const scope = input.scope ?? "project";
+    const kind = input.kind ?? "note";
+    const id = randomUUID();
+    const vector = await this.embedWithCache(input.text);
+    const providerId = vector ? this.provider.id : void 0;
+    this.db.exec("BEGIN");
+    try {
+      this.db.prepare(
+        `INSERT INTO entries
+            (id, text, summary, metadata, tags, scope, kind, content_hash, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).run(
+        id,
+        input.text,
+        input.summary ?? null,
+        JSON.stringify(metadata),
+        JSON.stringify(tags),
+        scope,
+        kind,
+        contentHash,
+        now,
+        now
+      );
+      if (vector && providerId) {
+        this.db.prepare(
+          `INSERT INTO vectors (entry_id, provider_id, dimensions, vector, created_at)
+             VALUES (?, ?, ?, ?, ?)
+             ON CONFLICT(entry_id, provider_id) DO UPDATE SET
+               vector = excluded.vector,
+               dimensions = excluded.dimensions,
+               created_at = excluded.created_at`
+        ).run(id, providerId, vector.length, encodeVector(vector), now);
+      }
+      this.db.exec("COMMIT");
+    } catch (e) {
+      this.db.exec("ROLLBACK");
+      throw e;
+    }
+    const result = {
+      id,
+      text: input.text,
+      summary: input.summary ?? void 0,
+      metadata,
+      tags,
+      scope,
+      kind,
+      contentHash,
+      createdAt: now,
+      updatedAt: now,
+      providerId: providerId ?? "",
+      dimensions: vector?.length ?? 0
+    };
+    if (vector) result.vector = vector;
+    return result;
+  }
+  get(id) {
+    this.assertOpen();
+    const row = this.db.prepare("SELECT * FROM entries WHERE id = ?").get(id);
+    if (!row) return void 0;
+    const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(id);
+    return this.rowToEntry(row, vectorRow);
+  }
+  /** Hard-delete an entry by id. Wrapped in `withFileLock` for cross-process safety. */
+  async forget(id) {
+    this.assertOpen();
+    return withFileLock(
+      this.lockPath,
+      async () => {
+        this.db.exec("BEGIN");
+        try {
+          const info = this.db.prepare("DELETE FROM entries WHERE id = ?").run(id);
+          this.db.exec("COMMIT");
+          return info.changes > 0;
+        } catch (e) {
+          this.db.exec("ROLLBACK");
+          throw e;
+        }
+      },
+      { timeoutMs: DEFAULT_LOCK_TIMEOUT_MS }
+    );
+  }
+  async search(query, opts = {}) {
+    this.assertOpen();
+    const limit = normalizeLimit(opts.limit);
+    const threshold = opts.threshold ?? 0;
+    const includeVectors = opts.includeVectors === true;
+    if (typeof query !== "string" || query.trim().length === 0) return [];
+    const queryVec = await this.embedWithCache(query);
+    if (!queryVec || queryVec.length === 0) return [];
+    const providerId = this.provider.id;
+    const dimensions = this.provider.dimensions;
+    const filters = ["v.provider_id = ?", "v.dimensions = ?"];
+    const params = [providerId, dimensions];
+    if (opts.scope !== void 0) {
+      filters.push("e.scope = ?");
+      params.push(opts.scope);
+    }
+    if (opts.kind !== void 0) {
+      filters.push("e.kind = ?");
+      params.push(opts.kind);
+    }
+    const scanRows = this.db.prepare(
+      `SELECT e.id AS id, v.vector AS vec_blob
+           FROM entries e
+           JOIN vectors v ON v.entry_id = e.id
+          WHERE ${filters.join(" AND ")}`
+    ).all(...params);
+    const top = [];
+    for (const row of scanRows) {
+      const vec = decodeVector(row.vec_blob);
+      const raw = cosineSimilarity(queryVec, vec);
+      const score = Math.max(0, Math.min(1, raw));
+      if (!Number.isFinite(score) || score < threshold) continue;
+      if (top.length >= limit && score <= (top[top.length - 1]?.score ?? 0)) continue;
+      let at = top.length;
+      while (at > 0 && (top[at - 1]?.score ?? 0) < score) at--;
+      top.splice(at, 0, { id: row.id, score, vector: vec });
+      if (top.length > limit) top.length = limit;
+    }
+    if (top.length === 0) return [];
+    const placeholders = top.map(() => "?").join(",");
+    const hydrated = this.db.prepare(
+      `SELECT id, text, summary, metadata, tags, scope, kind,
+                content_hash, created_at, updated_at
+           FROM entries WHERE id IN (${placeholders})`
+    ).all(...top.map((t) => t.id));
+    const entryById = /* @__PURE__ */ new Map();
+    for (const row of hydrated) {
+      entryById.set(row.id, this.rowToEntry(row));
+    }
+    const scored = [];
+    for (const candidate of top) {
+      const entry = entryById.get(candidate.id);
+      if (!entry) continue;
+      const hit = { entry, score: candidate.score, providerId };
+      if (includeVectors) hit.vector = candidate.vector;
+      scored.push(hit);
+    }
+    return scored;
+  }
+  /**
+   * Page through entries, newest first.
+   *
+   * Ordering is `(updated_at, id)` DESC — `updated_at` alone is not unique, so
+   * without the id tiebreak two entries written in the same millisecond can
+   * swap places between calls and a paging caller silently skips one.
+   *
+   * Pagination is keyset (`after`), not offset, because the only caller that
+   * pages is `forgetStaleSageMirrors`, which *deletes as it walks*. Under
+   * `OFFSET` every deletion shifts the remaining rows left and the next page
+   * skips exactly as many entries as were removed. Keyset is immune: it
+   * resumes from a position, and the rows a deletion removes are ones the
+   * sweep has already passed.
+   */
+  list(opts = {}) {
+    this.assertOpen();
+    const where = [];
+    const params = [];
+    if (opts.scope !== void 0) {
+      where.push("scope = ?");
+      params.push(opts.scope);
     }
-  }
-  const out = Array.from(fused.values());
-  out.sort((a, b) => b.finalScore - a.finalScore);
-  return out.slice(0, limit);
-}
-function asVectorRecallProvider(store) {
-  return {
-    async search(query, opts) {
-      const hits = await store.search(query, {
-        limit: opts.limit,
-        ...opts.threshold !== void 0 ? { threshold: opts.threshold } : {}
-      });
-      return hits.map((h) => ({
-        id: h.entry.id,
-        score: h.score,
-        text: h.entry.text,
-        ...h.entry.summary ? { summary: h.entry.summary } : {},
-        tags: h.entry.tags,
-        ...h.entry.metadata ? { metadata: h.entry.metadata } : {}
-      }));
+    if (opts.kind !== void 0) {
+      where.push("kind = ?");
+      params.push(opts.kind);
     }
-  };
-}
-function clamp01(value) {
-  if (!Number.isFinite(value)) return DEFAULT_VECTOR_WEIGHT;
-  if (value < 0) return 0;
-  if (value > 1) return 1;
-  return value;
-}
-
-// src/sage-port-wrapper.ts
-import {
-  augmentLexicalWithVectorRecall,
-  isSageVisibleForSearch,
-  SAGE_RETRIEVAL_CAPABILITY,
-  SAGE_SURFACE_CAPABILITY
-} from "@wrongstack/sage";
-function asVectorRecallProviderAdapter(store) {
-  return {
-    async search(query, opts) {
-      const hits = await store.search(query, {
-        limit: opts.limit,
-        ...opts.threshold !== void 0 ? { threshold: opts.threshold } : {}
-      });
-      return hits.map((h) => ({
-        id: h.entry.id,
-        score: h.score,
-        text: h.entry.text,
-        ...h.entry.summary ? { summary: h.entry.summary } : {},
-        tags: h.entry.tags,
-        ...h.entry.metadata ? { metadata: h.entry.metadata } : {}
-      }));
+    if (opts.after) {
+      where.push("(updated_at < ? OR (updated_at = ? AND id < ?))");
+      params.push(opts.after.updatedAt, opts.after.updatedAt, opts.after.id);
     }
-  };
-}
-function wrapMemoryPortWithVectorRecall(port, options) {
-  const recall = options.vectorRecall ?? asVectorRecallProviderAdapter(options.store);
-  const materializeFor = (searchOpts) => async (sageId) => {
-    const surface = port.getCapability(SAGE_SURFACE_CAPABILITY);
-    if (!surface?.getSage) return void 0;
-    const memory = await surface.getSage(sageId);
-    if (!memory) return void 0;
-    return isSageVisibleForSearch(memory, searchOpts) ? memory : void 0;
-  };
-  const fusionOptions = (searchOpts) => ({
-    vectorRecall: recall,
-    materializeVectorOnly: materializeFor(searchOpts),
-    ...options.weight !== void 0 ? { vectorWeight: options.weight } : {},
-    ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
-    ...options.vectorOnlyThreshold !== void 0 ? { vectorOnlyThreshold: options.vectorOnlyThreshold } : {},
-    ...options.maxMaterializations !== void 0 ? { maxMaterializations: options.maxMaterializations } : {},
-    ...searchOpts?.limit !== void 0 ? { limit: searchOpts.limit } : {}
-  });
-  const callerOwnsFusion = (searchOpts) => Boolean(searchOpts?.vectorRecall);
-  const wrapSearchSage = (original) => async (query, searchOpts) => {
-    const opts = searchOpts;
-    const lexical = await original(query, searchOpts);
-    if (callerOwnsFusion(opts)) return lexical;
-    const fused = await augmentLexicalWithVectorRecall(query, lexical, fusionOptions(opts));
-    return fused.map((hit) => hit.memory);
-  };
-  const wrapSearchWithBreakdown = (original) => async (query, searchOpts) => {
-    const opts = searchOpts;
-    const lexicalHits = await original(query, searchOpts);
-    if (callerOwnsFusion(opts)) return lexicalHits;
-    return augmentLexicalWithVectorRecall(
-      query,
-      lexicalHits.map((hit) => hit.memory),
-      fusionOptions(opts)
+    const sql = `SELECT * FROM entries ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+                 ORDER BY updated_at DESC, id DESC LIMIT ?`;
+    params.push(opts.limit ?? 100);
+    const rows = this.db.prepare(sql).all(...params);
+    return rows.map((r) => this.rowToEntry(r));
+  }
+  async reindexAll() {
+    this.assertOpen();
+    return withFileLock(
+      this.lockPath,
+      async () => {
+        const rows = this.db.prepare("SELECT id, text FROM entries").all();
+        let processed = 0;
+        let errors = 0;
+        for (const row of rows) {
+          try {
+            const result = await this.provider.embed([row.text]);
+            const v = result[0];
+            if (!v) {
+              errors++;
+              continue;
+            }
+            const now = (/* @__PURE__ */ new Date()).toISOString();
+            this.db.prepare(
+              `INSERT INTO vectors (entry_id, provider_id, dimensions, vector, created_at)
+                 VALUES (?, ?, ?, ?, ?)
+                 ON CONFLICT(entry_id, provider_id) DO UPDATE SET
+                   vector = excluded.vector,
+                   dimensions = excluded.dimensions,
+                   created_at = excluded.created_at`
+            ).run(row.id, this.provider.id, v.length, encodeVector(v), now);
+            this.cacheVector(row.text, v, now);
+            processed++;
+          } catch {
+            errors++;
+          }
+        }
+        return { processed, errors };
+      },
+      { timeoutMs: 6e4 }
     );
-  };
-  const wrapped = Object.create(
-    Object.getPrototypeOf(port),
-    Object.getOwnPropertyDescriptors(port)
-  );
-  wrapped.getCapability = (capability) => {
-    if (capability.id === SAGE_RETRIEVAL_CAPABILITY.id) {
-      const original = port.getCapability(capability);
-      if (!original) return void 0;
-      return {
-        ...original,
-        searchSage: wrapSearchSage(original.searchSage),
-        ...original.searchSageWithBreakdown ? {
-          searchSageWithBreakdown: wrapSearchWithBreakdown(
-            original.searchSageWithBreakdown
-          )
-        } : {}
-      };
-    }
-    if (capability.id === SAGE_SURFACE_CAPABILITY.id) {
-      const original = port.getCapability(capability);
-      if (!original) return void 0;
-      return {
-        ...original,
-        searchSage: wrapSearchSage(original.searchSage),
-        ...original.searchSageWithBreakdown ? {
-          searchSageWithBreakdown: wrapSearchWithBreakdown(
-            original.searchSageWithBreakdown
-          )
-        } : {}
-      };
+  }
+  stats() {
+    this.assertOpen();
+    const entryCount = this.db.prepare("SELECT COUNT(*) AS n FROM entries").get().n;
+    const vectorCount = this.db.prepare("SELECT COUNT(*) AS n FROM vectors").get().n;
+    const providerRows = this.db.prepare("SELECT DISTINCT provider_id FROM vectors").all();
+    return {
+      entries: entryCount,
+      vectors: vectorCount,
+      providers: providerRows.map((r) => r.provider_id),
+      modelAvailable: true,
+      modelId: this.provider.id,
+      dimensions: this.provider.dimensions
+    };
+  }
+  /**
+   * Embedding-cache diagnostics — entries, hit/miss counters, oldest entry.
+   * Useful for the WebUI's vector-memory panel and for diagnosing the
+   * "why is search slow?" question.
+   */
+  cacheStats() {
+    this.assertOpen();
+    const entries = this.db.prepare("SELECT COUNT(*) AS n FROM embedding_cache").get().n;
+    const providers = this.db.prepare("SELECT COUNT(DISTINCT provider_id) AS n FROM embedding_cache").get().n;
+    const totalUseCount = this.db.prepare("SELECT COALESCE(SUM(use_count), 0) AS n FROM embedding_cache").get().n;
+    const oldest = this.db.prepare("SELECT MIN(last_used_at) AS t FROM embedding_cache").get();
+    return {
+      entries,
+      providers,
+      totalUseCount,
+      oldestLastUsedAt: oldest?.t ?? null
+    };
+  }
+  /**
+   * LRU-evict the embedding cache down to `keepMostRecent` rows. The
+   * `embedding_cache` table is independent of `entries`, so a sweep here
+   * only removes cached vectors — never stored entries. Called by hosts
+   * that want to bound cache growth on long-lived processes.
+   */
+  async evictCache(keepMostRecent) {
+    this.assertOpen();
+    if (keepMostRecent < 0) {
+      throw new Error("evictCache: keepMostRecent must be >= 0");
     }
-    return port.getCapability(capability);
-  };
-  return wrapped;
-}
-
-// src/sage-event-mirror.ts
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
-import { getSageSurface as getSageSurface2 } from "@wrongstack/sage";
-function subscribeVectorMemoryToSage(opts) {
-  const { store, memoryStore } = opts;
-  const log = opts.logger;
-  if (opts.enabled === false) {
-    return { dispose: () => void 0 };
+    return withFileLock(
+      this.lockPath,
+      async () => {
+        const total = this.db.prepare("SELECT COUNT(*) AS n FROM embedding_cache").get().n;
+        if (total <= keepMostRecent) return { removed: 0 };
+        const toRemove = total - keepMostRecent;
+        const stmt = this.db.prepare(
+          `DELETE FROM embedding_cache
+            WHERE content_hash IN (
+              SELECT content_hash FROM embedding_cache
+               ORDER BY last_used_at ASC
+               LIMIT ?
+            )`
+        );
+        const info = stmt.run(Math.min(toRemove, CACHE_EVICT_BATCH));
+        return { removed: Number(info.changes) };
+      },
+      { timeoutMs: DEFAULT_LOCK_TIMEOUT_MS }
+    );
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.db.close();
+  }
+  assertOpen() {
+    if (this.closed) throw new Error("VectorMemoryStore is closed");
+  }
+  rowToEntry(row, vectorRow) {
+    const summaryValue = row.summary;
+    const entry = {
+      id: row.id,
+      text: row.text,
+      summary: summaryValue ?? void 0,
+      metadata: safeParseJson(row.metadata, {}),
+      tags: safeParseJson(row.tags, []),
+      scope: row.scope,
+      kind: row.kind,
+      contentHash: row.content_hash,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+      providerId: vectorRow?.provider_id ?? "",
+      dimensions: vectorRow?.dimensions ?? 0
+    };
+    if (vectorRow?.vector) {
+      entry.vector = decodeVector(vectorRow.vector);
+    }
+    return entry;
   }
-  const surface = getSageSurface2(memoryStore);
-  if (!surface) {
-    log?.debug?.("vector-memory mirror disabled: memory store exposes no SAGE surface");
-    return { dispose: () => void 0 };
+  async syncFromSage(sage) {
+    this.assertOpen();
+    const memories = await sage.listActiveMemories({ limit: Number.POSITIVE_INFINITY });
+    let indexed = 0;
+    let skipped = 0;
+    let failed = 0;
+    const errors = [];
+    for (const memory of memories) {
+      try {
+        const hash = _VectorMemoryStore.contentHash(memory.text);
+        const existing = this.findByContentHash(hash);
+        if (existing) {
+          skipped++;
+          continue;
+        }
+        await this.rememberUnlocked({
+          text: memory.text,
+          summary: memory.summary ?? void 0,
+          metadata: { source: "sage", sageId: memory.id, ...memory.metadata ?? {} },
+          tags: memory.tags ?? [],
+          scope: "project",
+          kind: "note"
+        });
+        indexed++;
+      } catch (err) {
+        failed++;
+        errors.push({ memoryId: memory.id, message: errMsg2(err) });
+      }
+    }
+    return { scanned: memories.length, indexed, skipped, failed, errors };
   }
-  const events = memoryStore.events;
-  if (!events) {
-    log?.debug?.("vector-memory mirror disabled: memory store has no event bus");
-    return { dispose: () => void 0 };
+};
+function fallbackHashingProvider(dimensions) {
+  return new HashingEmbeddingProvider({ dimensions });
+}
+function safeParseJson(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
   }
-  const fetch = async (memoryId) => {
-    try {
-      return await surface.getSage(memoryId);
-    } catch (err) {
-      log?.warn?.(`vector-memory mirror fetch failed for ${memoryId}: ${errMsg2(err)}`);
-      return null;
+}
+function errMsg2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/tools.ts
+function createVectorMemoryTools(store) {
+  return [
+    vectorMemoryRememberTool(store),
+    vectorMemorySearchTool(store),
+    vectorMemoryStatsTool(store),
+    vectorMemoryForgetTool(store)
+  ];
+}
+function vectorMemoryRememberTool(store) {
+  return {
+    name: "vector_memory_remember",
+    category: "Memory",
+    description: "Persist a piece of knowledge into the local vector memory store. The text is embedded with the active embedding provider (transformers.js when available, otherwise the sage hashing provider). Returns the new entry id and whether an embedding was stored.",
+    usageHint: "Store text you want to find later by *meaning*, not just exact keywords. Embeddings happen locally \u2014 no project text leaves the machine.",
+    permission: "confirm",
+    mutating: true,
+    riskTier: "standard",
+    timeoutMs: 5e3,
+    capabilities: ["memory.write"],
+    icon: "settings",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", minLength: 1, description: "The text to embed and store." },
+        summary: { type: "string", description: "Optional short label." },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional tags for later filtering."
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "user", "session"],
+          description: "Visibility scope. Defaults to `project`."
+        },
+        kind: {
+          type: "string",
+          enum: ["note", "fact", "summary", "snippet", "link"],
+          description: "Entry kind. Defaults to `note`."
+        },
+        metadata: {
+          type: "object",
+          additionalProperties: true,
+          description: "Free-form metadata persisted as JSON."
+        }
+      },
+      required: ["text"],
+      additionalProperties: false
+    },
+    execute: async (input) => {
+      const entry = await store.remember(input);
+      return { id: entry.id, hasVector: entry.vector !== void 0 };
     }
   };
-  const mirror = async (memoryId) => {
-    const memory = await fetch(memoryId);
-    if (!memory) return;
-    if (memory.scope === "session") return;
-    try {
-      const existing = store.findBySageId(memoryId);
-      if (existing) await store.forget(existing.id);
-      await store.remember({
-        text: memory.text,
-        ...memory.summary ? { summary: memory.summary } : {},
-        tags: memory.tags ?? [],
-        scope: "project",
-        kind: "note",
-        metadata: {
-          source: "sage",
-          sageId: memory.id,
-          sageKind: memory.kind,
-          sageScope: memory.scope,
-          importance: memory.importance,
-          confidence: memory.confidence
+}
+function vectorMemorySearchTool(store) {
+  return {
+    name: "vector_memory_search",
+    category: "Memory",
+    description: "Semantic search over the vector memory store. Embeds the query with the active provider and returns the top-k entries ranked by cosine similarity. Returns an empty list when the embedding provider is unavailable \u2014 callers should fall back to lexical search.",
+    usageHint: "Use when you want results ranked by meaning. Pairs well with sage `memory_search` for keyword precision.",
+    permission: "auto",
+    mutating: false,
+    riskTier: "safe",
+    timeoutMs: 5e3,
+    capabilities: ["memory.read"],
+    icon: "search",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", minLength: 1, description: "The natural-language query." },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 100,
+          description: "Max results (default 10)."
+        },
+        threshold: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Minimum cosine similarity. Results below the floor are dropped."
+        },
+        scope: {
+          type: "string",
+          enum: ["project", "user", "session"],
+          description: "Restrict to a scope."
+        },
+        kind: {
+          type: "string",
+          enum: ["note", "fact", "summary", "snippet", "link"],
+          description: "Restrict to a kind."
         }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    execute: async (input) => {
+      const hits = await store.search(input.query, {
+        limit: input.limit !== void 0 ? input.limit : void 0,
+        threshold: input.threshold !== void 0 ? input.threshold : void 0,
+        scope: input.scope,
+        kind: input.kind
       });
-    } catch (err) {
-      log?.warn?.(`vector-memory mirror remember failed for ${memoryId}: ${errMsg2(err)}`);
+      return {
+        hits: hits.map((h) => ({
+          id: h.entry.id,
+          score: h.score,
+          text: h.entry.text,
+          summary: h.entry.summary ?? void 0,
+          tags: h.entry.tags
+        }))
+      };
     }
   };
-  const forgetMirror = async (memoryId) => {
-    try {
-      const existing = store.findBySageId(memoryId);
-      if (existing) await store.forget(existing.id);
-    } catch (err) {
-      log?.warn?.(`vector-memory mirror forget failed for ${memoryId}: ${errMsg2(err)}`);
-    }
+}
+function vectorMemoryStatsTool(store) {
+  return {
+    name: "vector_memory_stats",
+    category: "Memory",
+    description: "Return counts, providers, and dimensions for the local vector memory store.",
+    usageHint: "Cheap diagnostic \u2014 safe to call any time.",
+    permission: "auto",
+    mutating: false,
+    riskTier: "safe",
+    timeoutMs: 1e3,
+    capabilities: ["memory.read"],
+    icon: "search",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    execute: async () => store.stats()
   };
-  const offAccepted = events.onPattern("memory.accepted", (_event, payload) => {
-    const memoryId = payload?.memoryId;
-    if (typeof memoryId !== "string") return;
-    void mirror(memoryId);
-  });
-  const offRecovered = events.onPattern("memory.recovered", (_event, payload) => {
-    const memoryId = payload?.memoryId;
-    if (typeof memoryId !== "string") return;
-    void mirror(memoryId);
-  });
-  const offUpdated = events.onPattern("memory.updated", (_event, payload) => {
-    const memoryId = payload?.memoryId;
-    if (typeof memoryId !== "string") return;
-    const status = payload?.status;
-    if (status === "deleted") return;
-    void mirror(memoryId);
-  });
-  const offDeleted = events.onPattern("memory.deleted", (_event, payload) => {
-    const memoryId = payload?.memoryId;
-    if (typeof memoryId !== "string") return;
-    void forgetMirror(memoryId);
-  });
+}
+function vectorMemoryForgetTool(store) {
   return {
-    dispose: () => {
-      offAccepted();
-      offRecovered();
-      offUpdated();
-      offDeleted();
-    }
+    name: "vector_memory_forget",
+    category: "Memory",
+    description: "Remove an entry (and its vector) from the vector memory store.",
+    usageHint: "Hard delete \u2014 no soft-delete tombstone. Use `vector_memory_search` to find the id first if you only have text.",
+    permission: "confirm",
+    mutating: true,
+    riskTier: "standard",
+    timeoutMs: 1e3,
+    capabilities: ["memory.write"],
+    icon: "settings",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          minLength: 1,
+          description: "Entry id returned by `vector_memory_remember`."
+        }
+      },
+      required: ["id"],
+      additionalProperties: false
+    },
+    execute: async (input) => ({ removed: await store.forget(input.id) })
   };
 }
-async function forgetStaleSageMirrors(store, memoryStore, logger, options) {
-  const surface = getSageSurface2(memoryStore);
-  if (!surface) return { scanned: 0, removed: 0 };
-  let scanned = 0;
-  let removed = 0;
-  const PAGE = Math.max(1, options?.pageSize ?? 500);
-  let after;
-  for (; ; ) {
-    const page = store.list(after ? { limit: PAGE, after } : { limit: PAGE });
-    if (page.length === 0) break;
-    const last = page[page.length - 1];
-    after = { updatedAt: last.updatedAt, id: last.id };
-    for (const entry of page) {
-      scanned++;
-      const sageId = entry.metadata?.sageId;
-      if (typeof sageId !== "string") continue;
-      try {
-        const memory = await surface.getSage(sageId);
-        if (memory !== null && memory.status !== "deleted") continue;
-        await store.forget(entry.id);
-        removed++;
-      } catch (err) {
-        logger?.warn?.(`vector-memory stale-mirror sweep failed for ${sageId}: ${errMsg2(err)}`);
-      }
-    }
-    if (page.length < PAGE) break;
+
+// src/transformers-provider.ts
+var DEFAULT_VECTOR_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+var DEFAULT_VECTOR_DIMENSIONS = 384;
+var DEFAULT_VECTOR_DTYPE = "q8";
+var TransformersEmbeddingProvider = class {
+  id;
+  dimensions;
+  modelId;
+  cacheDir;
+  dtype;
+  device;
+  batchSize;
+  maxChars;
+  allowRemote;
+  extractor;
+  loadPromise;
+  constructor(opts = {}) {
+    this.modelId = opts.modelId ?? DEFAULT_VECTOR_MODEL_ID;
+    this.cacheDir = opts.cacheDir;
+    this.dtype = opts.dtype ?? DEFAULT_VECTOR_DTYPE;
+    this.device = opts.device ?? "cpu";
+    this.batchSize = opts.batchSize ?? 16;
+    this.maxChars = opts.maxChars ?? 2048;
+    this.allowRemote = opts.allowRemoteModels ?? true;
+    this.dimensions = DEFAULT_VECTOR_DIMENSIONS;
+    this.id = `transformers-js:${this.modelId}:${this.dtype}`;
   }
-  return { scanned, removed };
-}
-function errMsg2(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-var SAGE_SWEEP_MARKER_FILENAME = "sage-mirror-sweep.json";
-var DEFAULT_SWEEP_INTERVAL_MS = 60 * 6e4;
-async function sweepStaleSageMirrors(opts) {
-  const markerPath2 = path3.join(opts.store.directory, SAGE_SWEEP_MARKER_FILENAME);
-  const interval = opts.minIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
-  if (!opts.force) {
+  /**
+   * Synchronous capability check. Returns false when the optional
+   * `@huggingface/transformers` dependency is not installed.
+   *
+   * NOTE: this probes via dynamic import and caches the result, but does
+   * NOT load the model itself — model loading is deferred to `embed()`.
+   */
+  async isAvailable() {
     try {
-      const raw = JSON.parse(fs3.readFileSync(markerPath2, "utf8"));
-      const at = typeof raw.at === "string" ? Date.parse(raw.at) : Number.NaN;
-      if (Number.isFinite(at) && Date.now() - at < interval) {
-        return { swept: false, reason: "throttled" };
-      }
+      await this.loadModule();
+      return true;
     } catch {
+      return false;
     }
   }
-  try {
-    fs3.writeFileSync(markerPath2, JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString() }), "utf8");
-  } catch {
-  }
-  try {
-    const result = await forgetStaleSageMirrors(opts.store, opts.memoryStore, opts.logger);
-    opts.logger?.debug?.(
-      `vector-memory stale-mirror sweep: scanned=${result.scanned} removed=${result.removed}`
-    );
-    return { swept: true, ...result };
-  } catch (err) {
-    opts.logger?.warn?.(`vector-memory stale-mirror sweep failed: ${errMsg2(err)}`);
-    return { swept: false, reason: errMsg2(err) };
-  }
-}
-
-// src/search-race.ts
-function previewText(text, maxLen) {
-  if (text.length <= maxLen) return text;
-  return text.slice(0, maxLen - 1) + "\u2026";
-}
-async function runSearchRace(query, lexical, vectorStore, options = {}) {
-  const limit = options.limit ?? 20;
-  const threshold = options.threshold ?? 0;
-  let vectorHits = [];
-  try {
-    vectorHits = await vectorStore.search(query, {
-      limit,
-      ...threshold > 0 ? { threshold } : {}
-    });
-  } catch {
-    vectorHits = [];
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const extractor = await this.getExtractor();
+    const prepared = texts.map((t) => this.prepare(t));
+    const batches = [];
+    for (let i = 0; i < prepared.length; i += this.batchSize) {
+      batches.push(prepared.slice(i, i + this.batchSize));
+    }
+    const results = [];
+    for (const batch of batches) {
+      const out = await extractor(batch, { pooling: "mean", normalize: true });
+      results.push(...this.tensorToVectors(out, batch.length));
+    }
+    return results;
   }
-  const lexicalOnly = [];
-  const vectorOnly = [];
-  const overlap = [];
-  const seenIds = /* @__PURE__ */ new Set();
-  const lexicalCapped = lexical.slice(0, limit);
-  for (let i = 0; i < lexicalCapped.length; i++) {
-    const mem = lexicalCapped[i];
-    const score = lexicalCapped.length <= 1 ? 1 : 1 - i / Math.max(1, lexicalCapped.length - 1);
-    const id = mem.id;
-    seenIds.add(id);
-    overlap.push({
-      id,
-      lexicalScore: score,
-      vectorScore: null,
-      // patched below when a vector hit carries this id
-      preview: previewText(mem.text, 140)
-    });
+  /** Truncate + normalize text before embedding. */
+  prepare(text) {
+    if (!text) return "";
+    const normalized = text.normalize("NFKC").trim();
+    return normalized.length > this.maxChars ? normalized.slice(0, this.maxChars) : normalized;
   }
-  const overlapById = /* @__PURE__ */ new Map();
-  for (const row of overlap) overlapById.set(row.id, row);
-  for (const hit of vectorHits) {
-    const sageId = hit.entry.metadata?.["sageId"];
-    if (typeof sageId !== "string") continue;
-    const existing = overlapById.get(sageId);
-    if (existing) {
-      if (existing.vectorScore === null) {
-        existing.vectorScore = hit.score;
+  tensorToVectors(out, batchSize) {
+    if (typeof out.tolist === "function") {
+      const nested = out.tolist();
+      if (Array.isArray(nested) && Array.isArray(nested[0])) {
+        return nested.map((row) => Float32Array.from(row));
       }
-      continue;
+      return [Float32Array.from(nested)];
     }
-    if (seenIds.has(sageId)) continue;
-    seenIds.add(sageId);
-    vectorOnly.push({
-      id: sageId,
-      lexicalScore: null,
-      vectorScore: hit.score,
-      preview: previewText(hit.entry.text, 140)
+    const flat = out.data;
+    if (flat instanceof Float32Array) {
+      if (batchSize === 1) return [flat];
+      const dim = flat.length / batchSize;
+      const vectors = [];
+      for (let i = 0; i < batchSize; i++) {
+        vectors.push(Float32Array.from(flat.subarray(i * dim, (i + 1) * dim)));
+      }
+      return vectors;
+    }
+    if (Array.isArray(flat) && Array.isArray(flat[0])) {
+      return flat.map((row) => Float32Array.from(row));
+    }
+    if (Array.isArray(flat)) {
+      return [Float32Array.from(flat)];
+    }
+    throw new Error("TransformersEmbeddingProvider: unexpected pipeline output shape");
+  }
+  async getExtractor() {
+    if (this.extractor) return this.extractor;
+    if (!this.loadPromise) this.loadPromise = this.loadExtractor();
+    this.extractor = await this.loadPromise;
+    return this.extractor;
+  }
+  async loadExtractor() {
+    const mod = await this.loadModule();
+    if (this.cacheDir) mod.env.cacheDir = this.cacheDir;
+    mod.env.allowRemoteModels = this.allowRemote;
+    if (!this.allowRemote) mod.env.localModelPath = this.cacheDir ?? "";
+    const pipe = await mod.pipeline("feature-extraction", this.modelId, {
+      dtype: this.dtype,
+      device: this.device
     });
+    return pipe;
   }
-  const finalOverlap = [];
-  for (const row of overlap) {
-    if (row.vectorScore === null) {
-      lexicalOnly.push({
-        id: row.id,
-        lexicalScore: row.lexicalScore,
-        vectorScore: null,
-        preview: row.preview
-      });
-    } else {
-      finalOverlap.push(row);
+  async loadModule() {
+    try {
+      const packageName = "@huggingface/transformers";
+      return await import(packageName);
+    } catch (err) {
+      throw new VectorMemoryProviderUnavailableError(
+        "@huggingface/transformers is not installed. Install it (pnpm add @huggingface/transformers) or wire a fallback EmbeddingProvider.",
+        err
+      );
     }
   }
-  const lexicalCount = lexicalOnly.length + finalOverlap.length;
-  const vectorCount = vectorOnly.length + finalOverlap.length;
-  const denom = Math.max(lexicalCount, vectorCount, 1);
-  return {
-    query,
-    lexicalOnly,
-    vectorOnly,
-    overlap: finalOverlap,
-    metrics: {
-      lexicalCount,
-      vectorCount,
-      overlapCount: finalOverlap.length,
-      lexicalOnlyRatio: lexicalCount === 0 ? 0 : lexicalOnly.length / lexicalCount,
-      vectorOnlyRatio: vectorCount === 0 ? 0 : vectorOnly.length / vectorCount,
-      agreementRatio: finalOverlap.length / denom
-    }
-  };
-}
+};
 export {
   DEFAULT_SWEEP_INTERVAL_MS,
   DEFAULT_VECTOR_DIMENSIONS,