AgentDB Performance Optimization

Quick Start

# Run benchmarks
npx agentdb@latest benchmark

import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';

const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb/optimized.db',
  quantizationType: 'binary',   // 32x memory reduction
  cacheSize: 1000,
  enableLearning: true,
  enableReasoning: true,
});

---

Quantization Types

Type	Memory Reduction	Speed Gain	Accuracy Retained	Best For
binary	32x	10x	95-98%	1M+ vectors, edge/mobile
scalar	4x	3x	98-99%	10K-1M, production
product	8-16x	5x	93-97%	High-dim (>512d) embeddings
none	1x	1x	100%	<10K vectors, max accuracy

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // or 'scalar', 'product', 'none'
});

---

HNSW Tuning

const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb/vectors.db',
  hnswM: 16,              // Connections per layer
  hnswEfConstruction: 200, // Build quality
  hnswEfSearch: 100,       // Search quality
});

Parameter guide by dataset size:

Dataset	hnswM	hnswEfConstruction	hnswEfSearch
<10K	8	100	50
10K-100K	16	200	100
100K-1M	32	200	100
>1M	48	400	200

Higher M = better recall, more memory. Higher efSearch = better recall, slower search.

---

Caching

const adapter = await createAgentDBAdapter({
  cacheSize: 1000,  // LRU cache for most-used patterns
});

// Monitor hit rate
const stats = await adapter.getStats();
console.log('Cache Hit Rate:', stats.cacheHitRate);  // Target >80%

Sizing: small apps 100-500, medium 500-2000, large 2000-5000.

---

Batch Operations

Batch Insert

// Use insertPattern in a loop -- AgentDB batches internally per transaction
const patterns = documents.map(doc => ({
  id: '',
  type: 'document',
  domain: 'knowledge',
  pattern_data: JSON.stringify({ embedding: doc.embedding, text: doc.text }),
  confidence: 1.0,
  usage_count: 0,
  success_count: 0,
  created_at: Date.now(),
  last_used: Date.now(),
}));

for (const pattern of patterns) {
  await adapter.insertPattern(pattern);
}

Batch Retrieval

const results = await Promise.all(
  queries.map(q => adapter.retrieveWithReasoning(q, { k: 5 }))
);

---

Memory Optimization

Automatic Consolidation

const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'documents',
  optimizeMemory: true,  // Merges similar patterns, prunes low-quality
  k: 10,
});
// result.optimizations: { consolidated, pruned, improved_quality }

Manual Optimization

await adapter.optimize();

Pruning

await adapter.prune({
  minConfidence: 0.5,
  minUsageCount: 2,
  maxAge: 30 * 24 * 3600,  // 30 days
});

---

Monitoring

npx agentdb@latest stats .agentdb/vectors.db

const stats = await adapter.getStats();
// stats: { totalPatterns, dbSize, avgConfidence, cacheHitRate, avgSearchLatency, avgInsertLatency }

---

Optimization Recipes

Maximum Speed

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',
  cacheSize: 5000,
  hnswM: 8,
  hnswEfSearch: 50,
});
// <50us search, 90-95% accuracy

Balanced

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',
  cacheSize: 1000,
  hnswM: 16,
  hnswEfSearch: 100,
});
// <100us search, 98-99% accuracy

Maximum Accuracy

const adapter = await createAgentDBAdapter({
  quantizationType: 'none',
  cacheSize: 2000,
  hnswM: 32,
  hnswEfSearch: 200,
});
// <200us search, 100% accuracy

Edge/Mobile

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',
  cacheSize: 100,
  hnswM: 8,
});
// ~10MB for 100K vectors

---

Troubleshooting

High memory: Check npx agentdb@latest stats, switch to binary quantization.

Slow search: Increase cacheSize, reduce k, lower hnswEfSearch.

Low accuracy: Use scalar instead of binary, increase hnswEfSearch.