context-vault 2.2.0 → 2.4.0

package/src/server/index.js

@@ -9,74 +9,133 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"));
 
-import { resolveConfig } from "../core/config.js";
-import { embed } from "../index/embed.js";
-import { initDatabase, prepareStatements, insertVec, deleteVec } from "../index/db.js";
-import { registerTools } from "./tools.js";
-
-// ─── Config Resolution ──────────────────────────────────────────────────────
-
-const config = resolveConfig();
-
-// Create directories
-mkdirSync(config.dataDir, { recursive: true });
-mkdirSync(config.vaultDir, { recursive: true });
-
-// Write .context-mcp marker (always update to reflect current version)
-const markerPath = join(config.vaultDir, ".context-mcp");
-const markerData = existsSync(markerPath) ? JSON.parse(readFileSync(markerPath, "utf-8")) : {};
-writeFileSync(markerPath, JSON.stringify({ created: markerData.created || new Date().toISOString(), version: pkg.version }, null, 2) + "\n");
-
-// Update existence flag after directory creation
-config.vaultDirExists = existsSync(config.vaultDir);
-
-// Startup diagnostics
-console.error(`[context-mcp] Vault: ${config.vaultDir}`);
-console.error(`[context-mcp] Database: ${config.dbPath}`);
-console.error(`[context-mcp] Dev dir: ${config.devDir}`);
-if (!config.vaultDirExists) {
-  console.error(`[context-mcp] WARNING: Vault directory not found!`);
+import { resolveConfig } from "@context-vault/core/core/config";
+import { embed } from "@context-vault/core/index/embed";
+import { initDatabase, NativeModuleError, prepareStatements, insertVec, deleteVec } from "@context-vault/core/index/db";
+import { registerTools } from "@context-vault/core/server/tools";
+
+// ─── Phased Startup ─────────────────────────────────────────────────────────
+
+async function main() {
+  let phase = "CONFIG";
+  let db;
+
+  try {
+    // ── Phase: CONFIG ────────────────────────────────────────────────────────
+    const config = resolveConfig();
+
+    // ── Phase: DIRS ──────────────────────────────────────────────────────────
+    phase = "DIRS";
+    mkdirSync(config.dataDir, { recursive: true });
+    mkdirSync(config.vaultDir, { recursive: true });
+
+    // Write .context-mcp marker (non-fatal)
+    try {
+      const markerPath = join(config.vaultDir, ".context-mcp");
+      const markerData = existsSync(markerPath) ? JSON.parse(readFileSync(markerPath, "utf-8")) : {};
+      writeFileSync(markerPath, JSON.stringify({ created: markerData.created || new Date().toISOString(), version: pkg.version }, null, 2) + "\n");
+    } catch (markerErr) {
+      console.error(`[context-mcp] Warning: could not write marker file: ${markerErr.message}`);
+    }
+
+    config.vaultDirExists = existsSync(config.vaultDir);
+
+    // Startup diagnostics
+    console.error(`[context-mcp] Vault: ${config.vaultDir}`);
+    console.error(`[context-mcp] Database: ${config.dbPath}`);
+    console.error(`[context-mcp] Dev dir: ${config.devDir}`);
+    if (!config.vaultDirExists) {
+      console.error(`[context-mcp] WARNING: Vault directory not found!`);
+    }
+
+    // ── Phase: DB ────────────────────────────────────────────────────────────
+    phase = "DB";
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+
+    const ctx = {
+      db,
+      config,
+      stmts,
+      embed,
+      insertVec: (rowid, embedding) => insertVec(stmts, rowid, embedding),
+      deleteVec: (rowid) => deleteVec(stmts, rowid),
+    };
+
+    // ── Phase: SERVER ────────────────────────────────────────────────────────
+    phase = "SERVER";
+    const server = new McpServer(
+      { name: "context-mcp", version: pkg.version },
+      { capabilities: { tools: {} } }
+    );
+
+    registerTools(server, ctx);
+
+    // ── Graceful Shutdown ────────────────────────────────────────────────────
+    function shutdown(signal) {
+      console.error(`[context-mcp] Received ${signal}, shutting down...`);
+      try {
+        if (db.inTransaction) {
+          console.error("[context-mcp] Rolling back active transaction...");
+          db.exec("ROLLBACK");
+        }
+        db.pragma("wal_checkpoint(TRUNCATE)");
+        db.close();
+        console.error("[context-mcp] Database closed cleanly.");
+      } catch (shutdownErr) {
+        console.error(`[context-mcp] Shutdown error: ${shutdownErr.message}`);
+      }
+      process.exit(0);
+    }
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+    // ── Phase: CONNECTED ─────────────────────────────────────────────────────
+    phase = "CONNECTED";
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    // ── Non-blocking Update Check ────────────────────────────────────────────
+    setTimeout(() => {
+      import("node:child_process").then(({ execSync }) => {
+        try {
+          const latest = execSync("npm view context-vault version", {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+          }).trim();
+          if (latest && latest !== pkg.version) {
+            console.error(`[context-mcp] Update available: v${pkg.version} → v${latest}. Run: context-mcp update`);
+          }
+        } catch {}
+      }).catch(() => {});
+    }, 3000);
+
+  } catch (err) {
+    if (err instanceof NativeModuleError) {
+      // Boxed diagnostic for native module mismatch
+      console.error("");
+      console.error("╔══════════════════════════════════════════════════════════════╗");
+      console.error("║  context-mcp: Native Module Error                           ║");
+      console.error("╚══════════════════════════════════════════════════════════════╝");
+      console.error("");
+      console.error(err.message);
+      console.error("");
+      console.error(`  Node.js path:    ${process.execPath}`);
+      console.error(`  Node.js version: ${process.version}`);
+      console.error("");
+      process.exit(78); // EX_CONFIG
+    }
+
+    console.error(`[context-mcp] Fatal error during ${phase} phase: ${err.message}`);
+    if (phase === "DB") {
+      console.error(`[context-mcp] Try deleting the DB file and restarting: rm "${err.dbPath || "vault.db"}"`);
+    }
+    process.exit(1);
+  }
 }
 
-// ─── Database Init ───────────────────────────────────────────────────────────
-
-let db, stmts;
-try {
-  db = initDatabase(config.dbPath);
-  stmts = prepareStatements(db);
-} catch (e) {
-  console.error(`[context-mcp] Database init failed: ${e.message}`);
-  console.error(`[context-mcp] DB path: ${config.dbPath}`);
-  console.error(`[context-mcp] Try deleting the DB file and restarting: rm "${config.dbPath}"`);
+main().catch((err) => {
+  console.error(`[context-mcp] Unexpected fatal error: ${err.message}`);
   process.exit(1);
-}
-
-const ctx = {
-  db,
-  config,
-  stmts,
-  embed,
-  insertVec: (rowid, embedding) => insertVec(stmts, rowid, embedding),
-  deleteVec: (rowid) => deleteVec(stmts, rowid),
-};
-
-// ─── MCP Server ──────────────────────────────────────────────────────────────
-
-const server = new McpServer(
-  { name: "context-mcp", version: pkg.version },
-  { capabilities: { tools: {} } }
-);
-
-registerTools(server, ctx);
-
-// ─── Graceful Shutdown ───────────────────────────────────────────────────────
-
-function shutdown() {
-  try { db.close(); } catch {}
-  process.exit(0);
-}
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+});

package/ui/serve.js

@@ -12,10 +12,10 @@ import { createServer } from "node:http";
 import { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from "node:fs";
 import { resolve, dirname, join, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveConfig } from "../src/config.js";
-import { initDatabase } from "../src/db.js";
-import { embed } from "../src/embed.js";
-import { hybridSearch } from "../src/search.js";
+import { resolveConfig } from "@context-vault/core/core/config";
+import { initDatabase } from "@context-vault/core/index/db";
+import { embed } from "@context-vault/core/index/embed";
+import { hybridSearch } from "@context-vault/core/retrieve";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -348,8 +348,9 @@ async function handleSearch(res, url) {
 
   if (!query) return jsonResponse(res, { results: [] });
 
-  const sorted = await hybridSearch(db, embed, query, kindFilter);
-  jsonResponse(res, { query, results: sorted });
+  const searchCtx = { db, config, embed };
+  const results = await hybridSearch(searchCtx, query, { kindFilter });
+  jsonResponse(res, { query, results });
 }
 
 // ─── Config Handlers ─────────────────────────────────────────────────────────

package/README.md

@@ -1,431 +0,0 @@
-# context-mcp
-
-[![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)
-
-Persistent memory for AI agents — saves and searches knowledge across sessions.
-
-<p align="center">
-  <img src="assets/demo.gif" alt="context-vault demo — Claude Code and Cursor using the knowledge vault" width="800">
-</p>
-
-## Quick Start
-
-```bash
-npm install -g context-vault
-context-mcp setup
-```
-
-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:
-
-> "Search my vault for getting started"
-
-## What It Does
-
-- **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 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 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
-
-```js
-get_context({
-  query: "react query caching",       // Natural language or keywords
-  kind: "insight",                     // Optional: filter by kind
-  tags: ["react"],                     // Optional: filter by tags
-  limit: 5                             // Optional: max results (default 10)
-})
-```
-
-Returns entries ranked by combined full-text and semantic similarity, with recency weighting.
-
-### `save_context` — Save or update knowledge
-
-```js
-// Create new entry
-save_context({
-  kind: "insight",                     // Determines folder: insights/
-  body: "React Query staleTime defaults to 0",
-  tags: ["react", "performance"],
-  title: "staleTime gotcha",           // Optional
-  meta: { type: "gotcha" },            // Optional: any structured data
-  folder: "react/hooks",              // Optional: subfolder organization
-  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.
-
-## Knowledge Organization
-
-### Folders and Kinds
-
-Each top-level subdirectory in the vault maps to a `kind` value. The directory name is depluralized:
-
-```
-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)
-knowledge/insights/                        kind: "insight", meta.folder: null
-  flat-file.md
-knowledge/insights/react/hooks/            kind: "insight", meta.folder: "react/hooks"
-  use-query-gotcha.md
-```
-
-Tags are semantic (what the content is about). Folder structure is organizational (where it lives). These are separate concerns.
-
-### File Format
-
-All knowledge files use YAML frontmatter:
-
-```markdown
----
-id: 01HXYZ...
-tags: ["react", "performance"]
-source: claude-code
-created: 2026-02-17T12:00:00Z
----
-React Query's staleTime defaults to 0 — set it explicitly or every mount triggers a refetch.
-```
-
-Standard keys: `id`, `tags`, `source`, `created`. Any extra frontmatter keys (`type`, `status`, `language`, `folder`, etc.) are stored in a `meta` JSON column automatically.
-
-### Custom Kinds
-
-No code changes required:
-
-1. `mkdir ~/vault/knowledge/references/`
-2. Add `.md` files with YAML frontmatter
-3. The next session auto-indexes them
-
-The kind name comes from the directory: `references/` → kind `reference`.
-
-## Configuration
-
-Works out of the box with zero config. All paths are overridable:
-
-```
-CLI args  >  env vars  >  config file  >  convention defaults
-```
-
-### Defaults
-
-| Setting | Default |
-|---------|---------|
-| Vault dir | `~/vault/` |
-| Data dir | `~/.context-mcp/` |
-| Database | `~/.context-mcp/vault.db` |
-| Dev dir | `~/dev/` |
-
-### Config File (`~/.context-mcp/config.json`)
-
-Lives in the data directory alongside the database. Created by `setup`, or create it manually:
-
-```json
-{
-  "vaultDir": "/Users/you/vault/",
-  "dataDir": "/Users/you/.context-mcp",
-  "dbPath": "/Users/you/.context-mcp/vault.db",
-  "devDir": "/Users/you/dev"
-}
-```
-
-### Environment Variables
-
-| Variable | Overrides |
-|----------|-----------|
-| `CONTEXT_MCP_VAULT_DIR` | Vault directory (knowledge files) |
-| `CONTEXT_MCP_DB_PATH` | Database path |
-| `CONTEXT_MCP_DEV_DIR` | Dev directory |
-| `CONTEXT_MCP_DATA_DIR` | Data directory (DB + config storage) |
-
-### CLI Arguments
-
-```bash
-context-mcp serve --vault-dir /custom/vault --dev-dir /custom/dev
-context-mcp serve --data-dir /custom/data --db-path /custom/data/vault.db
-```
-
-## CLI
-
-```bash
-context-mcp <command> [options]
-```
-
-| Command | Description |
-|---------|-------------|
-| `setup` | Interactive MCP installer — detects tools, writes configs |
-| `serve` | Start the MCP server (used by AI clients in MCP configs) |
-| `ui [--port 3141]` | Launch the web dashboard |
-| `reindex` | Rebuild search index from knowledge files |
-| `status` | Show vault diagnostics (paths, counts, health) |
-
-If running from source without a global install, use `node bin/cli.js` instead of `context-mcp`.
-
-## Install
-
-### npm (Recommended)
-
-```bash
-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:
-
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "context-mcp",
-      "args": ["serve"],
-      "env": {
-        "CONTEXT_MCP_VAULT_DIR": "/path/to/vault"
-      }
-    }
-  }
-}
-```
-
-### 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
-osacompile -o "/Applications/Context.app" ui/Context.applescript
-```
-
-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`.
-
-## How It Works
-
-```
-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
-```
-
-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
-
-```
-src/
-├── core/                Shared utilities (config, frontmatter, files, status)
-├── capture/             Write path — creates .md files in the vault
-├── index/               Sync layer — SQLite schema, embeddings, reindex
-├── retrieve/            Read path — hybrid FTS5 + vector search
-└── server/              MCP server — wires layers into tool handlers
-
-bin/
-└── cli.js               CLI entry point (setup, serve, ui, reindex, status)
-
-ui/
-├── serve.js             HTTP server for web dashboard
-├── index.html           Single-page dashboard UI
-└── Context.applescript  macOS dock app launcher
-```
-
-Each layer has a single responsibility and can be understood independently. The server is the only module that imports across layer boundaries.
-
-### Module Dependency Graph
-
-```
-core/files.js, core/frontmatter.js  ←  capture/
-                                              ↑
-core/config.js                          server/  ←  bin/cli.js
-                                              ↑
-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 |
-|---------|---------|
-| `@modelcontextprotocol/sdk` | MCP protocol (McpServer, StdioServerTransport) |
-| `better-sqlite3` | SQLite driver |
-| `sqlite-vec` | Vector search (384-dim float32) |
-| `@huggingface/transformers` | Local embeddings (all-MiniLM-L6-v2, ~22MB) |
-
-## License
-
-MIT

package/smithery.yaml

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