audrey 0.23.1 → 1.0.1

package/dist/mcp-server/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { z } from 'zod';
 import { homedir, platform, tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { Audrey, MemoryController } from '../src/index.js';
@@ -120,6 +120,28 @@ export const memoryPreflightToolSchema = {
     include_capsule: z.boolean().optional().describe('If false, omit the embedded Memory Capsule from the response.'),
     scope: z.enum(['agent', 'shared']).optional().describe('agent restricts memory recall to this server agent identity. shared searches the whole store. Defaults to agent.'),
 };
+const { record_event: _preflightRecordEvent, ...memoryGuardBeforeFields } = memoryPreflightToolSchema;
+export const memoryGuardBeforeToolSchema = {
+    ...memoryGuardBeforeFields,
+    session_id: z.string().optional().describe('Session identifier for grouping the required guard receipt event.'),
+    files: z.array(z.string()).optional().describe('File paths to fingerprint in the required guard receipt.'),
+};
+export const memoryGuardAfterToolSchema = {
+    receipt_id: z.string()
+        .refine(isNonEmptyText, 'Receipt id must not be empty')
+        .describe('Receipt id returned by memory_guard_before.'),
+    tool: z.string().optional().describe('Tool or command family that completed, e.g. Bash, npm test, Edit, deploy.'),
+    session_id: z.string().optional().describe('Session identifier for grouping related guard events.'),
+    input: z.unknown().optional().describe('Tool input. Hashed and never stored raw; redacted metadata is only stored when retain_details is true.'),
+    output: z.unknown().optional().describe('Tool output. Same redaction and storage policy as input.'),
+    outcome: z.enum(['succeeded', 'failed', 'blocked', 'skipped', 'unknown']).optional().describe('Outcome classification'),
+    error_summary: z.string().optional().describe('Short error description if the action failed. Redacted and truncated to 2 KB.'),
+    cwd: z.string().optional().describe('Working directory at the time of the action.'),
+    files: z.array(z.string()).optional().describe('File paths to fingerprint (size + mtime + content hash).'),
+    metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary structured metadata (redacted before storage).'),
+    retain_details: z.boolean().optional().describe('If true, redacted input and output payloads are stored alongside hashes. Defaults to false.'),
+    evidence_feedback: z.record(z.string(), z.enum(['used', 'helpful', 'wrong'])).optional().describe('Map of evidence ids from the guard receipt to memory validation outcomes.'),
+};
 export const memoryReflexesToolSchema = {
     ...memoryPreflightToolSchema,
     include_preflight: z.boolean().optional().describe('If true, include the full underlying preflight report.'),
@@ -426,10 +448,20 @@ export function formatInstallGuide(host, env = process.env, dryRun = false) {
         'Generated MCP config:',
         formatMcpHostConfig(normalizedHost, env),
         '',
+        ...(normalizedHost === 'claude-code'
+            ? [
+                'Generated Claude Code hook config:',
+                formatClaudeCodeHookConfig(),
+                '',
+            ]
+            : []),
         'Next steps:',
     ];
     if (normalizedHost === 'claude-code') {
         lines.push('- Run without --dry-run to register Audrey through Claude Code: npx audrey install --host claude-code');
+        lines.push('- Apply project hooks with: npx audrey hook-config claude-code --apply --scope project');
+        lines.push('- Apply user hooks with: npx audrey hook-config claude-code --apply --scope user');
+        lines.push('- Verify hooks in Claude Code with: /hooks');
         lines.push('- Verify with: claude mcp list');
     }
     else if (normalizedHost === 'codex') {
@@ -496,49 +528,51 @@ function installClaudeCode(options = { includeSecrets: false }) {
         console.error('Failed to register MCP server. Is Claude Code installed and on your PATH?');
         process.exit(1);
     }
-    console.log(`
-Audrey registered as "${SERVER_NAME}" with Claude Code.
-
-20 MCP tools available in every session:
-  memory_encode        - Store observations, facts, preferences
-  memory_recall        - Search memories by semantic similarity
-  memory_consolidate   - Extract principles from accumulated episodes
-  memory_dream         - Full sleep cycle: consolidate + decay + stats
-  memory_introspect    - Check memory system health
-  memory_resolve_truth - Resolve contradictions between claims
-  memory_export        - Export all memories as JSON snapshot
-  memory_import        - Import a snapshot into a fresh database
-  memory_forget        - Forget a specific memory by ID or query
-  memory_validate      - Closed-loop feedback: helpful/used/wrong outcomes
-  memory_decay         - Apply forgetting curves, transition low-confidence to dormant
-  memory_status        - Check brain health (episode/vec sync, dimensions)
-  memory_reflect       - Form lasting memories from a conversation
-  memory_greeting      - Wake up as yourself: load identity, context, mood
-  memory_observe_tool  - Record redacted tool-use events
-  memory_recent_failures - Inspect recent failed tool events
-  memory_capsule       - Return a ranked, evidence-backed memory packet
-  memory_preflight     - Check memory before an agent acts
-  memory_reflexes      - Convert preflight evidence into trigger-response reflexes
-  memory_promote       - Promote repeated lessons into project rules
-
-CLI subcommands:
-  npx audrey demo      - Run a 60-second local proof with no network calls
-  npx audrey doctor    - Diagnose runtime, store health, and host config readiness
-  npx audrey install   - Register MCP server with Claude Code
-  npx audrey install --host codex --dry-run - Print safe host setup instructions
-  npx audrey mcp-config codex - Print Codex MCP TOML
-  npx audrey mcp-config generic - Print JSON config for other MCP hosts
-  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 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: ${dataDir}
-Verify: claude mcp list
+    console.log(`
+Audrey registered as "${SERVER_NAME}" with Claude Code.
+
+20 MCP tools available in every session:
+  memory_encode        - Store observations, facts, preferences
+  memory_recall        - Search memories by semantic similarity
+  memory_consolidate   - Extract principles from accumulated episodes
+  memory_dream         - Full sleep cycle: consolidate + decay + stats
+  memory_introspect    - Check memory system health
+  memory_resolve_truth - Resolve contradictions between claims
+  memory_export        - Export all memories as JSON snapshot
+  memory_import        - Import a snapshot into a fresh database
+  memory_forget        - Forget a specific memory by ID or query
+  memory_validate      - Closed-loop feedback: helpful/used/wrong outcomes
+  memory_decay         - Apply forgetting curves, transition low-confidence to dormant
+  memory_status        - Check brain health (episode/vec sync, dimensions)
+  memory_reflect       - Form lasting memories from a conversation
+  memory_greeting      - Wake up as yourself: load identity, context, mood
+  memory_observe_tool  - Record redacted tool-use events
+  memory_recent_failures - Inspect recent failed tool events
+  memory_capsule       - Return a ranked, evidence-backed memory packet
+  memory_preflight     - Check memory before an agent acts
+  memory_guard_before  - Create a guard receipt before an agent acts
+  memory_guard_after   - Record the outcome for a guard receipt
+  memory_reflexes      - Convert preflight evidence into trigger-response reflexes
+  memory_promote       - Promote repeated lessons into project rules
+
+CLI subcommands:
+  npx audrey demo      - Run a 60-second local proof with no network calls
+  npx audrey doctor    - Diagnose runtime, store health, and host config readiness
+  npx audrey install   - Register MCP server with Claude Code
+  npx audrey install --host codex --dry-run - Print safe host setup instructions
+  npx audrey mcp-config codex - Print Codex MCP TOML
+  npx audrey mcp-config generic - Print JSON config for other MCP hosts
+  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 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: ${dataDir}
+Verify: claude mcp list
 `);
 }
 function install() {
@@ -584,9 +618,238 @@ function printMcpConfig() {
         process.exit(2);
     }
 }
+function printHookConfig() {
+    let options;
+    try {
+        options = parseHookConfigOptions();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[audrey] hook-config failed: ${message}`);
+        process.exit(2);
+    }
+    if (options.host !== 'claude-code') {
+        console.error(`[audrey] hook-config currently supports claude-code only, got "${options.host}"`);
+        process.exit(2);
+    }
+    if (!options.apply) {
+        console.log(formatClaudeCodeHookConfig());
+        return;
+    }
+    try {
+        const settingsPath = options.settingsPath ?? defaultClaudeCodeSettingsPath(options);
+        const result = applyClaudeCodeHookConfig({
+            settingsPath,
+            dryRun: options.dryRun,
+        });
+        const action = result.dryRun
+            ? result.changed ? 'would update' : 'would leave unchanged'
+            : result.changed ? 'updated' : 'already up to date';
+        console.log(`[audrey] Claude Code hook settings ${action}: ${result.settingsPath}`);
+        if (result.backupPath)
+            console.log(`[audrey] backup written: ${result.backupPath}`);
+        if (result.dryRun)
+            console.log(JSON.stringify(result.settings, null, 2));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[audrey] hook-config failed: ${message}`);
+        process.exit(2);
+    }
+}
+export function recallPayload(results) {
+    return {
+        results: Array.from(results),
+        partial_failure: results.partialFailure ?? false,
+        errors: results.errors ?? [],
+    };
+}
 function sectionTitle(section) {
     return section.replace(/_/g, ' ');
 }
+function shellQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+export function formatClaudeCodeHookConfig(entrypoint = MCP_ENTRYPOINT) {
+    const node = shellQuote(process.execPath);
+    const entry = shellQuote(entrypoint);
+    const command = (subcommand) => `${node} ${entry} ${subcommand}`;
+    return JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: '.*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: command('guard --hook --fail-on-warn'),
+                        },
+                    ],
+                },
+            ],
+            PostToolUse: [
+                {
+                    matcher: '.*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: command('observe-tool --event PostToolUse'),
+                        },
+                    ],
+                },
+            ],
+            PostToolUseFailure: [
+                {
+                    matcher: '.*',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: command('observe-tool --event PostToolUseFailure'),
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2);
+}
+function asJsonRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function cloneHookRows(value) {
+    return Array.isArray(value) ? [...value] : [];
+}
+function hookCommandSet(settings) {
+    const commands = new Set();
+    const hooks = asJsonRecord(settings.hooks);
+    for (const rows of Object.values(hooks)) {
+        if (!Array.isArray(rows))
+            continue;
+        for (const row of rows) {
+            const record = asJsonRecord(row);
+            const hookItems = cloneHookRows(record.hooks);
+            for (const item of hookItems) {
+                const hook = asJsonRecord(item);
+                if (typeof hook.command === 'string')
+                    commands.add(hook.command);
+            }
+        }
+    }
+    return commands;
+}
+export function mergeClaudeCodeHookSettings(existingSettings, generatedSettings = JSON.parse(formatClaudeCodeHookConfig())) {
+    const existing = asJsonRecord(existingSettings);
+    const generated = asJsonRecord(generatedSettings);
+    const merged = { ...existing };
+    const existingHooks = asJsonRecord(existing.hooks);
+    const generatedHooks = asJsonRecord(generated.hooks);
+    const nextHooks = { ...existingHooks };
+    const existingCommands = hookCommandSet(existing);
+    for (const [eventName, generatedRows] of Object.entries(generatedHooks)) {
+        const rows = cloneHookRows(nextHooks[eventName]);
+        for (const row of cloneHookRows(generatedRows)) {
+            const hookRow = asJsonRecord(row);
+            const commands = cloneHookRows(hookRow.hooks)
+                .map(item => asJsonRecord(item).command)
+                .filter((command) => typeof command === 'string');
+            if (commands.some(command => existingCommands.has(command)))
+                continue;
+            rows.push(row);
+            for (const command of commands)
+                existingCommands.add(command);
+        }
+        nextHooks[eventName] = rows;
+    }
+    merged.hooks = nextHooks;
+    return merged;
+}
+function parseHookConfigOptions(argv = process.argv) {
+    let host = argv[3] || 'claude-code';
+    let apply = false;
+    let dryRun = false;
+    let scope = 'project';
+    let projectDir = process.cwd();
+    let settingsPath;
+    for (let i = 4; i < argv.length; i++) {
+        const token = argv[i];
+        const next = () => argv[++i];
+        if (token === '--apply')
+            apply = true;
+        else if (token === '--dry-run' || token === '--print')
+            dryRun = true;
+        else if (token === '--scope') {
+            const value = next();
+            if (value === 'project' || value === 'user')
+                scope = value;
+            else
+                throw new Error(`Unsupported hook-config scope "${value}". Use project or user.`);
+        }
+        else if (token?.startsWith('--scope=')) {
+            const value = token.slice('--scope='.length);
+            if (value === 'project' || value === 'user')
+                scope = value;
+            else
+                throw new Error(`Unsupported hook-config scope "${value}". Use project or user.`);
+        }
+        else if (token === '--project-dir') {
+            projectDir = next() ?? projectDir;
+        }
+        else if (token?.startsWith('--project-dir=')) {
+            projectDir = token.slice('--project-dir='.length) || projectDir;
+        }
+        else if (token === '--settings') {
+            settingsPath = next();
+        }
+        else if (token?.startsWith('--settings=')) {
+            settingsPath = token.slice('--settings='.length);
+        }
+        else if (token && !token.startsWith('-')) {
+            host = token;
+        }
+        else if (token) {
+            throw new Error(`Unknown hook-config option: ${token}`);
+        }
+    }
+    return { host, apply, dryRun, scope, projectDir, ...(settingsPath ? { settingsPath } : {}) };
+}
+function defaultClaudeCodeSettingsPath(options) {
+    if (options.scope === 'user')
+        return join(homedir(), '.claude', 'settings.json');
+    return join(resolve(options.projectDir), '.claude', 'settings.local.json');
+}
+export function applyClaudeCodeHookConfig(options) {
+    const settingsPath = resolve(options.settingsPath);
+    const existingText = existsSync(settingsPath) ? readFileSync(settingsPath, 'utf-8') : '';
+    let existing = {};
+    if (existingText.trim()) {
+        try {
+            existing = JSON.parse(existingText);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Cannot merge Audrey hooks into invalid JSON at ${settingsPath}: ${message}`);
+        }
+    }
+    const settings = mergeClaudeCodeHookSettings(existing);
+    const nextText = `${JSON.stringify(settings, null, 2)}\n`;
+    const changed = existingText !== nextText;
+    let backupPath = null;
+    if (changed && !options.dryRun) {
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        if (existingText) {
+            const stamp = (options.now ?? new Date()).toISOString().replace(/[:.]/g, '-');
+            backupPath = `${settingsPath}.audrey-${stamp}.bak`;
+            writeFileSync(backupPath, existingText, 'utf-8');
+        }
+        writeFileSync(settingsPath, nextText, 'utf-8');
+    }
+    return {
+        settingsPath,
+        dryRun: options.dryRun ?? false,
+        changed,
+        backupPath,
+        settings,
+    };
+}
 function createDemoDir() {
     const preferredParent = process.env['AUDREY_DEMO_PARENT_DIR'] || tmpdir();
     try {
@@ -598,13 +861,6 @@ function createDemoDir() {
         return mkdtempSync(join(fallbackParent, 'run-'));
     }
 }
-export function recallPayload(results) {
-    return {
-        results: Array.from(results),
-        partial_failure: results.partialFailure ?? false,
-        errors: results.errors ?? [],
-    };
-}
 function cliValue(flag, argv = process.argv) {
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
@@ -618,7 +874,7 @@ function cliValue(flag, argv = process.argv) {
 function demoScenario(argv = process.argv) {
     return cliValue('--scenario', argv);
 }
-function formatGuardResult(result, { explain = false } = {}) {
+function formatControllerGuardResult(result) {
     const label = result.decision === 'block'
         ? 'BLOCKED'
         : result.decision === 'warn'
@@ -632,39 +888,14 @@ function formatGuardResult(result, { explain = false } = {}) {
     if (result.evidenceIds.length > 0) {
         lines.push('');
         lines.push('Evidence:');
-        for (const id of result.evidenceIds.slice(0, 8)) {
+        for (const id of result.evidenceIds.slice(0, 8))
             lines.push(`- ${id}`);
-        }
     }
     if (result.recommendedActions.length > 0) {
         lines.push('');
         lines.push('Recommended action:');
-        for (const action of result.recommendedActions.slice(0, 5)) {
+        for (const action of result.recommendedActions.slice(0, 5))
             lines.push(`- ${action}`);
-        }
-    }
-    if (result.reflexes.length > 0) {
-        lines.push('');
-        lines.push('Memory reflexes:');
-        for (const reflex of result.reflexes.slice(0, 5)) {
-            lines.push(`- ${reflex.response_type}: ${reflex.response}`);
-        }
-    }
-    if (explain && result.capsule) {
-        lines.push('');
-        lines.push('Capsule:');
-        for (const [section, entries] of Object.entries(result.capsule.sections)) {
-            if (!Array.isArray(entries) || entries.length === 0)
-                continue;
-            lines.push(`- ${sectionTitle(section)}:`);
-            for (const entry of entries.slice(0, 3)) {
-                lines.push(`  * ${entry.memory_id}: ${entry.content}`);
-            }
-        }
-    }
-    if (result.decision === 'block') {
-        lines.push('');
-        lines.push('Next: fix the warning and retry, or pass --override to allow this guard check.');
     }
     return lines.join('\n');
 }
@@ -709,7 +940,7 @@ async function runRepeatedFailureDemo({ out = console.log, keep = process.argv.i
         const result = await controller.beforeAction(action);
         out('Step 3: a new preflight checks the same action before tool use.');
         out('');
-        out(formatGuardResult(result));
+        out(formatControllerGuardResult(result));
         audrey.validate({ id: lessonId, outcome: 'helpful' });
         const impactReport = audrey.impact({ windowDays: 7, limit: 3 });
         out('');
@@ -733,14 +964,10 @@ async function runRepeatedFailureDemo({ out = console.log, keep = process.argv.i
     }
 }
 export async function runDemoCommand({ out = console.log, keep = process.argv.includes('--keep'), } = {}) {
-    const scenario = demoScenario();
-    if (scenario === 'repeated-failure') {
+    if (demoScenario() === 'repeated-failure') {
         await runRepeatedFailureDemo({ out, keep });
         return;
     }
-    if (scenario) {
-        throw new Error(`Unknown demo scenario "${scenario}". Supported scenarios: repeated-failure`);
-    }
     const demoDir = createDemoDir();
     const audrey = new Audrey({
         dataDir: demoDir,
@@ -891,11 +1118,11 @@ export function buildStatusReport({ dataDir = resolveDataDir(process.env), claud
         });
         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
+        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();
     }
@@ -1324,10 +1551,10 @@ async function main() {
             };
             if (profileEnabled) {
                 const { results, diagnostics } = await audrey.recallWithDiagnostics(query, recallOptions);
-                return toolResult(recallPayload(results), diagnostics);
+                return toolResult(results, diagnostics);
             }
             const results = await audrey.recall(query, recallOptions);
-            return toolResult(recallPayload(results));
+            return toolResult(results);
         }
         catch (err) {
             return toolError(err);
@@ -1471,7 +1698,7 @@ async function main() {
         outcome: z.enum(['succeeded', 'failed', 'blocked', 'skipped', 'unknown']).optional().describe('Outcome classification'),
         error_summary: z.string().optional().describe('Short error description if the tool failed. Redacted and truncated to 2 KB.'),
         cwd: z.string().optional().describe('Working directory at the time of the tool call'),
-        files: z.array(z.string()).optional().describe('File paths under cwd to fingerprint (relative path + size + mtime)'),
+        files: z.array(z.string()).optional().describe('File paths to fingerprint (size + mtime + content hash)'),
         metadata: z.record(z.string(), z.unknown()).optional().describe('Arbitrary structured metadata (redacted before storage)'),
         retain_details: z.boolean().optional().describe('If true, redacted input and output payloads are stored alongside hashes. Defaults to false.'),
     }, async ({ event, tool, session_id, input, output, outcome, error_summary, cwd, files, metadata, retain_details, }) => {
@@ -1563,6 +1790,51 @@ async function main() {
             return toolError(err);
         }
     });
+    server.tool('memory_guard_before', memoryGuardBeforeToolSchema, async ({ action, tool, session_id, cwd, files, strict, limit, budget_chars, mode, failure_window_hours, include_status, include_capsule, scope, }) => {
+        try {
+            const decision = await audrey.beforeAction(action, {
+                tool,
+                sessionId: session_id,
+                cwd,
+                files,
+                strict,
+                limit,
+                budgetChars: budget_chars,
+                mode,
+                recentFailureWindowHours: failure_window_hours,
+                includeStatus: include_status,
+                recordEvent: true,
+                includeCapsule: include_capsule,
+                scope: scope ?? 'agent',
+            });
+            return toolResult(decision);
+        }
+        catch (err) {
+            return toolError(err);
+        }
+    });
+    server.tool('memory_guard_after', memoryGuardAfterToolSchema, async ({ receipt_id, tool, session_id, input, output, outcome, error_summary, cwd, files, metadata, retain_details, evidence_feedback, }) => {
+        try {
+            const result = audrey.afterAction({
+                receiptId: receipt_id,
+                tool,
+                sessionId: session_id,
+                input,
+                output,
+                outcome,
+                errorSummary: error_summary,
+                cwd,
+                files,
+                metadata,
+                retainDetails: retain_details,
+                evidenceFeedback: evidence_feedback,
+            });
+            return toolResult(result);
+        }
+        catch (err) {
+            return toolError(err);
+        }
+    });
     server.tool('memory_reflexes', memoryReflexesToolSchema, async ({ action, tool, session_id, cwd, files, strict, limit, budget_chars, mode, failure_window_hours, include_status, record_event, include_capsule, include_preflight, scope, }) => {
         try {
             const report = await audrey.reflexes(action, {
@@ -1783,6 +2055,9 @@ function parseGuardArgs(argv) {
     let override = false;
     let failOnWarn = false;
     let explain = false;
+    let hook = false;
+    let strict = false;
+    let includeCapsule = false;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
         const next = () => argv[++i];
@@ -1816,13 +2091,16 @@ function parseGuardArgs(argv) {
             failOnWarn = true;
         else if (token === '--explain')
             explain = true;
+        else if (token === '--hook')
+            hook = true;
+        else if (token === '--strict')
+            strict = true;
+        else if (token === '--include-capsule')
+            includeCapsule = true;
         else if (token && token !== '--')
             positional.push(token);
     }
     const action = positional.join(' ').trim();
-    if (!action) {
-        throw new Error('audrey guard requires an action, e.g. audrey guard --tool Bash "npm run deploy"');
-    }
     return {
         tool,
         action,
@@ -1833,28 +2111,164 @@ function parseGuardArgs(argv) {
         override,
         failOnWarn,
         explain,
+        hook,
+        strict,
+        includeCapsule,
     };
 }
+function guardDisplayDecision(result) {
+    if (result.decision === 'block')
+        return 'block';
+    if (result.decision === 'caution')
+        return 'warn';
+    return 'allow';
+}
+function summarizeToolInput(payload, tool) {
+    const input = (payload.tool_input && typeof payload.tool_input === 'object')
+        ? payload.tool_input
+        : {};
+    const command = typeof input.command === 'string' ? input.command : undefined;
+    const fileFields = ['file_path', 'path', 'notebook_path'];
+    const files = fileFields
+        .map(field => input[field])
+        .filter((value) => typeof value === 'string' && value.trim().length > 0);
+    if (command)
+        return { action: command, command, files };
+    const description = typeof input.description === 'string' ? input.description : undefined;
+    if (description)
+        return { action: `${tool}: ${description}`, files };
+    const compactInput = JSON.stringify(input);
+    return {
+        action: compactInput && compactInput !== '{}'
+            ? `${tool} ${compactInput}`
+            : `Use ${tool}`,
+        files,
+    };
+}
+async function readHookPayload() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (!raw)
+        return {};
+    return JSON.parse(raw);
+}
+function formatHookReason(result) {
+    const recommendations = result.recommended_actions.slice(0, 3);
+    return [
+        result.summary,
+        recommendations.length > 0 ? `Recommended: ${recommendations.join(' ')}` : '',
+        result.evidence_ids.length > 0 ? `Evidence: ${result.evidence_ids.slice(0, 5).join(', ')}` : '',
+    ].filter(Boolean).join('\n');
+}
+function formatPreToolUseHookOutput(result, failOnWarn) {
+    const decision = guardDisplayDecision(result);
+    const shouldDeny = decision === 'block' || (failOnWarn && decision === 'warn');
+    if (shouldDeny) {
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: formatHookReason(result),
+            },
+        };
+    }
+    if (decision === 'warn') {
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                additionalContext: formatHookReason(result),
+            },
+        };
+    }
+    return {};
+}
+function formatGuardDecision(result, { explain = false } = {}) {
+    const display = guardDisplayDecision(result);
+    const label = display === 'block' ? 'BLOCKED' : display === 'warn' ? 'WARN' : 'ALLOW';
+    const lines = [];
+    lines.push(`Audrey Guard: ${label}`);
+    lines.push('');
+    lines.push(`Receipt: ${result.receipt_id}`);
+    lines.push(`Reason: ${result.summary}`);
+    lines.push(`Risk score: ${result.risk_score.toFixed(2)}`);
+    if (result.evidence_ids.length > 0) {
+        lines.push('');
+        lines.push('Evidence:');
+        for (const id of result.evidence_ids.slice(0, 8))
+            lines.push(`- ${id}`);
+    }
+    if (result.recommended_actions.length > 0) {
+        lines.push('');
+        lines.push('Recommended action:');
+        for (const action of result.recommended_actions.slice(0, 5))
+            lines.push(`- ${action}`);
+    }
+    if (result.reflexes.length > 0) {
+        lines.push('');
+        lines.push('Memory reflexes:');
+        for (const reflex of result.reflexes.slice(0, 5)) {
+            lines.push(`- ${reflex.response_type}: ${reflex.response}`);
+        }
+    }
+    if (explain && result.capsule) {
+        lines.push('');
+        lines.push('Capsule:');
+        for (const [section, entries] of Object.entries(result.capsule.sections)) {
+            if (!Array.isArray(entries) || entries.length === 0)
+                continue;
+            lines.push(`- ${sectionTitle(section)}:`);
+            for (const entry of entries.slice(0, 3)) {
+                lines.push(`  * ${entry.memory_id}: ${entry.content}`);
+            }
+        }
+    }
+    if (display === 'block') {
+        lines.push('');
+        lines.push('Next: fix the warning and retry, or pass --override to allow this guard check.');
+    }
+    return lines.join('\n');
+}
 async function guardCli() {
     const args = parseGuardArgs(process.argv.slice(3));
-    const audrey = new Audrey(buildAudreyConfig());
+    if (!args.action && !args.hook) {
+        console.error('[audrey] guard: action is required');
+        process.exit(2);
+    }
+    const hookPayload = args.hook ? await readHookPayload() : null;
+    const hookTool = hookPayload && typeof hookPayload.tool_name === 'string' ? hookPayload.tool_name : undefined;
+    const hookSessionId = hookPayload && typeof hookPayload.session_id === 'string' ? hookPayload.session_id : undefined;
+    const hookCwd = hookPayload && typeof hookPayload.cwd === 'string' ? hookPayload.cwd : undefined;
+    const hookSummary = hookPayload ? summarizeToolInput(hookPayload, hookTool ?? args.tool) : null;
+    const dataDir = resolveDataDir(process.env);
+    const embedding = resolveEmbeddingProvider(process.env, process.env['AUDREY_EMBEDDING_PROVIDER']);
+    const audrey = new Audrey({
+        dataDir,
+        agent: process.env['AUDREY_AGENT'] ?? 'guard',
+        embedding,
+    });
     try {
-        const controller = new MemoryController(audrey);
-        const result = await controller.beforeAction({
-            tool: args.tool,
-            action: args.action,
-            command: args.action,
-            cwd: args.cwd ?? process.cwd(),
-            files: args.files.length > 0 ? args.files : undefined,
-            sessionId: args.sessionId,
+        const result = await audrey.beforeAction(hookSummary?.action ?? args.action, {
+            tool: hookTool ?? args.tool,
+            sessionId: args.sessionId ?? hookSessionId,
+            cwd: args.cwd ?? hookCwd ?? process.cwd(),
+            files: args.files.length > 0 ? args.files : hookSummary?.files?.length ? hookSummary.files : undefined,
+            strict: args.strict || args.failOnWarn || args.hook,
+            recordEvent: true,
+            includeCapsule: args.includeCapsule || args.explain,
         });
-        if (args.json) {
+        if (args.hook) {
+            console.log(JSON.stringify(formatPreToolUseHookOutput(result, args.failOnWarn)));
+        }
+        else if (args.json) {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
-            console.log(formatGuardResult(result, { explain: args.explain }));
+            console.log(formatGuardDecision(result, { explain: args.explain }));
         }
-        if ((result.decision === 'block' || (args.failOnWarn && result.decision === 'warn')) && !args.override) {
+        const display = guardDisplayDecision(result);
+        if (!args.hook && (display === 'block' || (args.failOnWarn && display === 'warn')) && !args.override) {
             process.exitCode = 2;
         }
     }
@@ -1862,6 +2276,100 @@ async function guardCli() {
         await audrey.closeAsync();
     }
 }
+function parseGuardAfterArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const next = () => argv[++i];
+        if (token === '--receipt')
+            out.receipt = next();
+        else if (token === '--tool')
+            out.tool = next();
+        else if (token === '--session-id')
+            out.sessionId = next();
+        else if (token === '--outcome')
+            out.outcome = next();
+        else if (token === '--error-summary')
+            out.errorSummary = next();
+        else if (token === '--cwd')
+            out.cwd = next();
+    }
+    return out;
+}
+async function readOptionalJsonFromStdin(command) {
+    if (process.stdin.isTTY)
+        return null;
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const raw = Buffer.concat(chunks).toString('utf-8').trim();
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.error(`[audrey] ${command}: stdin was not valid JSON, ignoring.`);
+        return null;
+    }
+}
+function inferGuardAfterOutcome(stdinPayload) {
+    const response = stdinPayload?.tool_response
+        ?? stdinPayload?.tool_output
+        ?? stdinPayload?.output;
+    const success = response?.success;
+    if (typeof success === 'boolean')
+        return success ? 'succeeded' : 'failed';
+    const errField = response?.error ?? response?.stderr ?? stdinPayload?.error ?? stdinPayload?.stderr;
+    if (errField && (typeof errField !== 'string' || errField.length > 0))
+        return 'failed';
+    return undefined;
+}
+async function guardAfterCli() {
+    const args = parseGuardAfterArgs(process.argv.slice(3));
+    if (!args.receipt) {
+        console.error('[audrey] guard-after: --receipt is required');
+        process.exit(2);
+    }
+    const stdinPayload = await readOptionalJsonFromStdin('guard-after');
+    const outputPayload = stdinPayload?.tool_response ?? stdinPayload?.tool_output ?? stdinPayload?.output;
+    const inputPayload = stdinPayload?.tool_input ?? stdinPayload?.input;
+    const outcome = args.outcome ?? inferGuardAfterOutcome(stdinPayload);
+    let errorSummary = args.errorSummary ?? stdinPayload?.error_summary;
+    if (outcome === 'failed' && !errorSummary) {
+        const response = outputPayload && typeof outputPayload === 'object'
+            ? outputPayload
+            : undefined;
+        const errField = response?.error ?? response?.stderr ?? stdinPayload?.error ?? stdinPayload?.stderr;
+        if (typeof errField === 'string')
+            errorSummary = errField;
+        else if (errField !== undefined)
+            errorSummary = JSON.stringify(errField);
+    }
+    const dataDir = resolveDataDir(process.env);
+    const embedding = resolveEmbeddingProvider(process.env, process.env['AUDREY_EMBEDDING_PROVIDER']);
+    const audrey = new Audrey({
+        dataDir,
+        agent: process.env['AUDREY_AGENT'] ?? 'guard-after',
+        embedding,
+    });
+    try {
+        const result = audrey.afterAction({
+            receiptId: args.receipt,
+            tool: args.tool ?? stdinPayload?.tool_name,
+            sessionId: args.sessionId ?? stdinPayload?.session_id,
+            input: inputPayload,
+            output: outputPayload,
+            outcome,
+            errorSummary,
+            cwd: args.cwd ?? stdinPayload?.cwd,
+        });
+        console.log(JSON.stringify(result));
+    }
+    finally {
+        await audrey.closeAsync();
+    }
+}
 function parsePromoteArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -1949,60 +2457,61 @@ function canonicalEntryPath(path) {
 const isDirectRun = Boolean(process.argv[1])
     && canonicalEntryPath(process.argv[1]) === canonicalEntryPath(fileURLToPath(import.meta.url));
 const KNOWN_SUBCOMMANDS = [
-    'install', 'uninstall', 'mcp-config', 'demo', 'guard', 'reembed', 'dream',
-    'greeting', 'reflect', 'serve', 'status', 'doctor', 'observe-tool', 'promote', 'impact',
+    'install', 'uninstall', 'mcp-config', 'hook-config', 'demo', 'reembed', 'dream',
+    'greeting', 'reflect', 'serve', 'status', 'doctor', 'observe-tool', 'guard', 'guard-after', 'promote', 'impact',
 ];
 function printHelp() {
-    process.stdout.write(`audrey ${VERSION} — local-first memory runtime for AI agents
-
-Usage: audrey <command> [options]
-
+    process.stdout.write(`audrey ${VERSION} — local-first memory runtime for AI agents
+
+Usage: audrey <command> [options]
+
 Commands:
   doctor                        Verify Node, MCP entrypoint, providers, and store health
   demo                          Run a no-key, no-network proof of recall + reflexes
-  demo --scenario repeated-failure
-                                Show Audrey Guard stopping a repeated deploy failure
-  guard --tool <Tool> "<action>" Run memory-before-action guard; exits 2 on block
-                                Use --fail-on-warn for hooks/CI, --override to allow
   status                        Print store health (add --json --fail-on-unhealthy for CI)
   install [--host <h>]          Register Audrey with an MCP host (codex, claude-code, generic)
-  uninstall                     Remove Audrey from a host's MCP config
-  mcp-config <host>             Print raw MCP config block for a host (codex|generic|vscode)
-  serve                         Start the REST sidecar (default port 7437; AUDREY_API_KEY recommended)
-  dream                         Run consolidation + decay sweep
-  reembed                       Recompute vectors after dimension/provider change
-  greeting                      Emit session-start briefing (used by host hooks)
-  reflect                       End-of-session memory capture from stdin transcript
-  observe-tool                  Record a tool-trace event (--event, --tool, --outcome)
-  impact                        Show closed-loop feedback metrics (--window N, --limit N, --json)
-  promote                       Promote rules from observed traces (--dry-run to preview)
-
-  (no command)                  Start the MCP stdio server (used by MCP hosts)
-
-Common options:
-  -h, --help                    Print this help and exit
-  -v, --version                 Print version and exit
-  --include-secrets             Include provider API keys in Claude Code install argv/config
-
-Environment:
-  AUDREY_DATA_DIR               Path to SQLite memory store (default: ~/.audrey/data)
-  AUDREY_AGENT                  Logical agent identity (default: local-agent)
-  AUDREY_EMBEDDING_PROVIDER     local | gemini | openai | mock
-  AUDREY_LLM_PROVIDER           anthropic | openai | mock
-  AUDREY_ENABLE_ADMIN_TOOLS=1   Enable export, import, and forget tools/routes
-  AUDREY_PORT                   REST sidecar port (default: 7437)
-  AUDREY_API_KEY                Bearer token required for non-loopback REST traffic
-  AUDREY_PROFILE=1              Emit per-stage timings via _meta.diagnostics
-  AUDREY_DISABLE_WARMUP=1       Skip background embedding warmup
-  AUDREY_ONNX_VERBOSE=1         Show ONNX runtime warnings (off by default)
-
+  uninstall                     Remove Audrey from a host's MCP config
+  mcp-config <host>             Print raw MCP config block for a host (codex|generic|vscode)
+  hook-config claude-code       Print Claude Code hook config (add --apply to merge settings)
+  serve                         Start the REST sidecar (default port 7437; AUDREY_API_KEY recommended)
+  dream                         Run consolidation + decay sweep
+  reembed                       Recompute vectors after dimension/provider change
+  greeting                      Emit session-start briefing (used by host hooks)
+  reflect                       End-of-session memory capture from stdin transcript
+  observe-tool                  Record a tool-trace event (--event, --tool, --outcome)
+  guard                         Check memory before an action (--json, --tool, --strict)
+  guard-after                   Record a guarded action outcome (--receipt, --outcome)
+  impact                        Show closed-loop feedback metrics (--window N, --limit N, --json)
+  promote                       Promote rules from observed traces (--dry-run to preview)
+
+  (no command)                  Start the MCP stdio server (used by MCP hosts)
+
+Common options:
+  -h, --help                    Print this help and exit
+  -v, --version                 Print version and exit
+  --include-secrets             Include provider API keys in Claude Code install argv/config
+
+Environment:
+  AUDREY_DATA_DIR               Path to SQLite memory store (default: ~/.audrey/data)
+  AUDREY_AGENT                  Logical agent identity (default: local-agent)
+  AUDREY_EMBEDDING_PROVIDER     local | gemini | openai | mock
+  AUDREY_LLM_PROVIDER           anthropic | openai | mock
+  AUDREY_ENABLE_ADMIN_TOOLS=1   Enable export, import, and forget tools/routes
+  AUDREY_PORT                   REST sidecar port (default: 7437)
+  AUDREY_API_KEY                Bearer token required for non-loopback REST traffic
+  AUDREY_PROFILE=1              Emit per-stage timings via _meta.diagnostics
+  AUDREY_DISABLE_WARMUP=1       Skip background embedding warmup
+  AUDREY_ONNX_VERBOSE=1         Show ONNX runtime warnings (off by default)
+
 Quick start:
   npx audrey doctor
   npx audrey demo --scenario repeated-failure
   npx audrey guard --tool Bash "npm run deploy"
   npx audrey install --host codex --dry-run
-
-Docs: https://github.com/Evilander/Audrey
+  npx audrey hook-config claude-code
+  npx audrey hook-config claude-code --apply --scope project
+
+Docs: https://github.com/Evilander/Audrey
 `);
 }
 function printVersion() {
@@ -2028,18 +2537,15 @@ if (isDirectRun) {
     else if (subcommand === 'mcp-config') {
         printMcpConfig();
     }
+    else if (subcommand === 'hook-config') {
+        printHookConfig();
+    }
     else if (subcommand === 'demo') {
         runDemoCommand().catch(err => {
             console.error('[audrey] demo failed:', err);
             process.exit(1);
         });
     }
-    else if (subcommand === 'guard') {
-        guardCli().catch(err => {
-            console.error('[audrey] guard failed:', err);
-            process.exit(1);
-        });
-    }
     else if (subcommand === 'reembed') {
         reembed().catch(err => {
             console.error('[audrey] reembed failed:', err);
@@ -2082,6 +2588,18 @@ if (isDirectRun) {
             process.exit(1);
         });
     }
+    else if (subcommand === 'guard') {
+        guardCli().catch(err => {
+            console.error('[audrey] guard failed:', err);
+            process.exit(1);
+        });
+    }
+    else if (subcommand === 'guard-after') {
+        guardAfterCli().catch(err => {
+            console.error('[audrey] guard-after failed:', err);
+            process.exit(1);
+        });
+    }
     else if (subcommand === 'impact') {
         impact().catch(err => {
             console.error('[audrey] impact failed:', err);