@wrongstack/vector-memory 0.308.0 → 0.308.2

package/dist/index.js

@@ -133,7 +133,7 @@ var TransformersEmbeddingProvider = class {
 };
 
 // src/schema.ts
-var VECTOR_SCHEMA_VERSION = 1;
+var VECTOR_SCHEMA_VERSION = 2;
 var VECTOR_PROVIDER_KEY = "active_provider_id";
 var VECTOR_DIMENSIONS_KEY = "active_provider_dimensions";
 function initVectorSchema(db) {
@@ -164,7 +164,7 @@ function initVectorSchema(db) {
   `);
   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 INDEX IF NOT EXISTS idx_entries_hash ON entries(content_hash)");
+  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)"
   );
@@ -180,6 +180,20 @@ function initVectorSchema(db) {
     );
   `);
   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'
@@ -206,6 +220,41 @@ function initVectorSchema(db) {
     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 {
+  }
+  return decodeVector(row.vector);
+}
 function encodeVector(vec) {
   return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
 }
@@ -224,11 +273,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { HashingEmbeddingProvider, cosineSimilarity } from "@wrongstack/sage";
+import { withFileLock } from "@wrongstack/core/utils";
 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) {
@@ -246,11 +299,33 @@ var VectorMemoryStore = class _VectorMemoryStore {
       throw new Error("Vector memory directory must stay inside the project root.");
     }
     fs.mkdirSync(rootDir, { recursive: true });
+    this.rootDir = rootDir;
     this.dbPath = path.join(rootDir, filename);
     this.db = new DatabaseSync(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;
@@ -275,28 +350,112 @@ var VectorMemoryStore = class _VectorMemoryStore {
   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 id = randomUUID();
     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";
-    let vector;
-    let providerId;
-    try {
-      const result2 = await this.provider.embed([input.text]);
-      vector = result2[0];
-      providerId = this.provider.id;
-    } catch {
-      providerId = void 0;
-      vector = void 0;
-    }
+    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(
@@ -354,31 +513,32 @@ var VectorMemoryStore = class _VectorMemoryStore {
     const vectorRow = this.db.prepare("SELECT * FROM vectors WHERE entry_id = ?").get(id);
     return this.rowToEntry(row, vectorRow);
   }
-  forget(id) {
+  /** Hard-delete an entry by id. Wrapped in `withFileLock` for cross-process safety. */
+  async forget(id) {
     this.assertOpen();
-    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;
-    }
+    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 = opts.limit ?? 10;
     const threshold = opts.threshold ?? 0;
+    const includeVectors = opts.includeVectors === true;
     if (typeof query !== "string" || query.trim().length === 0) return [];
-    let queryVec;
-    try {
-      const result = await this.provider.embed([query]);
-      if (!result[0]) return [];
-      queryVec = result[0];
-    } catch {
-      return [];
-    }
+    const queryVec = await this.embedWithCache(query);
     if (!queryVec || queryVec.length === 0) return [];
     const providerId = this.provider.id;
     const dimensions = this.provider.dimensions;
@@ -408,7 +568,9 @@ var VectorMemoryStore = class _VectorMemoryStore {
       const score = Math.max(0, Math.min(1, raw));
       if (score < threshold) continue;
       const entry = this.rowToEntry(row);
-      scored.push({ entry, score, providerId });
+      const hit = { entry, score, providerId };
+      if (includeVectors) hit.vector = vec;
+      scored.push(hit);
     }
     scored.sort((a, b) => b.score - a.score);
     return scored.slice(0, limit);
@@ -433,37 +595,45 @@ var VectorMemoryStore = class _VectorMemoryStore {
   }
   async reindexAll() {
     this.assertOpen();
-    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;
+    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++;
+          }
         }
-        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),
-          (/* @__PURE__ */ new Date()).toISOString()
-        );
-        processed++;
-      } catch {
-        errors++;
-      }
-    }
-    return { processed, errors };
+        return { processed, errors };
+      },
+      { timeoutMs: 6e4 }
+    );
   }
   stats() {
     this.assertOpen();
@@ -479,6 +649,55 @@ var VectorMemoryStore = class _VectorMemoryStore {
       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 }
+    );
+  }
   close() {
     if (this.closed) return;
     this.closed = true;
@@ -510,19 +729,20 @@ var VectorMemoryStore = class _VectorMemoryStore {
   }
   async syncFromSage(sage) {
     this.assertOpen();
-    const memories = await sage.listActiveMemories({ limit: 5e3 });
+    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 existing = this.db.prepare("SELECT id FROM entries WHERE content_hash = ? LIMIT 1").get(_VectorMemoryStore.contentHash(memory.text));
+        const hash = _VectorMemoryStore.contentHash(memory.text);
+        const existing = this.findByContentHash(hash);
         if (existing) {
           skipped++;
           continue;
         }
-        await this.remember({
+        await this.rememberUnlocked({
           text: memory.text,
           summary: memory.summary ?? void 0,
           metadata: { source: "sage", sageId: memory.id, ...memory.metadata ?? {} },
@@ -554,6 +774,227 @@ function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
+// src/sage-sync-source.ts
+var DEFAULT_PAGE_SIZE = 500;
+var HARD_FLOOR_PAGE = 1;
+var HARD_CEILING_PAGE = 500;
+var HARD_CEILING_TOTAL = 1e6;
+function createSageSurfaceSyncSource(sage, opts = {}) {
+  const pageSize = clamp(opts.pageSize ?? DEFAULT_PAGE_SIZE, HARD_FLOOR_PAGE, HARD_CEILING_PAGE);
+  const maxTotal = opts.maxTotal === void 0 ? Number.POSITIVE_INFINITY : clamp(opts.maxTotal, 1, HARD_CEILING_TOTAL);
+  return {
+    async listActiveMemories({ limit }) {
+      const requested = limit === void 0 ? maxTotal : clamp(limit, 1, maxTotal === Number.POSITIVE_INFINITY ? limit : maxTotal);
+      const memories = [];
+      let cursor;
+      let noProgressPages = 0;
+      while (memories.length < requested) {
+        const remaining = requested - memories.length;
+        const page = await sage.listSagePage({
+          statuses: ["active"],
+          limit: Math.min(pageSize, Math.max(1, remaining)),
+          ...cursor ? { cursor } : {}
+        });
+        const rows = page.memories ?? [];
+        for (const m of rows) {
+          memories.push({
+            id: m.id,
+            text: m.text,
+            ...m.summary ? { summary: m.summary } : {},
+            ...m.tags && m.tags.length > 0 ? { tags: m.tags } : {},
+            metadata: {
+              sageKind: m.kind,
+              sageScope: m.scope,
+              importance: m.importance,
+              confidence: m.confidence
+            }
+          });
+        }
+        if (!page.nextCursor || rows.length === 0) break;
+        if (rows.length === 0) {
+          noProgressPages++;
+          if (noProgressPages > 3) break;
+        } else {
+          noProgressPages = 0;
+        }
+        cursor = page.nextCursor;
+      }
+      return memories.slice(0, requested);
+    }
+  };
+}
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+// 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) {
+  const { store, memoryStore } = opts;
+  const log = opts.logger;
+  try {
+    if (opts.force) {
+      try {
+        fs2.unlinkSync(markerPath(store));
+      } catch {
+      }
+    }
+    const decision = decideWhetherToSync(
+      store,
+      opts.staleAfterMs ?? RUNNING_STALE_MS,
+      void 0,
+      opts.pidAlive
+    );
+    if (!decision.run) {
+      log?.debug?.(`vector-memory sage sync skipped: ${decision.reason}`);
+      return { synced: false, reason: decision.reason };
+    }
+    const provider = storeProvider(store);
+    if (provider && typeof provider.isAvailable === "function" && !await provider.isAvailable()) {
+      log?.debug?.(
+        "vector-memory sage sync deferred: embedding provider unavailable (optional dependency not installed?)"
+      );
+      return { synced: false, reason: "provider-unavailable" };
+    }
+    if (provider && typeof provider.embed === "function") {
+      try {
+        const probe = await provider.embed(["wrongstack vector memory warmup probe"]);
+        if (!probe[0] || probe[0].length === 0) throw new Error("empty embedding");
+      } catch {
+        log?.debug?.(
+          "vector-memory sage sync deferred: embedding probe failed (model not cached / backend error)"
+        );
+        return { synced: false, reason: "provider-unavailable" };
+      }
+    }
+    const surface = getSageSurface(memoryStore);
+    if (!surface) {
+      log?.debug?.("vector-memory sage sync skipped: memory store exposes no SAGE surface");
+      return { synced: false, reason: "no-sage-surface" };
+    }
+    writeMarker(store, {
+      phase: "running",
+      pid: process.pid,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    const report = await store.syncFromSage(createSageSurfaceSyncSource(surface));
+    if (report.failed > 0) {
+      log?.warn?.(
+        `vector-memory sage sync finished with ${report.failed} failure(s) \u2014 will retry on next boot`
+      );
+      return {
+        synced: false,
+        reason: "partial-failure",
+        marker: { phase: "running", ...counts(report) }
+      };
+    }
+    let stats = store.stats();
+    if (stats.vectors !== stats.entries) {
+      log?.warn?.(
+        `vector-memory sage sync healed ${stats.entries - stats.vectors} vector-less entr(ies) via reindexAll()`
+      );
+      await store.reindexAll();
+      stats = store.stats();
+    }
+    if (stats.vectors !== stats.entries) {
+      log?.warn?.(
+        `vector-memory sage sync incomplete: ${stats.entries - stats.vectors} entr(ies) still vector-less \u2014 will retry on next boot`
+      );
+      return {
+        synced: false,
+        reason: "vector-incomplete",
+        marker: { phase: "running", ...counts(report) }
+      };
+    }
+    const marker = {
+      phase: "complete",
+      completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...provider ? { providerId: provider.id } : {},
+      ...counts(report)
+    };
+    writeMarker(store, marker);
+    log?.info?.(
+      `vector-memory sage sync complete: ${report.indexed} indexed, ${report.skipped} skipped (already present)`
+    );
+    return { synced: true, reason: "synced", marker };
+  } catch (error) {
+    log?.warn?.(
+      `vector-memory sage sync failed: ${error instanceof Error ? error.message : String(error)} \u2014 will retry on next boot`
+    );
+    return { synced: false, reason: "error" };
+  }
+}
+function decideWhetherToSync(store, staleAfterMs, now = /* @__PURE__ */ new Date(), pidAlive = defaultPidAlive) {
+  const existing = readMarker(store);
+  if (!existing) return { run: true, reason: "no-marker" };
+  if (existing.phase === "complete") return { run: false, reason: "already-complete" };
+  if (existing.pid === process.pid) {
+    return { run: true, reason: "running-own-pid" };
+  }
+  const startedAt = existing.startedAt ? Date.parse(existing.startedAt) : Number.NaN;
+  const ageMs = Number.isNaN(startedAt) ? Number.POSITIVE_INFINITY : now.getTime() - startedAt;
+  const stale = ageMs > staleAfterMs;
+  if (existing.pid === void 0) {
+    return Number.isNaN(startedAt) || stale ? { run: true, reason: Number.isNaN(startedAt) ? "running-marker-undated" : "running-marker-stale" } : { run: false, reason: "running-unknown-pid" };
+  }
+  try {
+    if (pidAlive(existing.pid)) {
+      return {
+        run: false,
+        reason: `running-pid-${existing.pid}${stale ? "-stale-but-alive" : ""}`
+      };
+    }
+    return { run: true, reason: `running-pid-${existing.pid}-dead` };
+  } catch {
+    return { run: false, reason: `running-pid-${existing.pid}-probe-failed` };
+  }
+}
+function defaultPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function readMarker(store) {
+  try {
+    const raw = fs2.readFileSync(markerPath(store), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && (parsed.phase === "running" || parsed.phase === "complete") ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function writeMarker(store, marker) {
+  try {
+    fs2.writeFileSync(markerPath(store), `${JSON.stringify(marker, null, 2)}
+`, "utf8");
+  } catch {
+  }
+}
+function markerPath(store) {
+  const dir = store.directory;
+  if (typeof dir !== "string") {
+    throw new Error("VectorMemoryStore.directory is required to place the sage sync marker");
+  }
+  return path2.join(dir, SAGE_SYNC_MARKER_FILENAME);
+}
+function storeProvider(store) {
+  const provider = store.provider;
+  if (provider && typeof provider.id === "string") {
+    return provider;
+  }
+  return void 0;
+}
+function counts(report) {
+  return { scanned: report.scanned, indexed: report.indexed, skipped: report.skipped, failed: report.failed };
+}
+
 // src/tools.ts
 function createVectorMemoryTools(store) {
   return [
@@ -706,13 +1147,420 @@ function vectorMemoryForgetTool(store) {
       required: ["id"],
       additionalProperties: false
     },
-    execute: async (input) => ({ removed: store.forget(input.id) })
+    execute: async (input) => ({ removed: await store.forget(input.id) })
+  };
+}
+
+// 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;
+  const vectorOnlyThreshold = options.vectorOnlyThreshold ?? 0;
+  let vectorHits = [];
+  if (options.vectorHits) {
+    vectorHits = [...options.vectorHits];
+  } else if (options.store) {
+    try {
+      vectorHits = await options.store.search(query, {
+        ...options.threshold !== void 0 ? { threshold: options.threshold } : {},
+        limit: Math.max(limit * 2, 50)
+      });
+    } catch {
+      vectorHits = [];
+    }
+  }
+  const sageById = /* @__PURE__ */ new Map();
+  for (const memory of lexical) sageById.set(memory.id, memory);
+  for (const hit of vectorHits) {
+    const sageId = hit.entry.metadata?.["sageId"];
+    if (typeof sageId === "string" && !sageById.has(sageId)) {
+      continue;
+    }
+  }
+  const lexicalRanked = lexical.map((memory, index) => ({
+    memory,
+    rankScore: lexicalRankScore(index, lexical.length),
+    lexicalScore: lexicalRankScore(index, lexical.length)
+  }));
+  const vectorRanked = [];
+  for (let i = 0; i < vectorHits.length; i++) {
+    const hit = vectorHits[i];
+    const sageId = hit.entry.metadata?.["sageId"];
+    if (typeof sageId !== "string") continue;
+    const memory = sageById.get(sageId);
+    if (!memory) continue;
+    vectorRanked.push({ memory, vectorScore: hit.score });
+  }
+  const fused = /* @__PURE__ */ new Map();
+  for (let i = 0; i < lexicalRanked.length; i++) {
+    const c = lexicalRanked[i];
+    const rrf = weight * 0 + (1 - weight) * (1 / (k + i + 1));
+    fused.set(c.memory.id, {
+      memory: c.memory,
+      vectorScore: null,
+      lexicalScore: c.lexicalScore,
+      finalScore: rrf,
+      source: "lexical"
+    });
+  }
+  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"
+      });
+    }
+  }
+  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 } : {}
+      }));
+    }
+  };
+}
+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 {
+  SAGE_RETRIEVAL_CAPABILITY,
+  SAGE_SURFACE_CAPABILITY
+} from "@wrongstack/sage";
+function mergeVectorRecall(options, recall, weight, threshold) {
+  if (options && typeof options === "object" && "vectorRecall" in options && options["vectorRecall"]) {
+    return options;
+  }
+  return {
+    ...options ?? {},
+    vectorRecall: recall,
+    ...weight !== void 0 ? { vectorRecallWeight: weight } : {},
+    ...threshold !== void 0 ? { vectorRecallMinScore: threshold } : {}
+  };
+}
+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 } : {}
+      }));
+    }
+  };
+}
+function wrapMemoryPortWithVectorRecall(port, options) {
+  const recall = options.vectorRecall ?? asVectorRecallProviderAdapter(options.store);
+  const weight = options.weight;
+  const threshold = options.threshold;
+  const wrapSearch = (original) => {
+    return ((query, searchOpts) => original(
+      query,
+      mergeVectorRecall(
+        searchOpts,
+        recall,
+        weight,
+        threshold
+      )
+    ));
+  };
+  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: wrapSearch(original.searchSage),
+        // The rich-breakdown variant uses the same options-merge
+        // helper — pass the vector recall through so consumers that
+        // want the per-channel score breakdown get the same fusion
+        // behaviour as `searchSage`.
+        ...original.searchSageWithBreakdown ? {
+          searchSageWithBreakdown: wrapSearch(
+            original.searchSageWithBreakdown
+          )
+        } : {}
+      };
+    }
+    if (capability.id === SAGE_SURFACE_CAPABILITY.id) {
+      const original = port.getCapability(capability);
+      if (!original) return void 0;
+      return {
+        ...original,
+        searchSage: wrapSearch(original.searchSage),
+        ...original.searchSageWithBreakdown ? {
+          searchSageWithBreakdown: wrapSearch(
+            original.searchSageWithBreakdown
+          )
+        } : {}
+      };
+    }
+    return port.getCapability(capability);
+  };
+  return wrapped;
+}
+
+// src/sage-event-mirror.ts
+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 };
+  }
+  const surface = getSageSurface2(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 {
+      return await surface.getSage(memoryId);
+    } catch (err) {
+      log?.warn?.(
+        `vector-memory mirror fetch failed for ${memoryId}: ${errMsg2(err)}`
+      );
+      return null;
+    }
+  };
+  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}: ${errMsg2(err)}`
+      );
+    }
+  };
+  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)}`
+      );
+    }
+  };
+  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();
+    }
+  };
+}
+async function forgetStaleSageMirrors(store, memoryStore, logger) {
+  const surface = getSageSurface2(memoryStore);
+  if (!surface) return { scanned: 0, removed: 0 };
+  let scanned = 0;
+  let removed = 0;
+  for (let offset = 0; ; offset += 1e3) {
+    const page = store.list({ limit: 1e3 });
+    if (page.length === 0) break;
+    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 < 1e3) break;
+  }
+  return { scanned, removed };
+}
+function errMsg2(err) {
+  return err instanceof Error ? err.message : String(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 = [];
+  }
+  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: 0,
+      // patched below
+      preview: previewText(mem.text, 140)
+    });
+  }
+  for (const hit of vectorHits) {
+    const sageId = hit.entry.metadata?.["sageId"];
+    if (typeof sageId !== "string") continue;
+    const existing = overlap.find((row) => row.id === sageId);
+    if (existing) {
+      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)
+    });
+  }
+  for (let i = overlap.length - 1; i >= 0; i--) {
+    const row = overlap[i];
+    if (row.vectorScore === 0) {
+      lexicalOnly.push({
+        id: row.id,
+        lexicalScore: row.lexicalScore,
+        vectorScore: null,
+        preview: row.preview
+      });
+      overlap.splice(i, 1);
+    }
+  }
+  const lexicalCount = lexicalOnly.length + overlap.length;
+  const vectorCount = vectorOnly.length + overlap.length;
+  const denom = Math.max(lexicalCount, vectorCount, 1);
+  return {
+    query,
+    lexicalOnly,
+    vectorOnly,
+    overlap,
+    metrics: {
+      lexicalCount,
+      vectorCount,
+      overlapCount: overlap.length,
+      lexicalOnlyRatio: lexicalCount === 0 ? 0 : lexicalOnly.length / lexicalCount,
+      vectorOnlyRatio: vectorCount === 0 ? 0 : vectorOnly.length / vectorCount,
+      agreementRatio: overlap.length / denom
+    }
   };
 }
 export {
   DEFAULT_VECTOR_DIMENSIONS,
   DEFAULT_VECTOR_DTYPE,
   DEFAULT_VECTOR_MODEL_ID,
+  SAGE_SYNC_MARKER_FILENAME,
   TransformersEmbeddingProvider,
   VECTOR_DIMENSIONS_KEY,
   VECTOR_PROVIDER_KEY,
@@ -720,10 +1568,21 @@ export {
   VectorMemoryError,
   VectorMemoryProviderUnavailableError,
   VectorMemoryStore,
+  asVectorRecallProvider,
+  createSageSurfaceSyncSource,
   createVectorMemoryTools,
+  decideWhetherToSync,
   decodeVector,
   encodeVector,
   fallbackHashingProvider,
-  initVectorSchema
+  forgetStaleSageMirrors,
+  fuseWithVectorMemory,
+  initVectorSchema,
+  lookupEmbeddingCache,
+  runSearchRace,
+  startFirstBootSageSync,
+  subscribeVectorMemoryToSage,
+  upsertEmbeddingCache,
+  wrapMemoryPortWithVectorRecall
 };
 //# sourceMappingURL=index.js.map