context-vault 2.0.1 → 2.1.0

package/README.md

@@ -1,128 +1,32 @@
 # 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
 
@@ -159,7 +63,7 @@ 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
 ```
 
 The `kind` field accepts any string — `"insight"`, `"decision"`, `"pattern"`, `"reference"`, or any custom kind. The folder is auto-created from the pluralized kind name.
@@ -175,19 +79,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 +117,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 +185,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):
 
-### Embedding model download stalls
+```json
+{
+  "mcpServers": {
+    "context-mcp": {
+      "command": "node",
+      "args": ["/path/to/context-mcp/src/server/index.js", "--vault-dir", "/path/to/vault"]
+    }
+  }
+}
+```
 
-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.
+You can also pass config via environment variables in the MCP config block:
 
-### Stale search index
+```json
+{
+  "mcpServers": {
+    "context-mcp": {
+      "command": "context-mcp",
+      "args": ["serve"],
+      "env": {
+        "CONTEXT_MCP_VAULT_DIR": "/path/to/vault"
+      }
+    }
+  }
+}
+```
 
-If search results seem outdated or missing:
+### How the Server Runs
+
+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.
 
-## Architecture
+Requires **Node.js 20** or later.
+
+### Architecture
 
 ```
 src/
@@ -369,6 +336,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,7 @@ const TOOLS = [
 
 function showHelp() {
   console.log(`
-${bold("context-mcp")} v${VERSION} — Personal knowledge vault for AI agents
+${bold("context-mcp")} v${VERSION} — Persistent memory for AI agents
 
 ${bold("Usage:")}
   context-mcp <command> [options]
@@ -181,7 +181,9 @@ 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(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();
 
   // Detect tools
@@ -230,11 +232,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 === "") {
@@ -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${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)) {
@@ -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,27 @@ async function runSetup() {
     }
   }
 
-  // Summary
-  console.log(bold("\n  Setup complete!\n"));
+  // Health check
   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}`);
-    }
+  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 },
+  ];
+  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(`\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.`);
+
+  // 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")}`);
   console.log();
 }
 
@@ -431,6 +458,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() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "type": "module",
   "description": "Personal context vault — connects any AI agent to your accumulated knowledge",
   "bin": {

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/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;
     }