context-vault 2.12.0 → 2.14.0

package/README.md

@@ -40,19 +40,63 @@ Entries are organized by `kind` (insight, decision, pattern, reference, contact,
 
 ## CLI
 
-| Command                       | Description                                               |
-| ----------------------------- | --------------------------------------------------------- |
-| `context-vault setup`         | Interactive installer — detects tools, writes MCP configs |
-| `context-vault connect --key` | Connect AI tools to hosted vault                          |
-| `context-vault switch`        | Switch between local and hosted MCP modes                 |
-| `context-vault serve`         | Start the MCP server (used by AI clients)                 |
-| `context-vault status`        | Vault health, paths, entry counts                         |
-| `context-vault reindex`       | Rebuild search index                                      |
-| `context-vault import <path>` | Import .md, .csv, .json, .txt                             |
-| `context-vault export`        | Export to JSON or CSV                                     |
-| `context-vault ingest <url>`  | Fetch URL and save as vault entry                         |
-| `context-vault update`        | Check for updates                                         |
-| `context-vault uninstall`     | Remove MCP configs                                        |
+| Command                       | Description                                                |
+| ----------------------------- | ---------------------------------------------------------- |
+| `context-vault setup`         | Interactive installer — detects tools, writes MCP configs  |
+| `context-vault connect --key` | Connect AI tools to hosted vault                           |
+| `context-vault switch`        | Switch between local and hosted MCP modes                  |
+| `context-vault serve`         | Start the MCP server (used by AI clients)                  |
+| `context-vault status`        | Vault health, paths, entry counts                          |
+| `context-vault flush`         | Confirm DB is accessible; prints entry count and last save |
+| `context-vault hooks install` | Install Claude Code memory and optional session flush hook |
+| `context-vault hooks remove`  | Remove the recall and session flush hooks                  |
+| `context-vault reindex`       | Rebuild search index                                       |
+| `context-vault import <path>` | Import .md, .csv, .json, .txt                              |
+| `context-vault export`        | Export to JSON or CSV                                      |
+| `context-vault ingest <url>`  | Fetch URL and save as vault entry                          |
+| `context-vault update`        | Check for updates                                          |
+| `context-vault uninstall`     | Remove MCP configs                                         |
+
+## Claude Code Lifecycle Hooks
+
+Claude Code exposes shell hooks that fire on session events. context-vault integrates with two of them:
+
+**UserPromptSubmit** — runs `context-vault recall` on every prompt, injecting relevant vault entries as context (installed via `hooks install`).
+
+**SessionEnd** — runs `context-vault flush` when a session ends, confirming the vault is healthy and logging the current entry count. Install it when prompted by `hooks install`, or add it manually to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx context-vault flush",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The `flush` command reads the DB, prints a one-line status (`context-vault ok — N entries, last save: <timestamp>`), and exits 0. It is intentionally a no-op write — its purpose is to confirm reachability at session boundaries.
+
+To install both hooks at once:
+
+```bash
+context-vault hooks install
+# Follow the second prompt: "Install session auto-flush hook? (y/N)"
+```
+
+To remove both hooks:
+
+```bash
+context-vault hooks remove
+```
 
 ## Manual MCP Config
 
@@ -73,6 +117,8 @@ If you prefer manual setup over `context-vault setup`:
 
 No Node.js required — sign up at [app.context-vault.com](https://app.context-vault.com), get an API key, connect in 2 minutes.
 
+Full setup instructions for Claude Code, Cursor, and GPT Actions: [docs/distribution/connect-in-2-minutes.md](../../docs/distribution/connect-in-2-minutes.md)
+
 ## Troubleshooting
 
 **Install fails (native modules):**

package/assets/skills/compile-context/skill.md

@@ -0,0 +1,45 @@
+---
+name: compile-context
+description: >
+  Compiles scattered vault entries on a topic into a single authoritative brief
+  for isolated retrieval in a fresh context window. Use when starting a new work
+  session on a project, preparing a handoff, or loading focused context without
+  noise. Also audits for stale or contradicting entries.
+  Triggers: "compile context", "create a brief", "context snapshot", "context bucket",
+  "make a brief for X", "load context for X".
+---
+
+# compile-context skill
+
+When the user asks to compile context or create a brief for a topic, call `create_snapshot` to synthesize a context brief from the vault.
+
+## Step 1 — Identify the topic
+
+If the user provided a topic or project name, use it. If not, ask:
+
+> "What topic or project should I compile context for?"
+
+Derive a slug: lowercase, hyphens, no spaces (e.g. `neonode`, `context-vault`, `klarhimmel-infra`).
+
+## Step 2 — Call create_snapshot
+
+Call `create_snapshot` with:
+
+- `topic`: the topic name the user provided
+- `identity_key`: `snapshot-<slug>` (e.g. `snapshot-context-vault`)
+- `tags` (optional): any relevant tags the user mentions
+- `kinds` (optional): restrict to specific entry kinds if the user requests it
+
+The tool handles retrieval, deduplication, LLM synthesis, and saving automatically.
+
+## Step 3 — Report
+
+After the tool returns, tell the user:
+
+- The ULID of the saved brief
+- How many entries were synthesized
+- The exact call to retrieve it in a future session:
+  ```
+  get_context(identity_key: "snapshot-<slug>")
+  ```
+- Suggest pinning the identity key in the relevant CLAUDE.md or MEMORY.md for zero-cost retrieval in fresh windows.

package/bin/cli.js

@@ -235,11 +235,15 @@ ${bold("Commands:")}
   ${cyan("connect")} --key cv_...  Connect AI tools to hosted vault
   ${cyan("switch")} local|hosted      Switch between local and hosted MCP modes
   ${cyan("serve")}                 Start the MCP server (used by AI clients)
-  ${cyan("hooks")} install|remove  Install or remove Claude Code memory hook
+  ${cyan("hooks")} install|uninstall  Install or remove Claude Code memory hook
+  ${cyan("claude")} install|uninstall  Alias for hooks install|uninstall
+  ${cyan("skills")} install          Install bundled Claude Code skills
+  ${cyan("flush")}                 Check vault health and confirm DB is accessible
   ${cyan("recall")}                Search vault from a Claude Code hook (reads stdin)
   ${cyan("reindex")}               Rebuild search index from knowledge files
   ${cyan("prune")}                 Remove expired entries (use --dry-run to preview)
   ${cyan("status")}                Show vault diagnostics
+  ${cyan("doctor")}                Diagnose and repair common issues
   ${cyan("update")}                Check for and install updates
   ${cyan("uninstall")}             Remove MCP configs and optionally data
   ${cyan("import")} <path>          Import entries from file or directory
@@ -729,6 +733,37 @@ async function runSetup() {
     }
   }
 
+  // Claude Code skills (opt-in)
+  if (claudeConfigured && !isNonInteractive) {
+    console.log();
+    console.log(dim("  Install Claude Code skills? (recommended)"));
+    console.log(
+      dim("  compile-context — compile vault entries into a project brief"),
+    );
+    console.log();
+    const skillAnswer = await prompt(
+      "  Install Claude Code skills? (Y/n):",
+      "Y",
+    );
+    const installSkillsFlag = skillAnswer.toLowerCase() !== "n";
+    if (installSkillsFlag) {
+      try {
+        const names = installSkills();
+        if (names.length > 0) {
+          for (const name of names) {
+            console.log(`\n  ${green("+")} ${name} skill installed`);
+          }
+        }
+      } catch (e) {
+        console.log(`\n  ${red("x")} Skills install failed: ${e.message}`);
+      }
+    } else {
+      console.log(
+        dim(`  Skipped — install later: context-vault skills install`),
+      );
+    }
+  }
+
   // Seed entry
   const seeded = createSeedEntries(resolvedVaultDir);
   if (seeded > 0) {
@@ -1484,6 +1519,8 @@ async function runStatus() {
   const { resolveConfig } = await import("@context-vault/core/core/config");
   const { initDatabase } = await import("@context-vault/core/index/db");
   const { gatherVaultStatus } = await import("@context-vault/core/core/status");
+  const { errorLogPath, errorLogCount } =
+    await import("@context-vault/core/core/error-log");
 
   const config = resolveConfig();
 
@@ -1566,6 +1603,18 @@ async function runStatus() {
     console.log(yellow("  Stale paths detected in DB."));
     console.log(`  Run ${cyan("context-vault reindex")} to update.`);
   }
+
+  const logCount = errorLogCount(config.dataDir);
+  if (logCount > 0) {
+    const logPath = errorLogPath(config.dataDir);
+    console.log();
+    console.log(
+      yellow(
+        `  ${logCount} startup error${logCount === 1 ? "" : "s"} logged — run ${cyan("context-vault doctor")} for details`,
+      ),
+    );
+    console.log(`  ${dim(logPath)}`);
+  }
   console.log();
 }
 
@@ -2110,16 +2159,25 @@ async function runRecall() {
     const results = await hybridSearch(ctx, query, { limit: 5 });
     if (!results.length) return;
 
-    const lines = ["## Context Vault\n"];
+    const MAX_TOTAL = 2000;
+    const ENTRY_BODY_LIMIT = 400;
+    const entries = [];
+    let totalChars = 0;
+
     for (const r of results) {
       const entryTags = r.tags ? JSON.parse(r.tags) : [];
-      lines.push(`### ${r.title || "(untitled)"} [${r.kind}]`);
-      if (entryTags.length) lines.push(`tags: ${entryTags.join(", ")}`);
-      lines.push(r.body?.slice(0, 400) + (r.body?.length > 400 ? "..." : ""));
-      lines.push("");
+      const tagsAttr = entryTags.length ? ` tags="${entryTags.join(",")}"` : "";
+      const body = r.body?.slice(0, ENTRY_BODY_LIMIT) ?? "";
+      const entry = `<entry kind="${r.kind || "knowledge"}"${tagsAttr}>\n${body}\n</entry>`;
+      if (totalChars + entry.length > MAX_TOTAL) break;
+      entries.push(entry);
+      totalChars += entry.length;
     }
 
-    process.stdout.write(lines.join("\n"));
+    if (!entries.length) return;
+
+    const block = `<context-vault>\n${entries.join("\n")}\n</context-vault>\n`;
+    process.stdout.write(block);
   } catch {
     // fail silently — never interrupt the user's workflow
   } finally {
@@ -2129,6 +2187,69 @@ async function runRecall() {
   }
 }
 
+async function runFlush() {
+  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { initDatabase } = await import("@context-vault/core/index/db");
+
+  let db;
+  try {
+    const config = resolveConfig();
+    db = await initDatabase(config.dbPath);
+
+    const { c: entryCount } = db
+      .prepare("SELECT COUNT(*) as c FROM vault")
+      .get();
+
+    const lastSaveRow = db
+      .prepare("SELECT MAX(COALESCE(updated_at, created_at)) as ts FROM vault")
+      .get();
+    const lastSave = lastSaveRow?.ts ?? "n/a";
+
+    console.log(
+      `context-vault ok — ${entryCount} ${entryCount === 1 ? "entry" : "entries"}, last save: ${lastSave}`,
+    );
+  } catch (e) {
+    console.error(red(`context-vault flush failed: ${e.message}`));
+    process.exit(1);
+  } finally {
+    try {
+      db?.close();
+    } catch {}
+  }
+}
+
+/**
+ * Copies all skills from the bundled assets/skills/ directory into ~/.claude/skills/.
+ * Returns an array of installed skill names.
+ */
+function installSkills() {
+  const assetsSkillsDir = join(ROOT, "assets", "skills");
+  const targetDir = join(HOME, ".claude", "skills");
+
+  if (!existsSync(assetsSkillsDir)) return [];
+
+  const skillNames = readdirSync(assetsSkillsDir).filter((name) => {
+    try {
+      return statSync(join(assetsSkillsDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  const installed = [];
+  for (const skillName of skillNames) {
+    const srcDir = join(assetsSkillsDir, skillName);
+    const destDir = join(targetDir, skillName);
+    mkdirSync(destDir, { recursive: true });
+    const files = readdirSync(srcDir);
+    for (const file of files) {
+      copyFileSync(join(srcDir, file), join(destDir, file));
+    }
+    installed.push(skillName);
+  }
+  return installed;
+}
+
 /** Returns the path to Claude Code's global settings.json */
 function claudeSettingsPath() {
   return join(HOME, ".claude", "settings.json");
@@ -2176,6 +2297,76 @@ function installClaudeHook() {
   return true;
 }
 
+/**
+ * Writes a SessionEnd hook entry for context-vault flush to ~/.claude/settings.json.
+ * Returns true if installed, false if already present.
+ */
+function installSessionEndHook() {
+  const settingsPath = claudeSettingsPath();
+  let settings = {};
+
+  if (existsSync(settingsPath)) {
+    const raw = readFileSync(settingsPath, "utf-8");
+    try {
+      settings = JSON.parse(raw);
+    } catch {
+      const bak = settingsPath + ".bak";
+      copyFileSync(settingsPath, bak);
+      console.log(yellow(`  Backed up corrupted settings to ${bak}`));
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.SessionEnd) settings.hooks.SessionEnd = [];
+
+  const alreadyInstalled = settings.hooks.SessionEnd.some((h) =>
+    h.hooks?.some((hh) => hh.command?.includes("context-vault flush")),
+  );
+  if (alreadyInstalled) return false;
+
+  settings.hooks.SessionEnd.push({
+    hooks: [
+      {
+        type: "command",
+        command: "npx context-vault flush",
+        timeout: 10,
+      },
+    ],
+  });
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return true;
+}
+
+/**
+ * Removes the context-vault flush SessionEnd hook from ~/.claude/settings.json.
+ * Returns true if removed, false if not found.
+ */
+function removeSessionEndHook() {
+  const settingsPath = claudeSettingsPath();
+  if (!existsSync(settingsPath)) return false;
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return false;
+  }
+
+  if (!settings.hooks?.SessionEnd) return false;
+
+  const before = settings.hooks.SessionEnd.length;
+  settings.hooks.SessionEnd = settings.hooks.SessionEnd.filter(
+    (h) => !h.hooks?.some((hh) => hh.command?.includes("context-vault flush")),
+  );
+
+  if (settings.hooks.SessionEnd.length === before) return false;
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return true;
+}
+
 /**
  * Removes the context-vault recall hook from ~/.claude/settings.json.
  * Returns true if removed, false if not found.
@@ -2204,62 +2395,371 @@ function removeClaudeHook() {
   return true;
 }
 
-async function runHooks() {
+async function runSkills() {
   const sub = args[1];
 
   if (sub === "install") {
+    console.log();
     try {
-      const installed = installClaudeHook();
-      if (installed) {
-        console.log(`\n  ${green("✓")} Claude Code memory hook installed.\n`);
-        console.log(
-          dim(
-            "  On every prompt, context-vault searches your vault for relevant entries",
-          ),
-        );
-        console.log(
-          dim(
-            "  and injects them as additional context alongside Claude's native memory.",
-          ),
-        );
-        console.log(
-          dim(`\n  To remove: ${cyan("context-vault hooks remove")}`),
-        );
+      const names = installSkills();
+      if (names.length === 0) {
+        console.log(`  ${yellow("!")} No bundled skills found.\n`);
       } else {
-        console.log(`\n  ${yellow("!")} Hook already installed.\n`);
+        for (const name of names) {
+          console.log(
+            `  ${green("+")} ${name} — installed to ~/.claude/skills/${name}/`,
+          );
+        }
+        console.log();
+        console.log(dim("  Skills are active immediately in Claude Code."));
+        console.log(dim(`  Trigger with: /${names.join(", /")}`));
       }
     } catch (e) {
-      console.error(`\n  ${red("x")} Failed to install hook: ${e.message}\n`);
+      console.error(`  ${red("x")} Skills install failed: ${e.message}\n`);
       process.exit(1);
     }
     console.log();
-  } else if (sub === "remove") {
+  } else {
+    console.log(`
+  ${bold("context-vault skills")} <install>
+
+  Manage bundled Claude Code skills.
+
+${bold("Commands:")}
+  ${cyan("skills install")}   Copy bundled skills into ~/.claude/skills/
+
+${bold("Bundled skills:")}
+  ${cyan("compile-context")}  Compile vault entries into a project brief using create_snapshot
+`);
+  }
+}
+
+async function runHooksInstall() {
+  try {
+    const installed = installClaudeHook();
+    if (installed) {
+      console.log(
+        `\n  ${green("✓")} Hook installed. Context vault will inject relevant entries on every prompt.\n`,
+      );
+      console.log(
+        dim(
+          "  On every prompt, context-vault searches your vault for relevant entries",
+        ),
+      );
+      console.log(
+        dim(
+          "  and injects them as a <context-vault> block before Claude sees your message.",
+        ),
+      );
+      console.log(
+        dim(`\n  To remove: ${cyan("context-vault hooks uninstall")}`),
+      );
+    } else {
+      console.log(`\n  ${yellow("!")} Hook already installed.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red("x")} Failed to install hook: ${e.message}\n`);
+    process.exit(1);
+  }
+  console.log();
+
+  const installFlush =
+    flags.has("--flush") ||
+    (await prompt(
+      "  Install SessionEnd flush hook? (saves vault health summary at session end) (y/N):",
+      "n",
+    ));
+  const shouldInstallFlush =
+    installFlush === true ||
+    (typeof installFlush === "string" &&
+      installFlush.toLowerCase().startsWith("y"));
+
+  if (shouldInstallFlush) {
     try {
-      const removed = removeClaudeHook();
-      if (removed) {
-        console.log(`\n  ${green("✓")} Claude Code memory hook removed.\n`);
+      const flushInstalled = installSessionEndHook();
+      if (flushInstalled) {
+        console.log(`\n  ${green("✓")} SessionEnd flush hook installed.\n`);
+        console.log(
+          dim(
+            "  At the end of each session, context-vault flush confirms the vault is healthy.",
+          ),
+        );
       } else {
-        console.log(`\n  ${yellow("!")} Hook not found — nothing to remove.\n`);
+        console.log(
+          `\n  ${yellow("!")} SessionEnd flush hook already installed.\n`,
+        );
       }
     } catch (e) {
-      console.error(`\n  ${red("x")} Failed to remove hook: ${e.message}\n`);
+      console.error(
+        `\n  ${red("x")} Failed to install session flush hook: ${e.message}\n`,
+      );
       process.exit(1);
     }
+    console.log();
+  }
+}
+
+async function runHooksUninstall() {
+  try {
+    const removed = removeClaudeHook();
+    if (removed) {
+      console.log(`\n  ${green("✓")} Claude Code memory hook removed.\n`);
+    } else {
+      console.log(`\n  ${yellow("!")} Hook not found — nothing to remove.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red("x")} Failed to remove hook: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  try {
+    const flushRemoved = removeSessionEndHook();
+    if (flushRemoved) {
+      console.log(`\n  ${green("✓")} SessionEnd flush hook removed.\n`);
+    }
+  } catch (e) {
+    console.error(
+      `\n  ${red("x")} Failed to remove session flush hook: ${e.message}\n`,
+    );
+  }
+}
+
+async function runHooks() {
+  const sub = args[1];
+
+  if (sub === "install") {
+    await runHooksInstall();
+  } else if (sub === "remove" || sub === "uninstall") {
+    await runHooksUninstall();
   } else {
     console.log(`
-  ${bold("context-vault hooks")} <install|remove>
+  ${bold("context-vault hooks")} <install|uninstall>
 
   Manage the Claude Code memory hook integration.
   When installed, context-vault automatically searches your vault on every user
-  prompt and injects relevant entries as additional context.
+  prompt and injects relevant entries as a <context-vault> XML block.
 
 ${bold("Commands:")}
-  ${cyan("hooks install")}   Write UserPromptSubmit hook to ~/.claude/settings.json
-  ${cyan("hooks remove")}    Remove the hook from ~/.claude/settings.json
+  ${cyan("hooks install")}     Write UserPromptSubmit hook to ~/.claude/settings.json
+                    Also prompts to install a SessionEnd flush hook
+  ${cyan("hooks uninstall")}   Remove the recall hook and SessionEnd flush hook
 `);
   }
 }
 
+async function runClaude() {
+  const sub = args[1];
+
+  if (sub === "install") {
+    await runHooksInstall();
+  } else if (sub === "uninstall" || sub === "remove") {
+    await runHooksUninstall();
+  } else {
+    console.log(`
+  ${bold("context-vault claude")} <install|uninstall>
+
+  Manage the Claude Code memory hook integration.
+  Alias for ${cyan("context-vault hooks install|uninstall")}.
+
+${bold("Commands:")}
+  ${cyan("claude install")}     Write UserPromptSubmit hook to ~/.claude/settings.json
+  ${cyan("claude uninstall")}   Remove the recall hook and SessionEnd flush hook
+`);
+  }
+}
+
+async function runDoctor() {
+  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { errorLogPath, errorLogCount } =
+    await import("@context-vault/core/core/error-log");
+
+  console.log();
+  console.log(`  ${bold("◇ context-vault doctor")} ${dim(`v${VERSION}`)}`);
+  console.log();
+
+  let allOk = true;
+
+  // ── Node.js version ──────────────────────────────────────────────────────
+  const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+  if (nodeMajor < 20) {
+    console.log(
+      `  ${red("✘")} Node.js ${process.versions.node} — requires >= 20`,
+    );
+    console.log(
+      `    ${dim("Fix: install a newer Node.js from https://nodejs.org/")}`,
+    );
+    allOk = false;
+  } else {
+    console.log(
+      `  ${green("✓")} Node.js ${process.versions.node} ${dim(`(${process.execPath})`)}`,
+    );
+  }
+
+  // ── Config ───────────────────────────────────────────────────────────────
+  let config;
+  try {
+    config = resolveConfig();
+    const configExists = existsSync(config.configPath);
+    console.log(
+      `  ${green("✓")} Config ${dim(`(${configExists ? "exists" : "using defaults"}: ${config.configPath})`)}`,
+    );
+  } catch (e) {
+    console.log(`  ${red("✘")} Config parse error: ${e.message}`);
+    console.log(
+      `    ${dim(`Fix: delete or repair ${join(HOME, ".context-mcp", "config.json")}`)}`,
+    );
+    allOk = false;
+  }
+
+  if (config) {
+    // ── Data dir ───────────────────────────────────────────────────────────
+    if (existsSync(config.dataDir)) {
+      console.log(`  ${green("✓")} Data dir ${dim(config.dataDir)}`);
+    } else {
+      console.log(
+        `  ${yellow("!")} Data dir missing — will be created on next start`,
+      );
+      console.log(`    ${dim(`mkdir -p "${config.dataDir}"`)}`);
+    }
+
+    // ── Vault dir ─────────────────────────────────────────────────────────
+    if (existsSync(config.vaultDir)) {
+      try {
+        const probe = join(config.vaultDir, ".write-probe");
+        writeFileSync(probe, "");
+        unlinkSync(probe);
+        console.log(`  ${green("✓")} Vault dir ${dim(config.vaultDir)}`);
+      } catch {
+        console.log(`  ${red("✘")} Vault dir not writable: ${config.vaultDir}`);
+        console.log(`    ${dim(`Fix: chmod u+w "${config.vaultDir}"`)}`);
+        allOk = false;
+      }
+    } else {
+      console.log(
+        `  ${yellow("!")} Vault dir missing — will be created on next start`,
+      );
+      console.log(`    ${dim(`mkdir -p "${config.vaultDir}"`)}`);
+    }
+
+    // ── Database ──────────────────────────────────────────────────────────
+    if (existsSync(config.dbPath)) {
+      try {
+        const { initDatabase } = await import("@context-vault/core/index/db");
+        const db = await initDatabase(config.dbPath);
+        db.close();
+        console.log(`  ${green("✓")} Database ${dim(config.dbPath)}`);
+      } catch (e) {
+        console.log(`  ${red("✘")} Database error: ${e.message}`);
+        console.log(
+          `    ${dim(`Fix: rm "${config.dbPath}" (data will be lost)`)}`,
+        );
+        allOk = false;
+      }
+    } else {
+      console.log(
+        `  ${yellow("!")} Database missing — will be created on next start`,
+      );
+    }
+
+    // ── Launcher (server.mjs) ─────────────────────────────────────────────
+    const launcherPath = join(HOME, ".context-mcp", "server.mjs");
+    if (existsSync(launcherPath)) {
+      const launcherContent = readFileSync(launcherPath, "utf-8");
+      const match = launcherContent.match(/import "(.+?)"/);
+      if (match) {
+        const serverEntryPath = match[1];
+        if (existsSync(serverEntryPath)) {
+          console.log(
+            `  ${green("✓")} Launcher ${dim(`→ ${serverEntryPath}`)}`,
+          );
+        } else {
+          console.log(
+            `  ${red("✘")} Launcher points to missing server: ${serverEntryPath}`,
+          );
+          console.log(
+            `    ${dim("Fix: run context-vault setup to reinstall")}`,
+          );
+          allOk = false;
+        }
+      } else {
+        console.log(`  ${green("✓")} Launcher exists ${dim(launcherPath)}`);
+      }
+    } else {
+      console.log(`  ${yellow("!")} Launcher not found at ${launcherPath}`);
+      console.log(`    ${dim("Fix: run context-vault setup")}`);
+      allOk = false;
+    }
+
+    // ── Error log ─────────────────────────────────────────────────────────
+    const logPath = errorLogPath(config.dataDir);
+    const logCount = errorLogCount(config.dataDir);
+    if (logCount > 0) {
+      console.log();
+      console.log(
+        `  ${yellow("!")} Error log has ${logCount} entr${logCount === 1 ? "y" : "ies"}: ${dim(logPath)}`,
+      );
+      try {
+        const lines = readFileSync(logPath, "utf-8")
+          .split("\n")
+          .filter((l) => l.trim());
+        const last = JSON.parse(lines[lines.length - 1]);
+        console.log(`    Last error: ${red(last.message)}`);
+        console.log(
+          `    Phase: ${dim(last.phase || "unknown")}  Time: ${dim(last.timestamp)}`,
+        );
+      } catch {}
+      console.log(`    ${dim(`To clear: rm "${logPath}"`)}`);
+      allOk = false;
+    } else {
+      console.log(`  ${green("✓")} No startup errors logged`);
+    }
+  }
+
+  // ── MCP tool configs ──────────────────────────────────────────────────────
+  console.log();
+  console.log(bold("  Tool Configurations"));
+  const claudeConfigPath = join(HOME, ".claude.json");
+  if (existsSync(claudeConfigPath)) {
+    try {
+      const claudeConfig = JSON.parse(readFileSync(claudeConfigPath, "utf-8"));
+      const servers = claudeConfig?.mcpServers || {};
+      if (servers["context-vault"]) {
+        const srv = servers["context-vault"];
+        const cmd = [srv.command, ...(srv.args || [])].join(" ");
+        console.log(`  ${green("+")} Claude Code: ${dim(cmd)}`);
+      } else {
+        console.log(`  ${dim("-")} Claude Code: context-vault not configured`);
+        console.log(`    ${dim("Fix: run context-vault setup")}`);
+      }
+    } catch {
+      console.log(
+        `  ${yellow("!")} Claude Code: could not read ~/.claude.json`,
+      );
+    }
+  } else {
+    console.log(`  ${dim("-")} Claude Code: ~/.claude.json not found`);
+  }
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  console.log();
+  if (allOk) {
+    console.log(
+      `  ${green("✓ All checks passed.")} If the MCP server still fails, try:`,
+    );
+    console.log(
+      `    ${dim("context-vault setup")}  — reconfigure tool integrations`,
+    );
+  } else {
+    console.log(
+      `  ${yellow("Some issues found.")} Address the items above, then restart your AI tool.`,
+    );
+    console.log(
+      `    ${dim("context-vault setup")}  — reconfigure and repair installation`,
+    );
+  }
+  console.log();
+}
+
 async function runServe() {
   await import("../src/server/index.js");
 }
@@ -2291,6 +2791,15 @@ async function main() {
     case "hooks":
       await runHooks();
       break;
+    case "claude":
+      await runClaude();
+      break;
+    case "skills":
+      await runSkills();
+      break;
+    case "flush":
+      await runFlush();
+      break;
     case "recall":
       await runRecall();
       break;
@@ -2321,6 +2830,9 @@ async function main() {
     case "migrate":
       await runMigrate();
       break;
+    case "doctor":
+      await runDoctor();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan("context-vault --help")} for usage.`);

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

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

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

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { ok } from "../helpers.js";
+
+export const name = "clear_context";
+
+export const description =
+  "Reset active in-memory session context without deleting vault entries. Call this when switching projects or topics mid-session. With `scope`, all subsequent get_context calls should filter to that tag/project. Vault data is never modified.";
+
+export const inputSchema = {
+  scope: z
+    .string()
+    .optional()
+    .describe(
+      "Optional tag or project name to focus on going forward. When provided, treat subsequent get_context calls as if filtered to this tag.",
+    ),
+};
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} _ctx
+ */
+export function handler({ scope } = {}) {
+  const lines = [
+    "## Context Reset",
+    "",
+    "Active session context has been cleared. All previous context from this session should be disregarded.",
+    "",
+    "Vault entries are unchanged — no data was deleted.",
+  ];
+
+  if (scope?.trim()) {
+    const trimmed = scope.trim();
+    lines.push(
+      "",
+      `### Active Scope: \`${trimmed}\``,
+      "",
+      `Going forward, treat \`get_context\` calls as scoped to the tag or project **"${trimmed}"** unless the user explicitly requests a different scope or passes their own tag filters.`,
+    );
+  } else {
+    lines.push(
+      "",
+      "No scope set. Use `get_context` normally — all vault entries are accessible.",
+    );
+  }
+
+  return ok(lines.join("\n"));
+}

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

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import { hybridSearch } from "../../retrieve/index.js";
+import { captureAndIndex } from "../../capture/index.js";
+import { normalizeKind } from "../../core/files.js";
+import { ok, err, ensureVaultExists } from "../helpers.js";
+
+const NOISE_KINDS = new Set(["prompt-history", "task-notification"]);
+const SYNTHESIS_MODEL = "claude-haiku-4-5-20251001";
+const MAX_ENTRIES_FOR_SYNTHESIS = 40;
+const MAX_BODY_PER_ENTRY = 600;
+
+export const name = "create_snapshot";
+
+export const description =
+  "Pull all relevant vault entries matching a topic, run an LLM synthesis pass to deduplicate and structure them into a context brief, then save and return the brief's ULID. The brief is saved as kind: 'brief' with a deterministic identity_key for retrieval.";
+
+export const inputSchema = {
+  topic: z.string().describe("The topic or project name to snapshot"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Optional tag filters — entries must match at least one"),
+  kinds: z
+    .array(z.string())
+    .optional()
+    .describe("Optional kind filters to restrict which entry types are pulled"),
+  identity_key: z
+    .string()
+    .optional()
+    .describe(
+      "Deterministic key for the saved brief (defaults to slugified topic). Use the same key to overwrite a previous snapshot.",
+    ),
+};
+
+function buildSynthesisPrompt(topic, entries) {
+  const entriesBlock = entries
+    .map((e, i) => {
+      const tags = e.tags ? JSON.parse(e.tags) : [];
+      const tagStr = tags.length ? tags.join(", ") : "none";
+      const body = e.body
+        ? e.body.slice(0, MAX_BODY_PER_ENTRY) +
+          (e.body.length > MAX_BODY_PER_ENTRY ? "…" : "")
+        : "(no body)";
+      return [
+        `### Entry ${i + 1} [${e.kind}] id: ${e.id}`,
+        `tags: ${tagStr}`,
+        `updated: ${e.updated_at || e.created_at || "unknown"}`,
+        body,
+      ].join("\n");
+    })
+    .join("\n\n");
+
+  return `You are a knowledge synthesis assistant. Given the following vault entries about "${topic}", produce a structured context brief.
+
+Deduplicate overlapping information, resolve any contradictions (note them in Audit Notes), and organise the content into the sections below. Keep each section concise and actionable. Omit sections that have no relevant content.
+
+Output ONLY the markdown document — no preamble, no explanation.
+
+Required format:
+# ${topic} — Context Brief
+## Status
+(current state of the topic)
+## Key Decisions
+(architectural or strategic decisions made)
+## Patterns & Conventions
+(recurring patterns, coding conventions, standards)
+## Active Constraints
+(known limitations, hard requirements, deadlines)
+## Open Questions
+(unresolved questions or areas needing investigation)
+## Audit Notes
+(contradictions detected, stale entries flagged with their ids)
+
+---
+VAULT ENTRIES:
+
+${entriesBlock}`;
+}
+
+async function callLlm(prompt) {
+  const { Anthropic } = await import("@anthropic-ai/sdk");
+  const client = new Anthropic();
+  const message = await client.messages.create({
+    model: SYNTHESIS_MODEL,
+    max_tokens: 2048,
+    messages: [{ role: "user", content: prompt }],
+  });
+  const block = message.content.find((b) => b.type === "text");
+  if (!block) throw new Error("LLM returned no text content");
+  return block.text;
+}
+
+function slugifyTopic(topic) {
+  return topic
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120);
+}
+
+export async function handler(
+  { topic, tags, kinds, identity_key },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!topic?.trim()) {
+    return err("Required: topic (non-empty string)", "INVALID_INPUT");
+  }
+
+  await ensureIndexed();
+
+  const normalizedKinds = kinds?.map(normalizeKind) ?? [];
+
+  let candidates = [];
+
+  if (normalizedKinds.length > 0) {
+    for (const kindFilter of normalizedKinds) {
+      const rows = await hybridSearch(ctx, topic, {
+        kindFilter,
+        limit: Math.ceil(MAX_ENTRIES_FOR_SYNTHESIS / normalizedKinds.length),
+        userIdFilter: userId,
+        includeSuperseeded: false,
+      });
+      candidates.push(...rows);
+    }
+    const seen = new Set();
+    candidates = candidates.filter((r) => {
+      if (seen.has(r.id)) return false;
+      seen.add(r.id);
+      return true;
+    });
+  } else {
+    candidates = await hybridSearch(ctx, topic, {
+      limit: MAX_ENTRIES_FOR_SYNTHESIS,
+      userIdFilter: userId,
+      includeSuperseeded: false,
+    });
+  }
+
+  if (tags?.length) {
+    candidates = candidates.filter((r) => {
+      const entryTags = r.tags ? JSON.parse(r.tags) : [];
+      return tags.some((t) => entryTags.includes(t));
+    });
+  }
+
+  const noiseIds = candidates
+    .filter((r) => NOISE_KINDS.has(r.kind))
+    .map((r) => r.id);
+
+  const synthesisEntries = candidates.filter((r) => !NOISE_KINDS.has(r.kind));
+
+  if (synthesisEntries.length === 0) {
+    return err(
+      `No entries found for topic "${topic}" to synthesize. Try a broader topic or different tags.`,
+      "NO_ENTRIES",
+    );
+  }
+
+  let briefBody;
+  try {
+    const prompt = buildSynthesisPrompt(topic, synthesisEntries);
+    briefBody = await callLlm(prompt);
+  } catch (e) {
+    return err(
+      `LLM synthesis failed: ${e.message}. Ensure ANTHROPIC_API_KEY is set.`,
+      "LLM_ERROR",
+    );
+  }
+
+  const effectiveIdentityKey =
+    identity_key ?? `snapshot-${slugifyTopic(topic)}`;
+
+  const briefTags = [
+    "snapshot",
+    ...(tags ?? []),
+    ...(normalizedKinds.length > 0 ? [] : []),
+  ];
+
+  const supersedes = noiseIds.length > 0 ? noiseIds : undefined;
+
+  const entry = await captureAndIndex(ctx, {
+    kind: "brief",
+    title: `${topic} — Context Brief`,
+    body: briefBody,
+    tags: briefTags,
+    source: "create_snapshot",
+    identity_key: effectiveIdentityKey,
+    supersedes,
+    userId,
+    meta: {
+      topic,
+      entry_count: synthesisEntries.length,
+      noise_superseded: noiseIds.length,
+      synthesized_from: synthesisEntries.map((e) => e.id),
+    },
+  });
+
+  const parts = [
+    `✓ Snapshot created → id: ${entry.id}`,
+    `  title: ${entry.title}`,
+    `  identity_key: ${effectiveIdentityKey}`,
+    `  synthesized from: ${synthesisEntries.length} entries`,
+    noiseIds.length > 0
+      ? `  noise superseded: ${noiseIds.length} entries`
+      : null,
+    "",
+    "_Retrieve with: get_context(kind: 'brief', identity_key: '" +
+      effectiveIdentityKey +
+      "')_",
+  ]
+    .filter((l) => l !== null)
+    .join("\n");
+
+  return ok(parts);
+}

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

@@ -5,6 +5,87 @@ import { normalizeKind } from "../../core/files.js";
 import { ok, err } from "../helpers.js";
 import { isEmbedAvailable } from "../../index/embed.js";
 
+const STALE_DUPLICATE_DAYS = 7;
+
+/**
+ * Detect conflicts among a set of search result entries.
+ *
+ * Two checks are performed:
+ *   1. Supersession: if entry A's `superseded_by` points to any entry B in the
+ *      result set, A is stale and should be discarded in favour of B.
+ *   2. Stale duplicate: two entries share the same kind and at least one common
+ *      tag, but their `updated_at` timestamps differ by more than
+ *      STALE_DUPLICATE_DAYS days — suggesting the older one may be outdated.
+ *
+ * No LLM calls, no new dependencies — pure in-memory set operations on the
+ * rows already fetched from the DB.
+ *
+ * @param {Array} entries - Result rows (as returned by hybridSearch / filter-only mode)
+ * @param {import('../types.js').BaseCtx} _ctx - Unused for now; reserved for future DB look-ups
+ * @returns {Array<{entry_a_id: string, entry_b_id: string, reason: string, recommendation: string}>}
+ */
+export function detectConflicts(entries, _ctx) {
+  const conflicts = [];
+  const idSet = new Set(entries.map((e) => e.id));
+
+  for (const entry of entries) {
+    if (entry.superseded_by && idSet.has(entry.superseded_by)) {
+      conflicts.push({
+        entry_a_id: entry.id,
+        entry_b_id: entry.superseded_by,
+        reason: "superseded",
+        recommendation: `Discard \`${entry.id}\` — it has been explicitly superseded by \`${entry.superseded_by}\`.`,
+      });
+    }
+  }
+
+  const supersededConflictPairs = new Set(
+    conflicts.map((c) => `${c.entry_a_id}|${c.entry_b_id}`),
+  );
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      if (
+        supersededConflictPairs.has(`${a.id}|${b.id}`) ||
+        supersededConflictPairs.has(`${b.id}|${a.id}`)
+      ) {
+        continue;
+      }
+
+      if (a.kind !== b.kind) continue;
+
+      const tagsA = a.tags ? JSON.parse(a.tags) : [];
+      const tagsB = b.tags ? JSON.parse(b.tags) : [];
+
+      if (!tagsA.length || !tagsB.length) continue;
+
+      const tagsSetA = new Set(tagsA);
+      const sharedTag = tagsB.some((t) => tagsSetA.has(t));
+      if (!sharedTag) continue;
+
+      const dateA = new Date(a.updated_at || a.created_at);
+      const dateB = new Date(b.updated_at || b.created_at);
+      if (isNaN(dateA.getTime()) || isNaN(dateB.getTime())) continue;
+
+      const diffDays = Math.abs(dateA - dateB) / 86400000;
+      if (diffDays <= STALE_DUPLICATE_DAYS) continue;
+
+      const [older, newer] = dateA < dateB ? [a, b] : [b, a];
+      conflicts.push({
+        entry_a_id: older.id,
+        entry_b_id: newer.id,
+        reason: "stale_duplicate",
+        recommendation: `Verify \`${older.id}\` is still accurate — it shares kind "${older.kind}" and tags with \`${newer.id}\` but was last updated ${Math.round(diffDays)} days earlier.`,
+      });
+    }
+  }
+
+  return conflicts;
+}
+
 export const name = "get_context";
 
 export const description =
@@ -48,6 +129,12 @@ export const inputSchema = {
     .describe(
       "If true, include entries that have been superseded by newer ones. Default: false.",
     ),
+  detect_conflicts: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, compare results for contradicting entries and append a conflicts array. Flags superseded entries still in results and stale duplicates (same kind+tags, updated_at >7 days apart). No LLM calls — pure DB logic.",
+    ),
 };
 
 /**
@@ -66,6 +153,7 @@ export async function handler(
     until,
     limit,
     include_superseded,
+    detect_conflicts,
   },
   ctx,
   { ensureIndexed, reindexFailed },
@@ -227,6 +315,9 @@ export async function handler(
     }
   }
 
+  // Conflict detection
+  const conflicts = detect_conflicts ? detectConflicts(filtered, ctx) : [];
+
   const lines = [];
   if (reindexFailed)
     lines.push(
@@ -265,5 +356,23 @@ export async function handler(
     lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
     lines.push("");
   }
+
+  if (detect_conflicts) {
+    if (conflicts.length === 0) {
+      lines.push(
+        `## Conflict Detection\n\nNo conflicts detected among results.\n`,
+      );
+    } else {
+      lines.push(`## Conflict Detection (${conflicts.length} flagged)\n`);
+      for (const c of conflicts) {
+        lines.push(
+          `- **${c.reason}**: \`${c.entry_a_id}\` vs \`${c.entry_b_id}\``,
+        );
+        lines.push(`  Recommendation: ${c.recommendation}`);
+      }
+      lines.push("");
+    }
+  }
+
   return ok(lines.join("\n"));
 }

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

@@ -11,6 +11,8 @@ import * as deleteContext from "./tools/delete-context.js";
 import * as submitFeedback from "./tools/submit-feedback.js";
 import * as ingestUrl from "./tools/ingest-url.js";
 import * as contextStatus from "./tools/context-status.js";
+import * as clearContext from "./tools/clear-context.js";
+import * as createSnapshot from "./tools/create-snapshot.js";
 
 const toolModules = [
   getContext,
@@ -20,6 +22,8 @@ const toolModules = [
   submitFeedback,
   ingestUrl,
   contextStatus,
+  clearContext,
+  createSnapshot,
 ];
 
 const TOOL_TIMEOUT_MS = 60_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -17,6 +17,7 @@
     "prepack": "node scripts/prepack.js"
   },
   "files": [
+    "assets/",
     "bin/",
     "src/",
     "scripts/",
@@ -55,7 +56,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^2.12.0",
+    "@context-vault/core": "^2.14.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "sqlite-vec": "^0.1.0"
   }

package/src/server/index.js

@@ -265,6 +265,50 @@ async function main() {
   }
 }
 
+// ─── Top-level Safety Net ────────────────────────────────────────────────────
+// Catch any errors that escape the main() try/catch (e.g. thrown in MCP
+// transport callbacks or in unrelated async chains).  Claude Code surfaces
+// stderr when a server exits unexpectedly, so every message written here will
+// be visible to the user.
+
+process.on("uncaughtException", (err) => {
+  const dataDir = join(homedir(), ".context-mcp");
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    error_type: "uncaughtException",
+    message: err.message,
+    stack: err.stack?.split("\n").slice(0, 5).join(" | "),
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    cv_version: pkg.version,
+  };
+  appendErrorLog(dataDir, logEntry);
+  console.error(`[context-vault] Uncaught exception: ${err.message}`);
+  console.error(`[context-vault] Error log: ${join(dataDir, "error.log")}`);
+  console.error(`[context-vault] Run: context-vault doctor`);
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  const dataDir = join(homedir(), ".context-mcp");
+  const message = reason instanceof Error ? reason.message : String(reason);
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    error_type: "unhandledRejection",
+    message,
+    node_version: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    cv_version: pkg.version,
+  };
+  appendErrorLog(dataDir, logEntry);
+  console.error(`[context-vault] Unhandled rejection: ${message}`);
+  console.error(`[context-vault] Error log: ${join(dataDir, "error.log")}`);
+  console.error(`[context-vault] Run: context-vault doctor`);
+  process.exit(1);
+});
+
 main().catch((err) => {
   console.error(`[context-vault] Unexpected fatal error: ${err.message}`);
   process.exit(1);