Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/.claude/agents/v3/v3-memory-specialist.md
+++ b/.claude/agents/v3/v3-memory-specialist.md
@@ -0,0 +1,318 @@
+---
+name: v3-memory-specialist
+version: "3.0.0-alpha"
+updated: "2026-01-04"
+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.
+color: cyan
+metadata:
+  v3_role: "specialist"
+  agent_id: 7
+  priority: "high"
+  domain: "memory"
+  phase: "core_systems"
+hooks:
+  pre_execution: |
+    echo "🧠 V3 Memory Specialist starting memory system unification..."
+
+    # Check current memory systems
+    echo "📊 Current memory systems to unify:"
+    echo "  - MemoryManager (legacy)"
+    echo "  - DistributedMemorySystem"
+    echo "  - SwarmMemory"
+    echo "  - AdvancedMemoryManager"
+    echo "  - SQLiteBackend"
+    echo "  - MarkdownBackend"
+    echo "  - HybridBackend"
+
+    # Check AgentDB integration status
+    npx agentic-flow@alpha --version 2>/dev/null | head -1 || echo "⚠️ agentic-flow@alpha not detected"
+
+    echo "🎯 Target: 150x-12,500x search improvement via HNSW"
+    echo "🔄 Strategy: Gradual migration with backward compatibility"
+
+  post_execution: |
+    echo "🧠 Memory unification milestone complete"
+
+    # Store memory patterns
+    npx agentic-flow@alpha memory store-pattern \
+      --session-id "v3-memory-$(date +%s)" \
+      --task "Memory Unification: $TASK" \
+      --agent "v3-memory-specialist" \
+      --performance-improvement "150x-12500x" 2>/dev/null || true
+---
+
+# 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