context-vault 2.11.0 → 2.13.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/bin/cli.js

@@ -25,6 +25,7 @@ import { join, resolve, dirname } from "node:path";
 import { homedir, platform } from "node:os";
 import { execSync, execFile, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { APP_URL, API_URL, MARKETING_URL } from "@context-vault/core/constants";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -235,10 +236,12 @@ ${bold("Commands:")}
   ${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("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
@@ -272,9 +275,39 @@ async function runSetup() {
       existingVault = cfg.vaultDir || existingVault;
     } catch {}
 
+    // Version check against npm registry (5s timeout, fail silently if offline)
+    let latestVersion = null;
+    try {
+      latestVersion = execSync("npm view context-vault version", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      }).trim();
+    } catch {}
+
+    if (latestVersion === VERSION) {
+      console.log(
+        green(`  ✓ context-vault v${VERSION} is up to date`) +
+          dim(`  (vault: ${existingVault})`),
+      );
+      console.log();
+      return;
+    }
+
     console.log(yellow(`  Existing installation detected`));
     console.log(dim(`  Vault: ${existingVault}`));
-    console.log(dim(`  Config: ${existingConfig}`));
+    if (latestVersion) {
+      console.log();
+      console.log(`  Current: ${dim(VERSION)}`);
+      console.log(`  Latest:  ${green(latestVersion)}`);
+      const upgradeCmd = isNpx()
+        ? "npx context-vault@latest setup"
+        : "npm install -g context-vault";
+      console.log();
+      console.log(dim(`  To upgrade: ${upgradeCmd}`));
+    } else {
+      console.log(dim(`  Config: ${existingConfig}`));
+    }
     console.log();
     console.log(`    1) Full reconfigure`);
     console.log(`    2) Update tool configs only ${dim("(skip vault setup)")}`);
@@ -354,6 +387,7 @@ async function runSetup() {
 
       console.log();
       console.log(green("  ✓ Tool configs updated."));
+      console.log(dim("  Restart your AI tools to apply the changes."));
       console.log();
       return;
     }
@@ -501,7 +535,7 @@ async function runSetup() {
   console.log(
     dim("  file paths, or personal data is ever sent. Off by default."),
   );
-  console.log(dim("  Full schema: https://contextvault.dev/telemetry"));
+  console.log(dim(`  Full schema: ${MARKETING_URL}/telemetry`));
   console.log();
 
   let telemetryEnabled = vaultConfig.telemetry === true;
@@ -541,7 +575,12 @@ async function runSetup() {
     console.log(
       `\n  ${dim("[4/6]")}${bold(" Downloading embedding model...")}`,
     );
-    console.log(dim("  all-MiniLM-L6-v2 (~22MB, one-time download)\n"));
+    console.log(dim("  all-MiniLM-L6-v2 (~22MB, one-time download)"));
+    console.log(
+      dim(
+        `  Slow connection? Re-run with --skip-embeddings (enables FTS-only mode)\n`,
+      ),
+    );
     {
       const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
       let frame = 0;
@@ -731,7 +770,9 @@ async function runSetup() {
   const boxLines = [
     `  ✓ Setup complete — ${passed}/${checks.length} checks passed (${elapsed}s)`,
     ``,
-    `  ${bold("AI Tools")} — open ${toolName} and try:`,
+    `  ${bold("Next:")} restart ${toolName} to activate the vault`,
+    ``,
+    `  ${bold("AI Tools")} — once active, try:`,
     `  "Search my vault for getting started"`,
     `  "Save an insight about [topic]"`,
     `  "Show my vault status"`,
@@ -979,7 +1020,7 @@ This is an example entry showing the decision format. Feel free to delete it.
 
 async function runConnect() {
   const apiKey = getFlag("--key");
-  const hostedUrl = getFlag("--url") || "https://api.context-vault.com";
+  const hostedUrl = getFlag("--url") || API_URL;
 
   if (!apiKey) {
     console.log(`\n  ${bold("context-vault connect")}\n`);
@@ -988,9 +1029,7 @@ async function runConnect() {
     console.log(`    context-vault connect --key cv_...\n`);
     console.log(`  Options:`);
     console.log(`    --key <key>   API key (required)`);
-    console.log(
-      `    --url <url>   Hosted server URL (default: https://api.context-vault.com)`,
-    );
+    console.log(`    --url <url>   Hosted server URL (default: ${API_URL})`);
     console.log();
     return;
   }
@@ -1232,9 +1271,7 @@ async function runSwitch() {
     );
     console.log(`  Options:`);
     console.log(`    --key <key>   API key for hosted mode (cv_...)`);
-    console.log(
-      `    --url <url>   Hosted server URL (default: https://api.context-vault.com)\n`,
-    );
+    console.log(`    --url <url>   Hosted server URL (default: ${API_URL})\n`);
     return;
   }
 
@@ -1291,10 +1328,7 @@ async function runSwitch() {
     console.log(dim(`  Server: node ${launcherPath}`));
     console.log();
   } else {
-    const hostedUrl =
-      getFlag("--url") ||
-      vaultConfig.hostedUrl ||
-      "https://api.context-vault.com";
+    const hostedUrl = getFlag("--url") || vaultConfig.hostedUrl || API_URL;
     const apiKey = getFlag("--key") || vaultConfig.apiKey;
 
     if (!apiKey) {
@@ -1452,6 +1486,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();
 
@@ -1534,6 +1570,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();
 }
 
@@ -1674,15 +1722,13 @@ async function runMigrate() {
       `    context-vault migrate --to-local   Download hosted vault to local files`,
     );
     console.log(`\n  Options:`);
-    console.log(
-      `    --url <url>      Hosted server URL (default: https://api.context-vault.com)`,
-    );
+    console.log(`    --url <url>      Hosted server URL (default: ${API_URL})`);
     console.log(`    --key <key>      API key (cv_...)`);
     console.log();
     return;
   }
 
-  const hostedUrl = getFlag("--url") || "https://api.context-vault.com";
+  const hostedUrl = getFlag("--url") || API_URL;
   const apiKey = getFlag("--key");
 
   if (!apiKey) {
@@ -2099,6 +2145,37 @@ 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 {}
+  }
+}
+
 /** Returns the path to Claude Code's global settings.json */
 function claudeSettingsPath() {
   return join(HOME, ".claude", "settings.json");
@@ -2146,6 +2223,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.
@@ -2203,6 +2350,44 @@ async function runHooks() {
       process.exit(1);
     }
     console.log();
+
+    // Prompt for optional session auto-flush (SessionEnd) hook
+    const installFlush =
+      flags.has("--flush") ||
+      (await prompt(
+        "  Install session auto-flush hook? (runs context-vault flush at session end) (y/N):",
+        "n",
+      ));
+    const shouldInstallFlush =
+      installFlush === true ||
+      (typeof installFlush === "string" &&
+        installFlush.toLowerCase().startsWith("y"));
+
+    if (shouldInstallFlush) {
+      try {
+        const flushInstalled = installSessionEndHook();
+        if (flushInstalled) {
+          console.log(
+            `\n  ${green("✓")} Session auto-flush hook installed (SessionEnd).\n`,
+          );
+          console.log(
+            dim(
+              "  At the end of each session, context-vault flush confirms the vault is healthy.",
+            ),
+          );
+        } else {
+          console.log(
+            `\n  ${yellow("!")} Session auto-flush hook already installed.\n`,
+          );
+        }
+      } catch (e) {
+        console.error(
+          `\n  ${red("x")} Failed to install session flush hook: ${e.message}\n`,
+        );
+        process.exit(1);
+      }
+      console.log();
+    }
   } else if (sub === "remove") {
     try {
       const removed = removeClaudeHook();
@@ -2215,6 +2400,19 @@ async function runHooks() {
       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("✓")} Session auto-flush hook removed (SessionEnd).\n`,
+        );
+      }
+    } catch (e) {
+      console.error(
+        `\n  ${red("x")} Failed to remove session flush hook: ${e.message}\n`,
+      );
+    }
   } else {
     console.log(`
   ${bold("context-vault hooks")} <install|remove>
@@ -2225,11 +2423,204 @@ async function runHooks() {
 
 ${bold("Commands:")}
   ${cyan("hooks install")}   Write UserPromptSubmit hook to ~/.claude/settings.json
-  ${cyan("hooks remove")}    Remove the hook from ~/.claude/settings.json
+                  Also prompts to install a SessionEnd auto-flush hook
+  ${cyan("hooks remove")}    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");
 }
@@ -2261,6 +2652,9 @@ async function main() {
     case "hooks":
       await runHooks();
       break;
+    case "flush":
+      await runFlush();
+      break;
     case "recall":
       await runRecall();
       break;
@@ -2291,6 +2685,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.11.0",
+  "version": "2.13.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/constants.js

@@ -1,3 +1,9 @@
+export const APP_URL = "https://app.context-vault.com";
+export const API_URL = "https://api.context-vault.com";
+export const MARKETING_URL = "https://contextvault.dev";
+export const GITHUB_ISSUES_URL =
+  "https://github.com/fellanH/context-vault/issues";
+
 export const MAX_BODY_LENGTH = 100 * 1024; // 100KB
 export const MAX_TITLE_LENGTH = 500;
 export const MAX_KIND_LENGTH = 64;

package/node_modules/@context-vault/core/src/core/telemetry.js

@@ -1,8 +1,10 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { API_URL, MARKETING_URL, GITHUB_ISSUES_URL } from "../constants.js";
 
-const TELEMETRY_ENDPOINT = "https://api.context-vault.com/telemetry";
+const TELEMETRY_ENDPOINT = `${API_URL}/telemetry`;
 const NOTICE_MARKER = ".telemetry-notice-shown";
+const FEEDBACK_PROMPT_MARKER = ".feedback-prompt-shown";
 
 export function isTelemetryEnabled(config) {
   const envVal = process.env.CONTEXT_VAULT_TELEMETRY;
@@ -56,7 +58,31 @@ export function maybeShowTelemetryNotice(dataDir) {
     "[context-vault] Reports contain only: event type, error code, tool name, version, node version, platform, arch, timestamp.",
     "[context-vault] No vault content, file paths, or personal data is ever sent.",
     '[context-vault] Opt in: set "telemetry": true in ~/.context-mcp/config.json or set CONTEXT_VAULT_TELEMETRY=1.',
-    "[context-vault] Full payload schema: https://contextvault.dev/telemetry",
+    `[context-vault] Full payload schema: ${MARKETING_URL}/telemetry`,
+  ];
+  for (const line of lines) {
+    process.stderr.write(line + "\n");
+  }
+}
+
+/**
+ * Print a one-time feedback prompt after the user's first successful save.
+ * Uses a marker file in dataDir to ensure it's only shown once.
+ * Never throws, never blocks.
+ */
+export function maybeShowFeedbackPrompt(dataDir) {
+  try {
+    const markerPath = join(dataDir, FEEDBACK_PROMPT_MARKER);
+    if (existsSync(markerPath)) return;
+    writeFileSync(markerPath, new Date().toISOString() + "\n");
+  } catch {
+    return;
+  }
+
+  const lines = [
+    "[context-vault] First entry saved — nice work!",
+    "[context-vault] Got feedback, a bug, or a feature request?",
+    `[context-vault] Open an issue: ${GITHUB_ISSUES_URL}`,
   ];
   for (const line of lines) {
     process.stderr.write(line + "\n");

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/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/save-context.js

@@ -4,6 +4,7 @@ import { indexEntry } from "../../index/index.js";
 import { categoryFor } from "../../core/categories.js";
 import { normalizeKind } from "../../core/files.js";
 import { ok, err, ensureVaultExists, ensureValidKind } from "../helpers.js";
+import { maybeShowFeedbackPrompt } from "../../core/telemetry.js";
 import {
   MAX_BODY_LENGTH,
   MAX_TITLE_LENGTH,
@@ -398,6 +399,11 @@ export async function handler(
     supersedes,
     userId,
   });
+
+  if (ctx.config?.dataDir) {
+    maybeShowFeedbackPrompt(ctx.config.dataDir);
+  }
+
   const relPath = entry.filePath
     ? entry.filePath.replace(config.vaultDir + "/", "")
     : entry.filePath;

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

@@ -11,6 +11,7 @@ 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";
 
 const toolModules = [
   getContext,
@@ -20,6 +21,7 @@ const toolModules = [
   submitFeedback,
   ingestUrl,
   contextStatus,
+  clearContext,
 ];
 
 const TOOL_TIMEOUT_MS = 60_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -55,7 +55,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^2.11.0",
+    "@context-vault/core": "^2.13.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);