context-vault 2.6.1 → 2.7.1

package/bin/cli.js

@@ -1425,6 +1425,8 @@ async function runImport() {
 async function runExport() {
   const format = getFlag("--format") || "json";
   const output = getFlag("--output");
+  const rawPageSize = getFlag("--page-size");
+  const pageSize = rawPageSize ? Math.max(1, parseInt(rawPageSize, 10) || 100) : null;
 
   const { resolveConfig } = await import("@context-vault/core/core/config");
   const { initDatabase, prepareStatements } = await import("@context-vault/core/index/db");
@@ -1438,25 +1440,33 @@ async function runExport() {
 
   const db = await initDatabase(config.dbPath);
 
-  const rows = db.prepare(
-    "SELECT * FROM vault WHERE (expires_at IS NULL OR expires_at > datetime('now')) ORDER BY created_at DESC"
-  ).all();
+  const whereClause = "WHERE (expires_at IS NULL OR expires_at > datetime('now'))";
 
-  db.close();
+  let entries;
+  if (pageSize) {
+    // Paginated: fetch in chunks to avoid loading everything into memory
+    entries = [];
+    let offset = 0;
+    const stmt = db.prepare(
+      `SELECT * FROM vault ${whereClause} ORDER BY created_at DESC LIMIT ? OFFSET ?`
+    );
+    while (true) {
+      const rows = stmt.all(pageSize, offset);
+      if (rows.length === 0) break;
+      for (const row of rows) {
+        entries.push(mapExportRow(row));
+      }
+      offset += rows.length;
+      if (rows.length < pageSize) break;
+    }
+  } else {
+    const rows = db.prepare(
+      `SELECT * FROM vault ${whereClause} ORDER BY created_at DESC`
+    ).all();
+    entries = rows.map(mapExportRow);
+  }
 
-  const entries = rows.map((row) => ({
-    id: row.id,
-    kind: row.kind,
-    category: row.category,
-    title: row.title || null,
-    body: row.body || null,
-    tags: row.tags ? JSON.parse(row.tags) : [],
-    meta: row.meta ? JSON.parse(row.meta) : {},
-    source: row.source || null,
-    identity_key: row.identity_key || null,
-    expires_at: row.expires_at || null,
-    created_at: row.created_at,
-  }));
+  db.close();
 
   let content;
 
@@ -1489,6 +1499,22 @@ async function runExport() {
   }
 }
 
+function mapExportRow(row) {
+  return {
+    id: row.id,
+    kind: row.kind,
+    category: row.category,
+    title: row.title || null,
+    body: row.body || null,
+    tags: row.tags ? JSON.parse(row.tags) : [],
+    meta: row.meta ? JSON.parse(row.meta) : {},
+    source: row.source || null,
+    identity_key: row.identity_key || null,
+    expires_at: row.expires_at || null,
+    created_at: row.created_at,
+  };
+}
+
 // ─── Ingest Command ─────────────────────────────────────────────────────────
 
 async function runIngest() {

package/node_modules/@context-vault/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",

package/node_modules/@context-vault/core/src/core/status.js

@@ -10,7 +10,7 @@ import { isEmbedAvailable } from "../index/embed.js";
 /**
  * Gather raw vault status data for formatting by consumers.
  *
- * @param {{ db, config }} ctx
+ * @param {import('../server/types.js').BaseCtx} ctx
  * @param {{ userId?: string }} opts — optional userId for per-user stats
  * @returns {{ fileCount, subdirs, kindCounts, dbSize, stalePaths, resolvedFrom, embeddingStatus, errors }}
  */

package/node_modules/@context-vault/core/src/index/index.js

@@ -25,8 +25,8 @@ const EMBED_BATCH_SIZE = 32;
  *
  * 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
+ * @param {import('../server/types.js').BaseCtx & Partial<import('../server/types.js').HostedCtxExtensions>} ctx
+ * @param {{ id, kind, category, title, body, meta, tags, source, filePath, createdAt, identity_key, expires_at, userId }} entry
  */
 export async function indexEntry(ctx, { id, kind, category, title, body, meta, tags, source, filePath, createdAt, identity_key, expires_at, userId }) {
   const tagsJson = tags ? JSON.stringify(tags) : null;
@@ -108,7 +108,7 @@ export async function indexEntry(ctx, { id, kind, category, title, body, meta, t
  * P3: Detects title/tag/meta changes, not just body.
  * P4: Batches embedding calls for performance.
  *
- * @param {{ db, config, stmts, embed, insertVec, deleteVec }} ctx
+ * @param {import('../server/types.js').BaseCtx} ctx
  * @param {{ fullSync?: boolean }} opts — fullSync=true adds/updates/deletes; false=add-only
  * @returns {Promise<{added: number, updated: number, removed: number, unchanged: number}>}
  */

package/node_modules/@context-vault/core/src/retrieve/index.js

@@ -68,7 +68,7 @@ export function buildFilterClauses({ categoryFilter, since, until, userIdFilter,
 /**
  * Hybrid search combining FTS5 text matching and vector similarity.
  *
- * @param {{ db, embed }} ctx
+ * @param {import('../server/types.js').BaseCtx} 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}>>}

package/node_modules/@context-vault/core/src/server/tools/context-status.js

@@ -0,0 +1,90 @@
+import { gatherVaultStatus } from "../../core/status.js";
+import { ok } from "../helpers.js";
+
+export const name = "context_status";
+
+export const description =
+  "Show vault health: resolved config, file counts per kind, database size, and any issues. Use to verify setup or troubleshoot. Call this when a user asks about their vault or to debug search issues.";
+
+export const inputSchema = {};
+
+/**
+ * @param {object} _args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ */
+export function handler(_args, ctx) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const status = gatherVaultStatus(ctx, { userId });
+
+  const hasIssues = status.stalePaths || (status.embeddingStatus?.missing > 0);
+  const healthIcon = hasIssues ? "⚠" : "✓";
+
+  const lines = [
+    `## ${healthIcon} Vault Status (connected)`,
+    ``,
+    `Vault:     ${config.vaultDir} (${config.vaultDirExists ? status.fileCount + " files" : "missing"})`,
+    `Database:  ${config.dbPath} (${status.dbSize})`,
+    `Dev dir:   ${config.devDir}`,
+    `Data dir:  ${config.dataDir}`,
+    `Config:    ${config.configPath}`,
+    `Resolved via: ${status.resolvedFrom}`,
+    `Schema:    v7 (teams)`,
+  ];
+
+  if (status.embeddingStatus) {
+    const { indexed, total, missing } = status.embeddingStatus;
+    const pct = total > 0 ? Math.round((indexed / total) * 100) : 100;
+    lines.push(`Embeddings: ${indexed}/${total} (${pct}%)`);
+  }
+  if (status.embedModelAvailable === false) {
+    lines.push(`Embed model: unavailable (semantic search disabled, FTS still works)`);
+  } else if (status.embedModelAvailable === true) {
+    lines.push(`Embed model: loaded`);
+  }
+  lines.push(`Decay:     ${config.eventDecayDays} days (event recency window)`);
+  if (status.expiredCount > 0) {
+    lines.push(`Expired:   ${status.expiredCount} entries (pruned on next reindex)`);
+  }
+
+  lines.push(``, `### Indexed`);
+
+  if (status.kindCounts.length) {
+    for (const { kind, c } of status.kindCounts) lines.push(`- ${c} ${kind}s`);
+  } else {
+    lines.push(`- (empty)`);
+  }
+
+  if (status.categoryCounts.length) {
+    lines.push(``);
+    lines.push(`### Categories`);
+    for (const { category, c } of status.categoryCounts) lines.push(`- ${category}: ${c}`);
+  }
+
+  if (status.subdirs.length) {
+    lines.push(``);
+    lines.push(`### Disk Directories`);
+    for (const { name, count } of status.subdirs) lines.push(`- ${name}/: ${count} files`);
+  }
+
+  if (status.stalePaths) {
+    lines.push(``);
+    lines.push(`### ⚠ Stale Paths`);
+    lines.push(`DB contains ${status.staleCount} paths not matching current vault dir.`);
+    lines.push(`Auto-reindex will fix this on next search or save.`);
+  }
+
+  // Suggested actions
+  const actions = [];
+  if (status.stalePaths) actions.push("- Run `context-vault reindex` to fix stale paths");
+  if (status.embeddingStatus?.missing > 0) actions.push("- Run `context-vault reindex` to generate missing embeddings");
+  if (!config.vaultDirExists) actions.push("- Run `context-vault setup` to create the vault directory");
+  if (status.kindCounts.length === 0 && config.vaultDirExists) actions.push("- Use `save_context` to add your first entry");
+
+  if (actions.length) {
+    lines.push("", "### Suggested Actions", ...actions);
+  }
+
+  return ok(lines.join("\n"));
+}

package/node_modules/@context-vault/core/src/server/tools/delete-context.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { unlinkSync } from "node:fs";
+import { ok, err } from "../helpers.js";
+
+export const name = "delete_context";
+
+export const description =
+  "Delete an entry from your vault by its ULID id. Removes the file from disk and cleans up the search index.";
+
+export const inputSchema = {
+  id: z.string().describe("The entry ULID to delete"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler({ id }, ctx, { ensureIndexed }) {
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  if (!id?.trim()) return err("Required: id (non-empty string)", "INVALID_INPUT");
+  await ensureIndexed();
+
+  const entry = ctx.stmts.getEntryById.get(id);
+  if (!entry) return err(`Entry not found: ${id}`, "NOT_FOUND");
+
+  // Ownership check: don't leak existence across users
+  if (userId !== undefined && entry.user_id !== userId) {
+    return err(`Entry not found: ${id}`, "NOT_FOUND");
+  }
+
+  // Delete file from disk first (source of truth)
+  if (entry.file_path) {
+    try { unlinkSync(entry.file_path); } catch {}
+  }
+
+  // Delete vector embedding
+  const rowidResult = ctx.stmts.getRowid.get(id);
+  if (rowidResult?.rowid) {
+    try { ctx.deleteVec(Number(rowidResult.rowid)); } catch {}
+  }
+
+  // Delete DB row (FTS trigger handles FTS cleanup)
+  ctx.stmts.deleteEntry.run(id);
+
+  return ok(`Deleted ${entry.kind}: ${entry.title || "(untitled)"} [${id}]`);
+}

package/node_modules/@context-vault/core/src/server/tools/get-context.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { hybridSearch } from "../../retrieve/index.js";
+import { categoryFor } from "../../core/categories.js";
+import { normalizeKind } from "../../core/files.js";
+import { ok, err } from "../helpers.js";
+import { isEmbedAvailable } from "../../index/embed.js";
+
+export const name = "get_context";
+
+export const description =
+  "Search your knowledge vault. Returns entries ranked by relevance using hybrid full-text + semantic search. Use this to find insights, decisions, patterns, or any saved context. Each result includes an `id` you can use with save_context or delete_context.";
+
+export const inputSchema = {
+  query: z.string().optional().describe("Search query (natural language or keywords). Optional if filters (tags, kind, category) are provided."),
+  kind: z.string().optional().describe("Filter by kind (e.g. 'insight', 'decision', 'pattern')"),
+  category: z.enum(["knowledge", "entity", "event"]).optional().describe("Filter by category"),
+  identity_key: z.string().optional().describe("For entity lookup: exact match on identity key. Requires kind."),
+  tags: z.array(z.string()).optional().describe("Filter by tags (entries must match at least one)"),
+  since: z.string().optional().describe("ISO date, return entries created after this"),
+  until: z.string().optional().describe("ISO date, return entries created before this"),
+  limit: z.number().optional().describe("Max results to return (default 10)"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler({ query, kind, category, identity_key, tags, since, until, limit }, ctx, { ensureIndexed, reindexFailed }) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const hasQuery = query?.trim();
+  const hasFilters = kind || category || tags?.length || since || until || identity_key;
+  if (!hasQuery && !hasFilters) return err("Required: query or at least one filter (kind, category, tags, since, until, identity_key)", "INVALID_INPUT");
+  await ensureIndexed();
+
+  const kindFilter = kind ? normalizeKind(kind) : null;
+
+  // Gap 1: Entity exact-match by identity_key
+  if (identity_key) {
+    if (!kindFilter) return err("identity_key requires kind to be specified", "INVALID_INPUT");
+    const match = ctx.stmts.getByIdentityKey.get(kindFilter, identity_key, userId !== undefined ? userId : null);
+    if (match) {
+      const entryTags = match.tags ? JSON.parse(match.tags) : [];
+      const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+      const relPath = match.file_path && config.vaultDir ? match.file_path.replace(config.vaultDir + "/", "") : match.file_path || "n/a";
+      const lines = [
+        `## Entity Match (exact)\n`,
+        `### ${match.title || "(untitled)"} [${match.kind}/${match.category}]`,
+        `1.000 · ${tagStr} · ${relPath} · id: \`${match.id}\``,
+        match.body?.slice(0, 300) + (match.body?.length > 300 ? "..." : ""),
+      ];
+      return ok(lines.join("\n"));
+    }
+    // Fall through to semantic search as fallback
+  }
+
+  // Gap 2: Event default time-window
+  const effectiveCategory = category || (kindFilter ? categoryFor(kindFilter) : null);
+  let effectiveSince = since || null;
+  let effectiveUntil = until || null;
+  let autoWindowed = false;
+  if (effectiveCategory === "event" && !since && !until) {
+    const decayMs = (config.eventDecayDays || 30) * 86400000;
+    effectiveSince = new Date(Date.now() - decayMs).toISOString();
+    autoWindowed = true;
+  }
+
+  const effectiveLimit = limit || 10;
+  // When tag-filtering, over-fetch to compensate for post-filter reduction
+  const fetchLimit = tags?.length ? effectiveLimit * 10 : effectiveLimit;
+
+  let filtered;
+  if (hasQuery) {
+    // Hybrid search mode
+    const sorted = await hybridSearch(ctx, query, {
+      kindFilter,
+      categoryFilter: category || null,
+      since: effectiveSince,
+      until: effectiveUntil,
+      limit: fetchLimit,
+      decayDays: config.eventDecayDays || 30,
+      userIdFilter: userId,
+    });
+
+    // Post-filter by tags if provided, then apply requested limit
+    filtered = tags?.length
+      ? sorted.filter((r) => {
+          const entryTags = r.tags ? JSON.parse(r.tags) : [];
+          return tags.some((t) => entryTags.includes(t));
+        }).slice(0, effectiveLimit)
+      : sorted;
+  } else {
+    // Filter-only mode (no query, use SQL directly)
+    const clauses = [];
+    const params = [];
+    if (userId !== undefined) { clauses.push("user_id = ?"); params.push(userId); }
+    if (kindFilter) { clauses.push("kind = ?"); params.push(kindFilter); }
+    if (category) { clauses.push("category = ?"); params.push(category); }
+    if (effectiveSince) { clauses.push("created_at >= ?"); params.push(effectiveSince); }
+    if (effectiveUntil) { clauses.push("created_at <= ?"); params.push(effectiveUntil); }
+    clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    params.push(fetchLimit);
+    const rows = ctx.db.prepare(`SELECT * FROM vault ${where} ORDER BY created_at DESC LIMIT ?`).all(...params);
+
+    // Post-filter by tags if provided, then apply requested limit
+    filtered = tags?.length
+      ? rows.filter((r) => {
+          const entryTags = r.tags ? JSON.parse(r.tags) : [];
+          return tags.some((t) => entryTags.includes(t));
+        }).slice(0, effectiveLimit)
+      : rows;
+
+    // Add score field for consistent output
+    for (const r of filtered) r.score = 0;
+  }
+
+  if (!filtered.length) return ok(hasQuery ? "No results found for: " + query : "No entries found matching the given filters.");
+
+  // Decrypt encrypted entries if ctx.decrypt is available
+  if (ctx.decrypt) {
+    for (const r of filtered) {
+      if (r.body_encrypted) {
+        const decrypted = await ctx.decrypt(r);
+        r.body = decrypted.body;
+        if (decrypted.title) r.title = decrypted.title;
+        if (decrypted.meta) r.meta = JSON.stringify(decrypted.meta);
+      }
+    }
+  }
+
+  const lines = [];
+  if (reindexFailed) lines.push(`> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-vault reindex\` to fix.\n`);
+  if (hasQuery && isEmbedAvailable() === false) lines.push(`> **Note:** Semantic search unavailable — results ranked by keyword match only. Run \`context-vault setup\` to download the embedding model.\n`);
+  const heading = hasQuery ? `Results for "${query}"` : "Filtered entries";
+  lines.push(`## ${heading} (${filtered.length} matches)\n`);
+  for (let i = 0; i < filtered.length; i++) {
+    const r = filtered[i];
+    const entryTags = r.tags ? JSON.parse(r.tags) : [];
+    const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+    const relPath = r.file_path && config.vaultDir ? r.file_path.replace(config.vaultDir + "/", "") : r.file_path || "n/a";
+    lines.push(`### [${i + 1}/${filtered.length}] ${r.title || "(untitled)"} [${r.kind}/${r.category}]`);
+    lines.push(`${r.score.toFixed(3)} · ${tagStr} · ${relPath} · id: \`${r.id}\``);
+    lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
+    lines.push("");
+  }
+  if (autoWindowed) {
+    lines.push(`_Showing events from last ${config.eventDecayDays || 30} days. Use since/until for custom range._`);
+  }
+  return ok(lines.join("\n"));
+}

package/node_modules/@context-vault/core/src/server/tools/ingest-url.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+import { captureAndIndex } from "../../capture/index.js";
+import { indexEntry } from "../../index/index.js";
+import { ok, err, ensureVaultExists } from "../helpers.js";
+
+// ─── Input size limits (mirrors hosted validation) ────────────────────────────
+const MAX_URL_LENGTH = 2048;
+const MAX_KIND_LENGTH = 64;
+const MAX_TAG_LENGTH = 100;
+const MAX_TAGS_COUNT = 20;
+
+export const name = "ingest_url";
+
+export const description =
+  "Fetch a URL, extract its readable content, and save it as a vault entry. Useful for saving articles, documentation, or web pages to your knowledge vault.";
+
+export const inputSchema = {
+  url: z.string().describe("The URL to fetch and save"),
+  kind: z.string().optional().describe("Entry kind (default: reference)"),
+  tags: z.array(z.string()).optional().describe("Tags for the entry"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler({ url: targetUrl, kind, tags }, ctx, { ensureIndexed }) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!targetUrl?.trim()) return err("Required: url (non-empty string)", "INVALID_INPUT");
+  if (targetUrl.length > MAX_URL_LENGTH) return err(`url must be under ${MAX_URL_LENGTH} chars`, "INVALID_INPUT");
+  if (kind !== undefined && kind !== null) {
+    if (typeof kind !== "string" || kind.length > MAX_KIND_LENGTH) {
+      return err(`kind must be a string, max ${MAX_KIND_LENGTH} chars`, "INVALID_INPUT");
+    }
+  }
+  if (tags !== undefined && tags !== null) {
+    if (!Array.isArray(tags)) return err("tags must be an array of strings", "INVALID_INPUT");
+    if (tags.length > MAX_TAGS_COUNT) return err(`tags: max ${MAX_TAGS_COUNT} tags allowed`, "INVALID_INPUT");
+    for (const tag of tags) {
+      if (typeof tag !== "string" || tag.length > MAX_TAG_LENGTH) {
+        return err(`each tag must be a string, max ${MAX_TAG_LENGTH} chars`, "INVALID_INPUT");
+      }
+    }
+  }
+
+  await ensureIndexed();
+
+  // Hosted tier limit enforcement
+  if (ctx.checkLimits) {
+    const usage = ctx.checkLimits();
+    if (usage.entryCount >= usage.maxEntries) {
+      return err(`Entry limit reached (${usage.maxEntries}). Upgrade to Pro for unlimited entries.`, "LIMIT_EXCEEDED");
+    }
+  }
+
+  try {
+    const { ingestUrl } = await import("../../capture/ingest-url.js");
+    const entryData = await ingestUrl(targetUrl, { kind, tags });
+    const entry = await captureAndIndex(ctx, { ...entryData, userId }, indexEntry);
+    const relPath = entry.filePath ? entry.filePath.replace(config.vaultDir + "/", "") : entry.filePath;
+    const parts = [
+      `✓ Ingested URL → ${relPath}`,
+      `  id: ${entry.id}`,
+      `  title: ${entry.title || "(untitled)"}`,
+      `  source: ${entry.source || targetUrl}`,
+    ];
+    if (entry.tags?.length) parts.push(`  tags: ${entry.tags.join(", ")}`);
+    parts.push(`  body: ${entry.body?.length || 0} chars`);
+    parts.push("", "_Use this id to update or delete later._");
+    return ok(parts.join("\n"));
+  } catch (e) {
+    return err(`Failed to ingest URL: ${e.message}`, "INGEST_FAILED");
+  }
+}

package/node_modules/@context-vault/core/src/server/tools/list-context.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { normalizeKind } from "../../core/files.js";
+import { ok } from "../helpers.js";
+
+export const name = "list_context";
+
+export const description =
+  "Browse vault entries without a search query. Returns id, title, kind, category, tags, created_at. Use get_context with a query for semantic search. Use this to browse by tags or find recent entries.";
+
+export const inputSchema = {
+  kind: z.string().optional().describe("Filter by kind (e.g. 'insight', 'decision', 'pattern')"),
+  category: z.enum(["knowledge", "entity", "event"]).optional().describe("Filter by category"),
+  tags: z.array(z.string()).optional().describe("Filter by tags (entries must match at least one)"),
+  since: z.string().optional().describe("ISO date, return entries created after this"),
+  until: z.string().optional().describe("ISO date, return entries created before this"),
+  limit: z.number().optional().describe("Max results to return (default 20, max 100)"),
+  offset: z.number().optional().describe("Skip first N results for pagination"),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler({ kind, category, tags, since, until, limit, offset }, ctx, { ensureIndexed, reindexFailed }) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  await ensureIndexed();
+
+  const clauses = [];
+  const params = [];
+
+  if (userId !== undefined) {
+    clauses.push("user_id = ?");
+    params.push(userId);
+  }
+  if (kind) {
+    clauses.push("kind = ?");
+    params.push(normalizeKind(kind));
+  }
+  if (category) {
+    clauses.push("category = ?");
+    params.push(category);
+  }
+  if (since) {
+    clauses.push("created_at >= ?");
+    params.push(since);
+  }
+  if (until) {
+    clauses.push("created_at <= ?");
+    params.push(until);
+  }
+  clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
+
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  const effectiveLimit = Math.min(limit || 20, 100);
+  const effectiveOffset = offset || 0;
+  // When tag-filtering, over-fetch to compensate for post-filter reduction
+  const fetchLimit = tags?.length ? effectiveLimit * 10 : effectiveLimit;
+
+  const countParams = [...params];
+  const total = ctx.db.prepare(`SELECT COUNT(*) as c FROM vault ${where}`).get(...countParams).c;
+
+  params.push(fetchLimit, effectiveOffset);
+  const rows = ctx.db.prepare(`SELECT id, title, kind, category, tags, created_at, SUBSTR(body, 1, 120) as preview FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...params);
+
+  // Post-filter by tags if provided, then apply requested limit
+  const filtered = tags?.length
+    ? rows.filter((r) => {
+        const entryTags = r.tags ? JSON.parse(r.tags) : [];
+        return tags.some((t) => entryTags.includes(t));
+      }).slice(0, effectiveLimit)
+    : rows;
+
+  if (!filtered.length) return ok("No entries found matching the given filters.");
+
+  const lines = [];
+  if (reindexFailed) lines.push(`> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-vault reindex\` to fix.\n`);
+  lines.push(`## Vault Entries (${filtered.length} shown, ${total} total)\n`);
+  for (const r of filtered) {
+    const entryTags = r.tags ? JSON.parse(r.tags) : [];
+    const tagStr = entryTags.length ? entryTags.join(", ") : "none";
+    lines.push(`- **${r.title || "(untitled)"}** [${r.kind}/${r.category}] — ${tagStr} — ${r.created_at} — \`${r.id}\``);
+    if (r.preview) lines.push(`  ${r.preview.replace(/\n+/g, " ").trim()}${r.preview.length >= 120 ? "…" : ""}`);
+  }
+
+  if (effectiveOffset + effectiveLimit < total) {
+    lines.push(`\n_Page ${Math.floor(effectiveOffset / effectiveLimit) + 1}. Use offset: ${effectiveOffset + effectiveLimit} for next page._`);
+  }
+
+  return ok(lines.join("\n"));
+}