context-vault 2.10.3 → 2.12.0

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);
@@ -234,7 +235,10 @@ ${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("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("update")}                Check for and install updates
   ${cyan("uninstall")}             Remove MCP configs and optionally data
@@ -269,9 +273,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)")}`);
@@ -351,6 +385,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;
     }
@@ -359,7 +394,7 @@ async function runSetup() {
   }
 
   // Detect tools
-  console.log(dim(`  [1/5]`) + bold(" Detecting tools...\n"));
+  console.log(dim(`  [1/6]`) + bold(" Detecting tools...\n"));
   const { detected, results: detectionResults } = await detectAllTools();
   printDetectionResults(detectionResults);
   console.log();
@@ -427,7 +462,7 @@ async function runSetup() {
   }
 
   // Vault directory (content files)
-  console.log(dim(`  [2/5]`) + bold(" Configuring vault...\n"));
+  console.log(dim(`  [2/6]`) + bold(" Configuring vault...\n"));
   const defaultVaultDir = getFlag("--vault-dir") || join(HOME, "vault");
   const vaultDir = isNonInteractive
     ? defaultVaultDir
@@ -484,6 +519,39 @@ async function runSetup() {
   vaultConfig.dbPath = join(dataDir, "vault.db");
   vaultConfig.devDir = join(HOME, "dev");
   vaultConfig.mode = "local";
+
+  // Telemetry opt-in
+  console.log(`\n  ${dim("[3/6]")}${bold(" Anonymous error reporting\n")}`);
+  console.log(
+    dim(
+      "  When enabled, unhandled errors send a minimal event (type, tool name,",
+    ),
+  );
+  console.log(
+    dim("  version, platform) to help diagnose issues. No vault content,"),
+  );
+  console.log(
+    dim("  file paths, or personal data is ever sent. Off by default."),
+  );
+  console.log(dim(`  Full schema: ${MARKETING_URL}/telemetry`));
+  console.log();
+
+  let telemetryEnabled = vaultConfig.telemetry === true;
+  if (!isNonInteractive) {
+    const defaultChoice = telemetryEnabled ? "Y" : "n";
+    const telemetryAnswer = await prompt(
+      `  Enable anonymous error reporting? (y/N):`,
+      defaultChoice,
+    );
+    telemetryEnabled =
+      telemetryAnswer.toLowerCase() === "y" ||
+      telemetryAnswer.toLowerCase() === "yes";
+  }
+  vaultConfig.telemetry = telemetryEnabled;
+  console.log(
+    `  ${telemetryEnabled ? green("+") : dim("-")} Telemetry: ${telemetryEnabled ? "enabled" : "disabled"}`,
+  );
+
   writeFileSync(configPath, JSON.stringify(vaultConfig, null, 2) + "\n");
   console.log(`\n  ${green("+")} Wrote ${configPath}`);
 
@@ -491,7 +559,7 @@ async function runSetup() {
   const skipEmbeddings = flags.has("--skip-embeddings");
   if (skipEmbeddings) {
     console.log(
-      `\n  ${dim("[3/5]")}${bold(" Embedding model")} ${dim("(skipped)")}`,
+      `\n  ${dim("[4/6]")}${bold(" Embedding model")} ${dim("(skipped)")}`,
     );
     console.log(
       dim(
@@ -503,9 +571,14 @@ async function runSetup() {
     );
   } else {
     console.log(
-      `\n  ${dim("[3/5]")}${bold(" Downloading embedding model...")}`,
+      `\n  ${dim("[4/6]")}${bold(" Downloading embedding model...")}`,
+    );
+    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`,
+      ),
     );
-    console.log(dim("  all-MiniLM-L6-v2 (~22MB, one-time download)\n"));
     {
       const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
       let frame = 0;
@@ -592,7 +665,7 @@ async function runSetup() {
   }
 
   // Configure each tool — pass vault dir as arg if non-default
-  console.log(`\n  ${dim("[4/5]")}${bold(" Configuring tools...\n")}`);
+  console.log(`\n  ${dim("[5/6]")}${bold(" Configuring tools...\n")}`);
   const results = [];
   const defaultVDir = join(HOME, "vault");
   const customVaultDir =
@@ -615,6 +688,47 @@ async function runSetup() {
     }
   }
 
+  // Claude Code memory hook (opt-in)
+  const claudeConfigured = results.some(
+    (r) => r.ok && r.tool.id === "claude-code",
+  );
+  const hookFlag = flags.has("--hooks");
+  if (claudeConfigured) {
+    let installHook = hookFlag;
+    if (!hookFlag && !isNonInteractive) {
+      console.log();
+      console.log(dim("  Claude Code detected — install memory hook?"));
+      console.log(
+        dim(
+          "  Searches your vault on every prompt and injects relevant entries",
+        ),
+      );
+      console.log(
+        dim("  as additional context alongside Claude's native memory."),
+      );
+      console.log();
+      const answer = await prompt(
+        "  Install Claude Code memory hook? (y/N):",
+        "N",
+      );
+      installHook = answer.toLowerCase() === "y";
+    }
+    if (installHook) {
+      try {
+        const installed = installClaudeHook();
+        if (installed) {
+          console.log(`\n  ${green("+")} Memory hook installed`);
+        }
+      } catch (e) {
+        console.log(`\n  ${red("x")} Hook install failed: ${e.message}`);
+      }
+    } else if (!isNonInteractive && !hookFlag) {
+      console.log(
+        dim(`  Skipped — install later: context-vault hooks install`),
+      );
+    }
+  }
+
   // Seed entry
   const seeded = createSeedEntries(resolvedVaultDir);
   if (seeded > 0) {
@@ -624,7 +738,7 @@ async function runSetup() {
   }
 
   // Health check
-  console.log(`\n  ${dim("[5/5]")}${bold(" Health check...")}\n`);
+  console.log(`\n  ${dim("[6/6]")}${bold(" Health check...")}\n`);
   const okResults = results.filter((r) => r.ok);
 
   // Verify DB is accessible
@@ -654,7 +768,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"`,
@@ -902,7 +1018,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`);
@@ -911,9 +1027,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;
   }
@@ -1155,9 +1269,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;
   }
 
@@ -1214,10 +1326,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) {
@@ -1308,6 +1417,69 @@ async function runReindex() {
   console.log(`  ${dim("·")} ${stats.unchanged} unchanged`);
 }
 
+async function runPrune() {
+  const dryRun = flags.has("--dry-run");
+
+  const { resolveConfig } = await import("@context-vault/core/core/config");
+  const { initDatabase, prepareStatements, insertVec, deleteVec } =
+    await import("@context-vault/core/index/db");
+  const { pruneExpired } = await import("@context-vault/core/index");
+
+  const config = resolveConfig();
+  if (!config.vaultDirExists) {
+    console.error(red(`Vault directory not found: ${config.vaultDir}`));
+    console.error("Run " + cyan("context-vault setup") + " to configure.");
+    process.exit(1);
+  }
+
+  const db = await initDatabase(config.dbPath);
+
+  if (dryRun) {
+    const expired = db
+      .prepare(
+        "SELECT id, kind, title, expires_at FROM vault WHERE expires_at IS NOT NULL AND expires_at <= datetime('now')",
+      )
+      .all();
+    db.close();
+
+    if (expired.length === 0) {
+      console.log(green("  No expired entries found."));
+      return;
+    }
+
+    console.log(
+      `\n  ${bold(String(expired.length))} expired ${expired.length === 1 ? "entry" : "entries"} would be removed:\n`,
+    );
+    for (const e of expired) {
+      const label = e.title ? `${e.kind}: ${e.title}` : `${e.kind} (${e.id})`;
+      console.log(`  ${dim("-")} ${label} ${dim(`(expired ${e.expires_at})`)}`);
+    }
+    console.log(dim("\n  Dry run — no entries were removed."));
+    return;
+  }
+
+  const stmts = prepareStatements(db);
+  const ctx = {
+    db,
+    config,
+    stmts,
+    embed: async () => null,
+    insertVec: (r, e) => insertVec(stmts, r, e),
+    deleteVec: (r) => deleteVec(stmts, r),
+  };
+
+  const count = await pruneExpired(ctx);
+  db.close();
+
+  if (count === 0) {
+    console.log(green("  No expired entries found."));
+  } else {
+    console.log(
+      green(`  ✓ Pruned ${count} expired ${count === 1 ? "entry" : "entries"}`),
+    );
+  }
+}
+
 async function runStatus() {
   const { resolveConfig } = await import("@context-vault/core/core/config");
   const { initDatabase } = await import("@context-vault/core/index/db");
@@ -1534,15 +1706,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) {
@@ -1900,6 +2070,196 @@ async function runIngest() {
   console.log();
 }
 
+async function runRecall() {
+  let query;
+
+  if (!process.stdin.isTTY) {
+    const raw = await new Promise((resolve) => {
+      let data = "";
+      process.stdin.on("data", (chunk) => (data += chunk));
+      process.stdin.on("end", () => resolve(data));
+    });
+    try {
+      const payload = JSON.parse(raw);
+      query = payload.prompt || payload.query || "";
+    } catch {
+      query = args[1] || raw.trim();
+    }
+  } else {
+    query = args.slice(1).join(" ");
+  }
+
+  if (!query?.trim()) return;
+
+  let db;
+  try {
+    const { resolveConfig } = await import("@context-vault/core/core/config");
+    const config = resolveConfig();
+
+    if (!config.vaultDirExists) return;
+
+    const { initDatabase, prepareStatements } =
+      await import("@context-vault/core/index/db");
+    const { embed } = await import("@context-vault/core/index/embed");
+    const { hybridSearch } = await import("@context-vault/core/retrieve/index");
+
+    db = await initDatabase(config.dbPath);
+    const stmts = prepareStatements(db);
+    const ctx = { db, config, stmts, embed };
+
+    const results = await hybridSearch(ctx, query, { limit: 5 });
+    if (!results.length) return;
+
+    const lines = ["## Context Vault\n"];
+    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("");
+    }
+
+    process.stdout.write(lines.join("\n"));
+  } catch {
+    // fail silently — never interrupt the user's workflow
+  } finally {
+    try {
+      db?.close();
+    } catch {}
+  }
+}
+
+/** Returns the path to Claude Code's global settings.json */
+function claudeSettingsPath() {
+  return join(HOME, ".claude", "settings.json");
+}
+
+/**
+ * Writes a UserPromptSubmit hook entry for context-vault recall to ~/.claude/settings.json.
+ * Returns true if installed, false if already present.
+ */
+function installClaudeHook() {
+  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.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  const alreadyInstalled = settings.hooks.UserPromptSubmit.some((h) =>
+    h.hooks?.some((hh) => hh.command?.includes("context-vault recall")),
+  );
+  if (alreadyInstalled) return false;
+
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [
+      {
+        type: "command",
+        command: "context-vault recall",
+        timeout: 10,
+      },
+    ],
+  });
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  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.
+ */
+function removeClaudeHook() {
+  const settingsPath = claudeSettingsPath();
+  if (!existsSync(settingsPath)) return false;
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return false;
+  }
+
+  if (!settings.hooks?.UserPromptSubmit) return false;
+
+  const before = settings.hooks.UserPromptSubmit.length;
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+    (h) => !h.hooks?.some((hh) => hh.command?.includes("context-vault recall")),
+  );
+
+  if (settings.hooks.UserPromptSubmit.length === before) return false;
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return true;
+}
+
+async function runHooks() {
+  const sub = args[1];
+
+  if (sub === "install") {
+    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")}`),
+        );
+      } 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();
+  } else if (sub === "remove") {
+    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);
+    }
+  } else {
+    console.log(`
+  ${bold("context-vault hooks")} <install|remove>
+
+  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.
+
+${bold("Commands:")}
+  ${cyan("hooks install")}   Write UserPromptSubmit hook to ~/.claude/settings.json
+  ${cyan("hooks remove")}    Remove the hook from ~/.claude/settings.json
+`);
+  }
+}
+
 async function runServe() {
   await import("../src/server/index.js");
 }
