v3-memory-specialist

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**

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**

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**

# 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**

# 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**

# 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**

// 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