@aitytech/agentkits-memory 1.0.0 → 2.0.0

package/src/cli/setup.ts

@@ -2,14 +2,18 @@
 /**
  * AgentKits Memory Setup CLI
  *
- * Sets up memory hooks in a project's .claude/settings.json
+ * Sets up memory hooks, MCP server, and downloads embedding model.
+ * Supports multiple AI tools: Claude Code, Cursor, Windsurf, etc.
  *
  * Usage:
  *   npx agentkits-memory-setup [options]
  *
  * Options:
  *   --project-dir=X   Project directory (default: cwd)
- *   --force           Overwrite existing hooks
+ *   --force           Overwrite existing configuration
+ *   --skip-model      Skip embedding model download
+ *   --skip-mcp        Skip MCP server configuration
+ *   --show-hooks      Show full hooks JSON for manual configuration
  *   --json            Output result as JSON
  *
  * @module @agentkits/memory/cli/setup
@@ -17,6 +21,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { LocalEmbeddingsService } from '../embeddings/local-embeddings.js';
 
 const args = process.argv.slice(2);
 
@@ -27,6 +32,8 @@ interface HookEntry {
 
 interface HooksConfig {
   SessionStart?: HookEntry[];
+  UserPromptSubmit?: HookEntry[];
+  PostToolUse?: HookEntry[];
   Stop?: HookEntry[];
   PreCompact?: HookEntry[];
   [key: string]: HookEntry[] | undefined;
@@ -34,10 +41,36 @@ interface HooksConfig {
 
 interface ClaudeSettings {
   hooks?: HooksConfig;
+  mcpServers?: Record<string, McpServerConfig>;
   [key: string]: unknown;
 }
 
+interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+interface McpConfig {
+  mcpServers: Record<string, McpServerConfig>;
+}
+
+const MEMORY_MCP_SERVER: McpServerConfig = {
+  command: 'npx',
+  args: ['-y', 'agentkits-memory-server'],
+};
+
+/**
+ * Memory hooks for Claude Code lifecycle events
+ *
+ * Hook Events:
+ * - SessionStart: Load memory context at session start
+ * - UserPromptSubmit: Capture user intent when prompt submitted
+ * - PostToolUse: Capture observations after tool execution (Edit, Write, Bash, Task)
+ * - Stop: Generate summary when session ends
+ */
 const MEMORY_HOOKS: HooksConfig = {
+  // Load memory context at session start
   SessionStart: [
     {
       matcher: '',
@@ -45,11 +78,42 @@ const MEMORY_HOOKS: HooksConfig = {
         {
           type: 'command',
           command: 'npx --yes agentkits-memory-hook context',
+          timeout: 15,
+        },
+      ],
+    },
+  ],
+
+  // Capture user intent when prompt submitted
+  UserPromptSubmit: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: 'npx --yes agentkits-memory-hook session-init',
           timeout: 10,
         },
       ],
     },
   ],
