context-vault 2.10.2 → 2.11.0

package/bin/cli.js

@@ -234,7 +234,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
@@ -359,7 +362,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 +430,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 +487,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: https://contextvault.dev/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 +527,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,7 +539,7 @@ 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)\n"));
     {
@@ -592,7 +628,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 +651,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 +701,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
@@ -1308,6 +1385,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");
@@ -1900,6 +2040,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 +2258,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 +2276,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,31 +1,22 @@
 {
   "name": "@context-vault/core",
-  "version": "2.10.2",
+  "version": "2.11.0",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./constants": "./src/constants.js",
     "./capture": "./src/capture/index.js",
-    "./capture/formatters": "./src/capture/formatters.js",
-    "./capture/file-ops": "./src/capture/file-ops.js",
-    "./index/db": "./src/index/db.js",
-    "./index/embed": "./src/index/embed.js",
+    "./capture/*": "./src/capture/*.js",
     "./index": "./src/index/index.js",
+    "./index/*": "./src/index/*.js",
     "./retrieve": "./src/retrieve/index.js",
-    "./server/tools": "./src/server/tools.js",
-    "./server/helpers": "./src/server/helpers.js",
-    "./core/categories": "./src/core/categories.js",
-    "./core/config": "./src/core/config.js",
-    "./core/files": "./src/core/files.js",
-    "./core/frontmatter": "./src/core/frontmatter.js",
-    "./core/error-log": "./src/core/error-log.js",
-    "./core/status": "./src/core/status.js",
-    "./capture/importers": "./src/capture/importers.js",
-    "./capture/import-pipeline": "./src/capture/import-pipeline.js",
-    "./capture/ingest-url": "./src/capture/ingest-url.js",
+    "./retrieve/*": "./src/retrieve/*.js",
     "./sync": "./src/sync/sync.js",
-    "./constants": "./src/constants.js"
+    "./sync/*": "./src/sync/*.js",
+    "./core/*": "./src/core/*.js",
+    "./server/*": "./src/server/*.js"
   },
   "files": [
     "src/"

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

package/node_modules/@context-vault/core/src/capture/index.js

@@ -26,6 +26,7 @@ export function writeEntry(
     folder,
     identity_key,
     expires_at,
+    supersedes,
     userId,
   },
 ) {
@@ -47,6 +48,7 @@ export function writeEntry(
   // Entity upsert: check for existing file at deterministic path
   let id;
   let createdAt;
+  let updatedAt;
   if (category === "entity" && identity_key) {
     const identitySlug = slugify(identity_key);
     const dir = resolve(ctx.config.vaultDir, kindToPath(kind));
@@ -58,13 +60,16 @@ export function writeEntry(
       const { meta: fmMeta } = parseFrontmatter(raw);
       id = fmMeta.id || ulid();
       createdAt = fmMeta.created || new Date().toISOString();
+      updatedAt = new Date().toISOString();
     } else {
       id = ulid();
       createdAt = new Date().toISOString();
+      updatedAt = createdAt;
     }
   } else {
     id = ulid();
     createdAt = new Date().toISOString();
+    updatedAt = createdAt;
   }
 
   const filePath = writeEntryFile(ctx.config.vaultDir, kind, {
@@ -75,10 +80,12 @@ export function writeEntry(
     tags,
     source,
     createdAt,
+    updatedAt,
     folder,
     category,
     identity_key,
     expires_at,
+    supersedes,
   });
 
   return {
@@ -92,8 +99,10 @@ export function writeEntry(
     tags,
     source,
     createdAt,
+    updatedAt,
     identity_key,
     expires_at,
+    supersedes,
     userId: userId || null,
   };
 }
@@ -121,6 +130,10 @@ export function updateEntryFile(ctx, existing, updates) {
     updates.source !== undefined ? updates.source : existing.source;
   const expires_at =
     updates.expires_at !== undefined ? updates.expires_at : existing.expires_at;
+  const supersedes =
+    updates.supersedes !== undefined
+      ? updates.supersedes
+      : fmMeta.supersedes || null;
 
   let mergedMeta;
   if (updates.meta !== undefined) {
@@ -130,6 +143,7 @@ export function updateEntryFile(ctx, existing, updates) {
   }
 
   // Build frontmatter
+  const now = new Date().toISOString();
   const fmFields = { id: existing.id };
   for (const [k, v] of Object.entries(mergedMeta)) {
     if (k === "folder") continue;
@@ -137,9 +151,11 @@ export function updateEntryFile(ctx, existing, updates) {
   }
   if (existing.identity_key) fmFields.identity_key = existing.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 = fmMeta.created || existing.created_at;
+  if (now !== fmFields.created) fmFields.updated = now;
 
   const mdBody = formatBody(existing.kind, { title, body, meta: mergedMeta });
   const md = formatFrontmatter(fmFields) + mdBody;
@@ -159,8 +175,10 @@ export function updateEntryFile(ctx, existing, updates) {
     tags,
     source,
     createdAt: fmMeta.created || existing.created_at,
+    updatedAt: now,
     identity_key: existing.identity_key,
     expires_at,
+    supersedes,
     userId: existing.user_id || null,
   };
 }
@@ -180,6 +198,14 @@ export async function captureAndIndex(ctx, data) {
   const entry = writeEntry(ctx, data);
   try {
     await indexEntry(ctx, entry);
+    // Apply supersedes: mark referenced entries as superseded by this entry
+    if (entry.supersedes?.length && ctx.stmts.updateSupersededBy) {
+      for (const supersededId of entry.supersedes) {
+        if (typeof supersededId === "string" && supersededId.trim()) {
+          ctx.stmts.updateSupersededBy.run(entry.id, supersededId.trim());
+        }
+      }
+    }
     return entry;
   } catch (err) {
     // Rollback: restore previous content for entity upserts, delete for new entries

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

@@ -6,3 +6,10 @@ export const MAX_TAGS_COUNT = 20;
 export const MAX_META_LENGTH = 10 * 1024; // 10KB
 export const MAX_SOURCE_LENGTH = 200;
 export const MAX_IDENTITY_KEY_LENGTH = 200;
+
+export const DEFAULT_GROWTH_THRESHOLDS = {
+  totalEntries: { warn: 1000, critical: 5000 },
+  eventEntries: { warn: 500, critical: 2000 },
+  vaultSizeBytes: { warn: 50 * 1024 * 1024, critical: 200 * 1024 * 1024 },
+  eventsWithoutTtl: { warn: 200 },
+};

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

@@ -40,6 +40,17 @@ const CATEGORY_DIR_NAMES = {
 /** Set of valid category directory names (for reindex discovery) */
 export const CATEGORY_DIRS = new Set(Object.values(CATEGORY_DIR_NAMES));
 
+/**
+ * Staleness thresholds (in days) per knowledge kind.
+ * Kinds not listed here are considered enduring (no staleness threshold).
+ * Based on updated_at; falls back to created_at if updated_at is null.
+ */
+export const KIND_STALENESS_DAYS = {
+  pattern: 180,
+  decision: 365,
+  reference: 90,
+};
+
 export function categoryFor(kind) {
   return KIND_CATEGORY[kind] || "knowledge";
 }