@@ -1928,6 +2288,12 @@ async function main() {
     case "serve":
       await runServe();
       break;
+    case "hooks":
+      await runHooks();
+      break;
+    case "recall":
+      await runRecall();
+      break;
     case "import":
       await runImport();
       break;
@@ -1940,6 +2306,9 @@ async function main() {
     case "reindex":
       await runReindex();
       break;
+    case "prune":
+      await runPrune();
+      break;
     case "status":
       await runStatus();
       break;

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

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.10.3",
+  "version": "2.12.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/capture/file-ops.js

@@ -32,10 +32,12 @@ export function writeEntryFile(
     tags,
     source,
     createdAt,
+    updatedAt,
     folder,
     category,
     identity_key,
     expires_at,
+    supersedes,
   },
 ) {
   // P5: folder is now a top-level param; also accept from meta for backward compat
@@ -61,9 +63,11 @@ export function writeEntryFile(
 
   if (identity_key) fmFields.identity_key = identity_key;
   if (expires_at) fmFields.expires_at = expires_at;
+  if (supersedes?.length) fmFields.supersedes = supersedes;
   fmFields.tags = tags || [];
   fmFields.source = source || "claude-code";
   fmFields.created = created;
+  if (updatedAt && updatedAt !== created) fmFields.updated = updatedAt;
 
   const mdBody = formatBody(kind, { title, body, meta });