context-vault 2.0.1 → 2.2.0

package/README.md

@@ -1,137 +1,43 @@
 # context-mcp
 
-[![npm version](https://img.shields.io/npm/v/@fellanh/context-mcp)](https://www.npmjs.com/package/@fellanh/context-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/@fellanh/context-mcp)](https://www.npmjs.com/package/@fellanh/context-mcp)
-[![license](https://img.shields.io/npm/l/@fellanh/context-mcp)](./LICENSE)
-[![node](https://img.shields.io/node/v/@fellanh/context-mcp)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/context-vault)](https://www.npmjs.com/package/context-vault)
+[![npm downloads](https://img.shields.io/npm/dm/context-vault)](https://www.npmjs.com/package/context-vault)
+[![license](https://img.shields.io/npm/l/context-vault)](./LICENSE)
+[![node](https://img.shields.io/node/v/context-vault)](https://nodejs.org)
 
-Personal context vault — an MCP server that connects any AI agent to your accumulated knowledge.
+Persistent memory for AI agents — saves and searches knowledge across sessions.
 
-Your knowledge lives as markdown files in plain folders you own and can edit, version, or move freely. The SQLite database is a derived search index — rebuilt from those files at any time. The canonical flow is **files → DB** with a clean two-way mapping: disk structure determines folder placement, the DB stays flat and lightweight.
+<p align="center">
+  <img src="assets/demo.gif" alt="context-vault demo — Claude Code and Cursor using the knowledge vault" width="800">
+</p>
 
-## How It Works
-
-```
-YOUR FILES (source of truth)         SEARCH INDEX (derived)
-~/vault/                         ~/.context-mcp/vault.db
-├── insights/                        ┌───────────────────────────────┐
-│   ├── react-query-caching.md       │ vault table                   │
-│   ├── sqlite-fts5-gotchas.md       │   kind: insight               │
-│   └── react/                       │   meta.folder: null (flat)    │
-│       └── hooks/                   │   meta.folder: "react/hooks"  │
-│           └── use-query-gotcha.md  │   kind: decision              │
-├── decisions/                       │   kind: pattern               │
-│   └── use-sqlite-over-pg.md        │   kind: <any custom>          │
-├── patterns/                        │ + FTS5 full-text              │
-│   └── api-error-handler.md         │ + vec0 embeddings             │
-└── references/  (custom kind)       └───────────────────────────────┘
-    └── react-19-notes.md
-Human-editable, git-versioned        Fast hybrid search, RAG-ready
-You own these files                  Rebuilt from files anytime
-```
-
-The SQLite database is stored at `~/.context-mcp/vault.db` by default (configurable via `--db-path`, `CONTEXT_MCP_DB_PATH`, or `config.json`). It contains FTS5 full-text indexes and sqlite-vec embeddings (384-dim float32, all-MiniLM-L6-v2). The database is a derived index — delete it and the server rebuilds it automatically on next session.
-
-Requires **Node.js 20** or later.
-
-## Install
-
-### Quick Start
+## Quick Start
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/fellanH/context-mcp/main/install.sh | sh
-```
-
-### npm (Recommended)
-
-```bash
-npm install -g @fellanh/context-mcp
+npm install -g context-vault
 context-mcp setup
 ```
 
-The `setup` command auto-detects installed tools (Claude Code, Claude Desktop, Cursor, Windsurf, Cline), lets you pick which to configure, and writes the correct MCP config for each. Existing configs are preserved — only the `context-mcp` entry is added or updated.
-
-### Local Development
-
-```bash
-git clone https://github.com/fellanH/context-mcp.git
-cd context-mcp
-npm install
-
-# Interactive setup — detects your tools and configures them
-node bin/cli.js setup
-```
-
-For non-interactive environments (CI, scripts):
-
-```bash
-context-mcp setup --yes
-```
-
-### Manual Configuration
-
-If you prefer manual setup, add to your tool's MCP config. Pass `--vault-dir` to point at your vault folder (omit it to use the default `~/vault/`).
-
-**npm install** (portable — survives upgrades):
-
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "context-mcp",
-      "args": ["serve", "--vault-dir", "/path/to/vault"]
-    }
-  }
-}
-```
-
-**Local dev clone** (absolute path to source):
-
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "node",
-      "args": ["/path/to/context-mcp/src/server/index.js", "--vault-dir", "/path/to/vault"]
-    }
-  }
-}
-```
-
-You can also pass config via environment variables in the MCP config block:
+Setup auto-detects your tools (Claude Code, Claude Desktop, Cursor, Windsurf, Cline), downloads the embedding model, seeds your vault with a starter entry, and verifies everything works. Then open your AI tool and try:
 
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "context-mcp",
-      "args": ["serve"],
-      "env": {
-        "CONTEXT_MCP_VAULT_DIR": "/path/to/vault"
-      }
-    }
-  }
-}
-```
+> "Search my vault for getting started"
 
-### How the Server Runs
+## What It Does
 
-The server is an MCP (Model Context Protocol) process — you don't start or stop it manually. Your AI client (Claude Code, Cursor, Cline, etc.) spawns it automatically as a child process when a session begins, based on the `mcpServers` config above. The server communicates over stdio and lives for the duration of the session. When the session ends, the client terminates the process and SQLite cleans up its WAL files.
-
-This means:
-- **No daemon, no port, no background service.** The server only runs while your AI client is active.
-- **Multiple sessions** can run separate server instances concurrently — SQLite WAL mode handles concurrent access safely.
-- **First launch** downloads the embedding model (~22MB, all-MiniLM-L6-v2) and creates the database. Subsequent starts are fast.
-- **Auto-reindex** on first tool call per session ensures the search index is always in sync with your files on disk. No manual reindex needed.
+- **Save** insights, decisions, patterns, and any custom knowledge kind from AI sessions
+- **Search** with hybrid full-text + semantic similarity, ranked by relevance and recency
+- **Own your data** — plain markdown files in folders you control, git-versioned, human-editable
 
 ## 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
@@ -147,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",
@@ -159,11 +66,44 @@ save_context({
   folder: "react/hooks",              // Optional: subfolder organization
   source: "debugging-session"          // Optional: provenance
 })
-// → ~/vault/insights/react/hooks/staletime-gotcha.md
+// → ~/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.
@@ -175,19 +115,19 @@ Shows vault path, database size, file counts per kind, embedding coverage, and a
 Each top-level subdirectory in the vault maps to a `kind` value. The directory name is depluralized:
 
 ```
-insights/    →  kind: "insight"
-decisions/   →  kind: "decision"
-patterns/    →  kind: "pattern"
-references/  →  kind: "reference"
+knowledge/insights/    →  kind: "insight"
+knowledge/decisions/   →  kind: "decision"
+knowledge/patterns/    →  kind: "pattern"
+knowledge/references/  →  kind: "reference"
 ```
 
 Within each kind directory, nested subfolders provide human-browsable organization. The subfolder path is stored in `meta.folder`:
 
 ```
 ON DISK                                    IN DB (vault table)
-insights/                                  kind: "insight", meta.folder: null
+knowledge/insights/                        kind: "insight", meta.folder: null
   flat-file.md
-insights/react/hooks/                      kind: "insight", meta.folder: "react/hooks"
+knowledge/insights/react/hooks/            kind: "insight", meta.folder: "react/hooks"
   use-query-gotcha.md
 ```
 
@@ -213,7 +153,7 @@ Standard keys: `id`, `tags`, `source`, `created`. Any extra frontmatter keys (`t
 
 No code changes required:
 
-1. `mkdir ~/vault/references/`
+1. `mkdir ~/vault/knowledge/references/`
 2. Add `.md` files with YAML frontmatter
 3. The next session auto-indexes them
 
@@ -281,62 +221,125 @@ context-mcp <command> [options]
 
 If running from source without a global install, use `node bin/cli.js` instead of `context-mcp`.
 
-## Desktop App (macOS)
+## Install
 
-A macOS dock application that starts the UI server and opens the dashboard in your browser.
+### npm (Recommended)
 
 ```bash
-osacompile -o "/Applications/Context.app" ui/Context.applescript
+npm install -g context-vault
+context-mcp setup
 ```
 
-The app checks if port 3141 is already in use, starts the server if not, and opens `http://localhost:3141`. Server logs are written to `/tmp/context-mcp.log`.
+The `setup` command auto-detects installed tools (Claude Code, Claude Desktop, Cursor, Windsurf, Cline), lets you pick which to configure, and writes the correct MCP config for each. Existing configs are preserved — only the `context-mcp` entry is added or updated.
 
-## Troubleshooting
+### Local Development
 
-### Native module build failures
+```bash
+git clone https://github.com/fellanH/context-mcp.git
+cd context-mcp
+npm install
 
-`better-sqlite3` and `sqlite-vec` include native C code compiled for your platform. If install fails:
+# Interactive setup — detects your tools and configures them
+node bin/cli.js setup
+```
+
+For non-interactive environments (CI, scripts):
 
 ```bash
-npm rebuild better-sqlite3 sqlite-vec
+context-mcp setup --yes
 ```
 
-On Apple Silicon Macs, ensure you're running a native ARM Node.js (not Rosetta). Check with `node -p process.arch` — it should say `arm64`.
+### Manual Configuration
 
-### Vault directory not found
+If you prefer manual setup, add to your tool's MCP config. Pass `--vault-dir` to point at your vault folder (omit it to use the default `~/vault/`).
 
-If `context_status` or `get_context` reports the vault directory doesn't exist:
+**npm install** (portable — survives upgrades):
 
-```bash
-context-mcp status    # Shows resolved paths
-mkdir -p ~/vault      # Create the default vault directory
+```json
+{
+  "mcpServers": {
+    "context-mcp": {
+      "command": "context-mcp",
+      "args": ["serve", "--vault-dir", "/path/to/vault"]
+    }
+  }
+}
 ```
 
-Or re-run `context-mcp setup` to reconfigure.
+**Local dev clone** (absolute path to source):
+
+```json
+{
+  "mcpServers": {
+    "context-mcp": {
+      "command": "node",
+      "args": ["/path/to/context-mcp/src/server/index.js", "--vault-dir", "/path/to/vault"]
+    }
+  }
+}
+```
 
-### Embedding model download stalls
+You can also pass config via environment variables in the MCP config block:
 
-The first run downloads the all-MiniLM-L6-v2 embedding model (~22MB) from Hugging Face. This requires internet access and can take a moment. If it hangs, check your network or proxy settings.
+```json
+{
+  "mcpServers": {
+    "context-mcp": {
+      "command": "context-mcp",
+      "args": ["serve"],
+      "env": {
+        "CONTEXT_MCP_VAULT_DIR": "/path/to/vault"
+      }
+    }
+  }
+}
+```
 
-### Stale search index
+### How the Server Runs
 
-If search results seem outdated or missing:
+The server is an MCP (Model Context Protocol) process — you don't start or stop it manually. Your AI client (Claude Code, Cursor, Cline, etc.) spawns it automatically as a child process when a session begins, based on the `mcpServers` config above. The server communicates over stdio and lives for the duration of the session. When the session ends, the client terminates the process and SQLite cleans up its WAL files.
+
+This means:
+- **No daemon, no port, no background service.** The server only runs while your AI client is active.
+- **Multiple sessions** can run separate server instances concurrently — SQLite WAL mode handles concurrent access safely.
+- **Embedding model** is downloaded during `setup` (~22MB, all-MiniLM-L6-v2). If setup was skipped, it downloads on first use.
+- **Auto-reindex** on first tool call per session ensures the search index is always in sync with your files on disk. No manual reindex needed.
+
+## Desktop App (macOS)
+
+A macOS dock application that starts the UI server and opens the dashboard in your browser.
 
 ```bash
-context-mcp reindex
+osacompile -o "/Applications/Context.app" ui/Context.applescript
 ```
 
-This rebuilds the entire index from your vault files. Auto-reindex runs on every session start, but manual reindex can help diagnose issues.
+The app checks if port 3141 is already in use, starts the server if not, and opens `http://localhost:3141`. Server logs are written to `/tmp/context-mcp.log`.
 
-### Config path debugging
+## How It Works
 
-```bash
-context-mcp status
+```
+YOUR FILES (source of truth)         SEARCH INDEX (derived)
+~/vault/                         ~/.context-mcp/vault.db
+├── knowledge/                       ┌───────────────────────────────┐
+│   ├── insights/                    │ vault table                   │
+│   │   ├── react-query-caching.md   │   kind: insight               │
+│   │   └── react/hooks/             │   meta.folder: "react/hooks"  │
+│   │       └── use-query-gotcha.md  │   kind: decision              │
+│   ├── decisions/                   │   kind: pattern               │
+│   │   └── use-sqlite-over-pg.md    │   kind: <any custom>          │
+│   └── patterns/                    │ + FTS5 full-text              │
+│       └── api-error-handler.md     │ + vec0 embeddings             │
+├── entities/                        └───────────────────────────────┘
+└── events/
+Human-editable, git-versioned        Fast hybrid search, RAG-ready
+You own these files                  Rebuilt from files anytime
 ```
 
-Shows all resolved paths (vault dir, data dir, DB path, config file) and where each was resolved from (defaults, config file, env, or CLI args).
+The SQLite database is stored at `~/.context-mcp/vault.db` by default (configurable via `--db-path`, `CONTEXT_MCP_DB_PATH`, or `config.json`). It contains FTS5 full-text indexes and sqlite-vec embeddings (384-dim float32, all-MiniLM-L6-v2). The database is a derived index — delete it and the server rebuilds it automatically on next session.
+
+Requires **Node.js 20** or later.
 
-## Architecture
+### Architecture
 
 ```
 src/
@@ -369,6 +372,51 @@ index/embed.js  ←  retrieve/        ←   ui/serve.js
 index/db.js     ←──────────────────  (all consumers)
 ```
 
+## Troubleshooting
+
+### Native module build failures
+
+`better-sqlite3` and `sqlite-vec` include native C code compiled for your platform. If install fails:
+
+```bash
+npm rebuild better-sqlite3 sqlite-vec
+```
+
+On Apple Silicon Macs, ensure you're running a native ARM Node.js (not Rosetta). Check with `node -p process.arch` — it should say `arm64`.
+
+### Vault directory not found
+
+If `context_status` or `get_context` reports the vault directory doesn't exist:
+
+```bash
+context-mcp status    # Shows resolved paths
+mkdir -p ~/vault      # Create the default vault directory
+```
+
+Or re-run `context-mcp setup` to reconfigure.
+
+### Embedding model download
+
+The embedding model (all-MiniLM-L6-v2, ~22MB) is normally downloaded during `context-mcp setup`. If setup was skipped or the cache was cleared, it downloads automatically on first use. If it hangs, check your network or proxy settings.
+
+### Stale search index
+
+If search results seem outdated or missing:
+
+```bash
+context-mcp reindex
+```
+
+This rebuilds the entire index from your vault files. Auto-reindex runs on every session start, but manual reindex can help diagnose issues.
+
+### Config path debugging
+
+```bash
+context-mcp status
+```
+
+Shows all resolved paths (vault dir, data dir, DB path, config file) and where each was resolved from (defaults, config file, env, or CLI args).
+
 ## Dependencies
 
 | Package | Purpose |

package/bin/cli.js

@@ -156,7 +156,8 @@ const TOOLS = [
 
 function showHelp() {
   console.log(`
-${bold("context-mcp")} v${VERSION} — Personal knowledge vault for AI agents
+  ${bold("◇ context-vault")} ${dim(`v${VERSION}`)}
+  ${dim("Persistent memory for AI agents")}
 
 ${bold("Usage:")}
   context-mcp <command> [options]
@@ -180,12 +181,12 @@ ${bold("Options:")}
 async function runSetup() {
   // Banner
   console.log();
-  console.log(bold("  context-mcp") + dim(` v${VERSION}`));
-  console.log(dim("  Personal knowledge vault for AI agents"));
+  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();
@@ -230,11 +231,13 @@ async function runSetup() {
   if (isNonInteractive) {
     selected = detected;
   } else {
-    const listing = detected
-      .map((t, i) => `${i + 1}) ${t.name}`)
-      .join("  ");
+    console.log(bold("  Which tools should context-mcp connect to?\n"));
+    for (let i = 0; i < detected.length; i++) {
+      console.log(`    ${i + 1}) ${detected[i].name}`);
+    }
+    console.log();
     const answer = await prompt(
-      `  Configure: ${dim("all")} or enter numbers (${listing}):`,
+      `  Select (${dim("1,2,3")} or ${dim('"all"')}):`,
       "all"
     );
     if (answer === "all" || answer === "") {
@@ -250,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
@@ -294,6 +298,17 @@ async function runSetup() {
   writeFileSync(configPath, JSON.stringify(vaultConfig, null, 2) + "\n");
   console.log(`\n  ${green("+")} Wrote ${configPath}`);
 
+  // Pre-download 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");
+    await embed("warmup");
+    console.log(`  ${green("+")} Embedding model ready`);
+  } catch (e) {
+    console.log(`  ${yellow("!")} Model download failed — will retry on first use`);
+  }
+
   // Clean up legacy project-root config.json if it exists
   const legacyConfigPath = join(ROOT, "config.json");
   if (existsSync(legacyConfigPath)) {
@@ -304,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;
@@ -324,6 +339,12 @@ async function runSetup() {
     }
   }
 
+  // Seed entry
+  const seeded = createSeedEntry(resolvedVaultDir);
+  if (seeded) {
+    console.log(`\n  ${green("+")} Created starter entry in vault`);
+  }
+
   // Offer to launch UI
   console.log();
   if (!isNonInteractive) {
@@ -338,21 +359,35 @@ async function runSetup() {
     }
   }
 
-  // Summary
-  console.log(bold("\n  Setup complete!\n"));
-  const ok = results.filter((r) => r.ok);
-  if (ok.length) {
-    console.log(
-      `  ${green(ok.length)} tool${ok.length > 1 ? "s" : ""} configured:`
-    );
-    for (const r of ok) {
-      console.log(`    ${r.tool.name}`);
-    }
+  // Health check
+  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: okResults.length > 0 },
+  ];
+  const passed = checks.filter((c) => c.pass).length;
+  for (const c of checks) {
+    console.log(`  ${c.pass ? green("✓") : red("✗")} ${c.label}`);
   }
-  console.log(`\n  Vault dir:   ${resolvedVaultDir}`);
-  console.log(`  Config:      ${configPath}`);
-  console.log(`  MCP server:  ${isInstalledPackage() ? "context-mcp serve" : SERVER_PATH}`);
-  console.log(`\n  Run ${cyan("context-mcp ui")} to open the dashboard.`);
+
+  // 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();
 }
 
@@ -431,6 +466,38 @@ function configureJsonTool(tool, vaultDir) {
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 }
 
+// ─── Seed Entry ─────────────────────────────────────────────────────────────
+
+function createSeedEntry(vaultDir) {
+  const seedDir = join(vaultDir, "knowledge", "insights");
+  const seedPath = join(seedDir, "getting-started.md");
+  if (existsSync(seedPath)) return false;
+  mkdirSync(seedDir, { recursive: true });
+  const id = Date.now().toString(36).toUpperCase().padStart(10, "0");
+  const now = new Date().toISOString();
+  const content = `---
+id: ${id}
+tags: ["getting-started"]
+source: context-mcp-setup
+created: ${now}
+---
+Welcome to your context vault! This is a seed entry created during setup.
+
+Your vault stores knowledge as plain markdown files with YAML frontmatter.
+AI agents search it using hybrid full-text + semantic search.
+
+Try these commands in your AI tool:
+- "Search my vault for getting started"
+- "Save an insight: JavaScript Date objects are mutable"
+- "Show my vault status"
+
+You can edit or delete this file anytime — it lives at:
+${seedPath}
+`;
+  writeFileSync(seedPath, content);
+  return true;
+}
+
 // ─── UI Command ──────────────────────────────────────────────────────────────
 
 function runUi() {
@@ -478,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 ──────────────────────────────────────────────────────────
@@ -500,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.0.1",
+  "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/smithery.yaml

@@ -7,4 +7,4 @@ startCommand:
         type: string
         description: "Path to the vault directory containing your knowledge files. Defaults to ~/vault/"
   commandFunction: |-
-    (config) => ({ command: 'npx', args: ['-y', '@fellanh/context-mcp', 'serve', ...(config.vaultDir ? ['--vault-dir', config.vaultDir] : [])] })
+    (config) => ({ command: 'npx', args: ['-y', 'context-vault', 'serve', ...(config.vaultDir ? ['--vault-dir', config.vaultDir] : [])] })

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/index/embed.js

@@ -9,10 +9,11 @@ let extractor = null;
 async function ensurePipeline() {
   if (!extractor) {
     try {
+      console.error("[context-mcp] Loading embedding model (first run may download ~22MB)...");
       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] The model (~22MB) is downloaded on first run.`);
       console.error(`[context-mcp] Check: network connectivity, disk space, Node.js >=20`);
       throw e;
     }

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"));
     }
   );