audrey 0.16.1 → 0.17.0

package/mcp-server/index.js

@@ -1,10 +1,8 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { Audrey } from '../src/index.js';
@@ -12,10 +10,11 @@ import { readStoredDimensions } from '../src/db.js';
 import {
   VERSION,
   SERVER_NAME,
-  DEFAULT_DATA_DIR,
   buildAudreyConfig,
   buildInstallArgs,
+  resolveDataDir,
   resolveEmbeddingProvider,
+  resolveLLMProvider,
 } from './config.js';
 
 const VALID_SOURCES = ['direct-observation', 'told-by-user', 'tool-result', 'inference', 'model-generated'];
@@ -50,6 +49,13 @@ export async function initializeEmbeddingProvider(provider) {
   }
 }
 
+async function closeAudreyGracefully(audrey) {
+  if (audrey && typeof audrey.waitForIdle === 'function') {
+    await audrey.waitForIdle();
+  }
+  audrey?.close();
+}
+
 export const memoryEncodeToolSchema = {
   content: z.string()
     .max(MAX_MEMORY_CONTENT_LENGTH)
@@ -105,7 +111,7 @@ export const memoryForgetToolSchema = {
 };
 
 async function reembed() {
-  const dataDir = process.env.AUDREY_DATA_DIR || DEFAULT_DATA_DIR;
+  const dataDir = resolveDataDir(process.env);
   const explicit = process.env.AUDREY_EMBEDDING_PROVIDER;
   const embedding = resolveEmbeddingProvider(process.env, explicit);
   const storedDims = readStoredDimensions(dataDir);
@@ -123,33 +129,12 @@ async function reembed() {
     const counts = await reembedAll(audrey.db, audrey.embeddingProvider, { dropAndRecreate: dimensionsChanged });
     console.log(`Done. Re-embedded: ${counts.episodes} episodes, ${counts.semantics} semantics, ${counts.procedures} procedures`);
   } finally {
-    audrey.close();
-  }
-}
-
-function resolveLLMConfig() {
-  const explicit = process.env.AUDREY_LLM_PROVIDER;
-  if (explicit === 'anthropic') {
-    return { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY };
+    await closeAudreyGracefully(audrey);
   }
-  if (explicit === 'openai') {
-    return { provider: 'openai', apiKey: process.env.OPENAI_API_KEY };
-  }
-  if (explicit === 'mock') {
-    return { provider: 'mock' };
-  }
-  // Auto-detect: prefer anthropic, then openai
-  if (process.env.ANTHROPIC_API_KEY) {
-    return { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY };
-  }
-  if (process.env.OPENAI_API_KEY) {
-    return { provider: 'openai', apiKey: process.env.OPENAI_API_KEY };
-  }
-  return null;
 }
 
 async function dream() {
-  const dataDir = process.env.AUDREY_DATA_DIR || DEFAULT_DATA_DIR;
+  const dataDir = resolveDataDir(process.env);
   const explicit = process.env.AUDREY_EMBEDDING_PROVIDER;
   const embedding = resolveEmbeddingProvider(process.env, explicit);
   const storedDims = readStoredDimensions(dataDir);
@@ -160,7 +145,7 @@ async function dream() {
     embedding,
   };
 
-  const llm = resolveLLMConfig();
+  const llm = resolveLLMProvider(process.env, process.env.AUDREY_LLM_PROVIDER);
   if (llm) config.llm = llm;
 
   const audrey = new Audrey(config);
@@ -192,34 +177,52 @@ async function dream() {
     );
     console.log('[audrey] Dream complete.');
   } finally {
-    audrey.close();
+    await closeAudreyGracefully(audrey);
   }
 }
 
 async function greeting() {
-  const dataDir = process.env.AUDREY_DATA_DIR || DEFAULT_DATA_DIR;
+  const dataDir = resolveDataDir(process.env);
+  const contextArg = process.argv[3] || undefined;
 
   if (!existsSync(dataDir)) {
-    console.log('[audrey] No data yet — fresh start.');
+    console.log('[audrey] No data yet - fresh start.');
     return;
   }
 
-  const dimensions = readStoredDimensions(dataDir) || 8;
+  const storedDimensions = readStoredDimensions(dataDir);
+  const resolvedEmbedding = resolveEmbeddingProvider(process.env, process.env.AUDREY_EMBEDDING_PROVIDER);
+  const canUseResolvedEmbedding = Boolean(contextArg)
+    && storedDimensions !== null
+    && storedDimensions === resolvedEmbedding.dimensions;
+  const dimensions = storedDimensions || resolvedEmbedding.dimensions || 8;
   const audrey = new Audrey({
     dataDir,
     agent: 'greeting',
-    embedding: { provider: 'mock', dimensions },
+    embedding: canUseResolvedEmbedding
+      ? resolvedEmbedding
+      : { provider: 'mock', dimensions },
   });
 
   try {
-    const contextArg = process.argv[3] || undefined;
-    const result = await audrey.greeting({ context: contextArg });
+    if (canUseResolvedEmbedding) {
+      await initializeEmbeddingProvider(audrey.embeddingProvider);
+    }
+    const result = await audrey.greeting({ context: canUseResolvedEmbedding ? contextArg : undefined });
     const health = audrey.memoryStatus();
 
     const lines = [];
     lines.push(`[Audrey v${VERSION}] Memory briefing`);
     lines.push('');
 
+    if (contextArg && !canUseResolvedEmbedding) {
+      lines.push(
+        `Context recall skipped: stored index is ${storedDimensions ?? 'unknown'}d `
+        + `but current embedding config resolves to ${resolvedEmbedding.dimensions}d.`
+      );
+      lines.push('');
+    }
+
     // Mood
     if (result.mood && result.mood.samples > 0) {
       const v = result.mood.valence;
@@ -280,7 +283,7 @@ async function greeting() {
 
     console.log(lines.join('\n'));
   } finally {
-    audrey.close();
+    await closeAudreyGracefully(audrey);
   }
 }
 
@@ -295,7 +298,7 @@ function timeSince(isoDate) {
 }
 
 async function reflect() {
-  const dataDir = process.env.AUDREY_DATA_DIR || DEFAULT_DATA_DIR;
+  const dataDir = resolveDataDir(process.env);
   const explicit = process.env.AUDREY_EMBEDDING_PROVIDER;
   const embedding = resolveEmbeddingProvider(process.env, explicit);
 
@@ -305,7 +308,7 @@ async function reflect() {
     embedding,
   };
 
-  const llm = resolveLLMConfig();
+  const llm = resolveLLMProvider(process.env, process.env.AUDREY_LLM_PROVIDER);
   if (llm) config.llm = llm;
 
   const audrey = new Audrey(config);
@@ -356,7 +359,340 @@ async function reflect() {
     );
     console.log('[audrey] Dream complete.');
   } finally {
-    audrey.close();
+    await closeAudreyGracefully(audrey);
+  }
+}
+
+async function recall() {
+  const dataDir = resolveDataDir(process.env);
+
+  if (!existsSync(dataDir)) {
+    // No data yet — nothing to recall
+    process.exit(0);
+  }
+
+  // Read hook JSON from stdin
+  let hookInput = null;
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (raw) {
+      try {
+        hookInput = JSON.parse(raw);
+      } catch {
+        console.error('[audrey] Could not parse stdin as JSON');
+        process.exit(0);
+      }
+    }
+  }
+
+  // Extract query from hook input or CLI arg
+  const query = hookInput?.prompt        // UserPromptSubmit hook
+    || hookInput?.query                  // direct query field
+    || process.argv[3];                  // CLI argument
+
+  if (!query || typeof query !== 'string' || !query.trim()) {
+    process.exit(0);
+  }
+
+  const storedDimensions = readStoredDimensions(dataDir);
+  const resolvedEmbedding = resolveEmbeddingProvider(process.env, process.env.AUDREY_EMBEDDING_PROVIDER);
+  const canEmbed = storedDimensions !== null && storedDimensions === resolvedEmbedding.dimensions;
+
+  if (!canEmbed) {
+    // Dimension mismatch — skip recall silently
+    process.exit(0);
+  }
+
+  const audrey = new Audrey({
+    dataDir,
+    agent: 'recall-hook',
+    embedding: resolvedEmbedding,
+  });
+
+  try {
+    await initializeEmbeddingProvider(audrey.embeddingProvider);
+
+    const limit = parseInt(process.argv[4], 10) || 5;
+    const results = await audrey.recall(query.trim(), {
+      limit,
+      includePrivate: false,
+    });
+
+    if (!results || results.length === 0) {
+      process.exit(0);
+    }
+
+    const lines = results.map(r => {
+      const type = r.type === 'semantic' ? 'principle' : r.type === 'procedural' ? 'procedure' : 'memory';
+      return `[${type}] ${r.content}`;
+    });
+
+    const output = {
+      additionalContext: `Relevant memories from Audrey:\n\n${lines.join('\n\n')}`,
+    };
+
+    console.log(JSON.stringify(output));
+  } finally {
+    await closeAudreyGracefully(audrey);
+  }
+}
+
+export function buildHooksConfig({ scope = 'user' } = {}) {
+  const audreyBin = 'npx audrey';
+
+  return {
+    SessionStart: [
+      {
+        matcher: 'startup|resume',
+        hooks: [
+          {
+            type: 'command',
+            command: `${audreyBin} greeting`,
+            timeout: 30,
+          },
+        ],
+      },
+    ],
+    UserPromptSubmit: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `${audreyBin} recall`,
+            timeout: 15,
+          },
+        ],
+      },
+    ],
+    Stop: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `${audreyBin} reflect`,
+            timeout: 120,
+          },
+        ],
+      },
+    ],
+    PostCompact: [
+      {
+        matcher: '',
+        hooks: [
+          {
+            type: 'command',
+            command: `${audreyBin} greeting`,
+            timeout: 30,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function hooksInstall() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  const settingsDir = join(homedir(), '.claude');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      console.error(`[audrey] Could not parse ${settingsPath}. Please fix it manually.`);
+      process.exit(1);
+    }
+  }
+
+  const audreyHooks = buildHooksConfig();
+
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  // Merge Audrey hooks with existing hooks, preserving user's existing hooks
+  for (const [event, audreyEntries] of Object.entries(audreyHooks)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    // Remove any previously-installed Audrey hooks (by command match)
+    settings.hooks[event] = settings.hooks[event].filter(entry => {
+      if (!entry.hooks) return true;
+      return !entry.hooks.some(h => h.command && h.command.includes('npx audrey'));
+    });
+
+    // Add Audrey hooks
+    settings.hooks[event].push(...audreyEntries);
+  }
+
+  mkdirSync(settingsDir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  console.log(`[audrey] Hooks installed in ${settingsPath}
+
+Hooks configured:
+  SessionStart  → npx audrey greeting   (load identity, principles, mood)
+  UserPromptSubmit → npx audrey recall   (semantic memory search per prompt)
+  Stop          → npx audrey reflect     (consolidate learnings + dream cycle)
+  PostCompact   → npx audrey greeting    (re-inject memories after compaction)
+
+Verify: Open ${settingsPath} or run claude /hooks
+`);
+}
+
+function hooksUninstall() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+
+  if (!existsSync(settingsPath)) {
+    console.log('[audrey] No settings.json found. Nothing to remove.');
+    return;
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    console.error(`[audrey] Could not parse ${settingsPath}.`);
+    process.exit(1);
+  }
+
+  if (!settings.hooks) {
+    console.log('[audrey] No hooks configured. Nothing to remove.');
+    return;
+  }
+
+  let removed = 0;
+  for (const event of Object.keys(settings.hooks)) {
+    const before = settings.hooks[event].length;
+    settings.hooks[event] = settings.hooks[event].filter(entry => {
+      if (!entry.hooks) return true;
+      return !entry.hooks.some(h => h.command && h.command.includes('npx audrey'));
+    });
+    removed += before - settings.hooks[event].length;
+
+    // Clean up empty arrays
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+
+  // Clean up empty hooks object
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`[audrey] Removed ${removed} hook(s) from ${settingsPath}`);
+}
+
+export function resolveSnapshotPath(outputArg, dataDir) {
+  if (outputArg) return resolve(outputArg);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+  return resolve(dataDir, '..', `audrey-snapshot-${timestamp}.json`);
+}
+
+async function snapshot() {
+  const dataDir = resolveDataDir(process.env);
+
+  if (!existsSync(dataDir)) {
+    console.error('[audrey] No data directory found. Nothing to snapshot.');
+    process.exit(1);
+  }
+
+  const storedDimensions = readStoredDimensions(dataDir);
+  const dimensions = storedDimensions || 8;
+  const audrey = new Audrey({
+    dataDir,
+    agent: 'snapshot',
+    embedding: { provider: 'mock', dimensions },
+  });
+
+  try {
+    const data = audrey.export();
+    const stats = audrey.introspect();
+
+    const outputPath = resolveSnapshotPath(process.argv[3], dataDir);
+
+    writeFileSync(outputPath, JSON.stringify(data, null, 2) + '\n');
+
+    console.log(`[audrey] Snapshot saved to ${outputPath}`);
+    console.log(`  ${stats.episodic} episodes, ${stats.semantic} semantics, ${stats.procedural} procedures`);
+    console.log(`  ${data.contradictions?.length || 0} contradictions, ${data.causalLinks?.length || 0} causal links`);
+    console.log(`  Version: ${data.version}, exported at: ${data.exportedAt}`);
+    console.log('');
+    console.log('To restore: npx audrey restore ' + outputPath);
+  } finally {
+    await closeAudreyGracefully(audrey);
+  }
+}
+
+async function restore() {
+  const snapshotPath = process.argv[3];
+  if (!snapshotPath) {
+    console.error('Usage: npx audrey restore <snapshot-file>');
+    console.error('  e.g.: npx audrey restore audrey-snapshot-2026-03-24.json');
+    process.exit(1);
+  }
+
+  const resolvedPath = resolve(snapshotPath);
+  if (!existsSync(resolvedPath)) {
+    console.error(`[audrey] Snapshot file not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
+  } catch {
+    console.error(`[audrey] Could not parse snapshot file: ${resolvedPath}`);
+    process.exit(1);
+  }
+
+  if (!data.version || !data.episodes) {
+    console.error('[audrey] Invalid snapshot: missing version or episodes field.');
+    process.exit(1);
+  }
+
+  const dataDir = resolveDataDir(process.env);
+  const explicit = process.env.AUDREY_EMBEDDING_PROVIDER;
+  const embedding = resolveEmbeddingProvider(process.env, explicit);
+
+  const audrey = new Audrey({ dataDir, agent: 'restore', embedding });
+
+  try {
+    await initializeEmbeddingProvider(audrey.embeddingProvider);
+
+    const stats = audrey.introspect();
+    const isEmpty = stats.episodic === 0 && stats.semantic === 0 && stats.procedural === 0;
+
+    if (!isEmpty) {
+      const force = process.argv.includes('--force');
+      if (!force) {
+        console.error('[audrey] Database is not empty. Use --force to purge and restore.');
+        console.error(`  Current: ${stats.episodic} episodes, ${stats.semantic} semantics, ${stats.procedural} procedures`);
+        process.exit(1);
+      }
+      console.log('[audrey] --force: purging existing memories before restore...');
+      audrey.purge();
+    }
+
+    console.log(`[audrey] Restoring from snapshot v${data.version} (${data.exportedAt || 'unknown date'})...`);
+    console.log(`[audrey] Re-embedding with ${embedding.provider} (${embedding.dimensions}d)...`);
+
+    await audrey.import(data);
+
+    const restored = audrey.introspect();
+    console.log(`[audrey] Restored: ${restored.episodic} episodes, ${restored.semantic} semantics, ${restored.procedural} procedures`);
+    console.log('[audrey] Restore complete.');
+  } finally {
+    await closeAudreyGracefully(audrey);
   }
 }
 
@@ -368,17 +704,27 @@ function install() {
     process.exit(1);
   }
 
-  const resolvedEmbedding = resolveEmbeddingProvider(process.env);
+  const dataDir = resolveDataDir(process.env);
+  const resolvedEmbedding = resolveEmbeddingProvider(process.env, process.env.AUDREY_EMBEDDING_PROVIDER);
+  const resolvedLlm = resolveLLMProvider(process.env, process.env.AUDREY_LLM_PROVIDER);
   if (resolvedEmbedding.provider === 'gemini') {
-    console.log('Detected GOOGLE_API_KEY/GEMINI_API_KEY - using Gemini embeddings (3072d)');
+    console.log('Using Gemini embeddings (3072d)');
   } else if (resolvedEmbedding.provider === 'local') {
-    console.log('No explicit embedding provider configured - using local embeddings (384d)');
+    console.log(`Using local embeddings (384d, device=${resolvedEmbedding.device || 'gpu'})`);
   } else if (resolvedEmbedding.provider === 'openai') {
-    console.log('Using explicit OpenAI embeddings (1536d)');
+    console.log('Using OpenAI embeddings (1536d)');
+  } else if (resolvedEmbedding.provider === 'mock') {
+    console.log('Using mock embeddings');
   }
 
-  if (process.env.ANTHROPIC_API_KEY) {
-    console.log('Detected ANTHROPIC_API_KEY - enabling LLM-powered consolidation + contradiction detection');
+  if (resolvedLlm?.provider === 'anthropic') {
+    console.log('Using Anthropic for LLM-powered consolidation, contradiction detection, and reflection');
+  } else if (resolvedLlm?.provider === 'openai') {
+    console.log('Using OpenAI for LLM-powered consolidation, contradiction detection, and reflection');
+  } else if (resolvedLlm?.provider === 'mock') {
+    console.log('Using mock LLM provider');
+  } else {
+    console.log('No LLM provider configured - consolidation and contradiction detection will use heuristics');
   }
 
   try {
@@ -417,12 +763,28 @@ CLI subcommands:
   npx audrey install   - Register MCP server with Claude Code
   npx audrey uninstall - Remove MCP server registration
   npx audrey status    - Show memory store health and stats
+  npx audrey status --json - Emit machine-readable health output
+  npx audrey status --json --fail-on-unhealthy - Exit non-zero on unhealthy status
   npx audrey greeting  - Output session briefing (for hooks)
+  npx audrey recall    - Semantic recall for hook context injection
   npx audrey reflect   - Reflect on conversation + dream cycle (for hooks)
   npx audrey dream     - Run consolidation + decay cycle
   npx audrey reembed   - Re-embed all memories with current provider
 
-Data stored in: ${DEFAULT_DATA_DIR}
+Versioning (git-friendly memory snapshots):
+  npx audrey snapshot [file] - Export memories to a JSON snapshot file
+  npx audrey restore <file>  - Restore memories from a snapshot (--force to overwrite)
+
+Hooks integration (automatic memory in every session):
+  npx audrey hooks install   - Add Audrey hooks to ~/.claude/settings.json
+  npx audrey hooks uninstall - Remove Audrey hooks from settings
+
+REST API server (any language, any framework):
+  npx audrey serve [port]    - Start HTTP server (default: 3487)
+  AUDREY_API_KEY=secret npx audrey serve - Start with Bearer token auth
+  npx audrey dashboard       - Start server and open memory dashboard
+
+Data stored in: ${dataDir}
 Verify: claude mcp list
 `);
 }
@@ -444,9 +806,15 @@ function uninstall() {
   }
 }
 
-function status() {
+function cliHasFlag(flag, argv = process.argv) {
+  return Array.isArray(argv) && argv.includes(flag);
+}
+
+export function buildStatusReport({
+  dataDir = resolveDataDir(process.env),
+  claudeJsonPath = join(homedir(), '.claude.json'),
+} = {}) {
   let registered = false;
-  const claudeJsonPath = join(homedir(), '.claude.json');
   try {
     const claudeConfig = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
     registered = SERVER_NAME in (claudeConfig.mcpServers || {});
@@ -454,41 +822,108 @@ function status() {
     // Ignore unreadable config.
   }
 
-  console.log(`Registration: ${registered ? 'active' : 'not registered'}`);
+  const report = {
+    generatedAt: new Date().toISOString(),
+    registered,
+    dataDir,
+    exists: existsSync(dataDir),
+    storedDimensions: null,
+    stats: null,
+    health: null,
+    lastConsolidation: null,
+    error: null,
+  };
 
-  if (!existsSync(DEFAULT_DATA_DIR)) {
-    console.log(`Data directory: ${DEFAULT_DATA_DIR} (not yet created - will be created on first use)`);
-    return;
+  if (!report.exists) {
+    return report;
   }
 
   try {
-    const dimensions = readStoredDimensions(DEFAULT_DATA_DIR) || 8;
+    report.storedDimensions = readStoredDimensions(dataDir);
+    const dimensions = report.storedDimensions || 8;
     const audrey = new Audrey({
-      dataDir: DEFAULT_DATA_DIR,
+      dataDir,
       agent: 'status-check',
       embedding: { provider: 'mock', dimensions },
     });
-    const stats = audrey.introspect();
-    const health = audrey.memoryStatus();
-    const lastConsolidation = audrey.db.prepare(`
+    report.stats = audrey.introspect();
+    report.health = audrey.memoryStatus();
+    report.lastConsolidation = audrey.db.prepare(`
       SELECT completed_at FROM consolidation_runs
       WHERE status = 'completed'
       ORDER BY completed_at DESC
       LIMIT 1
     `).get()?.completed_at || 'never';
     audrey.close();
-
-    console.log(`Data directory: ${DEFAULT_DATA_DIR}`);
-    console.log(`Memories: ${stats.episodic} episodic, ${stats.semantic} semantic, ${stats.procedural} procedural`);
-    console.log(`Index sync: ${health.vec_episodes}/${health.searchable_episodes} episodic, ${health.vec_semantics}/${health.searchable_semantics} semantic, ${health.vec_procedures}/${health.searchable_procedures} procedural`);
-    console.log(`Health: ${health.healthy ? 'healthy' : 'unhealthy'}${health.reembed_recommended ? ' (re-embed recommended)' : ''}`);
-    console.log(`Dormant: ${stats.dormant}`);
-    console.log(`Causal links: ${stats.causalLinks}`);
-    console.log(`Contradictions: ${stats.contradictions.open} open, ${stats.contradictions.resolved} resolved`);
-    console.log(`Consolidation runs: ${stats.totalConsolidationRuns}`);
-    console.log(`Last consolidation: ${lastConsolidation}`);
   } catch (err) {
-    console.log(`Data directory: ${DEFAULT_DATA_DIR} (exists but could not read: ${err.message})`);
+    report.error = err.message || String(err);
+  }
+
+  return report;
+}
+
+export function formatStatusReport(report) {
+  const lines = [];
+  lines.push(`Registration: ${report.registered ? 'active' : 'not registered'}`);
+
+  if (!report.exists) {
+    lines.push(`Data directory: ${report.dataDir} (not yet created - will be created on first use)`);
+    return lines.join('\n');
+  }
+
+  if (report.error) {
+    lines.push(`Data directory: ${report.dataDir} (exists but could not read: ${report.error})`);
+    return lines.join('\n');
+  }
+
+  lines.push(`Data directory: ${report.dataDir}`);
+  lines.push(`Stored dimensions: ${report.storedDimensions ?? 'unknown'}`);
+  lines.push(
+    `Memories: ${report.stats.episodic} episodic, ${report.stats.semantic} semantic, ${report.stats.procedural} procedural`
+  );
+  lines.push(
+    `Index sync: ${report.health.vec_episodes}/${report.health.searchable_episodes} episodic, `
+    + `${report.health.vec_semantics}/${report.health.searchable_semantics} semantic, `
+    + `${report.health.vec_procedures}/${report.health.searchable_procedures} procedural`
+  );
+  lines.push(
+    `Health: ${report.health.healthy ? 'healthy' : 'unhealthy'}`
+    + `${report.health.reembed_recommended ? ' (re-embed recommended)' : ''}`
+  );
+  lines.push(`Dormant: ${report.stats.dormant}`);
+  lines.push(`Causal links: ${report.stats.causalLinks}`);
+  lines.push(`Contradictions: ${report.stats.contradictions.open} open, ${report.stats.contradictions.resolved} resolved`);
+  lines.push(`Consolidation runs: ${report.stats.totalConsolidationRuns}`);
+  lines.push(`Last consolidation: ${report.lastConsolidation}`);
+
+  return lines.join('\n');
+}
+
+export function runStatusCommand({
+  argv = process.argv,
+  dataDir = resolveDataDir(process.env),
+  claudeJsonPath = join(homedir(), '.claude.json'),
+  out = console.log,
+} = {}) {
+  const report = buildStatusReport({ dataDir, claudeJsonPath });
+  if (cliHasFlag('--json', argv)) {
+    out(JSON.stringify(report, null, 2));
+  } else {
+    out(formatStatusReport(report));
+  }
+
+  const exitCode = report.error
+    || (cliHasFlag('--fail-on-unhealthy', argv) && report.exists && report.health && !report.health.healthy)
+    ? 1
+    : 0;
+
+  return { report, exitCode };
+}
+
+function status() {
+  const { exitCode } = runStatusCommand();
+  if (exitCode !== 0) {
+    process.exitCode = exitCode;
   }
 }
 
@@ -500,6 +935,61 @@ function toolError(err) {
   return { isError: true, content: [{ type: 'text', text: `Error: ${err.message || String(err)}` }] };
 }
 
+export function registerShutdownHandlers(processRef, audrey, logger = console.error) {
+  let closed = false;
+
+  const shutdown = (message, exitCode = 0) => {
+    if (message) {
+      logger(message);
+    }
+    if (!closed) {
+      closed = true;
+      if (typeof audrey?.waitForIdle === 'function') {
+        Promise.resolve(audrey.waitForIdle())
+          .catch(err => {
+            logger(`[audrey-mcp] shutdown wait error: ${err.message || String(err)}`);
+            exitCode = exitCode === 0 ? 1 : exitCode;
+          })
+          .finally(() => {
+            try {
+              audrey.close();
+            } catch (err) {
+              logger(`[audrey-mcp] shutdown error: ${err.message || String(err)}`);
+              exitCode = exitCode === 0 ? 1 : exitCode;
+            }
+            if (typeof processRef.exit === 'function') {
+              processRef.exit(exitCode);
+            }
+          });
+        return;
+      }
+      try {
+        audrey.close();
+      } catch (err) {
+        logger(`[audrey-mcp] shutdown error: ${err.message || String(err)}`);
+        exitCode = exitCode === 0 ? 1 : exitCode;
+      }
+    }
+    if (typeof processRef.exit === 'function') {
+      processRef.exit(exitCode);
+    }
+  };
+
+  processRef.once('SIGINT', () => shutdown('[audrey-mcp] received SIGINT, shutting down'));
+  processRef.once('SIGTERM', () => shutdown('[audrey-mcp] received SIGTERM, shutting down'));
+  processRef.once('SIGHUP', () => shutdown('[audrey-mcp] received SIGHUP, shutting down'));
+  processRef.once('uncaughtException', err => {
+    logger('[audrey-mcp] uncaught exception:', err);
+    shutdown(null, 1);
+  });
+  processRef.once('unhandledRejection', reason => {
+    logger('[audrey-mcp] unhandled rejection:', reason);
+    shutdown(null, 1);
+  });
+
+  return shutdown;
+}
+
 export function registerDreamTool(server, audrey) {
   server.tool(
     'memory_dream',
@@ -524,6 +1014,8 @@ export function registerDreamTool(server, audrey) {
 }
 
 async function main() {
+  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
   const config = buildAudreyConfig();
   const audrey = new Audrey(config);
 
@@ -683,12 +1175,7 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('[audrey-mcp] connected via stdio');
-
-  process.on('SIGINT', () => {
-    console.error('[audrey-mcp] shutting down');
-    audrey.close();
-    process.exit(0);
-  });
+  registerShutdownHandlers(process, audrey);
 }
 
 const isDirectRun = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
@@ -718,6 +1205,55 @@ if (isDirectRun) {
       console.error('[audrey] reflect failed:', err);
       process.exit(1);
     });
+  } else if (subcommand === 'recall') {
+    recall().catch(err => {
+      console.error('[audrey] recall failed:', err);
+      process.exit(1);
+    });
+  } else if (subcommand === 'hooks') {
+    const hooksAction = process.argv[3];
+    if (hooksAction === 'install') {
+      hooksInstall();
+    } else if (hooksAction === 'uninstall') {
+      hooksUninstall();
+    } else {
+      console.error('Usage: npx audrey hooks [install|uninstall]');
+      process.exit(1);
+    }
+  } else if (subcommand === 'snapshot') {
+    snapshot().catch(err => {
+      console.error('[audrey] snapshot failed:', err);
+      process.exit(1);
+    });
+  } else if (subcommand === 'restore') {
+    restore().catch(err => {
+      console.error('[audrey] restore failed:', err);
+      process.exit(1);
+    });
+  } else if (subcommand === 'serve') {
+    import('./serve.js').then(({ startServer }) => {
+      const port = process.argv[3] ? parseInt(process.argv[3], 10) : undefined;
+      return startServer({ port });
+    }).catch(err => {
+      console.error('[audrey] serve failed:', err);
+      process.exit(1);
+    });
+  } else if (subcommand === 'dashboard') {
+    import('./serve.js').then(({ startServer }) => {
+      const port = process.argv[3] ? parseInt(process.argv[3], 10) : undefined;
+      return startServer({ port }).then(({ server }) => {
+        const addr = server.address();
+        const url = `http://localhost:${addr.port}/dashboard`;
+        console.log(`[audrey] Opening dashboard: ${url}`);
+        import('node:child_process').then(({ exec: execCmd }) => {
+          const cmd = process.platform === 'win32' ? `start ${url}` : process.platform === 'darwin' ? `open ${url}` : `xdg-open ${url}`;
+          execCmd(cmd);
+        });
+      });
+    }).catch(err => {
+      console.error('[audrey] dashboard failed:', err);
+      process.exit(1);
+    });
   } else if (subcommand === 'status') {
     status();
   } else {