agent-working-memory 0.5.6 → 0.6.0

package/src/cli.ts

@@ -15,7 +15,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, basename, join, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { randomBytes, randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { homedir as osHomedir } from 'node:os';
 
@@ -50,6 +50,13 @@ Usage:
   awm mcp                                           Start MCP server (used by Claude Code)
   awm serve [--port <port>]                         Start HTTP API server
   awm health [--port <port>]                        Check server health
+  awm export --db <path> [--agent <id>] [--output <file>] [--active-only]
+                                                    Export memories to JSON
+  awm import <file> --db <path> [--remap-agent <id>] [--dedupe] [--dry-run]
+                                                    Import memories from JSON
+  awm merge --target <db> --source <db> [--source ...]
+            [--remap uuid=name] [--remap-all-uuids <name>]
+            [--dedupe] [--dry-run]                  Merge multiple memory DBs
 
 Setup:
   awm setup --global     Recommended. Writes ~/.mcp.json so AWM is available
@@ -370,6 +377,443 @@ function health() {
   }
 }
 
+// ─── EXPORT ──────────────────────────────────────
+
+async function exportMemories() {
+  let dbPath = '';
+  let agentFilter: string | null = null;
+  let outputPath: string | null = null;
+  let activeOnly = false;
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--db' && args[i + 1]) dbPath = args[++i];
+    else if (args[i] === '--agent' && args[i + 1]) agentFilter = args[++i];
+    else if (args[i] === '--output' && args[i + 1]) outputPath = args[++i];
+    else if (args[i] === '--active-only') activeOnly = true;
+  }
+
+  if (!dbPath) {
+    console.error('Error: --db <path> is required');
+    process.exit(1);
+  }
+
+  if (!existsSync(dbPath)) {
+    console.error(`Error: database not found: ${dbPath}`);
+    process.exit(1);
+  }
+
+  // Dynamic import to avoid loading better-sqlite3 for other commands
+  const Database = (await import('better-sqlite3')).default;
+  const db = new Database(dbPath, { readonly: true });
+
+  // Build memory query
+  let memQuery = 'SELECT * FROM engrams';
+  const conditions: string[] = [];
+  const params: any[] = [];
+
+  if (agentFilter) {
+    conditions.push('agent_id = ?');
+    params.push(agentFilter);
+  }
+  if (activeOnly) {
+    conditions.push('retracted = 0');
+  }
+
+  if (conditions.length > 0) {
+    memQuery += ' WHERE ' + conditions.join(' AND ');
+  }
+  memQuery += ' ORDER BY created_at ASC';
+
+  const rows = db.prepare(memQuery).all(...params) as any[];
+
+  // Build memory objects (exclude embedding blobs)
+  const memories = rows.map((r: any) => ({
+    id: r.id,
+    agent_id: r.agent_id,
+    concept: r.concept,
+    content: r.content,
+    confidence: r.confidence,
+    salience: r.salience,
+    access_count: r.access_count,
+    last_accessed: r.last_accessed,
+    created_at: r.created_at,
+    stage: r.stage,
+    tags: r.tags ? JSON.parse(r.tags) : [],
+    memory_class: r.memory_class ?? 'working',
+    episode_id: r.episode_id ?? null,
+    task_status: r.task_status ?? null,
+    task_priority: r.task_priority ?? null,
+    supersedes: r.supersedes ?? null,
+    superseded_by: r.superseded_by ?? null,
+    retracted: r.retracted ?? 0,
+  }));
+
+  // Get memory IDs for association filtering
+  const memIds = new Set(memories.map((m: any) => m.id));
+
+  // Build associations
+  let assocQuery = 'SELECT * FROM associations';
+  const allAssocs = db.prepare(assocQuery).all() as any[];
+  const associations = allAssocs
+    .filter((a: any) => memIds.has(a.from_engram_id) && memIds.has(a.to_engram_id))
+    .map((a: any) => ({
+      from_id: a.from_engram_id,
+      to_id: a.to_engram_id,
+      weight: a.weight,
+      type: a.type ?? 'hebbian',
+      activation_count: a.activation_count ?? 0,
+    }));
+
+  // Collect unique agents
+  const agents = [...new Set(memories.map((m: any) => m.agent_id))];
+
+  const exportData = {
+    version: '0.6.0',
+    exported_at: new Date().toISOString(),
+    source_db: dbPath,
+    agent_filter: agentFilter,
+    memories,
+    associations,
+    stats: {
+      total_memories: memories.length,
+      total_associations: associations.length,
+      agents,
+    },
+  };
+
+  const json = JSON.stringify(exportData, null, 2);
+
+  if (outputPath) {
+    writeFileSync(outputPath, json + '\n');
+    console.error(`Exported ${memories.length} memories, ${associations.length} associations → ${outputPath}`);
+  } else {
+    process.stdout.write(json + '\n');
+  }
+
+  db.close();
+}
+
+// ─── IMPORT ──────────────────────────────────────
+
+async function importMemories() {
+  let filePath = '';
+  let dbPath = '';
+  let remapAgent: string | null = null;
+  let dedupe = false;
+  let dryRun = false;
+  let includeRetracted = false;
+
+  // First non-flag arg after 'import' is the file path
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--db' && args[i + 1]) dbPath = args[++i];
+    else if (args[i] === '--remap-agent' && args[i + 1]) remapAgent = args[++i];
+    else if (args[i] === '--dedupe') dedupe = true;
+    else if (args[i] === '--dry-run') dryRun = true;
+    else if (args[i] === '--include-retracted') includeRetracted = true;
+    else if (!args[i].startsWith('--') && !filePath) filePath = args[i];
+  }
+
+  if (!filePath) {
+    console.error('Error: <file> is required');
+    process.exit(1);
+  }
+  if (!dbPath) {
+    console.error('Error: --db <path> is required');
+    process.exit(1);
+  }
+  if (!existsSync(filePath)) {
+    console.error(`Error: import file not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  const importData = JSON.parse(readFileSync(filePath, 'utf-8'));
+  if (!importData.memories || !Array.isArray(importData.memories)) {
+    console.error('Error: invalid export file — missing memories array');
+    process.exit(1);
+  }
+
+  const Database = (await import('better-sqlite3')).default;
+  const db = new Database(dbPath);
+
+  // Ensure tables exist in target
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS engrams (
+      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
+      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
+      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
+      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
+      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
+      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]',
+      episode_id TEXT, task_status TEXT, task_priority TEXT, blocked_by TEXT,
+      memory_class TEXT NOT NULL DEFAULT 'working', superseded_by TEXT, supersedes TEXT
+    );
+    CREATE TABLE IF NOT EXISTS associations (
+      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
+      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL, last_activated TEXT
+    );
+  `);
+
+  // Build dedup set if needed
+  const existingHashes = new Set<string>();
+  if (dedupe) {
+    const existing = db.prepare('SELECT concept, content FROM engrams').all() as any[];
+    for (const row of existing) {
+      const hash = (row.concept ?? '').toLowerCase().trim() + '||' + (row.content ?? '').toLowerCase().trim();
+      existingHashes.add(hash);
+    }
+  }
+  const idMap = new Map<string, string>();
+  let imported = 0;
+  let skippedDupes = 0;
+  let skippedRetracted = 0;
+
+  const insertMem = db.prepare(`
+    INSERT INTO engrams (id, agent_id, concept, content, confidence, salience,
+      access_count, last_accessed, created_at, stage, tags, memory_class,
+      episode_id, task_status, task_priority, supersedes, superseded_by, retracted)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertAssoc = db.prepare(`
+    INSERT INTO associations (id, from_engram_id, to_engram_id, weight, type, activation_count, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+  `);
+
+  const importTx = db.transaction(() => {
+    // Import memories
+    for (const mem of importData.memories) {
+      // Skip retracted unless --include-retracted
+      if (mem.retracted && !includeRetracted) {
+        skippedRetracted++;
+        continue;
+      }
+
+      // Dedupe check
+      if (dedupe) {
+        const hash = (mem.concept ?? '').toLowerCase().trim() + '||' + (mem.content ?? '').toLowerCase().trim();
+        if (existingHashes.has(hash)) {
+          skippedDupes++;
+          continue;
+        }
+      }
+
+      const newId = randomUUID();
+      idMap.set(mem.id, newId);
+
+      const agentId = remapAgent ?? mem.agent_id;
+      const tags = Array.isArray(mem.tags) ? JSON.stringify(mem.tags) : (mem.tags ?? '[]');
+
+      if (!dryRun) {
+        insertMem.run(
+          newId, agentId, mem.concept, mem.content,
+          mem.confidence ?? 0.5, mem.salience ?? 0.5,
+          mem.access_count ?? 0, mem.last_accessed ?? mem.created_at,
+          mem.created_at, mem.stage ?? 'active', tags,
+          mem.memory_class ?? 'working', mem.episode_id ?? null,
+          mem.task_status ?? null, mem.task_priority ?? null,
+          mem.supersedes ?? null, mem.superseded_by ?? null,
+          mem.retracted ?? 0
+        );
+      }
+      imported++;
+    }
+
+    // Import associations (using remapped IDs)
+    let assocImported = 0;
+    const associations = importData.associations ?? [];
+    for (const assoc of associations) {
+      const fromId = idMap.get(assoc.from_id);
+      const toId = idMap.get(assoc.to_id);
+      if (!fromId || !toId) continue; // skip if either memory was skipped
+
+      if (!dryRun) {
+        insertAssoc.run(
+          randomUUID(), fromId, toId,
+          assoc.weight ?? 0.5, assoc.type ?? 'hebbian',
+          assoc.activation_count ?? 0
+        );
+      }
+      assocImported++;
+    }
+
+    return assocImported;
+  });
+
+  const assocCount = importTx();
+
+  const prefix = dryRun ? '[DRY RUN] Would import' : 'Imported';
+  console.log(`${prefix} ${imported} memories, ${assocCount} associations` +
+    (skippedDupes > 0 ? `, ${skippedDupes} skipped (dupes)` : '') +
+    (skippedRetracted > 0 ? `, ${skippedRetracted} skipped (retracted)` : '') +
+    (remapAgent ? ` (agent remapped to: ${remapAgent})` : ''));
+
+  db.close();
+}
+
+// ─── MERGE ──────────────────────────────────────
+
+async function mergeMemories() {
+  const Database = (await import('better-sqlite3')).default;
+  const { createHash, randomUUID } = await import('node:crypto');
+
+  let target = '';
+  const sources: string[] = [];
+  const remapEntries = new Map<string, string>();
+  let remapAllUuids = '';
+  let dedupe = false;
+  let dryRun = false;
+
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--target' && args[i + 1]) {
+      target = args[++i];
+    } else if (args[i] === '--source' && args[i + 1]) {
+      sources.push(args[++i]);
+    } else if (args[i] === '--remap' && args[i + 1]) {
+      const val = args[++i];
+      const eqIdx = val.indexOf('=');
+      if (eqIdx > 0) remapEntries.set(val.slice(0, eqIdx), val.slice(eqIdx + 1));
+    } else if (args[i] === '--remap-all-uuids' && args[i + 1]) {
+      remapAllUuids = args[++i];
+    } else if (args[i] === '--dedupe') {
+      dedupe = true;
+    } else if (args[i] === '--dry-run') {
+      dryRun = true;
+    }
+  }
+
+  if (!target || sources.length === 0) {
+    console.error('Usage: awm merge --target <path> --source <path> [--source <path>...] [--remap uuid=name] [--remap-all-uuids name] [--dedupe] [--dry-run]');
+    process.exit(1);
+  }
+
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+  function remapAgentId(agentId: string): string {
+    if (remapEntries.has(agentId)) return remapEntries.get(agentId)!;
+    if (remapAllUuids && UUID_RE.test(agentId)) return remapAllUuids;
+    return agentId;
+  }
+
+  function contentHash(concept: string, content: string): string {
+    return createHash('sha256').update((concept + '\n' + content).toLowerCase().trim()).digest('hex');
+  }
+
+  console.log(`Target: ${target}${dryRun ? ' (DRY RUN)' : ''}`);
+
+  const targetDb = new Database(target);
+  targetDb.pragma('journal_mode = WAL');
+  targetDb.pragma('foreign_keys = ON');
+
+  // Ensure tables exist in target
+  targetDb.exec(`
+    CREATE TABLE IF NOT EXISTS engrams (
+      id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, concept TEXT NOT NULL, content TEXT NOT NULL,
+      embedding BLOB, confidence REAL NOT NULL DEFAULT 0.5, salience REAL NOT NULL DEFAULT 0.5,
+      access_count INTEGER NOT NULL DEFAULT 0, last_accessed TEXT NOT NULL, created_at TEXT NOT NULL,
+      salience_features TEXT NOT NULL DEFAULT '{}', reason_codes TEXT NOT NULL DEFAULT '[]',
+      stage TEXT NOT NULL DEFAULT 'active', ttl INTEGER, retracted INTEGER NOT NULL DEFAULT 0,
+      retracted_by TEXT, retracted_at TEXT, tags TEXT NOT NULL DEFAULT '[]'
+    );
+    CREATE TABLE IF NOT EXISTS associations (
+      id TEXT PRIMARY KEY, from_engram_id TEXT NOT NULL, to_engram_id TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.1, confidence REAL NOT NULL DEFAULT 0.5,
+      type TEXT NOT NULL DEFAULT 'hebbian', activation_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL, last_activated TEXT NOT NULL
+    );
+  `);
+
+  // Build dedupe hash set from existing target memories
+  const existingHashes = new Set<string>();
+  if (dedupe) {
+    const rows = targetDb.prepare('SELECT concept, content FROM engrams').all() as { concept: string; content: string }[];
+    for (const row of rows) existingHashes.add(contentHash(row.concept, row.content));
+    console.log(`Target has ${existingHashes.size} unique memories (for dedupe)\n`);
+  }
+
+  const insertEngram = targetDb.prepare(`
+    INSERT OR IGNORE INTO engrams (id, agent_id, concept, content, confidence, salience, access_count,
+      last_accessed, created_at, salience_features, reason_codes, stage, ttl,
+      retracted, retracted_by, retracted_at, tags)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const insertAssoc = targetDb.prepare(`
+    INSERT OR IGNORE INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type,
+      activation_count, created_at, last_activated)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  let totalMemories = 0, totalAssociations = 0, totalSkipped = 0;
+
+  for (const sourcePath of sources) {
+    if (!existsSync(sourcePath)) {
+      console.error(`  Source not found: ${sourcePath}`);
+      continue;
+    }
+
+    const sourceDb = new Database(sourcePath, { readonly: true });
+    const engrams = sourceDb.prepare(
+      `SELECT id, agent_id, concept, content, confidence, salience, access_count,
+        last_accessed, created_at, salience_features, reason_codes, stage, ttl,
+        retracted, retracted_by, retracted_at, tags FROM engrams`
+    ).all() as any[];
+    const assocs = sourceDb.prepare(
+      `SELECT id, from_engram_id, to_engram_id, weight, confidence, type,
+        activation_count, created_at, last_activated FROM associations`
+    ).all() as any[];
+
+    const idMap = new Map<string, string>();
+    const skippedIds = new Set<string>();
+
+    const result = targetDb.transaction(() => {
+      let imported = 0, skipped = 0;
+      for (const e of engrams) {
+        const hash = contentHash(e.concept, e.content);
+        if (dedupe && existingHashes.has(hash)) { skippedIds.add(e.id); skipped++; continue; }
+        const newId = randomUUID();
+        idMap.set(e.id, newId);
+        existingHashes.add(hash);
+        if (!dryRun) {
+          insertEngram.run(newId, remapAgentId(e.agent_id), e.concept, e.content, e.confidence,
+            e.salience, e.access_count, e.last_accessed, e.created_at, e.salience_features,
+            e.reason_codes, e.stage, e.ttl, e.retracted, e.retracted_by, e.retracted_at, e.tags);
+        }
+        imported++;
+      }
+      let assocImported = 0;
+      for (const a of assocs) {
+        if (skippedIds.has(a.from_engram_id) || skippedIds.has(a.to_engram_id)) continue;
+        const fromId = idMap.get(a.from_engram_id);
+        const toId = idMap.get(a.to_engram_id);
+        if (!fromId || !toId) continue;
+        if (!dryRun) {
+          insertAssoc.run(randomUUID(), fromId, toId, a.weight, a.confidence, a.type,
+            a.activation_count, a.created_at, a.last_activated);
+        }
+        assocImported++;
+      }
+      return { imported, skipped, assocImported };
+    })();
+
+    sourceDb.close();
+
+    const agentSet = new Set(engrams.map((e: any) => remapAgentId(e.agent_id)));
+    console.log(`  Source: ${sourcePath}`);
+    console.log(`    Engrams: ${engrams.length} total, ${result.imported} imported, ${result.skipped} skipped`);
+    console.log(`    Associations: ${assocs.length} total, ${result.assocImported} imported`);
+    console.log(`    Agents: ${agentSet.size} (${[...agentSet].slice(0, 5).join(', ')}${agentSet.size > 5 ? '...' : ''})\n`);
+
+    totalMemories += result.imported;
+    totalAssociations += result.assocImported;
+    totalSkipped += result.skipped;
+  }
+
+  targetDb.close();
+  console.log(`\nTotal: ${totalMemories} memories, ${totalAssociations} associations imported. ${totalSkipped} skipped.`);
+  if (dryRun) console.log('(dry run — no data written)');
+}
+
 // ─── Dispatch ──────────────────────────────────────
 
 switch (command) {
@@ -385,6 +829,15 @@ switch (command) {
   case 'health':
     health();
     break;
+  case 'export':
+    exportMemories();
+    break;
+  case 'import':
+    importMemories();
+    break;
+  case 'merge':
+    mergeMemories();
+    break;
   case '--help':
   case '-h':
   case undefined:

package/src/coordination/mcp-tools.ts

@@ -27,14 +27,19 @@ export function registerCoordinationTools(server: McpServer, db: Database.Databa
     async ({ agent_name, role, pid, capabilities, workspace }) => {
       const capsJson = capabilities ? JSON.stringify(capabilities) : null;
 
+      // Look up ANY existing agent with same name+workspace — including dead ones (upsert, reuse UUID)
       const existing = workspace
-        ? db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? AND status != 'dead'`).get(agent_name, workspace) as { id: string; status: string } | undefined
-        : db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL AND status != 'dead'`).get(agent_name) as { id: string; status: string } | undefined;
+        ? db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? ORDER BY last_seen DESC LIMIT 1`).get(agent_name, workspace) as { id: string; status: string } | undefined
+        : db.prepare(`SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL ORDER BY last_seen DESC LIMIT 1`).get(agent_name) as { id: string; status: string } | undefined;
 
       if (existing) {
-        db.prepare(`UPDATE coord_agents SET last_seen = datetime('now'), pid = COALESCE(?, pid), capabilities = COALESCE(?, capabilities) WHERE id = ?`).run(pid ?? null, capsJson, existing.id);
-        db.prepare(`INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, 'heartbeat', ?)`).run(existing.id, `heartbeat from ${agent_name}`);
-        return { content: [{ type: 'text' as const, text: JSON.stringify({ agentId: existing.id, action: 'heartbeat', status: existing.status }) }] };
+        const wasDead = existing.status === 'dead';
+        db.prepare(`UPDATE coord_agents SET last_seen = datetime('now'), status = CASE WHEN status = 'dead' THEN 'idle' ELSE status END, pid = COALESCE(?, pid), capabilities = COALESCE(?, capabilities) WHERE id = ?`).run(pid ?? null, capsJson, existing.id);
+        const action = wasDead ? 'reconnected' : 'heartbeat';
+        const eventType = wasDead ? 'reconnected' : 'heartbeat';
+        const detail = wasDead ? `${agent_name} reconnected via MCP (was dead)` : `heartbeat from ${agent_name}`;
+        db.prepare(`INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, ?, ?)`).run(existing.id, eventType, detail);
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ agentId: existing.id, action, status: wasDead ? 'idle' : existing.status }) }] };
       }
 
       const id = randomUUID();