agentic-flow 1.7.3 → 1.7.5

package/docs/AGENTDB_INTEGRATION.md

@@ -1,379 +0,0 @@
-# AgentDB Integration Guide
-
-## Overview
-
-AgentDB is now fully integrated into agentic-flow as a drop-in replacement for the legacy ReasoningBank implementation. It provides 150x-12,500x performance improvements with 100% backward compatibility.
-
-## Quick Start
-
-### Using AgentDB Adapter
-
-```typescript
-import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
-
-// Create adapter with default configuration
-const adapter = await createAgentDBAdapter({
-  dbPath: '.agentdb/reasoningbank.db',
-  enableLearning: true,      // Enable learning plugins
-  enableReasoning: true,      // Enable reasoning agents
-  enableQUICSync: false,      // Enable QUIC sync
-  quantizationType: 'scalar', // binary | scalar | product | none
-  cacheSize: 1000,            // In-memory cache size
-});
-
-// Insert pattern
-const id = await adapter.insertPattern({
-  id: '',
-  type: 'pattern',
-  domain: 'code-generation',
-  pattern_data: JSON.stringify({
-    embedding: await computeEmbedding('example query'),
-    pattern: { code: 'function example() {}' }
-  }),
-  confidence: 0.9,
-  usage_count: 0,
-  success_count: 0,
-  created_at: Date.now(),
-  last_used: Date.now(),
-});
-
-// Retrieve with reasoning
-const result = await adapter.retrieveWithReasoning(queryEmbedding, {
-  domain: 'code-generation',
-  synthesizeContext: true, // Generate rich context
-  useMMR: true,            // Diverse results
-  k: 10,
-});
-
-console.log('Memories:', result.memories.length);
-console.log('Context:', result.context);
-console.log('Patterns:', result.patterns);
-```
-
-### Default Configuration
-
-```typescript
-import { createDefaultAgentDBAdapter } from 'agentic-flow/reasoningbank';
-
-const adapter = await createDefaultAgentDBAdapter();
-```
-
-## Migration from Legacy ReasoningBank
-
-### Automatic Migration
-
-```typescript
-import { migrateToAgentDB, validateMigration } from 'agentic-flow/reasoningbank';
-
-// Migrate from legacy database
-const result = await migrateToAgentDB(
-  '.swarm/memory.db',           // Source (legacy)
-  '.agentdb/reasoningbank.db'   // Destination (AgentDB)
-);
-
-console.log(`✅ Migrated ${result.patternsMigrated} patterns`);
-console.log(`✅ Migrated ${result.trajectoriesMigrated} trajectories`);
-console.log(`📦 Backup: ${result.backupPath}`);
-console.log(`⏱️  Duration: ${result.duration}ms`);
-
-// Validate migration
-const validation = await validateMigration(
-  '.swarm/memory.db',
-  '.agentdb/reasoningbank.db'
-);
-
-if (!validation.valid) {
-  console.error('❌ Migration issues:', validation.issues);
-} else {
-  console.log('✅ Migration validated successfully');
-}
-```
-
-### CLI Migration
-
-```bash
-# Using AgentDB CLI
-cd packages/agentdb
-agentdb migrate --source ../../agentic-flow/.swarm/memory.db
-
-# Or using npm script
-npm run migrate:legacy
-```
-
-## Features
-
-### 1. Vector Database
-- **HNSW Indexing**: O(log n) search complexity
-- **Quantization**: Binary (32x), Scalar (4x), Product (8-16x) memory reduction
-- **Caching**: 1000 pattern in-memory cache
-- **Performance**: Sub-millisecond search (<100µs)
-
-### 2. Learning Plugins (9 Algorithms)
-- Decision Transformer (Offline RL)
-- Q-Learning (Value-based RL)
-- SARSA (On-policy RL)
-- Actor-Critic (Policy gradient)
-- Active Learning (Query selection)
-- Adversarial Training (Robustness)
-- Curriculum Learning (Progressive difficulty)
-- Federated Learning (Distributed learning)
-- Multi-task Learning (Transfer learning)
-
-### 3. Reasoning Agents (4 Modules)
-- **PatternMatcher**: Find similar patterns with advanced algorithms
-- **ContextSynthesizer**: Generate rich context from multiple sources
-- **MemoryOptimizer**: Consolidate similar patterns, prune low-quality
-- **ExperienceCurator**: Quality-based experience filtering
-
-### 4. QUIC Synchronization
-- Sub-millisecond latency
-- Multiplexed streams
-- Event-based broadcasting
-- Automatic retry/recovery
-
-## Configuration Options
-
-```typescript
-interface AgentDBConfig {
-  // Database path
-  dbPath?: string;  // Default: '.agentdb/reasoningbank.db'
-
-  // Feature flags
-  enableLearning?: boolean;    // Default: true
-  enableReasoning?: boolean;   // Default: true
-  enableQUICSync?: boolean;    // Default: false
-
-  // Performance tuning
-  quantizationType?: 'binary' | 'scalar' | 'product' | 'none';  // Default: 'scalar'
-  cacheSize?: number;          // Default: 1000
-
-  // QUIC sync (if enabled)
-  syncPort?: number;           // Default: 4433
-  syncPeers?: string[];        // Default: []
-}
-```
-
-## Advanced Usage
-
-### Training Learning Models
-
-```typescript
-// Train Decision Transformer on stored experiences
-const metrics = await adapter.train({
-  epochs: 50,
-  batchSize: 32,
-});
-
-console.log('Loss:', metrics.loss);
-console.log('Duration:', metrics.duration);
-```
-
-### Using Reasoning Agents
-
-```typescript
-// Retrieve with full reasoning pipeline
-const result = await adapter.retrieveWithReasoning(queryEmbedding, {
-  domain: 'code-generation',
-  k: 10,
-  useMMR: true,                // Maximal Marginal Relevance
-  synthesizeContext: true,     // Context synthesis
-  optimizeMemory: true,        // Memory optimization
-});
-
-console.log('Memories:', result.memories);
-console.log('Synthesized Context:', result.context);
-console.log('Similar Patterns:', result.patterns);
-console.log('Optimizations:', result.optimizations);
-```
-
-### Memory Optimization
-
-```typescript
-// Run optimization manually
-await adapter.optimize();
-
-// Get statistics
-const stats = await adapter.getStats();
-
-console.log('Total Patterns:', stats.totalPatterns);
-console.log('Total Trajectories:', stats.totalTrajectories);
-console.log('Average Confidence:', stats.avgConfidence);
-console.log('Domains:', stats.domains);
-console.log('Database Size:', stats.dbSize);
-```
-
-## Performance Benchmarks
-
-### Speed Improvements
-- **Pattern Search**: 150x faster (100µs vs 15ms)
-- **Batch Insert**: 500x faster (2ms vs 1s for 100 patterns)
-- **Large-scale Query**: 12,500x faster (8ms vs 100s at 1M patterns)
-
-### Memory Efficiency
-- **Binary Quantization**: 32x reduction (768-dim → 96 bytes)
-- **Scalar Quantization**: 4x reduction (768-dim → 768 bytes)
-- **Product Quantization**: 8-16x reduction (768-dim → 48-96 bytes)
-
-### Latency
-- **Vector Search**: <100µs (HNSW)
-- **Pattern Retrieval**: <1ms (with cache)
-- **QUIC Sync**: <1ms (sub-millisecond)
-
-## Backward Compatibility
-
-AgentDB provides **100% backward compatibility** with the legacy ReasoningBank API:
-
-```typescript
-// All existing ReasoningBank methods work unchanged
-import { retrieveMemories, judgeTrajectory, distillMemories } from 'agentic-flow/reasoningbank';
-
-// Legacy API continues to work
-const memories = await retrieveMemories(query, { domain, agent });
-const verdict = await judgeTrajectory(trajectory, query);
-const newMemories = await distillMemories(trajectory, verdict, query, metadata);
-
-// New AgentDB adapter for enhanced features
-import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';
-const adapter = await createAgentDBAdapter();
-```
-
-## Environment Variables
-
-```bash
-# Enable/disable ReasoningBank
-REASONINGBANK_ENABLED=true
-
-# Database path (legacy)
-CLAUDE_FLOW_DB_PATH=.swarm/memory.db
-
-# AgentDB path (new)
-AGENTDB_PATH=.agentdb/reasoningbank.db
-
-# Enable AgentDB by default
-AGENTDB_ENABLED=true
-
-# Enable learning plugins
-AGENTDB_LEARNING=true
-
-# Enable reasoning agents
-AGENTDB_REASONING=true
-
-# Enable QUIC sync
-AGENTDB_QUIC_SYNC=false
-AGENTDB_QUIC_PORT=4433
-AGENTDB_QUIC_PEERS=host1:4433,host2:4433
-```
-
-## Examples
-
-### Complete Example
-
-```typescript
-import {
-  createAgentDBAdapter,
-  computeEmbedding,
-  formatMemoriesForPrompt
-} from 'agentic-flow/reasoningbank';
-
-async function main() {
-  // Initialize adapter
-  const adapter = await createAgentDBAdapter({
-    enableLearning: true,
-    enableReasoning: true,
-  });
-
-  // Compute query embedding
-  const query = 'How to implement authentication?';
-  const queryEmbedding = await computeEmbedding(query);
-
-  // Retrieve with reasoning
-  const result = await adapter.retrieveWithReasoning(queryEmbedding, {
-    domain: 'backend',
-    synthesizeContext: true,
-    useMMR: true,
-    k: 5,
-  });
-
-  // Format for prompt
-  const formattedMemories = formatMemoriesForPrompt(result.memories);
-
-  console.log('Retrieved Memories:', formattedMemories);
-  console.log('Context:', result.context);
-
-  // Insert new pattern after successful implementation
-  await adapter.insertPattern({
-    id: '',
-    type: 'pattern',
-    domain: 'backend',
-    pattern_data: JSON.stringify({
-      embedding: queryEmbedding,
-      pattern: {
-        query,
-        solution: 'Use JWT tokens with refresh tokens...',
-        code: 'import jwt from "jsonwebtoken";...'
-      }
-    }),
-    confidence: 0.95,
-    usage_count: 1,
-    success_count: 1,
-    created_at: Date.now(),
-    last_used: Date.now(),
-  });
-
-  // Train learning model
-  await adapter.train({ epochs: 10 });
-
-  // Cleanup
-  await adapter.close();
-}
-
-main().catch(console.error);
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Issue**: `AgentDB not found`
-```bash
-# Ensure AgentDB is built
-cd packages/agentdb
-npm run build
-```
-
-**Issue**: `Migration fails`
-```bash
-# Check source database exists
-ls -la .swarm/memory.db
-
-# Run with verbose logging
-DEBUG=agentdb:* agentdb migrate --source .swarm/memory.db
-```
-
-**Issue**: `Performance not improved`
-```typescript
-// Ensure HNSW indexing is enabled
-const adapter = await createAgentDBAdapter({
-  quantizationType: 'scalar',  // Enable quantization
-  cacheSize: 1000,             // Enable caching
-});
-```
-
-## API Reference
-
-See the complete API documentation in:
-- `/packages/agentdb/docs/integration/IMPLEMENTATION_SUMMARY.md`
-- `/packages/agentdb/docs/integration/README.md`
-
-## Support
-
-For issues or questions:
-- GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
-- Documentation: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
-
----
-
-**Status**: ✅ Production Ready
-**Version**: 1.0.0
-**Performance**: 150x-12,500x faster
-**Compatibility**: 100% backward compatible