/agentdb-optimization

name: agentdb-optimization
description: "Optimize AgentDB performance with quantization (4-32x memory reduction), HNSW indexing (150x faster search), caching, and batch operations. Use when optimizing memory usage, improving search speed, or scaling to millions of vectors."

AgentDB Performance Optimization

What This Skill Does

Provides comprehensive performance optimization techniques for AgentDB vector databases. Achieve 150x-12,500x performance improvements through quantization, HNSW indexing, caching strategies, and batch operations. Reduce memory usage by 4-32x while maintaining accuracy.

**Performance**: <100µs vector search, <1ms pattern retrieval, 2ms batch insert for 100 vectors.

Prerequisites

• Node.js 18+
• AgentDB v1.0.7+ (via agentic-flow)
• Existing AgentDB database or application

---

Quick Start

Run Performance Benchmarks

# Comprehensive performance benchmarking
npx agentdb@latest benchmark

# Results show:
# ✅ Pattern Search: 150x faster (100µs vs 15ms)
# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
# ✅ Large-scale Query: 12,500x faster (8ms vs 100s at 1M vectors)
# ✅ Memory Efficiency: 4-32x reduction with quantization

Enable Optimizations

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

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

---

Quantization Strategies

1. Binary Quantization (32x Reduction)

**Best For**: Large-scale deployments (1M+ vectors), memory-constrained environments **Trade-off**: ~2-5% accuracy loss, 32x memory reduction, 10x faster

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',
  // 768-dim float32 (3072 bytes) → 96 bytes binary
  // 1M vectors: 3GB → 96MB
});

**Use Cases**:

• Mobile/edge deployment
• Large-scale vector storage (millions of vectors)
• Real-time search with memory constraints

**Performance**:

• Memory: 32x smaller
• Search Speed: 10x faster (bit operations)
• Accuracy: 95-98% of original

2. Scalar Quantization (4x Reduction)

**Best For**: Balanced performance/accuracy, moderate datasets **Trade-off**: ~1-2% accuracy loss, 4x memory reduction, 3x faster

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',
  // 768-dim float32 (3072 bytes) → 768 bytes (uint8)
  // 1M vectors: 3GB → 768MB
});

**Use Cases**:

• Production applications requiring high accuracy
• Medium-scale deployments (10K-1M vectors)
• General-purpose optimization

**Performance**:

• Memory: 4x smaller
• Search Speed: 3x faster
• Accuracy: 98-99% of original

3. Product Quantization (8-16x Reduction)

**Best For**: High-dimensional vectors, balanced compression **Trade-off**: ~3-7% accuracy loss, 8-16x memory reduction, 5x faster

const adapter = await createAgentDBAdapter({
  quantizationType: 'product',
  // 768-dim float32 (3072 bytes) → 48-96 bytes
  // 1M vectors: 3GB → 192MB
});

**Use Cases**:

• High-dimensional embeddings (>512 dims)
• Image/video embeddings
• Large-scale similarity search

**Performance**:

• Memory: 8-16x smaller
• Search Speed: 5x faster
• Accuracy: 93-97% of original

4. No Quantization (Full Precision)

**Best For**: Maximum accuracy, small datasets **Trade-off**: No accuracy loss, full memory usage

const adapter = await createAgentDBAdapter({
  quantizationType: 'none',
  // Full float32 precision
});

---

HNSW Indexing

**Hierarchical Navigable Small World** - O(log n) search complexity

Automatic HNSW

AgentDB automatically builds HNSW indices:

const adapter = await createAgentDBAdapter({
  dbPath: '.agentdb/vectors.db',
  // HNSW automatically enabled
});

// Search with HNSW (100µs vs 15ms linear scan)
const results = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 10,
});

HNSW Parameters

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

**Parameter Tuning**:

• **M** (connections): Higher = better recall, more memory
• Small datasets (<10K): M = 8
• Medium datasets (10K-100K): M = 16
• Large datasets (>100K): M = 32
• **efConstruction**: Higher = better index quality, slower build
• Fast build: 100
• Balanced: 200 (default)
• High quality: 400
• **efSearch**: Higher = better recall, slower search
• Fast search: 50
• Balanced: 100 (default)
• High recall: 200

---

Caching Strategies

In-Memory Pattern Cache

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

// First retrieval: ~2ms (database)
// Subsequent: <1ms (cache hit)
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 10,
});

**Cache Tuning**:

• Small applications: 100-500 patterns
• Medium applications: 500-2000 patterns
• Large applications: 2000-5000 patterns

LRU Cache Behavior

// Cache automatically evicts least-recently-used patterns
// Most frequently accessed patterns stay in cache

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

---

Batch Operations

Batch Insert (500x Faster)

// ❌ SLOW: Individual inserts
for (const doc of documents) {
  await adapter.insertPattern({ /* ... */ });  // 1s for 100 docs
}

// ✅ FAST: Batch insert
const patterns = documents.map(doc => ({
  id: '',
  type: 'document',
  domain: 'knowledge',
  pattern_data: JSON.stringif