context-vault 2.0.1

package/src/index/README.md

@@ -0,0 +1,28 @@
+# Index Layer
+
+The sync layer. Owns the SQLite database as a derived index. Handles both single-entry indexing (write-through from capture) and bulk sync (reindex from disk).
+
+## Public API (`index.js`)
+
+```js
+indexEntry(ctx, entry)       → Promise<void>   // Index a single entry after capture
+reindex(ctx, { fullSync })   → Promise<stats>  // Bulk sync vault dir ↔ database
+```
+
+- `indexEntry` — called immediately after `writeEntry()` in the server coordinator. Inserts the row and generates a vector embedding.
+- `reindex` — walks the vault directory, diffs against DB state, and adds/updates/removes entries. `fullSync: true` enables updates and deletions; `false` is add-only.
+
+## Internal
+
+| File | Purpose |
+|------|---------|
+| `db.js` | Schema DDL (v4), `initDatabase()`, `prepareStatements()`, `insertVec()`, `deleteVec()` |
+| `embed.js` | HuggingFace `all-MiniLM-L6-v2` embedding via `@huggingface/transformers`. Lazy-loaded singleton. |
+
+## Dependency Rule
+
+```
+index/ → core/ (only)
+```
+
+Never import from `capture/`, `retrieve/`, or `server/`.

package/src/index/db.js

