context-vault 2.1.0 → 2.2.0

package/README.md

@@ -30,12 +30,14 @@ Setup auto-detects your tools (Claude Code, Claude Desktop, Cursor, Windsurf, Cl
 
 ## Tools
 
-The server exposes three tools. Your AI agent calls them automatically — you don't invoke them directly.
+The server exposes five tools. Your AI agent calls them automatically — you don't invoke them directly.
 
 | Tool | Type | Description |
 |------|------|-------------|
 | `get_context` | Read | Hybrid FTS5 + vector search across all knowledge |
-| `save_context` | Write | Save any kind of knowledge to the vault |
+| `save_context` | Write | Save new knowledge or update existing entries by ID |
+| `list_context` | Browse | List vault entries with filtering and pagination |
+| `delete_context` | Delete | Remove an entry by ID (file + index) |
 | `context_status` | Diag | Show resolved config, health, and per-kind file counts |
 
 ### `get_context` — Search your vault
@@ -51,9 +53,10 @@ get_context({
 
 Returns entries ranked by combined full-text and semantic similarity, with recency weighting.
 
-### `save_context` — Save knowledge
+### `save_context` — Save or update knowledge
 
 ```js
+// Create new entry
 save_context({
   kind: "insight",                     // Determines folder: insights/
   body: "React Query staleTime defaults to 0",
@@ -64,10 +67,43 @@ save_context({
   source: "debugging-session"          // Optional: provenance
 })
 // → ~/vault/knowledge/insights/react/hooks/staletime-gotcha.md
+
+// Update existing entry by ID
+save_context({
+  id: "01HXYZ...",                     // ULID from a previous save
+  body: "Updated content here",        // Only provide fields you want to change
+  tags: ["react", "updated"]           // Omitted fields are preserved
+})
 ```
 
 The `kind` field accepts any string — `"insight"`, `"decision"`, `"pattern"`, `"reference"`, or any custom kind. The folder is auto-created from the pluralized kind name.
 
+When updating (`id` provided), omitted fields are preserved from the original. You cannot change `kind` or `identity_key` — delete and re-create instead.
+
+### `list_context` — Browse entries
+
+```js
+list_context({
+  kind: "insight",                     // Optional: filter by kind
+  category: "knowledge",              // Optional: knowledge, entity, or event
+  tags: ["react"],                    // Optional: filter by tags
+  limit: 10,                          // Optional: max results (default 20, max 100)
+  offset: 0                           // Optional: pagination offset
+})
+```
+
+Returns entry metadata (id, title, kind, category, tags, created_at) without body content. Use `get_context` with a search query to retrieve full entries.
+
+### `delete_context` — Remove an entry
+
+```js
+delete_context({
+  id: "01HXYZ..."                      // ULID of the entry to delete
+})
+```
+
+Removes the markdown file from disk and cleans up the database and vector index.
+
 ### `context_status` — Diagnostics
 
 Shows vault path, database size, file counts per kind, embedding coverage, and any issues.

package/bin/cli.js

@@ -156,7 +156,8 @@ const TOOLS = [
 
 function showHelp() {
   console.log(`
-${bold("context-mcp")} v${VERSION} — Persistent memory for AI agents
+  ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}
+  ${dim("Persistent memory for AI agents")}
 
 ${bold("Usage:")}
   context-mcp <command> [options]
@@ -180,14 +181,12 @@ ${bold("Options:")}
 async function runSetup() {
   // Banner
   console.log();
-  console.log(bold("  context-mcp") + dim(` v${VERSION}`));
-  console.log(dim("  Persistent memory for AI agents — saves and searches knowledge across sessions"));
-  console.log();
-  console.log(dim("  Setup will: detect tools, configure MCP, download embeddings, and verify."));
+  console.log(`  ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}`);
+  console.log(dim("  Persistent memory for AI agents"));
   console.log();
 
   // Detect tools
-  console.log(bold("  Detecting installed tools...\n"));
+  console.log(dim(`  [1/5]`) + bold(" Detecting tools...\n"));
   const detected = [];
   for (const tool of TOOLS) {
     const found = tool.detect();
@@ -254,6 +253,7 @@ async function runSetup() {
   }
 
   // Vault directory (content files)
+  console.log(dim(`  [2/5]`) + bold(" Configuring vault...\n"));
   const defaultVaultDir = join(HOME, "vault");
   const vaultDir = isNonInteractive
     ? defaultVaultDir
@@ -299,7 +299,7 @@ async function runSetup() {
   console.log(`\n  ${green("+")} Wrote ${configPath}`);
 
   // Pre-download embedding model
-  console.log(`\n${bold("  Downloading embedding model...")}`);
+  console.log(`\n  ${dim("[3/5]")}${bold(" Downloading embedding model...")}`);
   console.log(dim("  all-MiniLM-L6-v2 (~22MB, one-time download)\n"));
   try {
     const { embed } = await import("../src/index/embed.js");
@@ -319,7 +319,7 @@ async function runSetup() {
   }
 
   // Configure each tool — pass vault dir as arg if non-default
-  console.log(`\n${bold("  Configuring tools...\n")}`);
+  console.log(`\n  ${dim("[4/5]")}${bold(" Configuring tools...\n")}`);
   const results = [];
   const defaultVDir = join(HOME, "vault");
   const customVaultDir = resolvedVaultDir !== resolve(defaultVDir) ? resolvedVaultDir : null;
@@ -360,26 +360,34 @@ async function runSetup() {
   }
 
   // Health check
-  const ok = results.filter((r) => r.ok);
+  console.log(`\n  ${dim("[5/5]")}${bold(" Health check...")}\n`);
+  const okResults = results.filter((r) => r.ok);
   const checks = [
     { label: "Vault directory exists", pass: existsSync(resolvedVaultDir) },
     { label: "Config file written", pass: existsSync(configPath) },
-    { label: "At least one tool configured", pass: ok.length > 0 },
+    { label: "At least one tool configured", pass: okResults.length > 0 },
   ];
   const passed = checks.filter((c) => c.pass).length;
-  console.log(bold(`\n  Health check: ${passed}/${checks.length} passed\n`));
   for (const c of checks) {
-    console.log(`  ${c.pass ? green("+") : red("x")} ${c.label}`);
+    console.log(`  ${c.pass ? green("✓") : red("✗")} ${c.label}`);
   }
 
-  // First-use guidance
-  const toolName = ok.length ? ok[0].tool.name : "your AI tool";
-  console.log(bold("\n  What to do next:\n"));
-  console.log(`  1. Open ${toolName}`);
-  console.log(`  2. Try: ${cyan('"Search my vault for getting started"')}`);
-  console.log(`  3. Try: ${cyan('"Save an insight: JavaScript Date objects are mutable"')}`);
-  console.log(`\n  Vault:     ${resolvedVaultDir}`);
-  console.log(`  Dashboard: ${cyan("context-mcp ui")}`);
+  // Completion box
+  const toolName = okResults.length ? okResults[0].tool.name : "your AI tool";
+  const boxLines = [
+    `  ✓ Setup complete — ${passed}/${checks.length} checks passed`,
+    ``,
+    `  Open ${toolName} and try:`,
+    `  "Search my vault for getting started"`,
+  ];
+  const innerWidth = Math.max(...boxLines.map((l) => l.length)) + 2;
+  const pad = (s) => s + " ".repeat(Math.max(0, innerWidth - s.length));
+  console.log();
+  console.log(`  ${dim("┌" + "─".repeat(innerWidth) + "┐")}`);
+  for (const line of boxLines) {
+    console.log(`  ${dim("│")}${pad(line)}${dim("│")}`);
+  }
+  console.log(`  ${dim("└" + "─".repeat(innerWidth) + "┘")}`);
   console.log();
 }
 
@@ -537,11 +545,11 @@ async function runReindex() {
   const stats = await reindex(ctx, { fullSync: true });
 
   db.close();
-  console.log(green("Reindex complete:"));
-  console.log(`  Added:     ${stats.added}`);
-  console.log(`  Updated:   ${stats.updated}`);
-  console.log(`  Removed:   ${stats.removed}`);
-  console.log(`  Unchanged: ${stats.unchanged}`);
+  console.log(green("✓ Reindex complete"));
+  console.log(`  ${green("+")} ${stats.added} added`);
+  console.log(`  ${yellow("~")} ${stats.updated} updated`);
+  console.log(`  ${red("-")} ${stats.removed} removed`);
+  console.log(`  ${dim("·")} ${stats.unchanged} unchanged`);
 }
 
 // ─── Status Command ──────────────────────────────────────────────────────────
@@ -559,26 +567,43 @@ async function runStatus() {
   db.close();
 
   console.log();
-  console.log(bold("  Vault Status"));
+  console.log(`  ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}`);
   console.log();
-  console.log(`  Vault:     ${config.vaultDir} (exists: ${config.vaultDirExists}, ${status.fileCount} files)`);
-  console.log(`  Database:  ${config.dbPath} (${status.dbSize})`);
+  console.log(`  Vault:     ${config.vaultDir} ${dim(`(${config.vaultDirExists ? status.fileCount + " files" : "missing"})`)}`);
+  console.log(`  Database:  ${config.dbPath} ${dim(`(${status.dbSize})`)}`);
   console.log(`  Dev dir:   ${config.devDir}`);
   console.log(`  Data dir:  ${config.dataDir}`);
-  console.log(`  Config:    ${config.configPath} (exists: ${existsSync(config.configPath)})`);
+  console.log(`  Config:    ${config.configPath} ${dim(`(${existsSync(config.configPath) ? "exists" : "missing"})`)}`);
   console.log(`  Resolved:  ${status.resolvedFrom}`);
   console.log(`  Schema:    v5 (categories)`);
 
   if (status.kindCounts.length) {
+    const BAR_WIDTH = 20;
+    const maxCount = Math.max(...status.kindCounts.map((k) => k.c));
     console.log();
     console.log(bold("  Indexed"));
     for (const { kind, c } of status.kindCounts) {
-      console.log(`    ${c} ${kind}s`);
+      const filled = maxCount > 0 ? Math.round((c / maxCount) * BAR_WIDTH) : 0;
+      const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+      const countStr = String(c).padStart(4);
+      console.log(`  ${countStr} ${kind}s   ${dim(bar)}`);
     }
   } else {
     console.log(`\n  ${dim("(empty — no entries indexed)")}`);
   }
 
+  if (status.embeddingStatus) {
+    const { indexed, total, missing } = status.embeddingStatus;
+    if (missing > 0) {
+      const BAR_WIDTH = 20;
+      const filled = total > 0 ? Math.round((indexed / total) * BAR_WIDTH) : 0;
+      const bar = "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+      const pct = total > 0 ? Math.round((indexed / total) * 100) : 0;
+      console.log();
+      console.log(`  Embeddings ${dim(bar)} ${indexed}/${total} (${pct}%)`);
+    }
+  }
+
   if (status.subdirs.length) {
     console.log();
     console.log(bold("  Disk Directories"));

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "context-vault",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
-  "description": "Personal context vault — connects any AI agent to your accumulated knowledge",
+  "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
     "context-mcp": "bin/cli.js"
   },
@@ -21,6 +21,13 @@
   "repository": { "type": "git", "url": "https://github.com/fellanH/context-mcp.git" },
   "homepage": "https://github.com/fellanH/context-mcp",
   "keywords": ["mcp", "model-context-protocol", "ai", "knowledge-base", "knowledge-management", "vault", "rag", "sqlite", "embeddings", "claude", "cursor", "cline", "windsurf"],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.26.0",

package/src/capture/index.js

@@ -11,7 +11,8 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ulid, slugify, kindToPath } from "../core/files.js";
 import { categoryFor } from "../core/categories.js";
-import { parseFrontmatter } from "../core/frontmatter.js";
+import { parseFrontmatter, formatFrontmatter } from "../core/frontmatter.js";
+import { formatBody } from "./formatters.js";
 import { writeEntryFile } from "./file-ops.js";
 
 export function writeEntry(ctx, { kind, title, body, meta, tags, source, folder, identity_key, expires_at }) {
@@ -61,6 +62,70 @@ export function writeEntry(ctx, { kind, title, body, meta, tags, source, folder,
   return { id, filePath, kind, category, title, body, meta, tags, source, createdAt, identity_key, expires_at };
 }
 
+/**
+ * Update an existing entry's file on disk (merge provided fields with existing).
+ * Does NOT re-index — caller must call indexEntry after.
+ *
+ * @param {{ config, stmts }} ctx
+ * @param {object} existing — Row from vault table (from getEntryById)
+ * @param {{ title?, body?, tags?, meta?, source?, expires_at? }} updates
+ * @returns {object} Entry object suitable for indexEntry
+ */
+export function updateEntryFile(ctx, existing, updates) {
+  const raw = readFileSync(existing.file_path, "utf-8");
+  const { meta: fmMeta } = parseFrontmatter(raw);
+
+  const existingMeta = existing.meta ? JSON.parse(existing.meta) : {};
+  const existingTags = existing.tags ? JSON.parse(existing.tags) : [];
+
+  const title = updates.title !== undefined ? updates.title : existing.title;
+  const body = updates.body !== undefined ? updates.body : existing.body;
+  const tags = updates.tags !== undefined ? updates.tags : existingTags;
+  const source = updates.source !== undefined ? updates.source : existing.source;
+  const expires_at = updates.expires_at !== undefined ? updates.expires_at : existing.expires_at;
+
+  let mergedMeta;
+  if (updates.meta !== undefined) {
+    mergedMeta = { ...existingMeta, ...(updates.meta || {}) };
+  } else {
+    mergedMeta = { ...existingMeta };
+  }
+
+  // Build frontmatter
+  const fmFields = { id: existing.id };
+  for (const [k, v] of Object.entries(mergedMeta)) {
+    if (k === "folder") continue;
+    if (v !== null && v !== undefined) fmFields[k] = v;
+  }
+  if (existing.identity_key) fmFields.identity_key = existing.identity_key;
+  if (expires_at) fmFields.expires_at = expires_at;
+  fmFields.tags = tags;
+  fmFields.source = source || "claude-code";
+  fmFields.created = fmMeta.created || existing.created_at;
+
+  const mdBody = formatBody(existing.kind, { title, body, meta: mergedMeta });
+  const md = formatFrontmatter(fmFields) + mdBody;
+
+  writeFileSync(existing.file_path, md);
+
+  const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
+
+  return {
+    id: existing.id,
+    filePath: existing.file_path,
+    kind: existing.kind,
+    category: existing.category,
+    title,
+    body,
+    meta: finalMeta,
+    tags,
+    source,
+    createdAt: fmMeta.created || existing.created_at,
+    identity_key: existing.identity_key,
+    expires_at,
+  };
+}
+
 export async function captureAndIndex(ctx, data, indexFn) {
   // For entity upserts, preserve previous file content for safe rollback
   let previousContent = null;

package/src/index/db.js

@@ -114,6 +114,7 @@ export function prepareStatements(db) {
     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 = ?`),
+    getEntryById: db.prepare(`SELECT * FROM vault WHERE id = ?`),
     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 (?, ?)`),

package/src/server/tools.js

@@ -1,14 +1,15 @@
 /**
  * tools.js — MCP tool registrations
  *
- * Three tools: save_context (write), get_context (read), context_status (diag).
+ * Five tools: save_context (write/update), get_context (search), list_context (browse),
+ * delete_context (remove), context_status (diag).
  * Auto-reindex runs transparently on first tool call per session.
  */
 
 import { z } from "zod";
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 
-import { captureAndIndex } from "../capture/index.js";
+import { captureAndIndex, updateEntryFile } from "../capture/index.js";
 import { hybridSearch } from "../retrieve/index.js";
 import { reindex, indexEntry } from "../index/index.js";
 import { gatherVaultStatus } from "../core/status.js";
@@ -58,7 +59,7 @@ export function registerTools(server, ctx) {
     return reindexPromise;
   }
 
-  // ─── get_context (read) ────────────────────────────────────────────────────
+  // ─── get_context (search) ──────────────────────────────────────────────────
 
   server.tool(
     "get_context",
@@ -98,10 +99,13 @@ export function registerTools(server, ctx) {
       const lines = [];
       if (reindexFailed) lines.push(`> **Warning:** Auto-reindex failed. Results may be stale. Run \`context-mcp reindex\` to fix.\n`);
       lines.push(`## Results for "${query}" (${filtered.length} matches)\n`);
-      for (const r of filtered) {
-        const meta = r.meta ? JSON.parse(r.meta) : {};
-        lines.push(`### ${r.title || "(untitled)"} [${r.kind}/${r.category}]`);
-        lines.push(`Score: ${r.score.toFixed(3)} | Tags: ${r.tags || "none"} | File: ${r.file_path || "n/a"}`);
+      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}`);
         lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
         lines.push("");
       }
@@ -109,15 +113,16 @@ export function registerTools(server, ctx) {
     }
   );
 
-  // ─── save_context (write) ──────────────────────────────────────────────────
+  // ─── save_context (write / update) ────────────────────────────────────────
 
   server.tool(
     "save_context",
     "Save knowledge to your vault. Creates a .md file and indexes it for search. Use for any kind of context: insights, decisions, patterns, references, or any custom kind.",
     {
-      kind: z.string().describe("Entry kind — determines folder (e.g. 'insight', 'decision', 'pattern', 'reference', or any custom kind)"),
+      id: z.string().optional().describe("Entry ULID to update. When provided, updates the existing entry instead of creating new. Omitted fields are preserved."),
+      kind: z.string().optional().describe("Entry kind — determines folder (e.g. 'insight', 'decision', 'pattern', 'reference', or any custom kind). Required for new entries."),
       title: z.string().optional().describe("Entry title (optional for insights)"),
-      body: z.string().describe("Main content"),
+      body: z.string().optional().describe("Main content. Required for new entries."),
       tags: z.array(z.string()).optional().describe("Tags for categorization and search"),
       meta: z.any().optional().describe("Additional structured metadata (JSON object, e.g. { language: 'js', status: 'accepted' })"),
       folder: z.string().optional().describe("Subfolder within the kind directory (e.g. 'react/hooks')"),
@@ -125,14 +130,40 @@ export function registerTools(server, ctx) {
       identity_key: z.string().optional().describe("Required for entity kinds (contact, project, tool, source). The unique identifier for this entity."),
       expires_at: z.string().optional().describe("ISO date for TTL expiry"),
     },
-    async ({ kind, title, body, tags, meta, folder, source, identity_key, expires_at }) => {
+    async ({ id, kind, title, body, tags, meta, folder, source, identity_key, expires_at }) => {
       const vaultErr = ensureVaultExists(config);
       if (vaultErr) return vaultErr;
+
+      // ── Update mode ──
+      if (id) {
+        await ensureIndexed();
+
+        const existing = ctx.stmts.getEntryById.get(id);
+        if (!existing) return err(`Entry not found: ${id}`, "NOT_FOUND");
+
+        if (kind && normalizeKind(kind) !== existing.kind) {
+          return err(`Cannot change kind (current: "${existing.kind}"). Delete and re-create instead.`, "INVALID_UPDATE");
+        }
+        if (identity_key && identity_key !== existing.identity_key) {
+          return err(`Cannot change identity_key (current: "${existing.identity_key}"). Delete and re-create instead.`, "INVALID_UPDATE");
+        }
+
+        const entry = updateEntryFile(ctx, existing, { title, body, tags, meta, source, expires_at });
+        await indexEntry(ctx, entry);
+        const relPath = entry.filePath ? entry.filePath.replace(config.vaultDir + "/", "") : entry.filePath;
+        const parts = [`✓ Updated ${entry.kind} → ${relPath}`, `  id: ${entry.id}`];
+        if (entry.title) parts.push(`  title: ${entry.title}`);
+        const entryTags = entry.tags || [];
+        if (entryTags.length) parts.push(`  tags: ${entryTags.join(", ")}`);
+        return ok(parts.join("\n"));
+      }
+
+      // ── Create mode ──
+      if (!kind) return err("Required: kind (for new entries)", "INVALID_INPUT");
       const kindErr = ensureValidKind(kind);
       if (kindErr) return kindErr;
-      if (!body?.trim()) return err("Required: body (non-empty string)", "INVALID_INPUT");
+      if (!body?.trim()) return err("Required: body (for new entries)", "INVALID_INPUT");
 
-      // Validate: entity kinds require identity_key
       if (categoryFor(kind) === "entity" && !identity_key) {
         return err(`Entity kind "${kind}" requires identity_key`, "MISSING_IDENTITY_KEY");
       }
@@ -144,7 +175,117 @@ export function registerTools(server, ctx) {
       const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
 
       const entry = await captureAndIndex(ctx, { kind, title, body, meta: finalMeta, tags, source, folder, identity_key, expires_at }, indexEntry);
-      return ok(`Saved ${kind} ${entry.id}\nFile: ${entry.filePath}${title ? "\nTitle: " + title : ""}`);
+      const relPath = entry.filePath ? entry.filePath.replace(config.vaultDir + "/", "") : entry.filePath;
+      const parts = [`✓ Saved ${kind} → ${relPath}`, `  id: ${entry.id}`];
+      if (title) parts.push(`  title: ${title}`);
+      if (tags?.length) parts.push(`  tags: ${tags.join(", ")}`);
+      return ok(parts.join("\n"));
+    }
+  );
+
+  // ─── list_context (browse) ────────────────────────────────────────────────
+
+  server.tool(
+    "list_context",
+    "Browse vault entries without a search query. Returns id, title, kind, category, tags, created_at. Use get_context with a query for semantic search.",
+    {
+      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"),
+    },
+    async ({ kind, category, tags, since, until, limit, offset }) => {
+      await ensureIndexed();
+
+      const clauses = [];
+      const params = [];
+
+      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;
+
+      const countParams = [...params];
+      const total = ctx.db.prepare(`SELECT COUNT(*) as c FROM vault ${where}`).get(...countParams).c;
+
+      params.push(effectiveLimit, effectiveOffset);
+      const rows = ctx.db.prepare(`SELECT id, title, kind, category, tags, created_at FROM vault ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...params);
+
+      // Post-filter by tags if provided
+      const filtered = tags?.length
+        ? rows.filter((r) => {
+            const entryTags = r.tags ? JSON.parse(r.tags) : [];
+            return tags.some((t) => entryTags.includes(t));
+          })
+        : rows;
+
+      if (!filtered.length) return ok("No entries found matching the given filters.");
+
+      const lines = [`## 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 (effectiveOffset + effectiveLimit < total) {
+        lines.push(`\n_Page ${Math.floor(effectiveOffset / effectiveLimit) + 1}. Use offset: ${effectiveOffset + effectiveLimit} for next page._`);
+      }
+
+      return ok(lines.join("\n"));
+    }
+  );
+
+  // ─── delete_context (remove) ──────────────────────────────────────────────
+
+  server.tool(
+    "delete_context",
+    "Delete an entry from your vault by its ULID id. Removes the file from disk and cleans up the search index.",
+    {
+      id: z.string().describe("The entry ULID to delete"),
+    },
+    async ({ id }) => {
+      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");
+
+      // 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}]`);
     }
   );
 
