EnhancedMemory (high-level API)
    ↓
FallbackMemoryStore (fallback logic)
    ↓
SqliteMemoryStore ←→ InMemoryStore
    ↓
better-sqlite3 / JSON

Operation          | Current     | With AgentDB | Improvement
-------------------|-------------|--------------|-------------
Pattern Search     | 15ms        | 100µs        | 150x faster
Batch Insert (100) | 1s          | 2ms          | 500x faster
Large Query (1M)   | 100s        | 8ms          | 12,500x faster
Memory Usage       | Baseline    | 4-32x less   | Up to 32x

Package Name: agentdb
Version: 1.0.7
Published: 2025-10-18
Size: 1.4 MB (compressed), 5.0 MB (unpacked)
Homepage: https://agentdb.ruv.io
Repository: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
License: MIT OR Apache-2.0

// package.json line 43-45
"bin": {
  "agentdb": "./bin/agentdb.js"
}

agentdb init ./my-agent-memory.db
agentdb list-templates
agentdb create-plugin
agentdb mcp                    # Start MCP server
agentdb --help

// Quantization Options (from docs)
  binary: {
    reduction: '32x',
    accuracy: '~95%',
    useCase: 'Large-scale deployment'
  },
  scalar: {
    reduction: '4x',
    accuracy: '~99%',
    useCase: 'Balanced performance'
  },
  product: {
    reduction: '8-16x',
    accuracy: '~97%',
    useCase: 'High-dimensional data'
  }
}

agentdb create-plugin  # Interactive CLI wizard
agentdb list-templates # Show all 11 templates

/**
 * New hybrid memory system combining backward compatibility with AgentDB performance
 */
AgentDBMemoryAdapter (new)
    ↓
  ┌─────────────────┬────────────────────┐
  ↓                 ↓                    ↓
FallbackMemoryStore  AgentDBBackend     LegacyDataBridge
(existing)          (new)              (compatibility layer)
  ↓                 ↓                    ↓
SQLite/InMemory    AgentDB Vector DB    Migration Tools

// src/memory/agentdb-adapter.js
export class AgentDBMemoryAdapter extends EnhancedMemory {
  constructor(options = {}) {
    super(options);
    this.agentdb = null;
    this.enableVector = options.enableVector ?? true;
    this.enableLearning = options.enableLearning ?? false;
    this.enableReasoning = options.enableReasoning ?? false;
  }

  // Existing API - 100% backward compatible
  async store(key, value, options) { /* ... */ }
  async retrieve(key, options) { /* ... */ }
  async list(options) { /* ... */ }
  async search(pattern, options) { /* ... */ }

  // New AI-powered methods
  async storeWithEmbedding(key, value, options) { /* ... */ }
  async vectorSearch(query, options) { /* ... */ }
  async semanticRetrieve(query, options) { /* ... */ }
}

// src/memory/backends/agentdb.js
export class AgentDBBackend {
  constructor(config) {
    this.adapter = null;
    this.config = {
      dbPath: config.dbPath || '.agentdb/claude-flow.db',
      quantizationType: config.quantizationType || 'scalar',
      cacheSize: config.cacheSize || 1000,
      enableLearning: config.enableLearning ?? false,
      enableReasoning: config.enableReasoning ?? false,
    };
  }

  async initialize() {
    const { createAgentDBAdapter } = await import('agentic-flow/reasoningbank');
    this.adapter = await createAgentDBAdapter(this.config);
  }

  async insertPattern(data) { /* ... */ }
  async retrieveWithReasoning(embedding, options) { /* ... */ }
  async train(options) { /* ... */ }
}

// src/memory/migration/legacy-bridge.js
export class LegacyDataBridge {
  async migrateToAgentDB(sourceStore, targetAdapter) {
    // Automatic migration from existing data
    const items = await sourceStore.list({ limit: 100000 });

    for (const item of items) {
      await targetAdapter.insertFromLegacy(item);
    }
  }

  async validateMigration(source, target) {
    // Verify data integrity after migration
  }
}

// claude-flow.config.js or package.json
{
  "claude-flow": {
    "memory": {
      "backend": "agentdb",  // "legacy" | "agentdb" | "hybrid"
      "agentdb": {
        "enabled": true,
        "dbPath": ".agentdb/claude-flow.db",
        "quantization": "scalar",  // "binary" | "scalar" | "product" | "none"
        "cacheSize": 1000,
        "features": {
          "vectorSearch": true,
          "learning": false,
          "reasoning": false,
          "quicSync": false
        },
        "quic": {
          "port": 4433,
          "peers": []
        }
      }
    }
  }
}