@@ -0,0 +1,138 @@
+/**
+ * db.js — Database schema, initialization, and prepared statements
+ */
+
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+import { unlinkSync } from "node:fs";
+
+// ─── Schema DDL (v5 — categories) ───────────────────────────────────────────
+
+export const SCHEMA_DDL = `
+  CREATE TABLE IF NOT EXISTS vault (
+    id           TEXT PRIMARY KEY,
+    kind         TEXT NOT NULL,
+    category     TEXT NOT NULL DEFAULT 'knowledge',
+    title        TEXT,
+    body         TEXT NOT NULL,
+    meta         TEXT,
+    tags         TEXT,
+    source       TEXT,
+    file_path    TEXT UNIQUE,
+    identity_key TEXT,
+    expires_at   TEXT,
+    created_at   TEXT DEFAULT (datetime('now'))
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_vault_kind ON vault(kind);
+  CREATE INDEX IF NOT EXISTS idx_vault_category ON vault(category);
+  CREATE INDEX IF NOT EXISTS idx_vault_category_created ON vault(category, created_at DESC);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_vault_identity ON vault(kind, identity_key) WHERE identity_key IS NOT NULL;
+
+  -- Single FTS5 table
+  CREATE VIRTUAL TABLE IF NOT EXISTS vault_fts USING fts5(
+    title, body, tags, kind,
+    content='vault', content_rowid='rowid'
+  );
+
+  -- FTS sync triggers
+  CREATE TRIGGER IF NOT EXISTS vault_ai AFTER INSERT ON vault BEGIN
+    INSERT INTO vault_fts(rowid, title, body, tags, kind)
+      VALUES (new.rowid, new.title, new.body, new.tags, new.kind);
+  END;
+  CREATE TRIGGER IF NOT EXISTS vault_ad AFTER DELETE ON vault BEGIN
+    INSERT INTO vault_fts(vault_fts, rowid, title, body, tags, kind)
+      VALUES ('delete', old.rowid, old.title, old.body, old.tags, old.kind);
+  END;
+  CREATE TRIGGER IF NOT EXISTS vault_au AFTER UPDATE ON vault BEGIN
+    INSERT INTO vault_fts(vault_fts, rowid, title, body, tags, kind)
+      VALUES ('delete', old.rowid, old.title, old.body, old.tags, old.kind);
+    INSERT INTO vault_fts(rowid, title, body, tags, kind)
+      VALUES (new.rowid, new.title, new.body, new.tags, new.kind);
+  END;
+
+  -- Single vec table (384-dim float32 for all-MiniLM-L6-v2)
+  CREATE VIRTUAL TABLE IF NOT EXISTS vault_vec USING vec0(embedding float[384]);
+`;
+
+// ─── Database Init ───────────────────────────────────────────────────────────
+
+export function initDatabase(dbPath) {
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  try {
+    sqliteVec.load(db);
+  } catch (e) {
+    console.error(`[context-mcp] Failed to load sqlite-vec native module.`);
+    console.error(`[context-mcp] This usually means prebuilt binaries aren't available for your platform.`);
+    console.error(`[context-mcp] Try: npm rebuild sqlite-vec`);
+    console.error(`[context-mcp] Error: ${e.message}`);
+    throw e;
+  }
+
+  const version = db.pragma("user_version", { simple: true });
+
+  // Enforce fresh-DB-only — old schemas get a full rebuild
+  if (version > 0 && version < 5) {
+    console.error(`[context-mcp] Schema v${version} is outdated. Rebuilding database...`);
+    db.close();
+    unlinkSync(dbPath);
+    try { unlinkSync(dbPath + "-wal"); } catch {}
+    try { unlinkSync(dbPath + "-shm"); } catch {}
+    const freshDb = new Database(dbPath);
+    freshDb.pragma("journal_mode = WAL");
+    freshDb.pragma("foreign_keys = ON");
+    try {
+      sqliteVec.load(freshDb);
+    } catch (e) {
+      console.error(`[context-mcp] Failed to load sqlite-vec native module.`);
+      console.error(`[context-mcp] This usually means prebuilt binaries aren't available for your platform.`);
+      console.error(`[context-mcp] Try: npm rebuild sqlite-vec`);
+      console.error(`[context-mcp] Error: ${e.message}`);
+      throw e;
+    }
+    freshDb.exec(SCHEMA_DDL);
+    freshDb.pragma("user_version = 5");
+    return freshDb;
+  }
+
+  if (version < 5) {
+    db.exec(SCHEMA_DDL);
+    db.pragma("user_version = 5");
+  }
+
+  return db;
+}
+
+// ─── Prepared Statements Factory ─────────────────────────────────────────────
+
+export function prepareStatements(db) {
+  return {
+    insertEntry: db.prepare(`INSERT INTO vault (id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+    updateEntry: db.prepare(`UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, identity_key = ?, expires_at = ? WHERE file_path = ?`),
+    deleteEntry: db.prepare(`DELETE FROM vault WHERE id = ?`),
+    getRowid: db.prepare(`SELECT rowid FROM vault WHERE id = ?`),
+    getRowidByPath: db.prepare(`SELECT rowid FROM vault WHERE file_path = ?`),
+    getByIdentityKey: db.prepare(`SELECT * FROM vault WHERE kind = ? AND identity_key = ?`),
+    upsertByIdentityKey: db.prepare(`UPDATE vault SET title = ?, body = ?, meta = ?, tags = ?, source = ?, category = ?, file_path = ?, expires_at = ? WHERE kind = ? AND identity_key = ?`),
+    insertVecStmt: db.prepare(`INSERT INTO vault_vec (rowid, embedding) VALUES (?, ?)`),
+    deleteVecStmt: db.prepare(`DELETE FROM vault_vec WHERE rowid = ?`),
+  };
+}
+
+// ─── Vector Helpers (parameterized rowid via cached statements) ──────────────
+
+export function insertVec(stmts, rowid, embedding) {
+  // sqlite-vec requires BigInt for primary key — better-sqlite3 binds Number as REAL,
+  // but vec0 virtual tables only accept INTEGER rowids
+  const safeRowid = BigInt(rowid);
+  if (safeRowid < 1n) throw new Error(`Invalid rowid: ${rowid}`);
+  stmts.insertVecStmt.run(safeRowid, embedding);
+}
+
+export function deleteVec(stmts, rowid) {
+  const safeRowid = BigInt(rowid);
+  if (safeRowid < 1n) throw new Error(`Invalid rowid: ${rowid}`);
+  stmts.deleteVecStmt.run(safeRowid);
+}

package/src/index/embed.js

@@ -0,0 +1,56 @@
+/**
+ * embed.js — Text embedding via HuggingFace transformers
+ */
+
+import { pipeline } from "@huggingface/transformers";
+
+let extractor = null;
+
+async function ensurePipeline() {
+  if (!extractor) {
+    try {
+      extractor = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2");
+    } catch (e) {
+      console.error(`[context-mcp] Failed to load embedding model: ${e.message}`);
+      console.error(`[context-mcp] The model (~80 MB) is downloaded on first run.`);
+      console.error(`[context-mcp] Check: network connectivity, disk space, Node.js >=20`);
+      throw e;
+    }
+  }
+  return extractor;
+}
+
+export async function embed(text) {
+  const ext = await ensurePipeline();
+  const result = await ext([text], { pooling: "mean", normalize: true });
+  // P5: Health check — force re-init on empty results
+  if (!result?.data?.length) {
+    extractor = null;
+    throw new Error("Embedding pipeline returned empty result");
+  }
+  return new Float32Array(result.data);
+}
+
+/**
+ * P4: Batch embedding — embed multiple texts in a single pipeline call.
+ * Returns an array of Float32Array embeddings (one per input text).
+ */
+export async function embedBatch(texts) {
+  if (!texts.length) return [];
+  const ext = await ensurePipeline();
+  const result = await ext(texts, { pooling: "mean", normalize: true });
+  if (!result?.data?.length) {
+    extractor = null;
+    throw new Error("Embedding pipeline returned empty result");
+  }
+  const dim = result.data.length / texts.length;
+  if (!Number.isInteger(dim) || dim <= 0) {
+    throw new Error(`Unexpected embedding dimension: ${result.data.length} / ${texts.length} = ${dim}`);
+  }
+  return texts.map((_, i) => new Float32Array(result.data.buffer, i * dim * 4, dim));
+}
+
+/** P5: Force re-initialization on next embed call. */
+export function resetEmbedPipeline() {
+  extractor = null;
+}

package/src/index/index.js

@@ -0,0 +1,258 @@
+/**
+ * Index Layer — Public API
+ *
+ * Owns the database as a derived index. Handles both bulk sync (reindex)
+ * and single-entry indexing (indexEntry) for write-through capture.
+ *
+ * Agent Constraint: Can import ../core. Owns db.js and embed.js.
+ */
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { dirToKind, walkDir, ulid } from "../core/files.js";
+import { categoryFor, CATEGORY_DIRS } from "../core/categories.js";
+import { parseFrontmatter, parseEntryFromMarkdown } from "../core/frontmatter.js";
+import { embedBatch } from "./embed.js";
+
+const EXCLUDED_DIRS = new Set(["projects", "_archive"]);
+const EXCLUDED_FILES = new Set(["context.md", "memory.md", "README.md"]);
+
+const EMBED_BATCH_SIZE = 32;
+
+/**
+ * Index a single entry with idempotent upsert behavior.
+ * Called immediately after Capture Layer writes the file.
+ *
+ * For entities with identity_key: uses upsertByIdentityKey if existing row found.
+ *
+ * @param {{ db, stmts, embed, insertVec, deleteVec }} ctx
+ * @param {{ id, kind, category, title, body, meta, tags, source, filePath, createdAt, identity_key, expires_at }} entry
+ */
+export async function indexEntry(ctx, { id, kind, category, title, body, meta, tags, source, filePath, createdAt, identity_key, expires_at }) {
+  const tagsJson = tags ? JSON.stringify(tags) : null;
+  const metaJson = meta ? JSON.stringify(meta) : null;
+  const cat = category || categoryFor(kind);
+
+  let wasUpdate = false;
+
+  // Entity upsert: check by (kind, identity_key) first
+  if (cat === "entity" && identity_key) {
+    const existing = ctx.stmts.getByIdentityKey.get(kind, identity_key);
+    if (existing) {
+      ctx.stmts.upsertByIdentityKey.run(
+        title || null, body, metaJson, tagsJson, source || "claude-code", cat, filePath, expires_at || null,
+        kind, identity_key
+      );
+      wasUpdate = true;
+    }
+  }
+
+  if (!wasUpdate) {
+    try {
+      ctx.stmts.insertEntry.run(id, kind, cat, title || null, body, metaJson, tagsJson, source || "claude-code", filePath, identity_key || null, expires_at || null, createdAt);
+    } catch (e) {
+      if (e.message.includes("UNIQUE constraint")) {
+        ctx.stmts.updateEntry.run(title || null, body, metaJson, tagsJson, source || "claude-code", cat, identity_key || null, expires_at || null, filePath);
+        wasUpdate = true;
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  // After update, get rowid by file_path (since id might differ); otherwise by id
+  const rowidResult = wasUpdate
+    ? ctx.stmts.getRowidByPath.get(filePath)
+    : ctx.stmts.getRowid.get(id);
+
+  if (!rowidResult || rowidResult.rowid == null) {
+    throw new Error(`Could not find rowid for entry: ${wasUpdate ? `file_path=${filePath}` : `id=${id}`}`);
+  }
+
+  const rowid = Number(rowidResult.rowid);
+  if (!Number.isFinite(rowid) || rowid < 1) {
+    throw new Error(`Invalid rowid retrieved: ${rowidResult.rowid} (type: ${typeof rowidResult.rowid})`);
+  }
+  const embeddingText = [title, body].filter(Boolean).join(" ");
+  const embedding = await ctx.embed(embeddingText);
+
+  // Upsert vec: delete old if exists, then insert new
+  try { ctx.deleteVec(rowid); } catch { /* no-op if not found */ }
+  ctx.insertVec(rowid, embedding);
+}
+
+/**
+ * Bulk reindex: sync vault directory into the database.
+ * P2: Wrapped in a transaction for atomicity.
+ * P3: Detects title/tag/meta changes, not just body.
+ * P4: Batches embedding calls for performance.
+ *
+ * @param {{ db, config, stmts, embed, insertVec, deleteVec }} ctx
+ * @param {{ fullSync?: boolean }} opts — fullSync=true adds/updates/deletes; false=add-only
+ * @returns {Promise<{added: number, updated: number, removed: number, unchanged: number}>}
+ */
+export async function reindex(ctx, opts = {}) {
+  const { fullSync = true } = opts;
+  const stats = { added: 0, updated: 0, removed: 0, unchanged: 0 };
+
+  if (!existsSync(ctx.config.vaultDir)) return stats;
+
+  // Use INSERT OR IGNORE for reindex — handles files with duplicate frontmatter IDs
+  const upsertEntry = ctx.db.prepare(
+    `INSERT OR IGNORE INTO vault (id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+
+  // Auto-discover kind directories, supporting both:
+  //   - Nested: knowledge/insights/, events/sessions/ (category dirs at top level)
+  //   - Flat:   insights/, decisions/ (legacy — kind dirs at top level)
+  const kindEntries = []; // { kind, dir }
+  const topDirs = readdirSync(ctx.config.vaultDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !EXCLUDED_DIRS.has(d.name) && !d.name.startsWith("_"));
+
+  for (const d of topDirs) {
+    if (CATEGORY_DIRS.has(d.name)) {
+      // Category directory — look one level deeper for kind directories
+      const catDir = join(ctx.config.vaultDir, d.name);
+      const subDirs = readdirSync(catDir, { withFileTypes: true })
+        .filter((sd) => sd.isDirectory() && !sd.name.startsWith("_"));
+      for (const sd of subDirs) {
+        kindEntries.push({ kind: dirToKind(sd.name), dir: join(catDir, sd.name) });
+      }
+    } else {
+      // Legacy flat structure — top-level dir is a kind dir
+      kindEntries.push({ kind: dirToKind(d.name), dir: join(ctx.config.vaultDir, d.name) });
+    }
+  }
+
+  // P2: Wrap entire reindex in a transaction
+  ctx.db.exec("BEGIN");
+  try {
+    // P4: Collect entries needing embedding, then batch-embed
+    const pendingEmbeds = []; // { rowid, text }
+
+    for (const { kind, dir } of kindEntries) {
+      const category = categoryFor(kind);
+      const mdFiles = walkDir(dir).filter((f) => !EXCLUDED_FILES.has(basename(f.filePath)));
+
+      // P3: Fetch all mutable fields for change detection
+      const dbRows = ctx.db.prepare("SELECT id, file_path, body, title, tags, meta FROM vault WHERE kind = ?").all(kind);
+      const dbByPath = new Map(dbRows.map((r) => [r.file_path, r]));
+      const diskPaths = new Set(mdFiles.map((e) => e.filePath));
+
+      for (const { filePath, relDir } of mdFiles) {
+        const existing = dbByPath.get(filePath);
+
+        // In add-only mode, skip files already in DB
+        if (!fullSync && existing) {
+          stats.unchanged++;
+          continue;
+        }
+
+        const raw = readFileSync(filePath, "utf-8");
+        if (!raw.startsWith("---\n")) {
+          console.error(`[reindex] skipping (no frontmatter): ${filePath}`);
+          continue;
+        }
+        const { meta: fmMeta, body: rawBody } = parseFrontmatter(raw);
+        const parsed = parseEntryFromMarkdown(kind, rawBody, fmMeta);
+
+        // Extract identity_key and expires_at from frontmatter
+        const identity_key = fmMeta.identity_key || null;
+        const expires_at = fmMeta.expires_at || null;
+
+        // Derive folder from disk location (source of truth)
+        const meta = { ...(parsed.meta || {}) };
+        if (relDir) meta.folder = relDir;
+        else delete meta.folder;
+        const metaJson = Object.keys(meta).length ? JSON.stringify(meta) : null;
+
+        if (!existing) {
+          // New file — add to DB (OR IGNORE if ID already exists at another path)
+          const id = fmMeta.id || ulid();
+          const tagsJson = fmMeta.tags ? JSON.stringify(fmMeta.tags) : null;
+          const created = fmMeta.created || new Date().toISOString();
+
+          const result = upsertEntry.run(id, kind, category, parsed.title || null, parsed.body, metaJson, tagsJson, fmMeta.source || "file", filePath, identity_key, expires_at, created);
+          if (result.changes > 0) {
+            const rowid = ctx.stmts.getRowid.get(id).rowid;
+            const embeddingText = [parsed.title, parsed.body].filter(Boolean).join(" ");
+            pendingEmbeds.push({ rowid, text: embeddingText });
+            stats.added++;
+          } else {
+            stats.unchanged++;
+          }
+        } else if (fullSync) {
+          // P3: Compare all mutable fields, not just body
+          const tagsJson = fmMeta.tags ? JSON.stringify(fmMeta.tags) : null;
+          const titleChanged = (parsed.title || null) !== (existing.title || null);
+          const bodyChanged = existing.body !== parsed.body;
+          const tagsChanged = tagsJson !== (existing.tags || null);
+          const metaChanged = metaJson !== (existing.meta || null);
+
+          if (bodyChanged || titleChanged || tagsChanged || metaChanged) {
+            ctx.stmts.updateEntry.run(parsed.title || null, parsed.body, metaJson, tagsJson, fmMeta.source || "file", category, identity_key, expires_at, filePath);
+
+            // P0: Re-embed if title or body changed
+            if (bodyChanged || titleChanged) {
+              const rowid = ctx.stmts.getRowid.get(existing.id)?.rowid;
+              if (rowid) {
+                ctx.deleteVec(rowid);
+                const embeddingText = [parsed.title, parsed.body].filter(Boolean).join(" ");
+                pendingEmbeds.push({ rowid, text: embeddingText });
+              }
+            }
+            stats.updated++;
+          } else {
+            stats.unchanged++;
+          }
+        } else {
+          stats.unchanged++;
+        }
+      }
+
+      // Find deleted files (in DB but not on disk) — only in fullSync mode
+      if (fullSync) {
+        for (const [dbPath, row] of dbByPath) {
+          if (!diskPaths.has(dbPath)) {
+            const vRowid = ctx.stmts.getRowid.get(row.id)?.rowid;
+            if (vRowid) ctx.deleteVec(vRowid);
+            ctx.stmts.deleteEntry.run(row.id);
+            stats.removed++;
+          }
+        }
+      }
+    }
+
+    // P4: Batch embed all pending texts
+    for (let i = 0; i < pendingEmbeds.length; i += EMBED_BATCH_SIZE) {
+      const batch = pendingEmbeds.slice(i, i + EMBED_BATCH_SIZE);
+      const embeddings = await embedBatch(batch.map((e) => e.text));
+      for (let j = 0; j < batch.length; j++) {
+        ctx.insertVec(batch[j].rowid, embeddings[j]);
+      }
+    }
+
+    // Clean up entries for kinds whose directories no longer exist on disk
+    if (fullSync) {
+      const indexedKinds = new Set(kindEntries.map((ke) => ke.kind));
+      const allDbKinds = ctx.db.prepare("SELECT DISTINCT kind FROM vault").all();
+      for (const { kind } of allDbKinds) {
+        if (!indexedKinds.has(kind)) {
+          const orphaned = ctx.db.prepare("SELECT id, rowid FROM vault WHERE kind = ?").all(kind);
+          for (const row of orphaned) {
+            try { ctx.deleteVec(row.rowid); } catch {}
+            ctx.stmts.deleteEntry.run(row.id);
+            stats.removed++;
+          }
+        }
+      }
+    }
+
+    ctx.db.exec("COMMIT");
+  } catch (e) {
+    ctx.db.exec("ROLLBACK");
+    throw e;
+  }
+
+  return stats;
+}

package/src/retrieve/README.md

@@ -0,0 +1,19 @@
+# Retrieve Layer
+
+The read path. All query logic lives here — hybrid search and any future retrieval strategies.
+
+## Public API (`index.js`)
+
+```js
+hybridSearch(ctx, query, { kindFilter, limit, offset })  → Promise<Array<result>>
+```
+
+Runs both FTS5 text matching and vector cosine similarity, merges scores with recency weighting, and returns results sorted by combined relevance.
+
+## Dependency Rule
+
+```
+retrieve/ → core/ (allowed but currently unused)
+```
+
+Read-only access to the database via `ctx.db`. Never imports from `capture/`, `index/`, or `server/`.

package/src/retrieve/index.js

@@ -0,0 +1,173 @@
+/**
+ * Retrieve Layer — Public API
+ *
+ * All read-path query logic: hybrid semantic search and any future
+ * query patterns (scoped, recency-weighted, etc.).
+ *
+ * Agent Constraint: Read-only access to DB. Never writes.
+ */
+
+const FTS_WEIGHT = 0.4;
+const VEC_WEIGHT = 0.6;
+
+/**
+ * Strip FTS5 metacharacters from query words and build an AND query.
+ * Returns null if no valid words remain.
+ */
+function buildFtsQuery(query) {
+  const words = query
+    .split(/\s+/)
+    .map((w) => w.replace(/[*"()\-:^~{}]/g, ""))
+    .filter((w) => w.length > 0);
+  if (!words.length) return null;
+  return words.map((w) => `"${w}"`).join(" AND ");
+}
+
+/**
+ * Category-aware recency decay:
+ *   knowledge + entity: no decay (enduring)
+ *   event: steeper decay (~0.5 at 30 days)
+ */
+function recencyBoost(createdAt, category) {
+  if (category !== "event") return 1.0;
+  const ageDays = (Date.now() - new Date(createdAt).getTime()) / 86400000;
+  return 1 / (1 + ageDays / 30);
+}
+
+/**
+ * Build additional WHERE clauses for category/time filtering.
+ * Returns { clauses: string[], params: any[] }
+ */
+function buildFilterClauses({ categoryFilter, since, until }) {
+  const clauses = [];
+  const params = [];
+  if (categoryFilter) {
+    clauses.push("e.category = ?");
+    params.push(categoryFilter);
+  }
+  if (since) {
+    clauses.push("e.created_at >= ?");
+    params.push(since);
+  }
+  if (until) {
+    clauses.push("e.created_at <= ?");
+    params.push(until);
+  }
+  clauses.push("(e.expires_at IS NULL OR e.expires_at > datetime('now'))");
+  return { clauses, params };
+}
+
+/**
+ * Hybrid search combining FTS5 text matching and vector similarity.
+ *
+ * @param {{ db, embed }} ctx
+ * @param {string} query
+ * @param {{ kindFilter?: string|null, categoryFilter?: string|null, since?: string|null, until?: string|null, limit?: number, offset?: number }} opts
+ * @returns {Promise<Array<{id, kind, category, title, body, meta, tags, source, file_path, created_at, score}>>}
+ */
+export async function hybridSearch(
+  ctx,
+  query,
+  { kindFilter = null, categoryFilter = null, since = null, until = null, limit = 20, offset = 0 } = {}
+) {
+  const results = new Map();
+  const extraFilters = buildFilterClauses({ categoryFilter, since, until });
+
+  // FTS5 search
+  const ftsQuery = buildFtsQuery(query);
+  if (ftsQuery) {
+    try {
+      const whereParts = ["vault_fts MATCH ?"];
+      const ftsParams = [ftsQuery];
+
+      if (kindFilter) {
+        whereParts.push("e.kind = ?");
+        ftsParams.push(kindFilter);
+      }
+      whereParts.push(...extraFilters.clauses);
+      ftsParams.push(...extraFilters.params);
+
+      const ftsSQL = `SELECT e.*, rank FROM vault_fts f JOIN vault e ON f.rowid = e.rowid WHERE ${whereParts.join(" AND ")} ORDER BY rank LIMIT 15`;
+      const rows = ctx.db.prepare(ftsSQL).all(...ftsParams);
+
+      // Normalize FTS scores to [0, 1]
+      const ftsScores = rows.map((r) => Math.abs(r.rank || 0));
+      const maxFts = Math.max(...ftsScores, 1);
+
+      for (let i = 0; i < rows.length; i++) {
+        const { rank: _rank, ...row } = rows[i];
+        const normalized = ftsScores[i] / maxFts;
+        results.set(row.id, { ...row, score: normalized * FTS_WEIGHT });
+      }
+    } catch (err) {
+      if (err.message?.includes("fts5: syntax error")) {
+        // Expected: malformed query, fall through to vector search
+      } else {
+        console.error(`[retrieve] FTS search error: ${err.message}`);
+      }
+    }
+  }
+
+  // Vector similarity search
+  try {
+    const vecCount = ctx.db
+      .prepare("SELECT COUNT(*) as c FROM vault_vec")
+      .get().c;
+    if (vecCount > 0) {
+      const queryVec = await ctx.embed(query);
+      const vecLimit = kindFilter ? 30 : 15;
+      const vecRows = ctx.db
+        .prepare(
+          `SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT ${vecLimit}`
+        )
+        .all(queryVec);
+
+      if (vecRows.length) {
+        // Batch hydration: single query instead of N+1
+        const rowids = vecRows.map((vr) => vr.rowid);
+        const placeholders = rowids.map(() => "?").join(",");
+        const hydrated = ctx.db
+          .prepare(`SELECT rowid, * FROM vault WHERE rowid IN (${placeholders})`)
+          .all(...rowids);
+
+        const byRowid = new Map();
+        for (const row of hydrated) byRowid.set(row.rowid, row);
+
+        for (const vr of vecRows) {
+          const row = byRowid.get(vr.rowid);
+          if (!row) continue;
+          if (kindFilter && row.kind !== kindFilter) continue;
+          if (categoryFilter && row.category !== categoryFilter) continue;
+          if (since && row.created_at < since) continue;
+          if (until && row.created_at > until) continue;
+          if (row.expires_at && new Date(row.expires_at) <= new Date()) continue;
+
+          const { rowid: _rowid, ...cleanRow } = row;
+          // sqlite-vec returns L2 distance [0, 2] for normalized vectors.
+          // Convert to similarity [1, 0] with: 1 - distance/2
+          const vecScore = Math.max(0, 1 - vr.distance / 2) * VEC_WEIGHT;
+          const existing = results.get(cleanRow.id);
+          if (existing) {
+            existing.score += vecScore;
+          } else {
+            results.set(cleanRow.id, { ...cleanRow, score: vecScore });
+          }
+        }
+      }
+    }
+  } catch (err) {
+    if (err.message?.includes("no such table")) {
+      // Expected on fresh vaults with no vec table yet
+    } else {
+      console.error(`[retrieve] Vector search error: ${err.message}`);
+    }
+  }
+
+  // Apply category-aware recency boost
+  for (const [, entry] of results) {
+    entry.score *= recencyBoost(entry.created_at, entry.category);
+  }
+
+  const sorted = [...results.values()].sort((a, b) => b.score - a.score);
+  return sorted.slice(offset, offset + limit);
+}