@rohirik/openltm-core 2.8.0

package/src/schema.sql

@@ -0,0 +1,191 @@
+-- Long-Term Memory Schema
+-- Two-table design: context_items (per-project context) + memories (global learned insights)
+
+-- ============================================================
+-- schema_migrations: versioned migration tracking
+-- ============================================================
+CREATE TABLE IF NOT EXISTS schema_migrations (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  version    TEXT    NOT NULL UNIQUE,
+  applied_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  checksum   TEXT
+);
+
+-- ============================================================
+-- context_items: replaces the 4 per-project Markdown context files
+-- ============================================================
+CREATE TABLE IF NOT EXISTS context_items (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_name TEXT    NOT NULL,
+  type         TEXT    NOT NULL CHECK(type IN ('goal','decision','progress','gotcha')),
+  content      TEXT    NOT NULL,
+  title        TEXT,
+  session_id   TEXT,                          -- for progress dedup
+  permanent    INTEGER NOT NULL DEFAULT 0,    -- 1 = never auto-delete (decisions, gotchas)
+  memory_id    INTEGER REFERENCES memories(id) ON DELETE SET NULL,
+  status       TEXT    NOT NULL DEFAULT 'active' CHECK(status IN ('active','pending_promotion','promoted')),
+  created_at   TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_ctx_project ON context_items(project_name);
+CREATE INDEX IF NOT EXISTS idx_ctx_type    ON context_items(project_name, type);
+
+-- ============================================================
+-- memories: global + project-scoped learned insights
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memories (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  content           TEXT    NOT NULL,
+  title             TEXT,
+  category          TEXT    NOT NULL CHECK(category IN (
+                      'preference','architecture','gotcha','pattern','workflow','constraint')),
+  importance        INTEGER NOT NULL DEFAULT 3 CHECK(importance BETWEEN 1 AND 5),
+  confidence        REAL    NOT NULL DEFAULT 1.0 CHECK(confidence BETWEEN 0.0 AND 1.0),
+  source            TEXT,
+  project_scope     TEXT,                     -- NULL = global, else project name
+  dedup_key         TEXT    UNIQUE,
+  created_at        TEXT    NOT NULL DEFAULT (datetime('now')),
+  last_confirmed_at TEXT    NOT NULL DEFAULT (datetime('now')),
+  confirm_count     INTEGER NOT NULL DEFAULT 1,
+  -- Phase 2: janitor fields
+  status            TEXT    NOT NULL DEFAULT 'active' CHECK(status IN ('active','pending','deprecated','superseded')),
+  embedding         BLOB,                     -- float32 vector for semantic search
+  last_used_at      TEXT    NOT NULL DEFAULT (datetime('now')),
+  -- Phase 3: temporal metadata
+  first_recalled_at  TEXT,
+  last_recalled_at  TEXT,
+  recall_count     INTEGER NOT NULL DEFAULT 0,
+  superseded_by    INTEGER REFERENCES memories(id) ON DELETE SET NULL,
+  superseded_at    TEXT,
+  -- Phase 7: graph humanization
+  hidden     INTEGER NOT NULL DEFAULT 0,
+  color      TEXT,
+  icon       TEXT,
+  user_note  TEXT,
+  -- Personal relevance signal: 'works' | 'doesnt' | NULL (unrated)
+  relevance_signal     TEXT,
+  relevance_signal_at  TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_category   ON memories(category);
+CREATE INDEX IF NOT EXISTS idx_memories_project    ON memories(project_scope);
+CREATE INDEX IF NOT EXISTS idx_memories_importance ON memories(importance DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_confidence ON memories(confidence DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_status     ON memories(status);
+CREATE INDEX IF NOT EXISTS idx_memories_last_used  ON memories(last_used_at);
+CREATE INDEX IF NOT EXISTS idx_memories_superseded ON memories(superseded_by);
+CREATE INDEX IF NOT EXISTS idx_memories_recall_count ON memories(recall_count DESC);
+
+-- ============================================================
+-- tags + memory_tags: many-to-many tagging for memories
+-- ============================================================
+CREATE TABLE IF NOT EXISTS tags (
+  id   INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT    NOT NULL UNIQUE
+);
+
+CREATE TABLE IF NOT EXISTS memory_tags (
+  memory_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  tag_id    INTEGER NOT NULL REFERENCES tags(id)     ON DELETE CASCADE,
+  PRIMARY KEY (memory_id, tag_id)
+);
+
+-- ============================================================
+-- memory_relations: knowledge graph edges
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memory_relations (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  source_memory_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  target_memory_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  relationship_type TEXT NOT NULL CHECK(relationship_type IN (
+                      'supports','contradicts','refines','depends_on','related_to','supersedes')),
+  note             TEXT,
+  weight           REAL NOT NULL DEFAULT 1.0 CHECK(weight BETWEEN 0.0 AND 1.0),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(source_memory_id, target_memory_id, relationship_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_relations_source ON memory_relations(source_memory_id);
+CREATE INDEX IF NOT EXISTS idx_relations_target ON memory_relations(target_memory_id);
+
+-- ============================================================
+-- memory_layout: per-view position persistence (Phase 7)
+-- Only saved on explicit drag/pin — simulation-placed nodes have no row.
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memory_layout (
+  memory_id  INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  view       TEXT    NOT NULL,
+  x          REAL    NOT NULL,
+  y          REAL    NOT NULL,
+  pinned     INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT    NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (memory_id, view)
+);
+
+CREATE INDEX IF NOT EXISTS idx_layout_view ON memory_layout(view);
+
+-- ============================================================
+-- FTS5 virtual table for full-text search on memories (includes title)
+-- ============================================================
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  title,
+  content,
+  content='memories',
+  content_rowid='id'
+);
+
+-- Triggers to keep FTS in sync with memories table
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+  INSERT INTO memories_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+-- ============================================================
+-- FTS5 for context_items
+-- ============================================================
+CREATE VIRTUAL TABLE IF NOT EXISTS context_items_fts USING fts5(
+  title,
+  content,
+  content='context_items',
+  content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS context_items_ai AFTER INSERT ON context_items BEGIN
+  INSERT INTO context_items_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS context_items_ad AFTER DELETE ON context_items BEGIN
+  INSERT INTO context_items_fts(context_items_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS context_items_au AFTER UPDATE ON context_items BEGIN
+  INSERT INTO context_items_fts(context_items_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+  INSERT INTO context_items_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+-- ============================================================
+-- settings: key-value store for janitor/provider configuration
+-- ============================================================
+CREATE TABLE IF NOT EXISTS settings (
+  key        TEXT PRIMARY KEY,
+  value      TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- workspace_id + agent_id indexes are created by migration 007_workspaces.sql
+-- after the columns are added via ALTER TABLE. Do not add them here.

package/src/secretsScrubber.ts

@@ -0,0 +1,105 @@
+/**
+ * secretsScrubber.ts — Redact secrets from LTM memory content before DB writes.
+ * Called from learn() in db.ts. Must never throw.
+ */
+
+export interface ScrubResult {
+  scrubbed: string;
+  redactions: string[]; // deduplicated pattern IDs found
+}
+
+interface Pattern {
+  id: string;
+  regex: RegExp;
+  replacement: string;
+}
+
+const PATTERNS: Pattern[] = [
+  {
+    id: "aws-access-key",
+    regex: /AKIA[0-9A-Z]{16}/g,
+    replacement: "[REDACTED:aws-access-key]",
+  },
+  {
+    id: "aws-secret-key",
+    // 40-char base64 string near aws/secret context
+    regex: /(?:aws|secret|SECRET)[^a-zA-Z0-9]{0,20}[0-9a-zA-Z/+]{40}(?![0-9a-zA-Z/+])/g,
+    replacement: "[REDACTED:aws-secret-key]",
+  },
+  {
+    id: "github-token",
+    regex: /gh[ps]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{82}/g,
+    replacement: "[REDACTED:github-token]",
+  },
+  {
+    id: "openai-key",
+    regex: /sk-proj-[a-zA-Z0-9_-]{40,}(?![a-zA-Z0-9_-])|sk-[a-zA-Z0-9]{40,}(?![a-zA-Z0-9_-])/g,
+    replacement: "[REDACTED:openai-key]",
+  },
+  {
+    id: "anthropic-key",
+    regex: /sk-ant-[a-zA-Z0-9_-]{93,}/g,
+    replacement: "[REDACTED:anthropic-key]",
+  },
+  {
+    id: "google-api-key",
+    regex: /AIza[0-9A-Za-z_-]{35}/g,
+    replacement: "[REDACTED:google-api-key]",
+  },
+  {
+    id: "stripe-key",
+    regex: /(?:sk|pk)_(?:test|live)_[0-9a-zA-Z]{24,}/g,
+    replacement: "[REDACTED:stripe-key]",
+  },
+  {
+    id: "slack-token",
+    regex: /xox[baprs]-[0-9A-Za-z-]{10,}/g,
+    replacement: "[REDACTED:slack-token]",
+  },
+  {
+    id: "jwt",
+    regex: /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+    replacement: "[REDACTED:jwt]",
+  },
+  {
+    id: "bearer-token",
+    regex: /Bearer\s+[A-Za-z0-9._\-]{20,}/gi,
+    replacement: "Bearer [REDACTED:bearer-token]",
+  },
+  {
+    id: "connection-string",
+    regex: /(?:postgres|mysql|mongodb|redis):\/\/[^@\s]+@[^\s]+/gi,
+    replacement: "[REDACTED:connection-string]",
+  },
+  {
+    id: "private-key",
+    regex: /-----BEGIN [\w\s]*PRIVATE KEY-----[\s\S]*?-----END [\w\s]*PRIVATE KEY-----/g,
+    replacement: "[REDACTED:private-key]",
+  },
+  {
+    id: "generic-api-key",
+    regex: /(?:api[_-]?key|secret[_-]?key|access[_-]?token)[^a-zA-Z].*?['"][A-Za-z0-9_\-]{20,}['"]/gi,
+    replacement: "[REDACTED:generic-api-key]",
+  },
+];
+
+export function scrubSecrets(text: string): ScrubResult {
+  try {
+    if (!text) return { scrubbed: text, redactions: [] };
+
+    let scrubbed = text;
+    const found = new Set<string>();
+
+    for (const pattern of PATTERNS) {
+      pattern.regex.lastIndex = 0;
+      const next = scrubbed.replace(pattern.regex, pattern.replacement);
+      if (next !== scrubbed) found.add(pattern.id);
+      scrubbed = next;
+    }
+
+    return { scrubbed, redactions: [...found] };
+  } catch {
+    // Never throw — return original text on any error
+    return { scrubbed: text, redactions: [] };
+  }
+}

package/src/shared-db.ts

@@ -0,0 +1,158 @@
+/**
+ * shared-db.ts — Single DB singleton shared by db.ts, context.ts, server.ts, and janitor.
+ * Prevents dual write connections that break WAL.
+ * Runs versioned schema migrations on first access via migrations.ts.
+ */
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import { dirname } from "path";
+import { getDbPath, getSchemaPath } from "./paths.js";
+import { runPendingMigrations } from "./migrations.js";
+import { writeQueue } from "./lib/writeQueue.js";
+import { ensureCustomSqlite, loadExtensions, getCapabilities } from "./extensions.js";
+import { backfillVecIndexIfEmpty } from "./vec/index.js";
+import type { LtmCoreConfig } from "./adapterTypes.js";
+
+export let DB_PATH = getDbPath();
+let SCHEMA_PATH = getSchemaPath();
+
+/** Configure openltm-core with host-specific paths. Call before first getDb(). */
+export function configure(config: LtmCoreConfig): void {
+  DB_PATH = config.dbPath;
+  if (config.schemaPath) SCHEMA_PATH = config.schemaPath;
+}
+
+let _db: Database | null = null;
+let _initPromise: Promise<Database> | null = null;
+
+export async function initDb(opts?: { dbPath?: string; schemaPath?: string }): Promise<Database> {
+  if (opts?.dbPath) DB_PATH = opts.dbPath;
+  if (opts?.schemaPath) SCHEMA_PATH = opts.schemaPath;
+  const dir = dirname(DB_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  // Must run before the first Database opens to switch to an extension-enabled
+  // system SQLite. No-op (degrades to FTS-only) when none is available.
+  ensureCustomSqlite();
+  const db = new Database(DB_PATH, { create: true });
+  db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
+  loadExtensions(db);
+  // Apply schema.sql first (CREATE IF NOT EXISTS — safe for fresh + existing DBs)
+  db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  // Then run versioned migrations (idempotent — skips already-applied versions)
+  await runPendingMigrations(db);
+  // One-time vec0 index backfill for DBs that predate vec wiring. No-op when
+  // vec is unavailable or the index is already populated.
+  if (getCapabilities().vec) backfillVecIndexIfEmpty(db);
+  return db;
+}
+
+export function getDb(): Database {
+  if (_db) return _db;
+  // Synchronous callers: run initDb eagerly and block via Bun's top-level await support.
+  // _initPromise guards against concurrent initialisation during async startup paths.
+  if (!_initPromise) {
+    _initPromise = initDb().then((db) => {
+      _db = db;
+      return db;
+    }).catch((err) => {
+      // Reset so the next call retries; swallow here — sync fallback below handles the cold path.
+      _initPromise = null;
+      throw err;
+    });
+    _initPromise.catch(() => {/* prevent unhandled rejection — sync fallback is active */});
+  }
+  // For synchronous callers on cold start: open a schema-only DB immediately.
+  // Migrations run via _initPromise (above) on a dedicated connection and swap
+  // _db once complete. Do NOT run runPendingMigrations here — that causes two
+  // concurrent runners on the same file and UNIQUE constraint races.
+  if (!_db) {
+    const dir = dirname(DB_PATH);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    ensureCustomSqlite();
+    _db = new Database(DB_PATH, { create: true });
+    _db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
+    loadExtensions(_db);
+    _db.exec(readFileSync(SCHEMA_PATH, "utf-8"));
+  }
+  return _db;
+}
+
+/**
+ * Await full DB initialisation (schema + all pending migrations).
+ * Use in async startup paths (tests, server boot) when migrated columns are
+ * needed before the first async tick completes.
+ */
+export async function waitForInit(): Promise<void> {
+  if (!_initPromise) getDb(); // ensure _initPromise is created
+  await _initPromise;
+}
+
+/**
+ * Test-only: inject a specific Database instance as the singleton.
+ * Closes any existing connection first. Never call in production code.
+ */
+export function _setDbForTesting(db: Database): void {
+  try { _db?.close(); } catch {}
+  _db = db;
+  // Resolve immediately — db is already fully migrated; prevents a second
+  // runPendingMigrations if getDb() or waitForInit() is called after injection.
+  _initPromise = Promise.resolve(db);
+}
+
+/** Retry helper for SQLITE_BUSY errors — wraps a function with automatic retry. */
+export function withRetry<T>(fn: () => T, maxRetries = 3): T {
+  let lastError: Error | null = null;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return fn();
+    } catch (err: unknown) {
+      const e = err as { message?: string; code?: number };
+      if (e?.message?.includes("SQLITE_BUSY") || e?.code === 5) {
+        lastError = err as Error;
+        if (i < maxRetries - 1) {
+          const delay = Math.pow(2, i) * 50;
+          const start = Date.now();
+          while (Date.now() - start < delay) { /* spin-wait */ }
+        }
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError;
+}
+
+// --- Settings helpers (used by janitor + server routes) ---
+
+export interface SettingRow {
+  key: string;
+  value: string;
+  updated_at: string;
+}
+
+export function getSetting(key: string): string | null {
+  const db = getDb();
+  const row = db
+    .query<SettingRow, [string]>("SELECT value FROM settings WHERE key=?")
+    .get(key);
+  return row?.value ?? null;
+}
+
+export function setSetting(key: string, value: string): Promise<void> {
+  const db = getDb();
+  return writeQueue.enqueue(() => {
+    db.run(
+      `INSERT INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))
+       ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at`,
+      [key, value],
+    );
+  }, db);
+}
+
+export function getAllSettings(): Record<string, string> {
+  const db = getDb();
+  const rows = db
+    .query<SettingRow, []>("SELECT key, value FROM settings")
+    .all();
+  return Object.fromEntries(rows.map((r) => [r.key, r.value]));
+}

package/src/vec/index.ts

@@ -0,0 +1,161 @@
+/**
+ * vec/index.ts — sqlite-vec (vec0) ANN index over memory embeddings.
+ *
+ * The vec0 virtual table `vec_memories` is a DERIVED index that mirrors the
+ * active-model rows of `memory_embeddings` (the source of truth). It is created
+ * lazily at runtime — never in schema.sql or a hard migration — because
+ * `CREATE VIRTUAL TABLE … USING vec0` throws "no such module: vec0" on any
+ * process where the extension failed to load, which would break DB init.
+ *
+ * Every function is gated on getCapabilities().vec and degrades to a no-op
+ * (false / [] / -1) when vec is unavailable; callers fall back to the brute-
+ * force JS-cosine path in embeddings.ts. Nothing here throws.
+ *
+ * Distance metric is cosine, so similarity = 1 - distance (identical → 1).
+ */
+import type { Database } from "bun:sqlite";
+import { getCapabilities } from "../extensions.js";
+
+export const VEC_TABLE = "vec_memories";
+export const DEFAULT_EMBED_DIM = 768;
+
+type Blob = Uint8Array | Buffer;
+
+/** Active embedding dimension from settings (ltm.embed.dim), default 768. */
+export function getActiveEmbedDim(db: Database): number {
+  try {
+    const row = db
+      .query<{ value: string }, [string]>("SELECT value FROM settings WHERE key=?")
+      .get("ltm.embed.dim");
+    const n = row ? parseInt(row.value, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_EMBED_DIM;
+  } catch {
+    return DEFAULT_EMBED_DIM;
+  }
+}
+
+export function isVecAvailable(): boolean {
+  return getCapabilities().vec;
+}
+
+/**
+ * Create the vec0 index table for the given dimension if vec is available.
+ * Idempotent (CREATE … IF NOT EXISTS). No-op + false when unavailable.
+ */
+export function ensureVecTable(db: Database, dim?: number): boolean {
+  if (!getCapabilities().vec) return false;
+  const d = dim ?? getActiveEmbedDim(db);
+  try {
+    db.exec(
+      `CREATE VIRTUAL TABLE IF NOT EXISTS ${VEC_TABLE} USING vec0(embedding float[${d}] distance_metric=cosine)`,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Upsert one vector into the index by memory id (rowid). No-op when unavailable. */
+export function upsertVec(db: Database, memoryId: number, blob: Blob): boolean {
+  if (!getCapabilities().vec) return false;
+  try {
+    db.transaction(() => {
+      db.run(`DELETE FROM ${VEC_TABLE} WHERE rowid=?`, [memoryId]);
+      db.run(`INSERT INTO ${VEC_TABLE}(rowid, embedding) VALUES (?, ?)`, [memoryId, blob]);
+    })();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Remove one vector from the index by memory id. No-op when unavailable. */
+export function deleteVec(db: Database, memoryId: number): boolean {
+  if (!getCapabilities().vec) return false;
+  try {
+    db.run(`DELETE FROM ${VEC_TABLE} WHERE rowid=?`, [memoryId]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface VecHit {
+  id: number;
+  distance: number;
+  similarity: number;
+}
+
+/**
+ * KNN search over the index. Returns [] when vec is unavailable.
+ * similarity = 1 - cosine distance (so higher = closer).
+ */
+export function knnVec(db: Database, queryBlob: Blob, k: number): VecHit[] {
+  if (!getCapabilities().vec) return [];
+  try {
+    const rows = db
+      .query<{ id: number; distance: number }, [Blob, number]>(
+        `SELECT rowid AS id, distance FROM ${VEC_TABLE} WHERE embedding MATCH ? ORDER BY distance LIMIT ?`,
+      )
+      .all(queryBlob, k);
+    return rows.map((r) => ({ id: r.id, distance: r.distance, similarity: 1 - r.distance }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Drop and rebuild the index from memory_embeddings for the active dim (and
+ * model when given). Use after a provider/model switch — vectors from a
+ * different model are not comparable in the same vec0 space. Returns the number
+ * of rows indexed, or -1 when vec is unavailable.
+ */
+export function rebuildVecIndex(db: Database, opts?: { model?: string; dim?: number }): number {
+  if (!getCapabilities().vec) return -1;
+  const dim = opts?.dim ?? getActiveEmbedDim(db);
+  try {
+    db.exec(`DROP TABLE IF EXISTS ${VEC_TABLE}`);
+    if (!ensureVecTable(db, dim)) return -1;
+    const where = opts?.model ? "WHERE dim=? AND model=?" : "WHERE dim=?";
+    const params: Array<number | string> = opts?.model ? [dim, opts.model] : [dim];
+    const rows = db
+      .query<{ memory_id: number; embedding: Buffer }, Array<number | string>>(
+        `SELECT memory_id, embedding FROM memory_embeddings ${where}`,
+      )
+      .all(...params);
+    let n = 0;
+    db.transaction(() => {
+      for (const r of rows) {
+        db.run(`INSERT INTO ${VEC_TABLE}(rowid, embedding) VALUES (?, ?)`, [r.memory_id, r.embedding]);
+        n++;
+      }
+    })();
+    return n;
+  } catch {
+    return -1;
+  }
+}
+
+/**
+ * One-time backfill for DBs that have embeddings but an empty/absent vec index
+ * (e.g. created before vec was wired in). Rebuilds the index only when it holds
+ * zero rows yet memory_embeddings has rows at the active dim. Cheap no-op on
+ * subsequent boots because vec0 shadow tables persist in the DB file. Returns
+ * the number of rows indexed, 0 when nothing to do, or -1 when unavailable.
+ */
+export function backfillVecIndexIfEmpty(db: Database): number {
+  if (!getCapabilities().vec) return -1;
+  try {
+    const dim = getActiveEmbedDim(db);
+    if (!ensureVecTable(db, dim)) return -1;
+    const indexed = db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${VEC_TABLE}`).get();
+    if ((indexed?.n ?? 0) > 0) return 0;
+    const stored = db
+      .query<{ n: number }, [number]>(`SELECT COUNT(*) AS n FROM memory_embeddings WHERE dim=?`)
+      .get(dim);
+    if ((stored?.n ?? 0) === 0) return 0;
+    return rebuildVecIndex(db, { dim });
+  } catch {
+    return -1;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}