// All existing methods continue to work
await memory.store(key, value, options);
await memory.retrieve(key, options);
await memory.list(options);
await memory.delete(key, options);
await memory.search(pattern, options);
await memory.cleanup();

// EnhancedMemory methods (preserved)
await memory.saveSessionState(sessionId, state);
await memory.resumeSession(sessionId);
await memory.trackWorkflow(workflowId, data);
await memory.recordMetric(name, value);
await memory.registerAgent(agentId, config);

// Legacy format (continues to work)
{
  key: 'user:123',
  value: { name: 'John', age: 30 },
  namespace: 'users',
  metadata: { createdAt: 123456789 },
  ttl: 3600000
}

// AgentDB format (new capabilities)
{
  id: 'pattern_user_123',
  type: 'pattern',
  domain: 'users',
  pattern_data: {
    embedding: [0.1, 0.2, ...],  // Vector representation
    data: { name: 'John', age: 30 },
    metadata: { createdAt: 123456789 }
  },
  confidence: 0.95,
  usage_count: 10,
  created_at: 123456789
}

// Phase 1: Hybrid mode (both backends active)
const memory = new AgentDBMemoryAdapter({
  mode: 'hybrid',  // Use AgentDB for new data, legacy for existing
  autoMigrate: false
});

// Phase 2: Migration mode (transparent background migration)
const memory = new AgentDBMemoryAdapter({
  mode: 'agentdb',
  autoMigrate: true,  // Gradually migrate on access
  fallbackToLegacy: true
});

// Phase 3: Pure AgentDB mode
const memory = new AgentDBMemoryAdapter({
  mode: 'agentdb',
  autoMigrate: false,
  fallbackToLegacy: false
});

class AgentDBMemoryAdapter {
  async retrieve(key, options) {
    try {
      // Try AgentDB first
      const result = await this.agentdb.retrieve(key, options);
      if (result) return result;
    } catch (error) {
      console.warn('AgentDB retrieval failed, falling back to legacy');
    }

    // Fallback to legacy store
    return super.retrieve(key, options);
  }
}

{
  name: 'memory_vector_search',
  description: 'Semantic vector search with HNSW indexing',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query or embedding' },
      domain: { type: 'string', description: 'Memory domain filter' },
      k: { type: 'number', description: 'Top-k results', default: 10 },
      threshold: { type: 'number', description: 'Similarity threshold (0-1)' },
      useMMR: { type: 'boolean', description: 'Use Maximal Marginal Relevance' },
      metric: {
        type: 'string',
        enum: ['cosine', 'euclidean', 'dot'],
        description: 'Distance metric'
      }
    },
    required: ['query']
  }
}

{
  name: 'memory_semantic_retrieve',
  description: 'Retrieve memories with semantic understanding',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string' },
      domain: { type: 'string' },
      synthesizeContext: { type: 'boolean', default: true },
      optimizeMemory: { type: 'boolean', default: false }
    },
    required: ['query']
  }
}

{
  name: 'memory_train_model',
  description: 'Train learning models on stored patterns',
  inputSchema: {
    type: 'object',
    properties: {
      algorithm: {
        type: 'string',
        enum: ['decision-transformer', 'q-learning', 'actor-critic'],
        description: 'Learning algorithm'
      },
      epochs: { type: 'number', default: 50 },
      batchSize: { type: 'number', default: 32 },
      domain: { type: 'string', description: 'Training data domain' }
    }
  }
}

{
  name: 'memory_apply_reasoning',
  description: 'Apply reasoning agents to optimize memory',
  inputSchema: {
    type: 'object',
    properties: {
      agent: {
        type: 'string',
        enum: ['pattern-matcher', 'context-synthesizer', 'memory-optimizer', 'experience-curator']
      },
      domain: { type: 'string' },
      options: { type: 'object' }
    },
    required: ['agent']
  }
}

{
  name: 'memory_migrate_to_agentdb',
  description: 'Migrate legacy data to AgentDB backend',
  inputSchema: {
    type: 'object',
    properties: {
      namespace: { type: 'string', description: 'Namespace to migrate (all if empty)' },
      validate: { type: 'boolean', default: true },
      backup: { type: 'boolean', default: true }
    }
  }
}

