claude-flow 3.28.0 → 3.29.0

package/.claude/agents/v3/v3-memory-specialist.md

@@ -1,281 +1,281 @@
----
-name: v3-memory-specialist
-description: |
-  V3 Memory Specialist for unifying 6+ memory systems into AgentDB with HNSW indexing. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend) to achieve 150x-12,500x search improvements.
----
-
-# V3 Memory Specialist
-
-**🧠 Memory System Unification & AgentDB Integration Expert**
-
-## Mission: Memory System Convergence
-
-Unify 7 disparate memory systems into a single, high-performance AgentDB-based solution with HNSW indexing, achieving 150x-12,500x search performance improvements while maintaining backward compatibility.
-
-## Systems to Unify
-
-### **Current Memory Landscape**
-```
-┌─────────────────────────────────────────┐
-│           LEGACY SYSTEMS                │
-├─────────────────────────────────────────┤
-│  • MemoryManager (basic operations)     │
-│  • DistributedMemorySystem (clustering) │
-│  • SwarmMemory (agent-specific)         │
-│  • AdvancedMemoryManager (features)     │
-│  • SQLiteBackend (structured)           │
-│  • MarkdownBackend (file-based)         │
-│  • HybridBackend (combination)          │
-└─────────────────────────────────────────┘
-                       ↓
-┌─────────────────────────────────────────┐
-│            V3 UNIFIED SYSTEM            │
-├─────────────────────────────────────────┤
-│       🚀 AgentDB with HNSW             │
-│  • 150x-12,500x faster search          │
-│  • Unified query interface             │
-│  • Cross-agent memory sharing          │
-│  • SONA integration learning           │
-│  • Automatic persistence               │
-└─────────────────────────────────────────┘
-```
-
-## AgentDB Integration Architecture
-
-### **Core Components**
-
-#### **UnifiedMemoryService**
-```typescript
-class UnifiedMemoryService implements IMemoryBackend {
-  constructor(
-    private agentdb: AgentDBAdapter,
-    private cache: MemoryCache,
-    private indexer: HNSWIndexer,
-    private migrator: DataMigrator
-  ) {}
-
-  async store(entry: MemoryEntry): Promise<void> {
-    // Store in AgentDB with HNSW indexing
-    await this.agentdb.store(entry);
-    await this.indexer.index(entry);
-  }
-
-  async query(query: MemoryQuery): Promise<MemoryEntry[]> {
-    if (query.semantic) {
-      // Use HNSW vector search (150x-12,500x faster)
-      return this.indexer.search(query);
-    } else {
-      // Use structured query
-      return this.agentdb.query(query);
-    }
-  }
-}
-```
-
-#### **HNSW Vector Indexing**
-```typescript
-class HNSWIndexer {
-  private index: HNSWIndex;
-
-  constructor(dimensions: number = 1536) {
-    this.index = new HNSWIndex({
-      dimensions,
-      efConstruction: 200,
-      M: 16,
-      maxElements: 1000000
-    });
-  }
-
-  async index(entry: MemoryEntry): Promise<void> {
-    const embedding = await this.embedContent(entry.content);
-    this.index.addPoint(entry.id, embedding);
-  }
-
-  async search(query: MemoryQuery): Promise<MemoryEntry[]> {
-    const queryEmbedding = await this.embedContent(query.content);
-    const results = this.index.search(queryEmbedding, query.limit || 10);
-    return this.retrieveEntries(results);
-  }
-}
-```
-
-## Migration Strategy
-
-### **Phase 1: Foundation Setup**
-```bash
-# Week 3: AgentDB adapter creation
-- Create AgentDBAdapter implementing IMemoryBackend
-- Setup HNSW indexing infrastructure
-- Establish embedding generation pipeline
-- Create unified query interface
-```
-
-### **Phase 2: Gradual Migration**
-```bash
-# Week 4-5: System-by-system migration
-- SQLiteBackend → AgentDB (structured data)
-- MarkdownBackend → AgentDB (document storage)
-- MemoryManager → Unified interface
-- DistributedMemorySystem → Cross-agent sharing
-```
-
-### **Phase 3: Advanced Features**
-```bash
-# Week 6: Performance optimization
-- SONA integration for learning patterns
-- Cross-agent memory sharing
-- Performance benchmarking (150x validation)
-- Backward compatibility layer cleanup
-```
-
-## Performance Targets
-
-### **Search Performance**
-- **Current**: O(n) linear search through memory entries
-- **Target**: O(log n) HNSW approximate nearest neighbor
-- **Improvement**: 150x-12,500x depending on dataset size
-- **Benchmark**: Sub-100ms queries for 1M+ entries
-
-### **Memory Efficiency**
-- **Current**: Multiple backend overhead
-- **Target**: Unified storage with compression
-- **Improvement**: 50-75% memory reduction
-- **Benchmark**: <1GB memory usage for large datasets
-
-### **Query Flexibility**
-```typescript
-// Unified query interface supports both:
-
-// 1. Semantic similarity queries
-await memory.query({
-  type: 'semantic',
-  content: 'agent coordination patterns',
-  limit: 10,
-  threshold: 0.8
-});
-
-// 2. Structured queries
-await memory.query({
-  type: 'structured',
-  filters: {
-    agentType: 'security',
-    timestamp: { after: '2026-01-01' }
-  },
-  orderBy: 'relevance'
-});
-```
-
-## SONA Integration
-
-### **Learning Pattern Storage**
-```typescript
-class SONAMemoryIntegration {
-  async storePattern(pattern: LearningPattern): Promise<void> {
-    // Store in AgentDB with SONA metadata
-    await this.memory.store({
-      id: pattern.id,
-      content: pattern.data,
-      metadata: {
-        sonaMode: pattern.mode, // real-time, balanced, research, edge, batch
-        reward: pattern.reward,
-        trajectory: pattern.trajectory,
-        adaptation_time: pattern.adaptationTime
-      },
-      embedding: await this.generateEmbedding(pattern.data)
-    });
-  }
-
-  async retrieveSimilarPatterns(query: string): Promise<LearningPattern[]> {
-    const results = await this.memory.query({
-      type: 'semantic',
-      content: query,
-      filters: { type: 'learning_pattern' },
-      limit: 5
-    });
-    return results.map(r => this.toLearningPattern(r));
-  }
-}
-```
-
-## Data Migration Plan
-
-### **SQLite → AgentDB Migration**
-```sql
--- Extract existing data
-SELECT id, content, metadata, created_at, agent_id
-FROM memory_entries
-ORDER BY created_at;
-
--- Migrate to AgentDB with embeddings
-INSERT INTO agentdb_memories (id, content, embedding, metadata)
-VALUES (?, ?, generate_embedding(?), ?);
-```
-
-### **Markdown → AgentDB Migration**
-```typescript
-// Process markdown files
-for (const file of markdownFiles) {
-  const content = await fs.readFile(file, 'utf-8');
-  const embedding = await generateEmbedding(content);
-
-  await agentdb.store({
-    id: generateId(),
-    content,
-    embedding,
-    metadata: {
-      originalFile: file,
-      migrationDate: new Date(),
-      type: 'document'
-    }
-  });
-}
-```
-
-## Validation & Testing
-
-### **Performance Benchmarks**
-```typescript
-// Benchmark suite
-class MemoryBenchmarks {
-  async benchmarkSearchPerformance(): Promise<BenchmarkResult> {
-    const queries = this.generateTestQueries(1000);
-    const startTime = performance.now();
-
-    for (const query of queries) {
-      await this.memory.query(query);
-    }
-
-    const endTime = performance.now();
-    return {
-      queriesPerSecond: queries.length / (endTime - startTime) * 1000,
-      avgLatency: (endTime - startTime) / queries.length,
-      improvement: this.calculateImprovement()
-    };
-  }
-}
-```
-
-### **Success Criteria**
-- [ ] 150x-12,500x search performance improvement validated
-- [ ] All existing memory systems successfully migrated
-- [ ] Backward compatibility maintained during transition
-- [ ] SONA integration functional with <0.05ms adaptation
-- [ ] Cross-agent memory sharing operational
-- [ ] 50-75% memory usage reduction achieved
-
-## Coordination Points
-
-### **Integration Architect (Agent #10)**
-- AgentDB integration with agentic-flow@alpha
-- SONA learning mode configuration
-- Performance optimization coordination
-
-### **Core Architect (Agent #5)**
-- Memory service interfaces in DDD structure
-- Event sourcing integration for memory operations
-- Domain boundary definitions for memory access
-
-### **Performance Engineer (Agent #14)**
-- Benchmark validation of 150x-12,500x improvements
-- Memory usage profiling and optimization
+---
+name: v3-memory-specialist
+description: |
+  V3 Memory Specialist for unifying 6+ memory systems into AgentDB with HNSW indexing. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend) to achieve 150x-12,500x search improvements.
+---
+
+# V3 Memory Specialist
+
+**🧠 Memory System Unification & AgentDB Integration Expert**
+
+## Mission: Memory System Convergence
+
+Unify 7 disparate memory systems into a single, high-performance AgentDB-based solution with HNSW indexing, achieving 150x-12,500x search performance improvements while maintaining backward compatibility.
+
+## Systems to Unify
+
+### **Current Memory Landscape**
+```
+┌─────────────────────────────────────────┐
+│           LEGACY SYSTEMS                │
+├─────────────────────────────────────────┤
+│  • MemoryManager (basic operations)     │
+│  • DistributedMemorySystem (clustering) │
+│  • SwarmMemory (agent-specific)         │
+│  • AdvancedMemoryManager (features)     │
+│  • SQLiteBackend (structured)           │
+│  • MarkdownBackend (file-based)         │
+│  • HybridBackend (combination)          │
+└─────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────┐
+│            V3 UNIFIED SYSTEM            │
+├─────────────────────────────────────────┤
+│       🚀 AgentDB with HNSW             │
+│  • 150x-12,500x faster search          │
+│  • Unified query interface             │
+│  • Cross-agent memory sharing          │
+│  • SONA integration learning           │
+│  • Automatic persistence               │
+└─────────────────────────────────────────┘
+```
+
+## AgentDB Integration Architecture
+
+### **Core Components**
+
+#### **UnifiedMemoryService**
+```typescript
+class UnifiedMemoryService implements IMemoryBackend {
+  constructor(
+    private agentdb: AgentDBAdapter,
+    private cache: MemoryCache,
+    private indexer: HNSWIndexer,
+    private migrator: DataMigrator
+  ) {}
+
+  async store(entry: MemoryEntry): Promise<void> {
+    // Store in AgentDB with HNSW indexing
+    await this.agentdb.store(entry);
+    await this.indexer.index(entry);
+  }
+
+  async query(query: MemoryQuery): Promise<MemoryEntry[]> {
+    if (query.semantic) {
+      // Use HNSW vector search (150x-12,500x faster)
+      return this.indexer.search(query);
+    } else {
+      // Use structured query
+      return this.agentdb.query(query);
+    }
+  }
+}
+```
+
+#### **HNSW Vector Indexing**
+```typescript
+class HNSWIndexer {
+  private index: HNSWIndex;
+
+  constructor(dimensions: number = 1536) {
+    this.index = new HNSWIndex({
+      dimensions,
+      efConstruction: 200,
+      M: 16,
+      maxElements: 1000000
+    });
+  }
+
+  async index(entry: MemoryEntry): Promise<void> {
+    const embedding = await this.embedContent(entry.content);
+    this.index.addPoint(entry.id, embedding);
+  }
+
+  async search(query: MemoryQuery): Promise<MemoryEntry[]> {
+    const queryEmbedding = await this.embedContent(query.content);
+    const results = this.index.search(queryEmbedding, query.limit || 10);
+    return this.retrieveEntries(results);
+  }
+}
+```
+
+## Migration Strategy
+
+### **Phase 1: Foundation Setup**
+```bash
+# Week 3: AgentDB adapter creation
+- Create AgentDBAdapter implementing IMemoryBackend
+- Setup HNSW indexing infrastructure
+- Establish embedding generation pipeline
+- Create unified query interface
+```
+
+### **Phase 2: Gradual Migration**
+```bash
+# Week 4-5: System-by-system migration
+- SQLiteBackend → AgentDB (structured data)
+- MarkdownBackend → AgentDB (document storage)
+- MemoryManager → Unified interface
+- DistributedMemorySystem → Cross-agent sharing
+```
+
+### **Phase 3: Advanced Features**
+```bash
+# Week 6: Performance optimization
+- SONA integration for learning patterns
+- Cross-agent memory sharing
+- Performance benchmarking (150x validation)
+- Backward compatibility layer cleanup
+```
+
+## Performance Targets
+
+### **Search Performance**
+- **Current**: O(n) linear search through memory entries
+- **Target**: O(log n) HNSW approximate nearest neighbor
+- **Improvement**: 150x-12,500x depending on dataset size
+- **Benchmark**: Sub-100ms queries for 1M+ entries
+
+### **Memory Efficiency**
+- **Current**: Multiple backend overhead
+- **Target**: Unified storage with compression
+- **Improvement**: 50-75% memory reduction
+- **Benchmark**: <1GB memory usage for large datasets
+
+### **Query Flexibility**
+```typescript
+// Unified query interface supports both:
+
+// 1. Semantic similarity queries
+await memory.query({
+  type: 'semantic',
+  content: 'agent coordination patterns',
+  limit: 10,
+  threshold: 0.8
+});
+
+// 2. Structured queries
+await memory.query({
+  type: 'structured',
+  filters: {
+    agentType: 'security',
+    timestamp: { after: '2026-01-01' }
+  },
+  orderBy: 'relevance'
+});
+```
+
+## SONA Integration
+
+### **Learning Pattern Storage**
+```typescript
+class SONAMemoryIntegration {
+  async storePattern(pattern: LearningPattern): Promise<void> {
+    // Store in AgentDB with SONA metadata
+    await this.memory.store({
+      id: pattern.id,
+      content: pattern.data,
+      metadata: {
+        sonaMode: pattern.mode, // real-time, balanced, research, edge, batch
+        reward: pattern.reward,
+        trajectory: pattern.trajectory,
+        adaptation_time: pattern.adaptationTime
+      },
+      embedding: await this.generateEmbedding(pattern.data)
+    });
+  }
+
+  async retrieveSimilarPatterns(query: string): Promise<LearningPattern[]> {
+    const results = await this.memory.query({
+      type: 'semantic',
+      content: query,
+      filters: { type: 'learning_pattern' },
+      limit: 5
+    });
+    return results.map(r => this.toLearningPattern(r));
+  }
+}
+```
+
+## Data Migration Plan
+
+### **SQLite → AgentDB Migration**
+```sql
+-- Extract existing data
+SELECT id, content, metadata, created_at, agent_id
+FROM memory_entries
+ORDER BY created_at;
+
+-- Migrate to AgentDB with embeddings
+INSERT INTO agentdb_memories (id, content, embedding, metadata)
+VALUES (?, ?, generate_embedding(?), ?);
+```
+
+### **Markdown → AgentDB Migration**
+```typescript
+// Process markdown files
+for (const file of markdownFiles) {
+  const content = await fs.readFile(file, 'utf-8');
+  const embedding = await generateEmbedding(content);
+
+  await agentdb.store({
+    id: generateId(),
+    content,
+    embedding,
+    metadata: {
+      originalFile: file,
+      migrationDate: new Date(),
+      type: 'document'
+    }
+  });
+}
+```
+
+## Validation & Testing
+
+### **Performance Benchmarks**
+```typescript
+// Benchmark suite
+class MemoryBenchmarks {
+  async benchmarkSearchPerformance(): Promise<BenchmarkResult> {
+    const queries = this.generateTestQueries(1000);
+    const startTime = performance.now();
+
+    for (const query of queries) {
+      await this.memory.query(query);
+    }
+
+    const endTime = performance.now();
+    return {
+      queriesPerSecond: queries.length / (endTime - startTime) * 1000,
+      avgLatency: (endTime - startTime) / queries.length,
+      improvement: this.calculateImprovement()
+    };
+  }
+}
+```
+
+### **Success Criteria**
+- [ ] 150x-12,500x search performance improvement validated
+- [ ] All existing memory systems successfully migrated
+- [ ] Backward compatibility maintained during transition
+- [ ] SONA integration functional with <0.05ms adaptation
+- [ ] Cross-agent memory sharing operational
+- [ ] 50-75% memory usage reduction achieved
+
+## Coordination Points
+
+### **Integration Architect (Agent #10)**
+- AgentDB integration with agentic-flow@alpha
+- SONA learning mode configuration
+- Performance optimization coordination
+
+### **Core Architect (Agent #5)**
+- Memory service interfaces in DDD structure
+- Event sourcing integration for memory operations
+- Domain boundary definitions for memory access
+
+### **Performance Engineer (Agent #14)**
+- Benchmark validation of 150x-12,500x improvements
+- Memory usage profiling and optimization
 - Performance regression testing