+
+  // Capture observations after tool execution
+  // Only track meaningful tools: Edit, Write, Bash, Task
+  PostToolUse: [
+    {
+      matcher: 'Edit|Write|Bash|Task',
+      hooks: [
+        {
+          type: 'command',
+          command: 'npx --yes agentkits-memory-hook observation',
+          timeout: 15,
+        },
+      ],
+    },
+  ],
+
+  // Generate summary when session ends
   Stop: [
     {
       matcher: '',
@@ -57,7 +121,7 @@ const MEMORY_HOOKS: HooksConfig = {
         {
           type: 'command',
           command: 'npx --yes agentkits-memory-hook summarize',
-          timeout: 10,
+          timeout: 15,
         },
       ],
     },
@@ -81,37 +145,222 @@ function parseArgs(): Record<string, string | boolean> {
   return parsed;
 }
 
+interface MergeResult {
+  merged: HooksConfig;
+  added: string[];
+  skipped: string[];
+  manualRequired: string[];
+}
+
+/**
+ * Merge memory hooks with existing hooks configuration
+ * Always preserves existing hooks, never overwrites
+ */
 function mergeHooks(
   existing: HooksConfig | undefined,
   newHooks: HooksConfig,
   force: boolean
-): HooksConfig {
-  if (!existing || force) {
-    return { ...existing, ...newHooks };
+): MergeResult {
+  const result: MergeResult = {
+    merged: { ...existing },
+    added: [],
+    skipped: [],
+    manualRequired: [],
+  };
+
+  // If no existing hooks, add all memory hooks
+  if (!existing) {
+    result.merged = { ...newHooks };
+    result.added = Object.keys(newHooks);
+    return result;
   }
 
-  const merged: HooksConfig = { ...existing };
+  for (const [event, memoryHooks] of Object.entries(newHooks)) {
+    if (!memoryHooks) continue;
 
-  for (const [event, hooks] of Object.entries(newHooks)) {
-    if (!hooks) continue;
+    const existingHooks = result.merged[event];
 
-    const existingHooks = merged[event];
+    // Case 1: No existing hooks for this event → add ours
     if (!existingHooks) {
-      merged[event] = hooks;
-    } else {
-      // Check if memory hook already exists
-      const hasMemoryHook = existingHooks.some((h: HookEntry) =>
-        h.hooks.some((hook) => hook.command.includes('agentkits-memory'))
+      result.merged[event] = memoryHooks;
+      result.added.push(event);
+      continue;
+    }
+
+    // Case 2: Check if our memory hook already exists
+    const hasMemoryHook = existingHooks.some((h: HookEntry) =>
+      h.hooks.some((hook) => hook.command.includes('agentkits-memory'))
+    );
+
+    if (hasMemoryHook) {
+      if (force) {
+        // Remove old memory hooks, add new ones
+        const filtered = existingHooks.filter(
+          (h: HookEntry) => !h.hooks.some((hook) => hook.command.includes('agentkits-memory'))
+        );
+        result.merged[event] = [...filtered, ...memoryHooks];
+        result.added.push(`${event} (updated)`);
+      } else {
+        result.skipped.push(`${event} (already configured)`);
+      }
+      continue;
+    }
+
+    // Case 3: PostToolUse with different matcher - needs attention
+    if (event === 'PostToolUse') {
+      const ourMatcher = memoryHooks[0]?.matcher || '';
+      const existingMatchers = existingHooks.map((h: HookEntry) => h.matcher || '');
+
+      // Check for potential conflicts (different matchers that might overlap)
+      const hasConflict = existingMatchers.some(
+        (m) => m && m !== ourMatcher && (m === '*' || ourMatcher.split('|').some((t) => m.includes(t)))
       );
 
-      if (!hasMemoryHook) {
-        // Append memory hooks
-        merged[event] = [...existingHooks, ...hooks];
+      if (hasConflict) {
+        // Add anyway but warn user
+        result.merged[event] = [...existingHooks, ...memoryHooks];
+        result.added.push(event);
+        result.manualRequired.push(
+          `PostToolUse: Added with matcher "${ourMatcher}", existing has different matchers - verify no conflicts`
+        );
+        continue;
       }
     }
+
+    // Case 4: Append our hooks to existing
+    result.merged[event] = [...existingHooks, ...memoryHooks];
+    result.added.push(event);
   }
 
-  return merged;
+  return result;
+}
+
+/**
+ * Configure MCP server for different AI tools
+ * Creates/updates config files for: Claude Code, Cursor, Windsurf, etc.
+ */
+function configureMcp(
+  projectDir: string,
+  claudeSettings: ClaudeSettings,
+  force: boolean,
+  asJson: boolean
+): { configured: string[]; skipped: string[] } {
+  const configured: string[] = [];
+  const skipped: string[] = [];
+
+  // 1. Add to Claude Code settings.json (mcpServers key)
+  // Always merge with existing servers, never overwrite
+  if (!claudeSettings.mcpServers) {
+    claudeSettings.mcpServers = {};
+  }
+
+  if (!claudeSettings.mcpServers.memory || force) {
+    claudeSettings.mcpServers.memory = MEMORY_MCP_SERVER;
+    configured.push('Claude Code (.claude/settings.json)');
+  } else {
+    skipped.push('Claude Code (already configured)');
+  }
+
+  // 2. Create/update root .mcp.json for other tools (Cursor, Windsurf, Claude Code, etc.)
+  // Always merge with existing servers, never overwrite
+  const mcpJsonPath = path.join(projectDir, '.mcp.json');
+  try {
+    let existing: McpConfig = { mcpServers: {} };
+
+    // Load existing config if present
+    if (fs.existsSync(mcpJsonPath)) {
+      try {
+        existing = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8')) as McpConfig;
+        existing.mcpServers = existing.mcpServers || {};
+      } catch {
+        // If parse fails, start fresh but warn
+        if (!asJson) {
+          console.warn('   ⚠ .mcp.json parse error, creating new config');
+        }
+        existing = { mcpServers: {} };
+      }
+    }
+
+    // Add or update memory server
+    if (!existing.mcpServers.memory || force) {
+      existing.mcpServers.memory = MEMORY_MCP_SERVER;
+      fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2));
+      configured.push('Universal (.mcp.json)');
+    } else {
+      skipped.push('.mcp.json (already configured)');
+    }
+  } catch (error) {
+    skipped.push(`.mcp.json (error: ${error instanceof Error ? error.message : 'unknown'})`);
+  }
+
+  if (!asJson && configured.length > 0) {
+    console.log('\n🔌 MCP Server configured for:');
+    for (const tool of configured) {
+      console.log(`   ✓ ${tool}`);
+    }
+  }
+
+  return { configured, skipped };
+}
+
+async function downloadModel(cacheDir: string, asJson: boolean): Promise<boolean> {
+  if (!asJson) {
+    console.log('\n📥 Downloading embedding model...');
+    console.log('   Model: multilingual-e5-small (~470MB)');
+    console.log('   This enables semantic search in 100+ languages.\n');
+  }
+
+  try {
+    const embeddingsService = new LocalEmbeddingsService({
+      showProgress: !asJson,
+      cacheDir: path.join(cacheDir, 'embeddings-cache'),
+    });
+
+    await embeddingsService.initialize();
+
+    // Verify model works with a test embedding
+    const testResult = await embeddingsService.embed('Test embedding');
+
+    if (testResult.embedding.length !== 384) {
+      throw new Error(`Unexpected embedding dimension: ${testResult.embedding.length}`);
+    }
+
+    if (!asJson) {
+      console.log('   ✓ Model downloaded and verified\n');
+    }
+
+    return true;
+  } catch (error) {
+    if (!asJson) {
+      console.error('   ⚠ Model download failed:', error instanceof Error ? error.message : error);
+      console.log('   Model will be downloaded on first use.\n');
+    }
+    return false;
+  }
+}
+
+/**
+ * Print full hooks configuration for manual setup
+ */
+function printHooksConfig(): void {
+  console.log('\n' + '━'.repeat(60));
+  console.log('📋 MEMORY HOOKS CONFIGURATION\n');
+  console.log('Copy and paste this JSON into your settings file.\n');
+
+  console.log('For Claude Code: .claude/settings.json');
+  console.log('─'.repeat(40));
+  console.log(JSON.stringify({ hooks: MEMORY_HOOKS }, null, 2));
+
+  console.log('\nFor Cursor/Windsurf: .cursor/mcp.json or settings');
+  console.log('─'.repeat(40));
+  console.log('Add hooks section with the same configuration above.\n');
+
+  console.log('Hook Events:');
+  console.log('  • SessionStart    - Load memory context when session begins');
+  console.log('  • UserPromptSubmit - Capture user intent on each prompt');
+  console.log('  • PostToolUse     - Record actions (Edit, Write, Bash, Task)');
+  console.log('  • Stop            - Generate summary when session ends');
+  console.log('━'.repeat(60) + '\n');
 }
 
 async function main() {
@@ -119,12 +368,25 @@ async function main() {
   const projectDir = (options['project-dir'] as string) || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const force = !!options.force;
   const asJson = !!options.json;
+  const skipModel = !!options['skip-model'];
+  const skipMcp = !!options['skip-mcp'];
+  const showHooks = !!options['show-hooks'];
+
+  // Just show hooks config and exit
+  if (showHooks) {
+    printHooksConfig();
+    return;
+  }
 
   const claudeDir = path.join(projectDir, '.claude');
   const settingsPath = path.join(claudeDir, 'settings.json');
   const memoryDir = path.join(claudeDir, 'memory');
 
   try {
+    if (!asJson) {
+      console.log('\n🧠 AgentKits Memory Setup\n');
+    }
+
     // Create directories
     if (!fs.existsSync(claudeDir)) {
       fs.mkdirSync(claudeDir, { recursive: true });
@@ -141,49 +403,98 @@ async function main() {
     }
 
     // Merge hooks
-    settings.hooks = mergeHooks(settings.hooks, MEMORY_HOOKS, force);
+    const hooksResult = mergeHooks(settings.hooks, MEMORY_HOOKS, force);
+    settings.hooks = hooksResult.merged;
+
+    // Configure MCP server
+    let mcpResult = { configured: [] as string[], skipped: [] as string[] };
+    if (!skipMcp) {
+      mcpResult = configureMcp(projectDir, settings, force, asJson);
+    }
 
     // Write settings
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
 
-    // Create initial memory files if they don't exist
-    const activeContextPath = path.join(memoryDir, 'active-context.md');
-    if (!fs.existsSync(activeContextPath)) {
-      fs.writeFileSync(
-        activeContextPath,
-        `# Active Context
-
-**Task**: None
-**Status**: Ready
-**Updated**: ${new Date().toISOString()}
-
-## Current Focus
-
-No active task.
-
-## Notes
-
-Memory system initialized.
-`
-      );
+    // Download embedding model
+    let modelDownloaded = false;
+    if (!skipModel) {
+      modelDownloaded = await downloadModel(memoryDir, asJson);
     }
 
     const result = {
       success: true,
       settingsPath,
       memoryDir,
-      hooksAdded: Object.keys(MEMORY_HOOKS),
-      message: 'Memory hooks configured successfully',
+      hooksAdded: hooksResult.added,
+      hooksSkipped: hooksResult.skipped,
+      hooksManualRequired: hooksResult.manualRequired,
+      mcpConfigured: mcpResult.configured,
+      modelDownloaded,
+      message: 'Memory setup complete',
     };
 
     if (asJson) {
       console.log(JSON.stringify(result, null, 2));
     } else {
-      console.log('\n✅ AgentKits Memory Setup Complete\n');
-      console.log(`Settings: ${settingsPath}`);
-      console.log(`Memory:   ${memoryDir}`);
-      console.log(`\nHooks added: ${result.hooksAdded.join(', ')}`);
-      console.log('\nRestart Claude Code to activate memory hooks.\n');
+      console.log('✅ Setup Complete\n');
+      console.log(`📁 Settings: ${settingsPath}`);
+      console.log(`📁 Memory:   ${memoryDir}`);
+
+      // Show hooks status
+      if (hooksResult.added.length > 0) {
+        console.log(`\n📋 Hooks added: ${hooksResult.added.join(', ')}`);
+      }
+      if (hooksResult.skipped.length > 0) {
+        console.log(`   Skipped: ${hooksResult.skipped.join(', ')}`);
+      }
+
+      // Show manual action required
+      if (hooksResult.manualRequired.length > 0) {
+        console.log('\n⚠️  Manual review recommended:');
+        for (const msg of hooksResult.manualRequired) {
+          console.log(`   • ${msg}`);
+        }
+      }
+
+      // Model status
+      if (modelDownloaded) {
+        console.log('\n📦 Model: Downloaded and ready');
+      } else if (skipModel) {
+        console.log('\n📦 Model: Skipped (will download on first use)');
+      }
+
+      console.log('\n👉 Restart your AI tool to activate.');
+      console.log('💡 Open web viewer: npx agentkits-memory-web');
+      console.log('📋 Show hooks config: npx agentkits-memory-setup --show-hooks\n');
+
+      // Show manual hook instructions if some hooks couldn't be added
+      const allHookEvents = Object.keys(MEMORY_HOOKS);
+      const addedEvents = hooksResult.added.map((h) => h.replace(/ \(.*\)$/, ''));
+      const missingEvents = allHookEvents.filter(
+        (e) => !addedEvents.includes(e) && !hooksResult.skipped.some((s) => s.startsWith(e))
+      );
+
+      if (missingEvents.length > 0) {
+        console.log('━'.repeat(60));
+        console.log('📝 MANUAL SETUP REQUIRED\n');
+        console.log(`Some hooks could not be auto-configured.`);
+        console.log(`Missing: ${missingEvents.join(', ')}\n`);
+        console.log(`To add manually:`);
+        console.log(`1. Open: ${settingsPath}`);
+        console.log(`2. Add/merge the following into the "hooks" section:\n`);
+
+        // Generate copy-paste JSON for missing hooks only
+        const missingHooksJson: Record<string, HookEntry[]> = {};
+        for (const event of missingEvents) {
+          const hookConfig = MEMORY_HOOKS[event];
+          if (hookConfig) {
+            missingHooksJson[event] = hookConfig;
+          }
+        }
+
+        console.log(JSON.stringify(missingHooksJson, null, 2));
+        console.log('\n━'.repeat(60));
+      }
     }
   } catch (error) {
     const result = {

package/src/cli/viewer.ts

@@ -20,8 +20,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { createRequire } from 'node:module';
-import initSqlJs, { Database as SqlJsDatabase } from 'sql.js';
+import Database from 'better-sqlite3';
+import type { Database as BetterDatabase } from 'better-sqlite3';
 
 const args = process.argv.slice(2);
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -37,54 +37,45 @@ function parseArgs(): Record<string, string | boolean> {
   return parsed;
 }
 
-async function loadDatabase(): Promise<SqlJsDatabase> {
-  const require = createRequire(import.meta.url);
-  const sqlJsPath = require.resolve('sql.js');
-
-  const SQL = await initSqlJs({
-    locateFile: (file: string) => path.join(path.dirname(sqlJsPath), file),
-  });
-
+function loadDatabase(): BetterDatabase | null {
   const dbPath = path.join(projectDir, '.claude/memory/memory.db');
 
   if (fs.existsSync(dbPath)) {
-    const buffer = fs.readFileSync(dbPath);
-    return new SQL.Database(new Uint8Array(buffer));
+    return new Database(dbPath);
   } else {
     console.log(`\n📭 No database found at: ${dbPath}\n`);
     console.log('Run Claude Code with memory MCP server to create entries.');
-    process.exit(0);
+    return null;
   }
 }
 
-async function main() {
+function main() {
   const options = parseArgs();
   const limit = parseInt(options.limit as string, 10) || 20;
   const namespace = options.namespace as string | undefined;
   const asJson = !!options.json;
 
   try {
-    const db = await loadDatabase();
+    const db = loadDatabase();
+    if (!db) {
+      process.exit(0);
+    }
 
     if (options.stats) {
       // Get stats
-      const totalResult = db.exec('SELECT COUNT(*) as count FROM memory_entries');
-      const total = totalResult[0]?.values[0]?.[0] || 0;
+      const totalRow = db.prepare('SELECT COUNT(*) as count FROM memory_entries').get() as { count: number };
+      const total = totalRow?.count || 0;
 
-      const nsResult = db.exec('SELECT namespace, COUNT(*) FROM memory_entries GROUP BY namespace');
+      const nsRows = db.prepare('SELECT namespace, COUNT(*) as count FROM memory_entries GROUP BY namespace').all() as { namespace: string; count: number }[];
       const byNamespace: Record<string, number> = {};
-      if (nsResult[0]) {
-        for (const row of nsResult[0].values) {
-          byNamespace[row[0] as string] = row[1] as number;
-        }
+      for (const row of nsRows) {
+        byNamespace[row.namespace] = row.count;
       }
 
-      const typeResult = db.exec('SELECT type, COUNT(*) FROM memory_entries GROUP BY type');
+      const typeRows = db.prepare('SELECT type, COUNT(*) as count FROM memory_entries GROUP BY type').all() as { type: string; count: number }[];
       const byType: Record<string, number> = {};
-      if (typeResult[0]) {
-        for (const row of typeResult[0].values) {
-          byType[row[0] as string] = row[1] as number;
-        }
+      for (const row of typeRows) {
+        byType[row.type] = row.count;
       }
 
       if (asJson) {
@@ -107,32 +98,23 @@ async function main() {
     }
 
     if (options.export) {
-      const result = db.exec('SELECT * FROM memory_entries');
-      if (!result[0]) {
+      const rows = db.prepare('SELECT * FROM memory_entries').all() as Record<string, unknown>[];
+      if (rows.length === 0) {
         console.log('No entries to export.');
         db.close();
         return;
       }
 
-      const columns = result[0].columns;
-      const entries = result[0].values.map(row => {
-        const entry: Record<string, unknown> = {};
-        columns.forEach((col, i) => {
-          entry[col] = row[i];
-        });
-        return entry;
-      });
-
       const filename = `memory-export-${Date.now()}.json`;
-      fs.writeFileSync(filename, JSON.stringify({ entries, exportedAt: new Date().toISOString() }, null, 2));
-      console.log(`✓ Exported ${entries.length} entries to ${filename}`);
+      fs.writeFileSync(filename, JSON.stringify({ entries: rows, exportedAt: new Date().toISOString() }, null, 2));
+      console.log(`✓ Exported ${rows.length} entries to ${filename}`);
       db.close();
       return;
     }
 
     // Default: list entries
     let query = 'SELECT id, key, content, type, namespace, tags, created_at FROM memory_entries';
-    const params: string[] = [];
+    const params: (string | number)[] = [];
 
     if (namespace) {
       query += ' WHERE namespace = ?';
@@ -140,12 +122,9 @@ async function main() {
     }
 
     query += ' ORDER BY created_at DESC LIMIT ?';
-    params.push(String(limit));
+    params.push(limit);
 
-    const stmt = db.prepare(query);
-    stmt.bind(params);
-
-    const entries: Array<{
+    const entries = db.prepare(query).all(...params) as {
       id: string;
       key: string;
       content: string;
@@ -153,21 +132,7 @@ async function main() {
       namespace: string;
       tags: string;
       created_at: number;
-    }> = [];
-
-    while (stmt.step()) {
-      const row = stmt.getAsObject();
-      entries.push({
-        id: row.id as string,
-        key: row.key as string,
-        content: row.content as string,
-        type: row.type as string,
-        namespace: row.namespace as string,
-        tags: row.tags as string,
-        created_at: row.created_at as number,
-      });
-    }
-    stmt.free();
+    }[];
 
     if (entries.length === 0) {
       console.log('\n📭 No memories found in database.\n');
@@ -201,8 +166,8 @@ async function main() {
     }
 
     // Get total count
-    const countResult = db.exec('SELECT COUNT(*) FROM memory_entries');
-    const totalCount = countResult[0]?.values[0]?.[0] || entries.length;
+    const countRow = db.prepare('SELECT COUNT(*) as count FROM memory_entries').get() as { count: number };
+    const totalCount = countRow?.count || entries.length;
 
     console.log(`\nShowing ${entries.length} of ${totalCount} total entries`);
     console.log('Use --limit=N to see more, --namespace=X to filter\n');