{
  name: 'memory_optimize',
  description: 'Run memory optimization (consolidation, pruning)',
  inputSchema: {
    type: 'object',
    properties: {
      domain: { type: 'string' },
      strategy: {
        type: 'string',
        enum: ['consolidate', 'prune', 'reindex'],
        description: 'Optimization strategy'
      }
    }
  }
}

{
  name: 'memory_quantize',
  description: 'Apply quantization to reduce memory usage',
  inputSchema: {
    type: 'object',
    properties: {
      type: {
        type: 'string',
        enum: ['binary', 'scalar', 'product'],
        description: 'Quantization type'
      },
      domain: { type: 'string' }
    },
    required: ['type']
  }
}

{
  name: 'memory_benchmark',
  description: 'Run performance benchmarks',
  inputSchema: {
    type: 'object',
    properties: {
      suite: {
        type: 'string',
        enum: ['search', 'insert', 'comprehensive'],
        default: 'comprehensive'
      },
      iterations: { type: 'number', default: 100 }
    }
  }
}

{
  name: 'memory_stats_advanced',
  description: 'Get advanced memory statistics',
  inputSchema: {
    type: 'object',
    properties: {
      includeVectorStats: { type: 'boolean', default: true },
      includeLearningMetrics: { type: 'boolean', default: true },
      domain: { type: 'string' }
    }
  }
}

{
  name: 'memory_sync_enable',
  description: 'Enable QUIC synchronization',
  inputSchema: {
    type: 'object',
    properties: {
      port: { type: 'number', default: 4433 },
      peers: { type: 'array', items: { type: 'string' } }
    }
  }
}

{
  name: 'memory_sync_status',
  description: 'Check synchronization status',
  inputSchema: {
    type: 'object',
    properties: {
      detailed: { type: 'boolean', default: false }
    }
  }
}

// Before: Simple key-value storage
await memory_usage({
  action: 'store',
  key: 'user:123',
  value: '{"name":"John"}'
});

// After: Optional vector embedding
await memory_usage({
  action: 'store',
  key: 'user:123',
  value: '{"name":"John"}',
  embedding: [0.1, 0.2, ...],  // NEW: Vector representation
  domain: 'users',             // NEW: Domain for semantic search
  confidence: 0.95             // NEW: Confidence score
});

// Before: Pattern matching only
await memory_search({
  pattern: 'user:*',
  namespace: 'users'
});

// After: Semantic search option
await memory_search({
  query: 'find all admin users',  // NEW: Natural language
  semantic: true,                  // NEW: Use vector search
  threshold: 0.8,                  // NEW: Similarity threshold
  namespace: 'users'
});

# Switch memory backend
claude-flow memory backend set agentdb
claude-flow memory backend set legacy
claude-flow memory backend set hybrid

# Get current backend info
claude-flow memory backend info

# Test backend performance
claude-flow memory backend test

# Migrate to AgentDB
claude-flow memory migrate to-agentdb [--namespace users] [--validate]

# Migrate from AgentDB
claude-flow memory migrate to-legacy [--namespace users]

# Check migration status
claude-flow memory migrate status

# Validate migration integrity
claude-flow memory migrate validate --source legacy --target agentdb

# Semantic search
claude-flow memory search-semantic "find error handling patterns" \
  --domain code-patterns \
  --top-k 10 \
  --threshold 0.75

# Vector similarity search
claude-flow memory vector-search \
  --embedding-file query.json \
  --metric cosine \
  --top-k 20

# Hybrid search (vector + filters)
claude-flow memory hybrid-search "authentication code" \
  --filter '{"language":"javascript","confidence":{"$gte":0.8}}'

# List available learning plugins
claude-flow memory learning list-plugins

# Train model
claude-flow memory learning train \
  --algorithm decision-transformer \
  --epochs 50 \
  --domain code-generation

# Get training status
claude-flow memory learning status

# Apply learned patterns
claude-flow memory learning apply --domain code-generation

# Apply reasoning agent
claude-flow memory reasoning apply \
  --agent memory-optimizer \
  --domain workflows

# Get reasoning insights
claude-flow memory reasoning insights --domain agents

# Context synthesis
claude-flow memory reasoning synthesize \
  --query "optimal swarm coordination" \
  --domain swarm-patterns

# Run memory optimization
claude-flow memory optimize \
  --strategy consolidate \
  --domain conversations

# Apply quantization
claude-flow memory quantize \
  --type binary \
  --namespace patterns

# Rebuild indices
claude-flow memory reindex --domain all

# Run benchmarks
claude-flow memory benchmark \
  --suite comprehensive \
  --iterations 1000

# Compare backends
claude-flow memory compare-backends

# Get detailed stats
claude-flow memory stats-advanced \
  --include-vectors \
  --include-learning

# Enable QUIC sync
claude-flow memory sync enable \
  --port 4433 \
  --peers "192.168.1.10:4433,192.168.1.11:4433"

# Check sync status
claude-flow memory sync status

# Force sync
claude-flow memory sync force

# Disable sync
claude-flow memory sync disable

# Before
claude-flow hooks post-edit --file src/api.js

# After (with AgentDB)
claude-flow hooks post-edit \
  --file src/api.js \
  --auto-vectorize    # NEW: Auto-create vector embedding
  --learn-pattern     # NEW: Learn from edit pattern
  --reasoning         # NEW: Apply reasoning agents

describe('AgentDBMemoryAdapter', () => {
  test('initializes with default configuration', async () => { });
  test('falls back to legacy on AgentDB failure', async () => { });
  test('maintains backward compatibility with existing API', async () => { });
});

describe('AgentDBBackend', () => {
  test('stores patterns with vector embeddings', async () => { });
  test('retrieves with semantic search', async () => { });
  test('applies quantization correctly', async () => { });
});

describe('LegacyDataBridge', () => {
  test('migrates all namespaces correctly', async () => { });
  test('validates data integrity after migration', async () => { });
  test('handles rollback on migration failure', async () => { });
});

describe('MCP Tools with AgentDB', () => {
  test('memory_vector_search returns accurate results', async () => { });
  test('memory_train_model completes successfully', async () => { });
  test('memory_migrate_to_agentdb preserves all data', async () => { });
});

describe('CLI Commands', () => {
  test('migrate command completes without errors', async () => { });
  test('search-semantic returns relevant results', async () => { });
  test('backend switch maintains data access', async () => { });
});

describe('Performance Benchmarks', () => {
  test('vector search <100µs', async () => { });
  test('pattern insertion <2ms for batch of 100', async () => { });
  test('large-scale query <10ms for 1M vectors', async () => { });
  test('memory usage with quantization reduces by 4-32x', async () => { });
});

describe('Backward Compatibility', () => {
  test('existing EnhancedMemory API works unchanged', async () => { });
  test('legacy data accessible from AgentDB backend', async () => { });
  test('MCP tools maintain existing behavior', async () => { });
  test('CLI commands work with both backends', async () => { });
});

# AgentDB Configuration
AGENTDB_ENABLED=true
AGENTDB_PATH=.agentdb/claude-flow.db
AGENTDB_QUANTIZATION=scalar  # binary|scalar|product|none
AGENTDB_CACHE_SIZE=1000
AGENTDB_HNSW_M=16
AGENTDB_HNSW_EF=100

# Learning Plugins
AGENTDB_LEARNING=false
AGENTDB_LEARNING_ALGORITHM=decision-transformer

# Reasoning Agents
AGENTDB_REASONING=false

# QUIC Synchronization
AGENTDB_QUIC_SYNC=false
AGENTDB_QUIC_PORT=4433
AGENTDB_QUIC_PEERS=

# Migration
AGENTDB_AUTO_MIGRATE=false
AGENTDB_FALLBACK_LEGACY=true

#!/bin/bash
# migrate-to-agentdb.sh

echo "🚀 Starting migration to AgentDB..."

# 1. Backup existing data
claude-flow memory backup --output ./backup-$(date +%Y%m%d).json

# 2. Validate backup
claude-flow memory backup validate ./backup-*.json

# 3. Enable hybrid mode
export AGENTDB_ENABLED=true
export AGENTDB_FALLBACK_LEGACY=true

# 4. Start migration
claude-flow memory migrate to-agentdb \
  --validate \
  --progress

# 5. Validate migration
claude-flow memory migrate validate

# 6. Run benchmarks
claude-flow memory benchmark --suite comprehensive

echo "✅ Migration complete!"