context-vault 3.6.0 → 3.8.0

package/bin/cli.js

@@ -301,12 +301,24 @@ const TOOLS = [
   {
     id: 'antigravity',
     name: 'Antigravity (Gemini CLI)',
-    detect: () => anyDirExists(join(HOME, '.gemini', 'antigravity'), join(HOME, '.gemini')),
+    detect: async () =>
+      anyDirExists(join(HOME, '.gemini', 'antigravity'), join(HOME, '.gemini')) ||
+      (await commandExistsAsync('gemini')),
     configType: 'json',
     configPath: join(HOME, '.gemini', 'antigravity', 'mcp_config.json'),
     configKey: 'mcpServers',
-    rulesPath: null,
-    rulesMethod: null,
+    rulesPath: join(HOME, '.gemini', 'antigravity', 'rules', 'context-vault.md'),
+    rulesMethod: 'write',
+  },
+  {
+    id: 'google-ai',
+    name: 'Google AI / Gemini CLI',
+    detect: () => existsSync(join(HOME, '.gemini', 'mcp_config.json')),
+    configType: 'json',
+    configPath: join(HOME, '.gemini', 'mcp_config.json'),
+    configKey: 'mcpServers',
+    rulesPath: join(HOME, '.gemini', 'rules', 'context-vault.md'),
+    rulesMethod: 'write',
   },
   {
     id: 'cline',
@@ -396,10 +408,12 @@ ${bold('Commands:')}
   ${cyan('ingest')} <url>               Fetch URL and save as vault entry
   ${cyan('ingest-project')} <path>      Scan project directory and register as project entity
   ${cyan('reindex')}                    Rebuild search index from knowledge files
+  ${cyan('sync')} [dir]                  Index .context/ files into vault DB (use --dry-run to preview)
   ${cyan('migrate-dirs')} [--dry-run]   Rename plural vault dirs to singular (post-2.18.0)
   ${cyan('archive')}                    Archive old ephemeral/event entries (use --dry-run to preview)
   ${cyan('restore')} <id>               Restore an archived entry back into the vault
   ${cyan('prune')}                      Remove expired entries (use --dry-run to preview)
+  ${cyan('stats')} recall|co-retrieval  Measure recall ratio and co-retrieval graph
   ${cyan('update')}                     Check for and install updates
   ${cyan('uninstall')}                  Remove MCP configs and optionally data
 `);
@@ -428,6 +442,9 @@ ${bold('Commands:')}
   --force               Overwrite existing config without confirmation
   --skip-embeddings     Skip embedding model download (FTS-only mode)
   --dry-run             Show what setup would do without writing anything
+  --upgrade             Upgrade installed agent rules to the latest bundled version
+  --no-rules            Skip agent rules installation during setup
+  --no-hooks            Skip recall/error hook installation during setup
 `);
 }
 
@@ -445,6 +462,106 @@ async function runSetup() {
   }
   console.log();
 
+  // --upgrade: only upgrade agent rules, then exit
+  if (flags.has('--upgrade')) {
+    console.log(dim('  Checking agent rules for updates...\n'));
+    const bundled = loadAgentRules();
+    if (!bundled) {
+      console.log(`  ${yellow('!')} Agent rules file not found in package.\n`);
+      return;
+    }
+    const bundledVersion = extractRulesVersion(bundled);
+
+    // Check all known tool paths (not just detected tools, since a tool may have been
+    // uninstalled but its rules file still exists)
+    const allToolsWithRules = TOOLS.filter((t) => t.rulesPath);
+    let found = 0;
+    let upgraded = 0;
+    const upgradeable = [];
+
+    for (const tool of allToolsWithRules) {
+      const installed = getInstalledRulesForTool(tool);
+      if (!installed) continue;
+      found++;
+
+      const installedVersion = extractRulesVersion(installed);
+      if (installed.trim() === bundled.trim()) {
+        console.log(`  ${green('✓')} ${tool.name}: up to date${bundledVersion ? ` (v${bundledVersion})` : ''}`);
+        continue;
+      }
+
+      upgradeable.push({ tool, installed, installedVersion });
+      console.log(
+        `  ${yellow('!')} ${tool.name}: ${installedVersion ? `v${installedVersion}` : 'unknown version'} → ${bundledVersion ? `v${bundledVersion}` : 'bundled'}`
+      );
+
+      // Show a compact diff
+      const installedLines = installed.split('\n');
+      const bundledLines = bundled.split('\n');
+      const maxLines = Math.max(installedLines.length, bundledLines.length);
+      let diffLines = 0;
+      for (let i = 0; i < maxLines; i++) {
+        const a = installedLines[i];
+        const b = bundledLines[i];
+        if (a === b) continue;
+        if (diffLines === 0) console.log();
+        if (diffLines >= 20) {
+          console.log(dim(`    ... and more changes`));
+          break;
+        }
+        if (a === undefined) {
+          console.log(`    ${green('+')} ${b}`);
+        } else if (b === undefined) {
+          console.log(`    ${red('-')} ${a}`);
+        } else {
+          console.log(`    ${red('-')} ${a}`);
+          console.log(`    ${green('+')} ${b}`);
+        }
+        diffLines++;
+      }
+      console.log();
+    }
+
+    if (found === 0) {
+      console.log(`  ${yellow('!')} No installed rules found. Run ${cyan('context-vault rules install')} first.\n`);
+      return;
+    }
+
+    if (upgradeable.length === 0) {
+      console.log(`\n  ${green('✓')} All rules are up to date.\n`);
+      return;
+    }
+
+    if (!isDryRun) {
+      const answer = isNonInteractive
+        ? 'Y'
+        : await prompt(`  Upgrade ${upgradeable.length} rules file(s)? (Y/n):`, 'Y');
+      if (answer.toLowerCase() === 'n') {
+        console.log(dim('  Skipped.\n'));
+        return;
+      }
+
+      for (const { tool } of upgradeable) {
+        try {
+          installAgentRulesForTool(tool, bundled);
+          console.log(`  ${green('+')} ${tool.name} — upgraded`);
+          upgraded++;
+        } catch (e) {
+          console.log(`  ${red('x')} ${tool.name} — ${e.message}`);
+        }
+      }
+    } else {
+      console.log(dim(`  [dry-run] Would upgrade ${upgradeable.length} rules file(s).`));
+    }
+
+    console.log();
+    if (upgraded > 0) {
+      console.log(dim('  Restart your AI tools to apply the updated rules.'));
+      console.log();
+    }
+    return;
+  }
+
   // Check for existing installation
   const existingConfig = join(HOME, '.context-mcp', 'config.json');
   if (existsSync(existingConfig) && !isNonInteractive && !isDryRun) {
@@ -653,6 +770,7 @@ async function runSetup() {
     if (userLevel === 'beginner') {
       console.log('  Install an AI tool first:');
       console.log(dim('    Claude Code:  https://docs.anthropic.com/en/docs/claude-code'));
+      console.log(dim('    Gemini CLI:   https://github.com/google-gemini/gemini-cli'));
       console.log(dim('    Cursor:       https://cursor.com'));
       console.log(dim('    Windsurf:     https://codeium.com/windsurf'));
       console.log();
@@ -1032,7 +1150,7 @@ async function runSetup() {
 
   if (claudeConfigured) {
     if (isDryRun) {
-      console.log(`  ${yellow('[dry-run]')} Would install Claude Code hooks (memory recall, session capture, auto-capture)`);
+      console.log(`  ${yellow('[dry-run]')} Would install Claude Code hooks (memory recall, session capture, auto-capture, vault recall, error recall)`);
       console.log(`  ${yellow('[dry-run]')} Would install Claude Code skills (compile-context, vault-setup)`);
     } else {
       // Bundled hooks prompt: one Y/n for all three hooks
@@ -1063,6 +1181,20 @@ async function runSetup() {
         } catch (e) {
           console.log(`  ${red('x')} Auto-capture hook failed: ${e.message}`);
         }
+        if (!flags.has('--no-hooks')) {
+          try {
+            const recallInstalled = installRecallHook();
+            if (recallInstalled) console.log(`  ${green('+')} Vault recall hook installed`);
+          } catch (e) {
+            console.log(`  ${red('x')} Recall hook failed: ${e.message}`);
+          }
+          try {
+            const errorInstalled = installErrorHook();
+            if (errorInstalled) console.log(`  ${green('+')} Vault error hook installed`);
+          } catch (e) {
+            console.log(`  ${red('x')} Error hook failed: ${e.message}`);
+          }
+        }
       } else {
         console.log(dim(`  Hooks skipped. Install later: context-vault hooks install`));
       }
@@ -2040,6 +2172,269 @@ async function runReindex() {
   }
 }
 
+async function runSync() {
+  const dryRun = flags.has('--dry-run');
+  const positional = args.slice(1).find((a) => !a.startsWith('--'));
+  const scanDir = positional ? resolve(positional) : process.cwd();
+
+  const contextDir = join(scanDir, '.context');
+  if (!existsSync(contextDir)) {
+    console.error(red(`No .context/ directory found in ${scanDir}`));
+    console.error(dim('The .context/ directory is created automatically when save_context is called from a workspace.'));
+    process.exit(1);
+  }
+
+  console.log(dim(dryRun ? 'Scanning .context/ (dry run)...' : 'Syncing .context/ to vault...'));
+
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase, prepareStatements, insertVec, deleteVec } =
+    await import('@context-vault/core/db');
+  const { embed } = await import('@context-vault/core/embed');
+  const { parseFrontmatter, parseEntryFromMarkdown } = await import('@context-vault/core/frontmatter');
+  const { categoryFor, defaultTierFor } = await import('@context-vault/core/categories');
+  const { dirToKind, walkDir } = await import('@context-vault/core/files');
+  const { shouldIndex } = await import('@context-vault/core/indexing');
+  const { DEFAULT_INDEXING } = await import('@context-vault/core/constants');
+
+  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);
+  const stmts = prepareStatements(db);
+  const ixConfig = config.indexing ?? DEFAULT_INDEXING;
+
+  let synced = 0;
+  let alreadyIndexed = 0;
+  let updated = 0;
+  let errors = 0;
+  let skippedIndexing = 0;
+
+  // Discover kind directories inside .context/
+  let kindDirs;
+  try {
+    kindDirs = readdirSync(contextDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith('.') && !d.name.startsWith('_'));
+  } catch (e) {
+    console.error(red(`Failed to read .context/: ${e.message}`));
+    db.close();
+    process.exit(1);
+  }
+
+  const pendingEmbeds = [];
+
+  if (!dryRun) db.exec('BEGIN');
+  try {
+    for (const kindEntry of kindDirs) {
+      const kind = dirToKind(kindEntry.name);
+      const kindDir = join(contextDir, kindEntry.name);
+      const mdFiles = walkDir(kindDir).filter((f) => f.filePath.endsWith('.md'));
+
+      for (const { filePath, relDir } of mdFiles) {
+        let raw;
+        try {
+          raw = readFileSync(filePath, 'utf-8');
+        } catch (e) {
+          console.error(dim(`  skip: could not read ${filePath}: ${e.message}`));
+          errors++;
+          continue;
+        }
+
+        if (!raw.startsWith('---\n')) {
+          console.error(dim(`  skip (no frontmatter): ${filePath}`));
+          errors++;
+          continue;
+        }
+
+        const { meta: fmMeta, body: rawBody } = parseFrontmatter(raw);
+        const entryId = fmMeta.id;
+        if (!entryId) {
+          console.error(dim(`  skip (no id in frontmatter): ${filePath}`));
+          errors++;
+          continue;
+        }
+
+        const parsed = parseEntryFromMarkdown(kind, rawBody, fmMeta);
+        const category = categoryFor(kind);
+
+        // Check if entry exists in DB
+        const existing = stmts.getEntryById.get(entryId);
+
+        if (existing) {
+          // Check if content differs
+          const bodyChanged = existing.body !== parsed.body;
+          const titleChanged = (parsed.title || null) !== (existing.title || null);
+
+          if (!bodyChanged && !titleChanged) {
+            alreadyIndexed++;
+            continue;
+          }
+
+          if (dryRun) {
+            console.log(`  ${yellow('~')} would update: ${entryId} (${parsed.title || '(untitled)'})`);
+            updated++;
+            continue;
+          }
+
+          // Update existing entry
+          const tagsJson = fmMeta.tags ? JSON.stringify(fmMeta.tags) : null;
+          const meta = { ...(parsed.meta || {}) };
+          if (relDir) meta.folder = relDir;
+          const metaJson = Object.keys(meta).length ? JSON.stringify(meta) : null;
+          const identity_key = fmMeta.identity_key || null;
+          const expires_at = fmMeta.expires_at || null;
+
+          stmts.updateEntry.run(
+            parsed.title || null,
+            parsed.body,
+            metaJson,
+            tagsJson,
+            fmMeta.source || 'file',
+            category,
+            identity_key,
+            expires_at,
+            existing.file_path
+          );
+
+          const entryIndexed = shouldIndex(
+            { kind, category, bodyLength: parsed.body.length },
+            ixConfig
+          );
+
+          if (entryIndexed && category !== 'event') {
+            const rowidResult = stmts.getRowid.get(entryId);
+            if (rowidResult?.rowid) {
+              const embeddingText = [parsed.title, parsed.body].filter(Boolean).join(' ');
+              pendingEmbeds.push({ rowid: rowidResult.rowid, text: embeddingText });
+            }
+          }
+
+          updated++;
+          continue;
+        }
+
+        // Entry not in DB: index it
+        const entryIndexed = shouldIndex(
+          { kind, category, bodyLength: parsed.body.length },
+          ixConfig
+        );
+
+        if (dryRun) {
+          if (entryIndexed) {
+            console.log(`  ${green('+')} would sync: ${entryId} (${parsed.title || '(untitled)'})`);
+            synced++;
+          } else {
+            console.log(`  ${dim('o')} would skip indexing: ${entryId}`);
+            skippedIndexing++;
+          }
+          continue;
+        }
+
+        const tagsJson = fmMeta.tags ? JSON.stringify(fmMeta.tags) : null;
+        const meta = { ...(parsed.meta || {}) };
+        if (relDir) meta.folder = relDir;
+        const metaJson = Object.keys(meta).length ? JSON.stringify(meta) : null;
+        const created = fmMeta.created || new Date().toISOString();
+        const identity_key = fmMeta.identity_key || null;
+        const expires_at = fmMeta.expires_at || null;
+        const effectiveTier = fmMeta.tier || defaultTierFor(kind);
+
+        // The entry should point to the vault file path (if it exists there), else use the .context path
+        const vaultFilePath = existing?.file_path || fmMeta.file_path || filePath;
+
+        try {
+          const upsertEntry = db.prepare(
+            `INSERT OR IGNORE INTO vault (id, kind, category, title, body, meta, tags, source, file_path, identity_key, expires_at, created_at, updated_at, tier, indexed) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+          );
+          const result = upsertEntry.run(
+            entryId,
+            kind,
+            category,
+            parsed.title || null,
+            parsed.body,
+            metaJson,
+            tagsJson,
+            fmMeta.source || 'file',
+            vaultFilePath,
+            identity_key,
+            expires_at,
+            created,
+            fmMeta.updated || created,
+            effectiveTier,
+            entryIndexed ? 1 : 0
+          );
+
+          if (result.changes > 0) {
+            if (entryIndexed && category !== 'event') {
+              const rowidResult = stmts.getRowid.get(entryId);
+              if (rowidResult?.rowid) {
+                const embeddingText = [parsed.title, parsed.body].filter(Boolean).join(' ');
+                pendingEmbeds.push({ rowid: rowidResult.rowid, text: embeddingText });
+              }
+            }
+            if (!entryIndexed) skippedIndexing++;
+            synced++;
+          } else {
+            alreadyIndexed++;
+          }
+        } catch (e) {
+          console.error(dim(`  error indexing ${entryId}: ${e.message}`));
+          errors++;
+        }
+      }
+    }
+
+    // Generate embeddings in batch
+    if (!dryRun && pendingEmbeds.length > 0) {
+      const { embedBatch: batchEmbed } = await import('@context-vault/core/embed');
+      const BATCH_SIZE = 32;
+      for (let i = 0; i < pendingEmbeds.length; i += BATCH_SIZE) {
+        const batch = pendingEmbeds.slice(i, i + BATCH_SIZE);
+        const texts = batch.map((b) => b.text);
+        try {
+          const embeddings = await batchEmbed(texts);
+          for (let j = 0; j < batch.length; j++) {
+            if (embeddings[j]) {
+              try { deleteVec(stmts, batch[j].rowid); } catch {}
+              insertVec(stmts, batch[j].rowid, embeddings[j]);
+            }
+          }
+        } catch (e) {
+          console.warn(dim(`  embedding batch failed: ${e.message}`));
+        }
+      }
+    }
+
+    if (!dryRun) db.exec('COMMIT');
+  } catch (e) {
+    if (!dryRun) {
+      try { db.exec('ROLLBACK'); } catch {}
+    }
+    throw e;
+  }
+
+  db.close();
+
+  if (dryRun) {
+    console.log(yellow('Dry run results (no changes made):'));
+    console.log(`  Would sync:     ${synced}`);
+    console.log(`  Would update:   ${updated}`);
+    console.log(`  Already indexed: ${alreadyIndexed}`);
+    if (skippedIndexing) console.log(`  Would skip indexing: ${skippedIndexing}`);
+    if (errors) console.log(`  ${red('Errors:')}        ${errors}`);
+  } else {
+    console.log(green('Sync complete'));
+    console.log(`  ${green('+')} ${synced} synced`);
+    if (updated) console.log(`  ${yellow('~')} ${updated} updated`);
+    console.log(`  ${dim('.')} ${alreadyIndexed} already indexed`);
+    if (skippedIndexing) console.log(`  ${dim('o')} ${skippedIndexing} skipped indexing`);
+    if (errors) console.log(`  ${red('!')} ${errors} errors`);
+  }
+}
+
 async function runMigrateDirs() {
   const dryRun = flags.has('--dry-run');
 
@@ -2542,7 +2937,9 @@ async function runUninstall() {
   const captureRemoved = removeSessionCaptureHook();
   const flushRemoved = removeSessionEndHook();
   const autoCaptureRemoved = removePostToolCallHook();
-  if (recallRemoved || captureRemoved || flushRemoved || autoCaptureRemoved) {
+  const recallHookRemoved = removeRecallHook();
+  const errorHookRemoved = removeErrorHook();
+  if (recallRemoved || captureRemoved || flushRemoved || autoCaptureRemoved || recallHookRemoved || errorHookRemoved) {
     console.log(`  ${green('+')} Removed Claude Code hooks`);
   } else {
     console.log(`  ${dim('-')} No Claude Code hooks to remove`);
@@ -4280,6 +4677,35 @@ function loadAgentRules() {
   return readFileSync(rulesPath, 'utf-8');
 }
 
+/**
+ * Extract the version string from a rules file content.
+ * Looks for <!-- context-vault-rules vX.Y --> comment on the first line.
+ * Returns the version string (e.g. "1.0") or null if not found.
+ */
+function extractRulesVersion(content) {
+  if (!content) return null;
+  const match = content.match(/<!--\s*context-vault-rules\s+v([\d.]+)\s*-->/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Get the installed rules content for a tool, handling both write and append methods.
+ * For append-based tools (Windsurf), extracts only the delimited section.
+ * Returns the rules content or null if not installed.
+ */
+function getInstalledRulesForTool(tool) {
+  const rulesPath = tool.rulesPath;
+  if (!rulesPath || !existsSync(rulesPath)) return null;
+  const content = readFileSync(rulesPath, 'utf-8');
+  if (tool.rulesMethod === 'append') {
+    const match = content.match(
+      new RegExp(`${RULES_DELIMITER_START}\\n([\\s\\S]*?)\\n${RULES_DELIMITER_END}`)
+    );
+    return match ? match[1] : null;
+  }
+  return content;
+}
+
 /**
  * Return the path where agent rules are/would be installed for a given tool.
  * Returns null for tools with no rules install path.
@@ -4656,6 +5082,159 @@ function removePostToolCallHook() {
   return true;
 }
 
+/**
+ * Install the vault-recall-hook.mjs into ~/.claude/hooks/ and register it
+ * as a UserPromptSubmit hook in ~/.claude/settings.json.
+ * Returns true if installed, false if already present.
+ */
+function installRecallHook() {
+  const srcPath = join(ROOT, 'assets', 'vault-recall-hook.mjs');
+  if (!existsSync(srcPath)) return false;
+
+  const hooksDir = join(HOME, '.claude', 'hooks');
+  mkdirSync(hooksDir, { recursive: true });
+  const destPath = join(hooksDir, 'vault-recall-hook.mjs');
+  copyFileSync(srcPath, destPath);
+
+  const settingsPath = claudeSettingsPath();
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      const bak = settingsPath + '.bak';
+      copyFileSync(settingsPath, bak);
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  const hookCmd = `node ${destPath}`;
+  const alreadyInstalled = settings.hooks.UserPromptSubmit.some((h) =>
+    h.hooks?.some((hh) => hh.command?.includes('vault-recall-hook'))
+  );
+  if (alreadyInstalled) return false;
+
+  settings.hooks.UserPromptSubmit.push({
+    hooks: [
+      {
+        type: 'command',
+        command: hookCmd,
+        timeout: 5,
+      },
+    ],
+  });
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
+/**
+ * Remove the vault-recall-hook UserPromptSubmit hook from settings.json.
+ * Returns true if removed, false if not found.
+ */
+function removeRecallHook() {
+  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('vault-recall-hook'))
+  );
+
+  if (settings.hooks.UserPromptSubmit.length === before) return false;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
+/**
+ * Install the vault-error-hook.mjs into ~/.claude/hooks/ and register it
+ * as a PostToolUse hook (matcher: Bash) in ~/.claude/settings.json.
+ * Returns true if installed, false if already present.
+ */
+function installErrorHook() {
+  const srcPath = join(ROOT, 'assets', 'vault-error-hook.mjs');
+  if (!existsSync(srcPath)) return false;
+
+  const hooksDir = join(HOME, '.claude', 'hooks');
+  mkdirSync(hooksDir, { recursive: true });
+  const destPath = join(hooksDir, 'vault-error-hook.mjs');
+  copyFileSync(srcPath, destPath);
+
+  const settingsPath = claudeSettingsPath();
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      const bak = settingsPath + '.bak';
+      copyFileSync(settingsPath, bak);
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  const hookCmd = `node ${destPath}`;
+  const alreadyInstalled = settings.hooks.PostToolUse.some((h) =>
+    h.hooks?.some((hh) => hh.command?.includes('vault-error-hook'))
+  );
+  if (alreadyInstalled) return false;
+
+  settings.hooks.PostToolUse.push({
+    matcher: 'Bash',
+    hooks: [
+      {
+        type: 'command',
+        command: hookCmd,
+        timeout: 5,
+      },
+    ],
+  });
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
+/**
+ * Remove the vault-error-hook PostToolUse hook from settings.json.
+ * Returns true if removed, false if not found.
+ */
+function removeErrorHook() {
+  const settingsPath = claudeSettingsPath();
+  if (!existsSync(settingsPath)) return false;
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+
+  if (!settings.hooks?.PostToolUse) return false;
+
+  const before = settings.hooks.PostToolUse.length;
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(
+    (h) => !h.hooks?.some((hh) => hh.command?.includes('vault-error-hook'))
+  );
+
+  if (settings.hooks.PostToolUse.length === before) return false;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
 async function runSkills() {
   const sub = args[1];
 
@@ -4953,6 +5532,25 @@ async function runHooksInstall() {
     }
     console.log();
   }
+
+  // Proactive surfacing hooks (vault recall + error recall)
+  try {
+    const recallInstalled = installRecallHook();
+    if (recallInstalled) {
+      console.log(`  ${green('✓')} Vault recall hook installed (proactive surfacing on prompts)`);
+    }
+  } catch (e) {
+    console.error(`  ${red('x')} Vault recall hook failed: ${e.message}`);
+  }
+  try {
+    const errorInstalled = installErrorHook();
+    if (errorInstalled) {
+      console.log(`  ${green('✓')} Vault error hook installed (surfaces past errors on Bash failures)`);
+    }
+  } catch (e) {
+    console.error(`  ${red('x')} Vault error hook failed: ${e.message}`);
+  }
+  console.log();
 }
 
 async function runHooksUninstall() {
@@ -4994,6 +5592,24 @@ async function runHooksUninstall() {
   } catch (e) {
     console.error(`\n  ${red('x')} Failed to remove auto-capture hook: ${e.message}\n`);
   }
+
+  try {
+    const recallHookRemoved = removeRecallHook();
+    if (recallHookRemoved) {
+      console.log(`\n  ${green('✓')} Vault recall hook removed.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red('x')} Failed to remove recall hook: ${e.message}\n`);
+  }
+
+  try {
+    const errorHookRemoved = removeErrorHook();
+    if (errorHookRemoved) {
+      console.log(`\n  ${green('✓')} Vault error hook removed.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red('x')} Failed to remove error hook: ${e.message}\n`);
+  }
 }
 
 async function runHooks() {
@@ -6313,6 +6929,113 @@ ${progArgs.map(a => `    <string>${a}</string>`).join('\n')}
   }
 }
 
+async function runStats() {
+  const { resolveConfig } = await import('@context-vault/core/config');
+  const { initDatabase } = await import('@context-vault/core/db');
+  const { gatherRecallSummary, gatherCoRetrievalSummary } = await import('../dist/stats/recall.js');
+
+  const sub = args[1];
+  if (!sub || sub === 'recall') {
+    await runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary });
+  } else if (sub === 'co-retrieval') {
+    await runStatsCoRetrieval({ resolveConfig, initDatabase, gatherCoRetrievalSummary });
+  } else {
+    console.error(red(`  Unknown stats subcommand: ${sub}`));
+    console.error(`  Available: recall, co-retrieval`);
+    process.exit(1);
+  }
+}
+
+async function runStatsRecall({ resolveConfig, initDatabase, gatherRecallSummary }) {
+  const config = resolveConfig();
+  let db;
+  try {
+    db = await initDatabase(config.dbPath);
+  } catch (e) {
+    console.error(red(`  Database not accessible: ${e.message}`));
+    process.exit(1);
+  }
+
+  let s;
+  try {
+    s = gatherRecallSummary({ db, config });
+  } finally {
+    db.close();
+  }
+
+  const ratioPct = Math.round(s.ratio * 100);
+  const targetPct = Math.round(s.target * 100);
+  const statusIcon = s.ratio >= s.target ? green('✓') : yellow('·');
+  console.log();
+  console.log(`  ${bold('◇ context-vault stats recall')}`);
+  console.log();
+  console.log(`  ${statusIcon} Recall ratio:     ${bold(s.ratio.toFixed(2))} (target: ${s.target.toFixed(2)})`);
+  console.log(`    Total entries:    ${s.total_entries}`);
+  console.log(`    Recalled (1+):    ${s.recalled_entries} (${ratioPct}%)`);
+  console.log(`    Never recalled:   ${s.never_recalled} (${100 - ratioPct}%)`);
+  console.log(`    Avg recall count: ${s.avg_recall_count} (among recalled entries)`);
+
+  if (s.top_recalled.length) {
+    console.log();
+    console.log(`  ${bold('Top recalled:')}`);
+    for (let i = 0; i < s.top_recalled.length; i++) {
+      const e = s.top_recalled[i];
+      const title = (e.title || '(untitled)').slice(0, 50);
+      console.log(`    ${i + 1}. "${title}" (recall: ${e.recall_count}, sessions: ${e.recall_sessions})`);
+    }
+  }
+
+  if (s.dead_entry_count > 0) {
+    console.log();
+    console.log(`  ${bold('Dead entries')} ${dim('(saved >30 days ago, never recalled):')}`);
+    console.log(`    - ${s.dead_entry_count} entries across ${s.dead_bucket_count} buckets`);
+    if (s.top_dead_buckets.length) {
+      const bucketStr = s.top_dead_buckets.map((b) => `${b.bucket} (${b.count})`).join(', ');
+      console.log(`    - Top dead buckets: ${bucketStr}`);
+    }
+  }
+
+  console.log();
+}
+
+async function runStatsCoRetrieval({ resolveConfig, initDatabase, gatherCoRetrievalSummary }) {
+  const config = resolveConfig();
+  let db;
+  try {
+    db = await initDatabase(config.dbPath);
+  } catch (e) {
+    console.error(red(`  Database not accessible: ${e.message}`));
+    process.exit(1);
+  }
+
+  let s;
+  try {
+    s = gatherCoRetrievalSummary({ db, config });
+  } finally {
+    db.close();
+  }
+
+  console.log();
+  console.log(`  ${bold('◇ context-vault stats co-retrieval')}`);
+  console.log();
+  console.log(`  Co-retrieval pairs: ${bold(String(s.total_pairs))}`);
+
+  if (s.top_pairs.length) {
+    console.log();
+    console.log(`  ${bold('Strongest pairs:')}`);
+    for (let i = 0; i < s.top_pairs.length; i++) {
+      const p = s.top_pairs[i];
+      const titleA = (p.title_a || '(untitled)').slice(0, 40);
+      const titleB = (p.title_b || '(untitled)').slice(0, 40);
+      console.log(`    ${i + 1}. "${titleA}" <-> "${titleB}" (weight: ${p.weight})`);
+    }
+  }
+
+  console.log();
+  console.log(`  Graph density: ${s.graph_density.toFixed(4)} ${dim('(sparse, expected for early usage)')}`);
+  console.log();
+}
+
 async function runServe() {
   await import('../dist/server.js');
 }
@@ -6402,6 +7125,9 @@ async function main() {
     case 'reindex':
       await runReindex();
       break;
+    case 'sync':
+      await runSync();
+      break;
     case 'migrate-dirs':
       await runMigrateDirs();
       break;
@@ -6444,6 +7170,9 @@ async function main() {
     case 'debug':
       await runDebug();
       break;
+    case 'stats':
+      await runStats();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan('context-vault --help')} for usage.`);