MCPInstall

agentdb performance optimization

by ruvnetCode Quality & Workflow

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.

Installs
1.1K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/ruvnet/ruflo --skill agentdb-performance-optimization
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads agentdb performance optimization automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.stringify({
    embedding: doc.embedding,
    text: doc.text,
  }),
  confidence: 1.0,
  usage_count: 0,
  success_count: 0,
  created_at: Date.now(),
  last_used: Date.now(),
}));

// Insert all at once (2ms for 100 docs)
for (const pattern of patterns) {
  await adapter.insertPattern(pattern);
}

Batch Retrieval

// Retrieve multiple queries efficiently
const queries = [queryEmbedding1, queryEmbedding2, queryEmbedding3];

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

Memory Optimization

Automatic Consolidation

// Enable automatic pattern consolidation
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'documents',
  optimizeMemory: true,  // Consolidate similar patterns
  k: 10,
});

console.log('Optimizations:', result.optimizations);
// {
//   consolidated: 15,  // Merged 15 similar patterns
//   pruned: 3,         // Removed 3 low-quality patterns
//   improved_quality: 0.12  // 12% quality improvement
// }

Manual Optimization

// Manually trigger optimization
await adapter.optimize();

// Get statistics
const stats = await adapter.getStats();
console.log('Before:', stats.totalPatterns);
console.log('After:', stats.totalPatterns);  // Reduced by ~10-30%

Pruning Strategies

// Prune low-confidence patterns
await adapter.prune({
  minConfidence: 0.5,     // Remove confidence < 0.5
  minUsageCount: 2,       // Remove usage_count < 2
  maxAge: 30 * 24 * 3600, // Remove >30 days old
});

Performance Monitoring

Database Statistics

# Get comprehensive stats
npx agentdb@latest stats .agentdb$vectors.db

# Output:
# Total Patterns: 125,430
# Database Size: 47.2 MB (with binary quantization)
# Avg Confidence: 0.87
# Domains: 15
# Cache Hit Rate: 84%
# Index Type: HNSW

Runtime Metrics

const stats = await adapter.getStats();

console.log('Performance Metrics:');
console.log('Total Patterns:', stats.totalPatterns);
console.log('Database Size:', stats.dbSize);
console.log('Avg Confidence:', stats.avgConfidence);
console.log('Cache Hit Rate:', stats.cacheHitRate);
console.log('Search Latency (avg):', stats.avgSearchLatency);
console.log('Insert Latency (avg):', stats.avgInsertLatency);

Optimization Recipes

Recipe 1: Maximum Speed (Sacrifice Accuracy)

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 32x memory reduction
  cacheSize: 5000,             // Large cache
  hnswM: 8,                    // Fewer connections = faster
  hnswEfSearch: 50,            // Low search quality = faster
});

// Expected: <50µs search, 90-95% accuracy

Recipe 2: Balanced Performance

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // 4x memory reduction
  cacheSize: 1000,             // Standard cache
  hnswM: 16,                   // Balanced connections
  hnswEfSearch: 100,           // Balanced quality
});

// Expected: <100µs search, 98-99% accuracy

Recipe 3: Maximum Accuracy

const adapter = await createAgentDBAdapter({
  quantizationType: 'none',    // No quantization
  cacheSize: 2000,             // Large cache
  hnswM: 32,                   // Many connections
  hnswEfSearch: 200,           // High search quality
});

// Expected: <200µs search, 100% accuracy

Recipe 4: Memory-Constrained (Mobile/Edge)

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 32x memory reduction
  cacheSize: 100,              // Small cache
  hnswM: 8,                    // Minimal connections
});

// Expected: <100µs search, ~10MB for 100K vectors

Scaling Strategies

Small Scale (<10K vectors)

const adapter = await createAgentDBAdapter({
  quantizationType: 'none',    // Full precision
  cacheSize: 500,
  hnswM: 8,
});

Medium Scale (10K-100K vectors)

const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // 4x reduction
  cacheSize: 1000,
  hnswM: 16,
});

Large Scale (100K-1M vectors)

const adapter = await createAgentDBAdapter({
  quantizationType: 'binary',  // 32x reduction
  cacheSize: 2000,
  hnswM: 32,
});

Massive Scale (>1M vectors)

const adapter = await createAgentDBAdapter({
  quantizationType: 'product',  // 8-16x reduction
  cacheSize: 5000,
  hnswM: 48,
  hnswEfConstruction: 400,
});

Troubleshooting

Issue: High memory usage

# Check database size
npx agentdb@latest stats .agentdb$vectors.db

# Enable quantization
# Use 'binary' for 32x reduction

Issue: Slow search performance

// Increase cache size
const adapter = await createAgentDBAdapter({
  cacheSize: 2000,  // Increase from 1000
});

// Reduce search quality (faster)
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 5,  // Reduce from 10
});

Issue: Low accuracy

// Disable or use lighter quantization
const adapter = await createAgentDBAdapter({
  quantizationType: 'scalar',  // Instead of 'binary'
  hnswEfSearch: 200,           // Higher search quality
});

Performance Benchmarks

Test System: AMD Ryzen 9 5950X, 64GB RAM

OperationVector CountNo OptimizationOptimizedImprovement
Search10K15ms100µs150x
Search100K150ms120µs1,250x
Search1M100s8ms12,500x
Batch Insert (100)-1s2ms500x
Memory Usage1M3GB96MB32x (binary)

Learn More

  • Quantization Paper: docs$quantization-techniques.pdf
  • HNSW Algorithm: docs$hnsw-index.pdf
  • GitHub: https:/$github.com$ruvnet$agentic-flow$tree$main$packages$agentdb
  • Website: https:/$agentdb.ruv.io

Category: Performance / Optimization Difficulty: Intermediate Estimated Time: 20-30 minutes

FAQ

What does the agentdb performance optimization skill do?

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.

How do I install agentdb performance optimization?

Run npx skills add https://github.com/ruvnet/ruflo --skill agentdb-performance-optimization in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/agentdb-performance-optimization/ (personal) or .claude/skills/agentdb-performance-optimization/ (project).

Which AI agents can use agentdb performance optimization?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is agentdb performance optimization safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains agentdb performance optimization?

It is published by ruvnet in ruvnet/ruflo. It has 1,125 recorded installs.

More from ruvnet/ruflo

View all →

ruflo

ruvnet/ruflo

Open the skill to read its SKILL.md instructions.

4K installs

swarm-orchestration

ruvnet/ruflo

Multi-agent swarm coordination for complex tasks. Uses hierarchical topology with specialized agents to break down and execute complex work across multiple files and modules. Use when: 3+ files need changes, new feature implementation, cross-module refactoring, API changes with tests, security-related changes, performance optimization across codebase, database schema changes. Skip when: single file edits, simple bug fixes (1-2 lines), documentation updates, configuration changes, quick exploration.

Code Quality & Workflow2.1K installs

agent-arch-system-design

ruvnet/ruflo

Agent skill for arch-system-design - invoke with $agent-arch-system-design

1.4K installs

agent-workflow

ruvnet/ruflo

Agent skill for workflow - invoke with $agent-workflow

Productivity & Automation1.4K installs

security-audit

ruvnet/ruflo

Comprehensive security scanning and vulnerability detection. Includes input validation, path traversal prevention, CVE detection, and secure coding pattern enforcement. Use when: authentication implementation, authorization logic, payment processing, user data handling, API endpoint creation, file upload handling, database queries, external API integration. Skip when: read-only operations on public data, internal development tooling, static documentation, styling changes.

Security1.4K installs

github-project-management

ruvnet/ruflo

Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning

Code Quality & Workflow1.4K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs