engram-sdk 0.1.0

package/dist/cli.js

@@ -0,0 +1,764 @@
+#!/usr/bin/env node
+import { Vault } from './vault.js';
+import { runEval } from './eval.js';
+import path from 'path';
+import { homedir } from 'os';
+import { parseArgs } from 'util';
+// ============================================================
+// Engram CLI — Quick interface for testing & exploration
+// ============================================================
+const HELP = `
+engram — Universal memory layer for AI agents
+
+Usage:
+  engram init                        Set up Engram for Claude Code / Cursor / MCP clients
+  engram mcp                         Start the MCP server (stdio transport)
+  engram shadow start                Start shadow mode (server + watcher, background)
+  engram shadow stop                 Stop shadow mode
+  engram shadow status               Check shadow mode status and memory count
+  engram shadow results              Compare Engram vs your CLAUDE.md
+  engram remember <text>             Store a memory
+  engram recall <context>            Retrieve relevant memories
+  engram stats                       Show vault statistics
+  engram entities                    List known entities
+  engram export                      Export entire vault as JSON
+  engram consolidate                 Run memory consolidation
+  engram forget <id> [--hard]        Forget a memory (soft or hard delete)
+  engram search <query>              Full-text search
+  engram eval                        Health report & value assessment
+  engram repl                        Interactive REPL mode
+
+Options:
+  --db <path>         Database file path (default: ~/.engram/default.db)
+  --owner <name>      Owner identifier (default: "default")
+  --agent <id>        Agent ID for source tracking
+  --json              Output as JSON
+  --help              Show this help
+`;
+function parseCliArgs() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            db: { type: 'string', default: '' },
+            owner: { type: 'string', default: 'default' },
+            agent: { type: 'string', default: '' },
+            json: { type: 'boolean', default: false },
+            hard: { type: 'boolean', default: false },
+            limit: { type: 'string', default: '20' },
+            help: { type: 'boolean', short: 'h', default: false },
+            entities: { type: 'string', default: '' },
+            topics: { type: 'string', default: '' },
+            type: { type: 'string', default: '' },
+            salience: { type: 'string', default: '' },
+            confidence: { type: 'string', default: '' },
+        },
+    });
+    return { values, positionals };
+}
+function createVault(values) {
+    const config = {
+        owner: values.owner || 'default',
+        dbPath: values.db || path.join(homedir(), '.engram', 'default.db'),
+        agentId: values.agent || undefined,
+    };
+    return new Vault(config);
+}
+function printMemory(mem, json) {
+    if (json) {
+        console.log(JSON.stringify(mem, null, 2));
+        return;
+    }
+    const m = mem;
+    const age = timeSince(m.createdAt);
+    const entityStr = m.entities?.length ? ` [${m.entities.join(', ')}]` : '';
+    const topicStr = m.topics?.length ? ` #${m.topics.join(' #')}` : '';
+    console.log(`  ${dim(m.id.slice(0, 8))}  ${m.type.padEnd(11)} ${bold(m.summary || m.content.slice(0, 80))}${entityStr}${topicStr}`);
+    console.log(`           salience=${m.salience}  confidence=${m.confidence}  stability=${m.stability?.toFixed(3)}  ${dim(age)}`);
+}
+function timeSince(iso) {
+    const ms = Date.now() - new Date(iso).getTime();
+    const mins = Math.floor(ms / 60000);
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days}d ago`;
+}
+function bold(s) { return `\x1b[1m${s}\x1b[0m`; }
+function dim(s) { return `\x1b[2m${s}\x1b[0m`; }
+function green(s) { return `\x1b[32m${s}\x1b[0m`; }
+function yellow(s) { return `\x1b[33m${s}\x1b[0m`; }
+function cyan(s) { return `\x1b[36m${s}\x1b[0m`; }
+// ============================================================
+// Init — Zero-friction setup for Claude Code / Cursor / MCP
+// ============================================================
+async function runInit(values) {
+    const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import('fs');
+    const { homedir } = await import('os');
+    const { join } = await import('path');
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise(r => rl.question(q, r));
+    console.log(bold('\n🧠 Engram Setup\n'));
+    console.log('This will configure Engram as an MCP server for your AI coding agent.\n');
+    // 1. Detect which tools are installed
+    const home = homedir();
+    const claudeConfigDir = join(home, '.claude');
+    const claudeConfigPath = join(claudeConfigDir, 'claude_desktop_config.json');
+    const cursorConfigDir = join(home, '.cursor');
+    const cursorMcpPath = join(cursorConfigDir, 'mcp.json');
+    const hasClaudeDir = existsSync(claudeConfigDir);
+    const hasCursorDir = existsSync(cursorConfigDir);
+    // Also check for Claude Code's settings.json approach
+    const claudeCodeSettingsDir = join(home, '.claude');
+    const claudeCodeMcpPath = join(claudeCodeSettingsDir, 'claude_desktop_config.json');
+    // 2. Ask for owner name
+    const defaultOwner = values.owner || process.env.USER || 'my-agent';
+    const owner = (await ask(`  Agent name [${cyan(defaultOwner)}]: `)).trim() || defaultOwner;
+    // 3. Ask for Gemini key (optional but recommended)
+    let geminiKey = process.env.GEMINI_API_KEY || '';
+    const geminiKeyPath = join(home, '.config', 'engram', 'gemini-key');
+    if (!geminiKey && existsSync(geminiKeyPath)) {
+        geminiKey = readFileSync(geminiKeyPath, 'utf-8').trim();
+    }
+    if (!geminiKey) {
+        console.log(dim('\n  Gemini API key enables embeddings + consolidation (free tier available).'));
+        console.log(dim('  Get one at: https://aistudio.google.com/apikey\n'));
+        geminiKey = (await ask('  Gemini API key (optional, press Enter to skip): ')).trim();
+    }
+    else {
+        console.log(`  ${green('✓')} Gemini API key found`);
+    }
+    // 4. Build the MCP server config block
+    const engramConfig = {
+        command: 'npx',
+        args: ['tsx', join(process.cwd(), 'src', 'mcp.ts')],
+        env: {
+            ENGRAM_OWNER: owner,
+            ...(geminiKey ? { GEMINI_API_KEY: geminiKey } : {}),
+        },
+    };
+    // For published package, use this instead:
+    const engramConfigPublished = {
+        command: 'npx',
+        args: ['engram', 'mcp'],
+        env: {
+            ENGRAM_OWNER: owner,
+            ...(geminiKey ? { GEMINI_API_KEY: geminiKey } : {}),
+        },
+    };
+    console.log('\n' + bold('  MCP Server Configuration:\n'));
+    console.log(dim('  ' + JSON.stringify({ engram: engramConfigPublished }, null, 2).split('\n').join('\n  ')));
+    // 5. Write config to detected tools
+    const targets = [];
+    if (hasClaudeDir) {
+        const write = (await ask(`\n  Write to Claude Code config? (${claudeConfigPath}) [Y/n]: `)).trim().toLowerCase();
+        if (write !== 'n') {
+            let config = {};
+            if (existsSync(claudeConfigPath)) {
+                try {
+                    config = JSON.parse(readFileSync(claudeConfigPath, 'utf-8'));
+                }
+                catch { }
+            }
+            if (!config.mcpServers)
+                config.mcpServers = {};
+            config.mcpServers.engram = engramConfig;
+            mkdirSync(claudeConfigDir, { recursive: true });
+            writeFileSync(claudeConfigPath, JSON.stringify(config, null, 2));
+            targets.push('Claude Code');
+            console.log(`  ${green('✓')} Written to ${claudeConfigPath}`);
+        }
+    }
+    if (hasCursorDir) {
+        const write = (await ask(`\n  Write to Cursor MCP config? (${cursorMcpPath}) [Y/n]: `)).trim().toLowerCase();
+        if (write !== 'n') {
+            let config = {};
+            if (existsSync(cursorMcpPath)) {
+                try {
+                    config = JSON.parse(readFileSync(cursorMcpPath, 'utf-8'));
+                }
+                catch { }
+            }
+            if (!config.mcpServers)
+                config.mcpServers = {};
+            config.mcpServers.engram = engramConfig;
+            mkdirSync(cursorConfigDir, { recursive: true });
+            writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2));
+            targets.push('Cursor');
+            console.log(`  ${green('✓')} Written to ${cursorMcpPath}`);
+        }
+    }
+    if (!hasClaudeDir && !hasCursorDir) {
+        console.log(yellow('\n  No Claude Code or Cursor installation detected.'));
+        console.log('  Add this to your MCP client config manually:\n');
+        console.log('  ' + JSON.stringify({ mcpServers: { engram: engramConfigPublished } }, null, 2).split('\n').join('\n  '));
+    }
+    // 5b. Add Engram instructions to CLAUDE.md (if Claude Code detected)
+    if (hasClaudeDir) {
+        const claudeMdPath = join(home, '.claude', 'CLAUDE.md');
+        const engramBlock = `
+## Engram
+You have access to Engram memory tools via MCP. Use them:
+- At session start: call \`engram_briefing\` to load relevant context
+- When you learn something important: call \`engram_remember\`
+- When you need context from past sessions: call \`engram_recall\`
+- At the end of a work session: call \`engram_ingest\` with a summary of what was accomplished
+`;
+        let claudeMd = '';
+        if (existsSync(claudeMdPath)) {
+            claudeMd = readFileSync(claudeMdPath, 'utf-8');
+        }
+        if (!claudeMd.includes('## Engram')) {
+            writeFileSync(claudeMdPath, claudeMd + '\n' + engramBlock.trim() + '\n');
+            console.log(`  ${green('✓')} Added Engram instructions to ${claudeMdPath}`);
+        }
+        else {
+            console.log(dim(`  ℹ CLAUDE.md already has Engram section, skipping`));
+        }
+    }
+    // 6. Save Gemini key if provided
+    if (geminiKey) {
+        const configDir = join(home, '.config', 'engram');
+        mkdirSync(configDir, { recursive: true });
+        writeFileSync(geminiKeyPath, geminiKey);
+        console.log(`  ${green('✓')} Gemini key saved to ${geminiKeyPath}`);
+    }
+    // 7. Create initial vault to verify setup
+    const engramDir = join(home, '.engram');
+    mkdirSync(engramDir, { recursive: true });
+    const dbPath = join(engramDir, `${owner}.db`);
+    const testVault = new Vault({ owner, dbPath });
+    const stats = testVault.stats();
+    await testVault.close();
+    console.log(`  ${green('✓')} Vault created at ${dbPath} (${stats.total} memories)`);
+    console.log(bold('\n  🎉 Setup complete!\n'));
+    if (targets.length > 0) {
+        console.log(`  Restart ${targets.join(' and ')} to activate Engram.\n`);
+        console.log('  Your agent now has 10 memory tools:');
+        console.log('    engram_remember    — Store a memory');
+        console.log('    engram_recall      — Retrieve relevant memories');
+        console.log('    engram_surface     — Proactive context surfacing');
+        console.log('    engram_briefing    — Session start briefing');
+        console.log('    engram_consolidate — Sleep cycle consolidation');
+        console.log('    engram_connect     — Link memories in the graph');
+        console.log('    engram_forget      — Remove memories');
+        console.log('    engram_entities    — List tracked entities');
+        console.log('    engram_stats       — Vault statistics');
+        console.log('    engram_ingest      — Auto-extract from text');
+    }
+    else {
+        console.log('  Add the config to your MCP client, then restart it.\n');
+    }
+    rl.close();
+}
+// ============================================================
+// Commands
+// ============================================================
+// ============================================================
+// Shadow Mode
+// ============================================================
+const SHADOW_PID_DIR = path.join(process.env.HOME ?? '', '.config', 'engram');
+const SERVER_PID_FILE = path.join(SHADOW_PID_DIR, 'shadow-server.pid');
+const WATCHER_PID_FILE = path.join(SHADOW_PID_DIR, 'shadow-watcher.pid');
+async function runShadow(subcommand, values) {
+    const { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } = await import('fs');
+    const { execSync, spawn } = await import('child_process');
+    const { homedir } = await import('os');
+    mkdirSync(SHADOW_PID_DIR, { recursive: true });
+    const owner = values.owner || 'default';
+    const engramDir = path.join(homedir(), '.engram');
+    mkdirSync(engramDir, { recursive: true });
+    const dbPath = path.join(engramDir, `${owner}.db`);
+    const geminiKey = process.env.GEMINI_API_KEY ?? '';
+    function isRunning(pidFile) {
+        if (!existsSync(pidFile))
+            return false;
+        const pid = readFileSync(pidFile, 'utf-8').trim();
+        try {
+            process.kill(parseInt(pid), 0);
+            return true;
+        }
+        catch {
+            unlinkSync(pidFile);
+            return false;
+        }
+    }
+    switch (subcommand) {
+        case 'start': {
+            if (isRunning(SERVER_PID_FILE)) {
+                console.log('Shadow mode is already running. Use `engram shadow status` to check.');
+                return;
+            }
+            console.log('🧠 Starting Engram shadow mode...\n');
+            // Start server
+            const distDir = path.resolve(path.dirname(new URL(import.meta.url).pathname), '.');
+            const serverPath = path.join(distDir, 'server.js');
+            const watcherPath = path.join(distDir, 'claude-watcher.js');
+            const serverEnv = {
+                ...process.env,
+                ENGRAM_OWNER: owner,
+                ENGRAM_DB_PATH: dbPath,
+                GEMINI_API_KEY: geminiKey,
+            };
+            const server = spawn('node', [serverPath], {
+                env: serverEnv,
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            // Capture the port from stdout
+            let serverPort = '';
+            server.stdout?.on('data', (data) => {
+                const line = data.toString();
+                const match = line.match(/:(\d+)/);
+                if (match && !serverPort) {
+                    serverPort = match[1];
+                }
+            });
+            server.unref();
+            writeFileSync(SERVER_PID_FILE, String(server.pid));
+            // Wait for server to start
+            await new Promise(r => setTimeout(r, 2000));
+            if (!serverPort)
+                serverPort = '3800'; // fallback
+            console.log(`   ✓ Server running on port ${serverPort} (PID ${server.pid})`);
+            console.log(`   ✓ Database: ${dbPath}`);
+            // Start Claude Code watcher
+            const watcherEnv = {
+                ...process.env,
+                ENGRAM_API: `http://127.0.0.1:${serverPort}/v1`,
+                GEMINI_API_KEY: geminiKey,
+                ENGRAM_INGEST_INTERVAL_MS: '300000',
+            };
+            const watcher = spawn('node', [watcherPath, '--watch'], {
+                env: watcherEnv,
+                detached: true,
+                stdio: 'ignore',
+            });
+            watcher.unref();
+            writeFileSync(WATCHER_PID_FILE, String(watcher.pid));
+            console.log(`   ✓ Claude Code watcher running (PID ${watcher.pid})`);
+            console.log(`\n✅ Shadow mode active. Engram is silently learning from your sessions.`);
+            console.log(`   Run \`engram shadow status\` to check progress.`);
+            console.log(`   Run \`engram shadow results\` after a few days to see what Engram caught.`);
+            console.log(`   Run \`engram shadow stop\` to stop.\n`);
+            break;
+        }
+        case 'stop': {
+            let stopped = 0;
+            for (const pidFile of [WATCHER_PID_FILE, SERVER_PID_FILE]) {
+                if (existsSync(pidFile)) {
+                    const pid = parseInt(readFileSync(pidFile, 'utf-8').trim());
+                    try {
+                        process.kill(pid, 'SIGTERM');
+                        stopped++;
+                        console.log(`Stopped PID ${pid}`);
+                    }
+                    catch { /* already dead */ }
+                    unlinkSync(pidFile);
+                }
+            }
+            if (stopped === 0) {
+                console.log('Shadow mode is not running.');
+            }
+            else {
+                console.log('Shadow mode stopped.');
+            }
+            break;
+        }
+        case 'status': {
+            const serverRunning = isRunning(SERVER_PID_FILE);
+            const watcherRunning = isRunning(WATCHER_PID_FILE);
+            console.log(`\n🧠 Engram Shadow Mode Status\n`);
+            console.log(`   Server:  ${serverRunning ? '✓ running' : '✗ stopped'}`);
+            console.log(`   Watcher: ${watcherRunning ? '✓ running' : '✗ stopped'}`);
+            console.log(`   Database: ${dbPath}`);
+            // Try to get stats from the server
+            if (serverRunning) {
+                try {
+                    const serverPid = readFileSync(SERVER_PID_FILE, 'utf-8').trim();
+                    // We don't know the port, so try common ones
+                    for (const port of ['3800']) {
+                        try {
+                            const res = await fetch(`http://127.0.0.1:${port}/v1/stats`);
+                            if (res.ok) {
+                                const stats = await res.json();
+                                console.log(`\n   📊 Vault Stats:`);
+                                console.log(`      Total memories: ${stats.total}`);
+                                console.log(`      Semantic: ${stats.semantic} | Episodic: ${stats.episodic} | Procedural: ${stats.procedural}`);
+                                console.log(`      Entities: ${stats.entities}`);
+                                break;
+                            }
+                        }
+                        catch { /* try next port */ }
+                    }
+                }
+                catch { /* can't reach server */ }
+            }
+            // Show vault stats directly from file
+            if (existsSync(dbPath)) {
+                const vault = new Vault({ owner, dbPath });
+                const stats = vault.stats();
+                console.log(`\n   📊 Vault Stats:`);
+                console.log(`      Total memories: ${stats.total}`);
+                console.log(`      Entities: ${stats.entities}`);
+                await vault.close();
+            }
+            else {
+                console.log(`\n   No vault yet — memories will appear after your first Claude Code session.`);
+            }
+            console.log('');
+            break;
+        }
+        case 'results': {
+            // Find the user's CLAUDE.md
+            const claudeMdPaths = [
+                path.join(homedir(), '.claude', 'CLAUDE.md'),
+                path.join(process.cwd(), 'CLAUDE.md'),
+                path.join(process.cwd(), '.claude', 'CLAUDE.md'),
+            ];
+            let claudeMdContent = '';
+            let claudeMdPath = '';
+            for (const p of claudeMdPaths) {
+                if (existsSync(p)) {
+                    claudeMdContent = readFileSync(p, 'utf-8');
+                    claudeMdPath = p;
+                    break;
+                }
+            }
+            if (!existsSync(dbPath)) {
+                console.log('\n❌ No Engram vault found. Start shadow mode first: `engram shadow start`\n');
+                return;
+            }
+            const vault = new Vault({ owner, dbPath });
+            const stats = vault.stats();
+            console.log(`\n🧠 Engram Shadow Mode Results\n`);
+            console.log(`   Vault: ${stats.total} memories, ${stats.entities} entities\n`);
+            if (stats.total < 10) {
+                console.log(`   ⚠️  Not enough memories yet. Keep using Claude Code for a few more sessions.`);
+                console.log(`   Engram needs at least 10-20 sessions to show meaningful results.\n`);
+                await vault.close();
+                return;
+            }
+            // Get Engram's briefing
+            const briefing = await vault.briefing('', 20);
+            console.log(`   📋 What Engram Knows (top items):`);
+            for (const fact of briefing.keyFacts.slice(0, 8)) {
+                console.log(`      • ${fact.content.slice(0, 100)}`);
+            }
+            if (claudeMdContent) {
+                console.log(`\n   📄 Your CLAUDE.md: ${claudeMdPath}`);
+                const fileLines = claudeMdContent.split('\n')
+                    .map(l => l.replace(/^[\s\-*#>]+/, '').trim())
+                    .filter(l => l.length > 20);
+                console.log(`      ${fileLines.length} meaningful lines\n`);
+                // Simple overlap analysis
+                const briefingText = briefing.keyFacts.map(f => f.content.toLowerCase()).join(' ');
+                const engramOnly = [];
+                for (const fact of briefing.keyFacts) {
+                    const keywords = fact.content.toLowerCase().split(/\s+/).filter(w => w.length > 4).slice(0, 5);
+                    const matchCount = keywords.filter(kw => claudeMdContent.toLowerCase().includes(kw)).length;
+                    if (keywords.length > 0 && matchCount / keywords.length < 0.4) {
+                        engramOnly.push(fact.content.slice(0, 120));
+                    }
+                }
+                if (engramOnly.length > 0) {
+                    console.log(`   🆕 Things Engram caught that your CLAUDE.md missed:`);
+                    for (const item of engramOnly.slice(0, 10)) {
+                        console.log(`      • ${item}`);
+                    }
+                }
+                else {
+                    console.log(`   Your CLAUDE.md and Engram are well-aligned.`);
+                }
+            }
+            else {
+                console.log(`   No CLAUDE.md found to compare against.`);
+            }
+            console.log('');
+            await vault.close();
+            break;
+        }
+        default:
+            console.log(`
+engram shadow — Test Engram alongside your existing memory
+
+Commands:
+  engram shadow start     Start shadow mode (server + watcher, runs in background)
+  engram shadow stop      Stop shadow mode
+  engram shadow status    Check how many memories Engram has collected
+  engram shadow results   Compare what Engram knows vs your CLAUDE.md
+`);
+    }
+}
+async function main() {
+    const { values, positionals } = parseCliArgs();
+    if (values.help || positionals.length === 0) {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const command = positionals[0];
+    // ── Commands that don't need a vault ──
+    if (command === 'init') {
+        await runInit(values);
+        process.exit(0);
+    }
+    if (command === 'mcp') {
+        // Delegate to the MCP server entry point
+        await import('./mcp.js');
+        return; // MCP server runs until killed
+    }
+    if (command === 'shadow') {
+        const subcommand = positionals[1] ?? 'help';
+        await runShadow(subcommand, values);
+        return;
+    }
+    if (command === 'eval') {
+        await runEval(values);
+        return;
+    }
+    const vault = createVault(values);
+    try {
+        switch (command) {
+            case 'remember': {
+                const text = positionals.slice(1).join(' ');
+                if (!text) {
+                    console.error('Error: provide text to remember');
+                    process.exit(1);
+                }
+                const input = { content: text };
+                if (values.entities)
+                    input.entities = values.entities.split(',');
+                if (values.topics)
+                    input.topics = values.topics.split(',');
+                if (values.type)
+                    input.type = values.type;
+                if (values.salience)
+                    input.salience = parseFloat(values.salience);
+                if (values.confidence)
+                    input.confidence = parseFloat(values.confidence);
+                const mem = vault.remember(input);
+                if (values.json) {
+                    console.log(JSON.stringify(mem, null, 2));
+                }
+                else {
+                    console.log(green('✓ Remembered:'));
+                    printMemory(mem, false);
+                }
+                break;
+            }
+            case 'recall': {
+                const context = positionals.slice(1).join(' ');
+                if (!context) {
+                    console.error('Error: provide context for recall');
+                    process.exit(1);
+                }
+                const input = { context, limit: parseInt(values.limit) };
+                if (values.entities)
+                    input.entities = values.entities.split(',');
+                if (values.topics)
+                    input.topics = values.topics.split(',');
+                if (values.type)
+                    input.types = [values.type];
+                const memories = await vault.recall(input);
+                if (values.json) {
+                    console.log(JSON.stringify(memories, null, 2));
+                }
+                else {
+                    console.log(cyan(`Found ${memories.length} relevant memories:\n`));
+                    for (const mem of memories) {
+                        printMemory(mem, false);
+                        console.log();
+                    }
+                }
+                break;
+            }
+            case 'search': {
+                const query = positionals.slice(1).join(' ');
+                if (!query) {
+                    console.error('Error: provide search query');
+                    process.exit(1);
+                }
+                // Access store directly isn't possible from Vault, so use recall with keywords
+                const memories = await vault.recall({ context: query, limit: parseInt(values.limit) });
+                if (values.json) {
+                    console.log(JSON.stringify(memories, null, 2));
+                }
+                else {
+                    console.log(cyan(`Search results for "${query}":\n`));
+                    for (const mem of memories) {
+                        printMemory(mem, false);
+                        console.log();
+                    }
+                }
+                break;
+            }
+            case 'stats': {
+                const stats = vault.stats();
+                if (values.json) {
+                    console.log(JSON.stringify(stats, null, 2));
+                }
+                else {
+                    console.log(bold('\n📊 Vault Statistics\n'));
+                    console.log(`  Total memories:  ${bold(String(stats.total))}`);
+                    console.log(`  Episodic:        ${stats.episodic}`);
+                    console.log(`  Semantic:        ${stats.semantic}`);
+                    console.log(`  Procedural:      ${stats.procedural}`);
+                    console.log(`  Entities:        ${stats.entities}`);
+                    console.log();
+                }
+                break;
+            }
+            case 'entities': {
+                const entities = vault.entities();
+                if (values.json) {
+                    console.log(JSON.stringify(entities, null, 2));
+                }
+                else {
+                    console.log(bold(`\n🧠 Known Entities (${entities.length})\n`));
+                    for (const e of entities) {
+                        console.log(`  ${bold(e.name)}  ${dim(e.type)}  mentions=${e.memoryCount}  importance=${e.importance}`);
+                    }
+                    console.log();
+                }
+                break;
+            }
+            case 'consolidate': {
+                console.log(yellow('⏳ Running consolidation...'));
+                const report = await vault.consolidate();
+                if (values.json) {
+                    console.log(JSON.stringify(report, null, 2));
+                }
+                else {
+                    console.log(green('\n✓ Consolidation Complete\n'));
+                    console.log(`  Episodes processed:      ${report.episodesProcessed}`);
+                    console.log(`  Semantic memories created: ${report.semanticMemoriesCreated}`);
+                    console.log(`  Semantic memories updated: ${report.semanticMemoriesUpdated}`);
+                    console.log(`  Entities discovered:      ${report.entitiesDiscovered}`);
+                    console.log(`  Connections formed:        ${report.connectionsFormed}`);
+                    console.log(`  Contradictions found:      ${report.contradictionsFound}`);
+                    console.log(`  Memories decayed:          ${report.memoriesDecayed}`);
+                    console.log(`  Memories archived:         ${report.memoriesArchived}`);
+                    console.log();
+                }
+                break;
+            }
+            case 'forget': {
+                const id = positionals[1];
+                if (!id) {
+                    console.error('Error: provide memory ID to forget');
+                    process.exit(1);
+                }
+                vault.forget(id, values.hard);
+                console.log(values.hard ? green('✓ Hard deleted') : yellow('✓ Soft forgotten (salience → 0)'));
+                break;
+            }
+            case 'export': {
+                const data = vault.export();
+                console.log(JSON.stringify(data, null, 2));
+                break;
+            }
+            case 'repl': {
+                await repl(vault, values.json);
+                break;
+            }
+            default:
+                console.error(`Unknown command: ${command}`);
+                console.log(HELP);
+                process.exit(1);
+        }
+    }
+    finally {
+        await vault.close();
+    }
+}
+// ============================================================
+// Interactive REPL
+// ============================================================
+async function repl(vault, jsonMode) {
+    const { createInterface } = await import('readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log(bold('\n🧠 Engram REPL'));
+    console.log(dim('Commands: remember <text> | recall <context> | stats | entities | consolidate | quit\n'));
+    const prompt = () => {
+        rl.question(cyan('engram> '), async (line) => {
+            const trimmed = line.trim();
+            if (!trimmed) {
+                prompt();
+                return;
+            }
+            if (trimmed === 'quit' || trimmed === 'exit') {
+                rl.close();
+                await vault.close();
+                return;
+            }
+            const [cmd, ...rest] = trimmed.split(/\s+/);
+            const text = rest.join(' ');
+            try {
+                switch (cmd) {
+                    case 'remember':
+                    case 'r':
+                        if (!text) {
+                            console.log('Usage: remember <text>');
+                            break;
+                        }
+                        const mem = vault.remember(text);
+                        console.log(green('✓ Remembered'));
+                        printMemory(mem, jsonMode);
+                        break;
+                    case 'recall':
+                    case 'q':
+                        if (!text) {
+                            console.log('Usage: recall <context>');
+                            break;
+                        }
+                        const results = await vault.recall(text);
+                        console.log(cyan(`\n${results.length} memories:\n`));
+                        for (const r of results) {
+                            printMemory(r, jsonMode);
+                            console.log();
+                        }
+                        break;
+                    case 'stats':
+                    case 's':
+                        const stats = vault.stats();
+                        console.log(`Total: ${stats.total} | Episodic: ${stats.episodic} | Semantic: ${stats.semantic} | Procedural: ${stats.procedural} | Entities: ${stats.entities}`);
+                        break;
+                    case 'entities':
+                    case 'e':
+                        const entities = vault.entities();
+                        for (const e of entities) {
+                            console.log(`  ${bold(e.name)} (${e.type}) — ${e.memoryCount} mentions`);
+                        }
+                        break;
+                    case 'consolidate':
+                    case 'c':
+                        console.log(yellow('Consolidating...'));
+                        const report = await vault.consolidate();
+                        console.log(green(`✓ ${report.episodesProcessed} episodes → ${report.semanticMemoriesCreated} semantic, ${report.connectionsFormed} connections`));
+                        break;
+                    default:
+                        // Treat unknown input as a remember shortcut
+                        const m = vault.remember(trimmed);
+                        console.log(green('✓ Remembered'));
+                        printMemory(m, jsonMode);
+                }
+            }
+            catch (err) {
+                console.error('Error:', err.message);
+            }
+            console.log();
+            prompt();
+        });
+    };
+    prompt();
+}
+main().catch(err => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map