@hbarefoot/engram 1.1.0 → 1.2.0

package/bin/engram.js

@@ -16,19 +16,35 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import fs from 'fs';
 
-// Read version from package.json
+// Read version from package.json (may not exist when running as bundled sidecar)
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJson = JSON.parse(
-  readFileSync(join(__dirname, '../package.json'), 'utf-8')
-);
+let version = '1.1.0';
+try {
+  const packageJson = JSON.parse(
+    readFileSync(join(__dirname, '../package.json'), 'utf-8')
+  );
+  version = packageJson.version;
+} catch {
+  // Running as bundled sidecar — package.json not available
+}
 
 const program = new Command();
 
 program
   .name('engram')
   .description('Persistent memory for AI agents - SQLite for agent state')
-  .version(packageJson.version);
+  .version(version);
+
+// ── Lazy format helpers (only loaded for non-MCP commands) ───────────
+
+let fmt;
+async function loadFormat() {
+  if (!fmt) {
+    fmt = await import('../src/utils/format.js');
+  }
+  return fmt;
+}
 
 // Start server command
 program
@@ -39,28 +55,32 @@ program
   .option('--config <path>', 'Path to config file')
   .action(async (options) => {
     if (options.mcpOnly) {
-      // Start MCP server only (stdio mode)
+      // Start MCP server only (stdio mode) — no formatting imports
       logger.info('Starting Engram MCP server (stdio mode)...');
       await startMCPServer(options.config);
     } else {
-      // Start REST API server
+      const f = await loadFormat();
+      const chalk = (await import('chalk')).default;
       const config = loadConfig(options.config);
       const port = parseInt(options.port);
 
-      logger.info('Starting Engram REST API server...');
-      logger.info(`Server available at http://localhost:${port}`);
-      logger.info(`Dashboard available at http://localhost:${port}`);
+      f.printHeader(version);
+
+      f.info(`REST API   ${chalk.cyan(`http://localhost:${port}`)}`);
+      f.info(`Dashboard  ${chalk.cyan(`http://localhost:${port}`)}`);
+      console.log('');
 
       await startRESTServer(config, port);
 
       // Keep process alive
       process.on('SIGINT', () => {
-        logger.info('Received SIGINT, shutting down...');
+        console.log('');
+        f.info('Shutting down...');
         process.exit(0);
       });
 
       process.on('SIGTERM', () => {
-        logger.info('Received SIGTERM, shutting down...');
+        f.info('Shutting down...');
         process.exit(0);
       });
     }
@@ -76,6 +96,7 @@ program
   .option('-n, --namespace <name>', 'Project/scope namespace', 'default')
   .option('--config <path>', 'Path to config file')
   .action(async (content, options) => {
+    const f = await loadFormat();
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -84,7 +105,7 @@ program
       const validation = validateContent(content, { autoRedact: config.security?.secretDetection !== false });
 
       if (!validation.valid) {
-        console.error('❌ Cannot store memory:', validation.errors.join(', '));
+        f.error(`Cannot store memory: ${validation.errors.join(', ')}`);
         process.exit(1);
       }
 
@@ -103,31 +124,40 @@ program
         memoryData.entity = extracted.entity;
       }
 
-      // Generate embedding
+      // Generate embedding with spinner
+      const spin = f.spinner('Generating embedding...');
+      spin.start();
       try {
         const { generateEmbedding } = await import('../src/embed/index.js');
         const embedding = await generateEmbedding(validation.content, getModelsPath(config));
         memoryData.embedding = embedding;
+        spin.succeed('Embedding generated');
       } catch (error) {
-        logger.warn('Failed to generate embedding', { error: error.message });
+        spin.warn('Embedding skipped (model unavailable)');
       }
 
       const memory = createMemory(db, memoryData);
 
-      console.log('✅ Memory stored successfully!');
-      console.log(`ID: ${memory.id}`);
-      console.log(`Category: ${memory.category}`);
-      console.log(`Entity: ${memory.entity || 'none'}`);
-      console.log(`Confidence: ${memory.confidence}`);
-      console.log(`Namespace: ${memory.namespace}`);
+      console.log('');
+      f.success('Memory stored');
+      console.log('');
+      f.printKeyValue([
+        ['ID',         memory.id],
+        ['Category',   f.categoryBadge(memory.category)],
+        ['Entity',     memory.entity || 'none'],
+        ['Confidence', f.confidenceColor(memory.confidence)],
+        ['Namespace',  memory.namespace]
+      ]);
 
       if (validation.warnings?.length > 0) {
-        console.log(`\n⚠️  Warnings: ${validation.warnings.join(', ')}`);
+        console.log('');
+        f.warning(`Warnings: ${validation.warnings.join(', ')}`);
       }
+      console.log('');
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -136,12 +166,14 @@ program
 program
   .command('recall <query>')
   .description('Recall memories matching a query')
-  .option('-l, --limit <n>', 'Max results (default 5)', parseInt, 5)
+  .option('-l, --limit <n>', 'Max results (default 5)', v => parseInt(v, 10), 5)
   .option('-c, --category <type>', 'Filter by category')
   .option('-n, --namespace <name>', 'Filter by namespace')
   .option('--threshold <score>', 'Minimum relevance score (0-1)', parseFloat, 0.3)
   .option('--config <path>', 'Path to config file')
   .action(async (query, options) => {
+    const f = await loadFormat();
+    const chalk = (await import('chalk')).default;
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -159,12 +191,42 @@ program
         modelsPath
       );
 
-      const formatted = formatRecallResults(memories);
-      console.log(formatted);
+      if (memories.length === 0) {
+        console.log('');
+        f.info('No relevant memories found.');
+        console.log('');
+        db.close();
+        return;
+      }
+
+      f.printSection(`${memories.length} result${memories.length === 1 ? '' : 's'}`);
+      console.log('');
+
+      memories.forEach((memory, index) => {
+        const num = chalk.bold(`#${index + 1}`);
+        const cat = f.categoryBadge(memory.category);
+        const id = f.shortId(memory.id);
+        const score = memory.score ? f.scoreDisplay(memory.score, { showBar: true }) : '';
+
+        console.log(`${num}  ${cat}  ${id}  ${score}`);
+        console.log(`   ${memory.content}`);
+
+        if (memory.scoreBreakdown) {
+          const bd = memory.scoreBreakdown;
+          const parts = [
+            `sim=${chalk.dim(bd.similarity.toFixed(2))}`,
+            `rec=${chalk.dim(bd.recency.toFixed(2))}`,
+            `conf=${chalk.dim(bd.confidence.toFixed(2))}`,
+            `fts=${chalk.dim(bd.ftsBoost.toFixed(2))}`
+          ];
+          console.log(`   ${chalk.dim(parts.join('  '))}`);
+        }
+        console.log('');
+      });
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -174,7 +236,9 @@ program
   .command('forget <id>')
   .description('Delete a memory by ID')
   .option('--config <path>', 'Path to config file')
-  .action((id, options) => {
+  .action(async (id, options) => {
+    const f = await loadFormat();
+    const chalk = (await import('chalk')).default;
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -182,23 +246,32 @@ program
       const memory = getMemory(db, id);
 
       if (!memory) {
-        console.error(`❌ Memory not found: ${id}`);
+        f.error(`Memory not found: ${id}`);
         db.close();
         process.exit(1);
       }
 
+      // Show preview before deletion
+      console.log('');
+      console.log(f.box(
+        `${chalk.bold('Deleting memory')}  ${f.shortId(memory.id)}\n` +
+        `${f.categoryBadge(memory.category)}  conf ${f.confidenceColor(memory.confidence)}\n` +
+        `${f.truncate(memory.content, 60)}`
+      ));
+
       const deleted = deleteMemory(db, id);
 
+      console.log('');
       if (deleted) {
-        console.log(`✅ Memory deleted: ${id}`);
-        console.log(`Content: ${memory.content}`);
+        f.success(`Memory deleted: ${id}`);
       } else {
-        console.error(`❌ Failed to delete memory: ${id}`);
+        f.error(`Failed to delete memory: ${id}`);
       }
+      console.log('');
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -207,12 +280,13 @@ program
 program
   .command('list')
   .description('List all memories (paginated)')
-  .option('-l, --limit <n>', 'Max results', parseInt, 50)
-  .option('--offset <n>', 'Offset for pagination', parseInt, 0)
+  .option('-l, --limit <n>', 'Max results', v => parseInt(v, 10), 50)
+  .option('--offset <n>', 'Offset for pagination', v => parseInt(v, 10), 0)
   .option('-c, --category <type>', 'Filter by category')
   .option('-n, --namespace <name>', 'Filter by namespace')
   .option('--config <path>', 'Path to config file')
-  .action((options) => {
+  .action(async (options) => {
+    const f = await loadFormat();
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -224,19 +298,37 @@ program
         namespace: options.namespace
       });
 
-      console.log(`\nFound ${memories.length} memories:\n`);
+      f.printSection(`${memories.length} memories`);
 
-      memories.forEach((memory, index) => {
-        console.log(`[${index + 1}] ${memory.id.substring(0, 8)}`);
-        console.log(`    ${memory.content}`);
-        console.log(`    Category: ${memory.category} | Entity: ${memory.entity || 'none'} | Confidence: ${memory.confidence}`);
-        console.log(`    Namespace: ${memory.namespace} | Accessed: ${memory.access_count} times`);
+      if (memories.length === 0) {
         console.log('');
+        f.info('No memories found.');
+        console.log('');
+        db.close();
+        return;
+      }
+
+      const table = f.createTable({
+        head: ['ID', 'Content', 'Category', 'Conf', 'Access', 'Namespace']
       });
 
+      for (const memory of memories) {
+        table.push([
+          f.shortId(memory.id),
+          f.truncate(memory.content, 50),
+          f.categoryBadge(memory.category),
+          f.confidenceColor(memory.confidence),
+          String(memory.access_count),
+          memory.namespace
+        ]);
+      }
+
+      console.log(table.toString());
+      console.log('');
+
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -247,50 +339,86 @@ program
   .description('Show Engram status and statistics')
   .option('--config <path>', 'Path to config file')
   .action(async (options) => {
+    const f = await loadFormat();
+    const chalk = (await import('chalk')).default;
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
       const stats = getStats(db);
 
-      console.log('\n📊 Engram Status\n');
+      f.printHeader(version);
 
-      console.log('Memory Statistics:');
-      console.log(`  Total memories: ${stats.total}`);
-      console.log(`  With embeddings: ${stats.withEmbeddings}`);
-      console.log(`  By category:`);
-      for (const [category, count] of Object.entries(stats.byCategory)) {
-        console.log(`    - ${category}: ${count}`);
+      // Memory statistics
+      f.printSection('Memory Statistics');
+      console.log('');
+      f.printKeyValue([
+        ['Total memories',  chalk.bold(String(stats.total))],
+        ['With embeddings', String(stats.withEmbeddings)]
+      ]);
+
+      // Categories table
+      if (Object.keys(stats.byCategory).length > 0) {
+        console.log('');
+        const catTable = f.createTable({ head: ['Category', 'Count'] });
+        for (const [category, count] of Object.entries(stats.byCategory)) {
+          catTable.push([f.categoryBadge(category), String(count)]);
+        }
+        console.log(catTable.toString());
       }
-      console.log(`  By namespace:`);
-      for (const [namespace, count] of Object.entries(stats.byNamespace)) {
-        console.log(`    - ${namespace}: ${count}`);
+
+      // Namespaces table
+      if (Object.keys(stats.byNamespace).length > 0) {
+        console.log('');
+        const nsTable = f.createTable({ head: ['Namespace', 'Count'] });
+        for (const [namespace, count] of Object.entries(stats.byNamespace)) {
+          nsTable.push([namespace, String(count)]);
+        }
+        console.log(nsTable.toString());
       }
 
       // Model info
+      f.printSection('Embedding Model');
+      console.log('');
       try {
         const { getModelInfo } = await import('../src/embed/index.js');
         const modelInfo = getModelInfo(getModelsPath(config));
 
-        console.log('\n🤖 Embedding Model:');
-        console.log(`  Name: ${modelInfo.name}`);
-        console.log(`  Available: ${modelInfo.available ? '✅' : '❌'}`);
-        console.log(`  Cached: ${modelInfo.cached ? '✅' : '❌'}`);
-        console.log(`  Size: ${modelInfo.sizeMB} MB`);
-        console.log(`  Path: ${modelInfo.path}`);
-      } catch (error) {
-        console.log('\n🤖 Embedding Model: ❌ Not available');
+        let statusText;
+        if (modelInfo.cached) {
+          statusText = chalk.green('Ready');
+        } else if (modelInfo.loading) {
+          statusText = chalk.yellow('Loading...');
+        } else if (modelInfo.available) {
+          statusText = chalk.green('Available');
+        } else {
+          statusText = chalk.red('Not available');
+        }
+
+        f.printKeyValue([
+          ['Name',   modelInfo.name],
+          ['Status', statusText],
+          ['Size',   `${modelInfo.sizeMB} MB`],
+          ['Path',   chalk.dim(modelInfo.path)]
+        ]);
+      } catch {
+        f.printKeyValue([['Status', chalk.red('Not available')]]);
       }
 
-      console.log('\n⚙️  Configuration:');
-      console.log(`  Data directory: ${config.dataDir}`);
-      console.log(`  Default namespace: ${config.defaults.namespace}`);
-      console.log(`  Recall limit: ${config.defaults.recallLimit}`);
-      console.log(`  Secret detection: ${config.security.secretDetection ? '✅' : '❌'}`);
+      // Configuration
+      f.printSection('Configuration');
+      console.log('');
+      f.printKeyValue([
+        ['Data directory',    chalk.dim(config.dataDir)],
+        ['Namespace',         config.defaults.namespace],
+        ['Recall limit',      String(config.defaults.recallLimit)],
+        ['Secret detection',  config.security.secretDetection ? chalk.green('on') : chalk.red('off')]
+      ]);
       console.log('');
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      const f2 = await loadFormat();
+      f2.error(error.message);
       process.exit(1);
     }
   });
@@ -305,11 +433,13 @@ program
   .option('--cleanup-stale', 'Enable stale memory cleanup')
   .option('--config <path>', 'Path to config file')
   .action(async (options) => {
+    const f = await loadFormat();
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
 
-      console.log('🔄 Running consolidation...\n');
+      const spin = f.spinner('Running consolidation...');
+      spin.start();
 
       const results = await consolidate(db, {
         detectDuplicates: options.duplicates !== false,
@@ -318,17 +448,23 @@ program
         cleanupStale: options.cleanupStale === true
       });
 
-      console.log('✅ Consolidation complete!');
-      console.log(`  Duplicates removed: ${results.duplicatesRemoved}`);
-      console.log(`  Contradictions detected: ${results.contradictionsDetected}`);
-      console.log(`  Memories decayed: ${results.memoriesDecayed}`);
-      console.log(`  Stale memories cleaned: ${results.staleMemoriesCleaned}`);
-      console.log(`  Duration: ${results.duration}ms`);
+      spin.succeed('Consolidation complete');
+      console.log('');
+
+      const table = f.createTable({ head: ['Metric', 'Count'] });
+      table.push(
+        ['Duplicates removed',      String(results.duplicatesRemoved)],
+        ['Contradictions detected',  String(results.contradictionsDetected)],
+        ['Memories decayed',         String(results.memoriesDecayed)],
+        ['Stale cleaned',            String(results.staleMemoriesCleaned)],
+        ['Duration',                 `${results.duration}ms`]
+      );
+      console.log(table.toString());
       console.log('');
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -338,7 +474,9 @@ program
   .command('conflicts')
   .description('Show detected contradictions')
   .option('--config <path>', 'Path to config file')
-  .action((options) => {
+  .action(async (options) => {
+    const f = await loadFormat();
+    const chalk = (await import('chalk')).default;
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -346,22 +484,28 @@ program
       const conflicts = getConflicts(db);
 
       if (conflicts.length === 0) {
-        console.log('✅ No conflicts detected');
+        console.log('');
+        f.success('No conflicts detected');
+        console.log('');
       } else {
-        console.log(`\n⚠️  Found ${conflicts.length} conflict(s):\n`);
+        f.printSection(`${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'}`);
+        console.log('');
 
         conflicts.forEach((conflict, index) => {
-          console.log(`Conflict ${index + 1}: ${conflict.conflictId}`);
-          conflict.memories.forEach((memory, mIndex) => {
-            console.log(`  [${String.fromCharCode(65 + mIndex)}] ${memory.id.substring(0, 8)}: ${memory.content}`);
-          });
+          const header = `${chalk.bold(`Conflict ${index + 1}`)}  ${chalk.dim(conflict.conflictId)}`;
+          const memLines = conflict.memories.map((memory, mIndex) => {
+            const label = chalk.bold(String.fromCharCode(65 + mIndex));
+            return `${label}  ${f.shortId(memory.id)}  ${f.categoryBadge(memory.category || 'fact')}\n   ${f.truncate(memory.content, 56)}`;
+          }).join('\n');
+
+          console.log(f.box(`${header}\n${memLines}`));
           console.log('');
         });
       }
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
       process.exit(1);
     }
   });
@@ -375,13 +519,15 @@ program
   .option('-f, --format <type>', 'Format: markdown, claude, txt, json', 'markdown')
   .option('-c, --categories <list>', 'Comma-separated list of categories')
   .option('--min-confidence <score>', 'Minimum confidence (0-1)', parseFloat, 0.5)
-  .option('--min-access <count>', 'Minimum access count', parseInt, 0)
+  .option('--min-access <count>', 'Minimum access count', v => parseInt(v, 10), 0)
   .option('--include-low-feedback', 'Include memories with negative feedback', false)
   .option('--group-by <field>', 'Group by: category, entity, none', 'category')
   .option('--header <text>', 'Custom header text')
   .option('--footer <text>', 'Custom footer text')
   .option('--config <path>', 'Path to config file')
-  .action((options) => {
+  .action(async (options) => {
+    const f = await loadFormat();
+    const chalk = (await import('chalk')).default;
     try {
       const config = loadConfig(options.config);
       const db = initDatabase(getDatabasePath(config));
@@ -403,17 +549,56 @@ program
       if (options.output) {
         // Write to file
         fs.writeFileSync(options.output, result.content, 'utf8');
-        console.log(`✅ Exported ${result.stats.totalExported} memories to ${options.output}`);
-        console.log(`   Size: ${result.stats.sizeKB} KB`);
-        console.log(`   By category:`, result.stats.byCategory);
+        console.log('');
+        f.success(`Exported to ${chalk.bold(options.output)}`);
+        console.log('');
+        f.printKeyValue([
+          ['Memories', String(result.stats.totalExported)],
+          ['Size',     `${result.stats.sizeKB} KB`],
+          ['Format',   options.format]
+        ]);
+
+        if (result.stats.byCategory && Object.keys(result.stats.byCategory).length > 0) {
+          console.log('');
+          const catTable = f.createTable({ head: ['Category', 'Count'] });
+          for (const [cat, count] of Object.entries(result.stats.byCategory)) {
+            catTable.push([f.categoryBadge(cat), String(count)]);
+          }
+          console.log(catTable.toString());
+        }
+        console.log('');
       } else {
-        // Output to stdout
+        // Output to stdout (raw, no formatting)
         console.log(result.content);
       }
 
       db.close();
     } catch (error) {
-      console.error('❌ Error:', error.message);
+      f.error(error.message);
+      process.exit(1);
+    }
+  });
+
+// Import wizard command
+program
+  .command('import')
+  .description('Import memories from developer artifacts (smart import wizard)')
+  .option('-s, --source <type>', 'Single source: cursorrules, claude, package, git, ssh, shell, obsidian, env')
+  .option('--dry-run', 'Preview without committing')
+  .option('-n, --namespace <name>', 'Override namespace for imported memories')
+  .option('--config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      const { runWizard } = await import('../src/import/wizard.js');
+      await runWizard({
+        source: options.source,
+        dryRun: options.dryRun,
+        namespace: options.namespace,
+        config: options.config
+      });
+    } catch (error) {
+      const f = await loadFormat();
+      f.error(`Import error: ${error.message}`);
       process.exit(1);
     }
   });