@@ -157,20 +298,29 @@ export function registerTools(server, ctx) {
     () => {
       const status = gatherVaultStatus(ctx);
 
+      const hasIssues = status.stalePaths || (status.embeddingStatus?.missing > 0);
+      const healthIcon = hasIssues ? "⚠" : "✓";
+
       const lines = [
-        `## Vault Status`,
+        `## ${healthIcon} Vault Status`,
         ``,
-        `Vault:     ${config.vaultDir} (exists: ${config.vaultDirExists}, ${status.fileCount} files)`,
-        `Database:  ${config.dbPath} (exists: ${existsSync(config.dbPath)}, ${status.dbSize})`,
+        `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:    v5 (categories)`,
-        ``,
-        `### Indexed`,
       ];
 
+      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}%)`);
+      }
+
+      lines.push(``, `### Indexed`);
+
       if (status.kindCounts.length) {
         for (const { kind, c } of status.kindCounts) lines.push(`- ${c} ${kind}s`);
       } else {
@@ -191,20 +341,11 @@ export function registerTools(server, ctx) {
 
       if (status.stalePaths) {
         lines.push(``);
-        lines.push(`### Stale Paths Detected`);
+        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.`);
       }
 
-      if (status.embeddingStatus) {
-        const { indexed, total, missing } = status.embeddingStatus;
-        if (missing > 0) {
-          lines.push(``);
-          lines.push(`### Embeddings`);
-          lines.push(`${indexed}/${total} entries have embeddings (${missing} missing)`);
-        }
-      }
-
       return ok(lines.join("\n"));
     }
   );