Skill v1.0.0
currentAutomated scan100/100version: "1.0.0" name: "AgentDB Advanced Features" description: "Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid search, and distributed systems integration. Use when building distributed AI systems, multi-agent coordination, or advanced vector search applications."
AgentDB Advanced Features
What This Skill Does
Covers advanced AgentDB capabilities for distributed systems, multi-database coordination, custom distance metrics, hybrid search (vector + metadata), QUIC synchronization, and production deployment patterns. Enables building sophisticated AI systems with sub-millisecond cross-node communication and advanced search capabilities.
Performance: <1ms QUIC sync, hybrid search with filters, custom distance metrics.
Prerequisites
- Node.js 18+
- AgentDB v1.0.7+ (via agentic-flow)
- Understanding of distributed systems (for QUIC sync)
- Vector search fundamentals
QUIC Synchronization
What is QUIC Sync?
QUIC (Quick UDP Internet Connections) enables sub-millisecond latency synchronization between AgentDB instances across network boundaries with automatic retry, multiplexing, and encryption.
Benefits:
- <1ms latency between nodes
- Multiplexed streams (multiple operations simultaneously)
- Built-in encryption (TLS 1.3)
- Automatic retry and recovery
- Event-based broadcasting
Enable QUIC Sync
import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';// Initialize with QUIC synchronizationconst adapter = await createAgentDBAdapter({dbPath: '.agentdb/distributed.db',enableQUICSync: true,syncPort: 4433,syncPeers: ['192.168.1.10:4433','192.168.1.11:4433','192.168.1.12:4433',],});// Patterns automatically sync across all peersawait adapter.insertPattern({// ... pattern data});// Available on all peers within ~1ms
QUIC Configuration
const adapter = await createAgentDBAdapter({enableQUICSync: true,syncPort: 4433, // QUIC server portsyncPeers: ['host1:4433'], // Peer addressessyncInterval: 1000, // Sync interval (ms)syncBatchSize: 100, // Patterns per batchmaxRetries: 3, // Retry failed syncscompression: true, // Enable compression});
Multi-Node Deployment
# Node 1 (192.168.1.10)AGENTDB_QUIC_SYNC=true \AGENTDB_QUIC_PORT=4433 \AGENTDB_QUIC_PEERS=192.168.1.11:4433,192.168.1.12:4433 \node server.js# Node 2 (192.168.1.11)AGENTDB_QUIC_SYNC=true \AGENTDB_QUIC_PORT=4433 \AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.12:4433 \node server.js# Node 3 (192.168.1.12)AGENTDB_QUIC_SYNC=true \AGENTDB_QUIC_PORT=4433 \AGENTDB_QUIC_PEERS=192.168.1.10:4433,192.168.1.11:4433 \node server.js
Distance Metrics
Cosine Similarity (Default)
Best for normalized vectors, semantic similarity:
# CLInpx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m cosine# APIconst result = await adapter.retrieveWithReasoning(queryEmbedding, {metric: 'cosine',k: 10,});
Use Cases:
- Text embeddings (BERT, GPT, etc.)
- Semantic search
- Document similarity
- Most general-purpose applications
Formula: cos(θ) = (A · B) / (||A|| × ||B||) Range: [-1, 1] (1 = identical, -1 = opposite)
Euclidean Distance (L2)
Best for spatial data, geometric similarity:
# CLInpx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m euclidean# APIconst result = await adapter.retrieveWithReasoning(queryEmbedding, {metric: 'euclidean',k: 10,});
Use Cases:
- Image embeddings
- Spatial data
- Computer vision
- When vector magnitude matters
Formula: d = √(Σ(ai - bi)²) Range: [0, ∞] (0 = identical, ∞ = very different)
Dot Product
Best for pre-normalized vectors, fast computation:
# CLInpx agentdb@latest query ./vectors.db "[0.1,0.2,...]" -m dot# APIconst result = await adapter.retrieveWithReasoning(queryEmbedding, {metric: 'dot',k: 10,});
Use Cases:
- Pre-normalized embeddings
- Fast similarity computation
- When vectors are already unit-length
Formula: dot = Σ(ai × bi) Range: [-∞, ∞] (higher = more similar)
Custom Distance Metrics
// Implement custom distance functionfunction customDistance(vec1: number[], vec2: number[]): number {// Weighted Euclidean distanceconst weights = [1.0, 2.0, 1.5, ...];let sum = 0;for (let i = 0; i < vec1.length; i++) {sum += weights[i] * Math.pow(vec1[i] - vec2[i], 2);}return Math.sqrt(sum);}// Use in search (requires custom implementation)
Hybrid Search (Vector + Metadata)
Basic Hybrid Search
Combine vector similarity with metadata filtering:
// Store documents with metadataawait adapter.insertPattern({id: '',type: 'document',domain: 'research-papers',pattern_data: JSON.stringify({embedding: documentEmbedding,text: documentText,metadata: {author: 'Jane Smith',year: 2025,category: 'machine-learning',citations: 150,}}),confidence: 1.0,usage_count: 0,success_count: 0,created_at: Date.now(),last_used: Date.now(),});// Hybrid search: vector similarity + metadata filtersconst result = await adapter.retrieveWithReasoning(queryEmbedding, {domain: 'research-papers',k: 20,filters: {year: { $gte: 2023 }, // Published 2023 or latercategory: 'machine-learning', // ML papers onlycitations: { $gte: 50 }, // Highly cited},});
Advanced Filtering
// Complex metadata queriesconst result = await adapter.retrieveWithReasoning(queryEmbedding, {domain: 'products',k: 50,filters: {price: { $gte: 10, $lte: 100 }, // Price rangecategory: { $in: ['electronics', 'gadgets'] }, // Multiple categoriesrating: { $gte: 4.0 }, // High ratedinStock: true, // Availabletags: { $contains: 'wireless' }, // Has tag},});
Weighted Hybrid Search
Combine vector and metadata scores:
const result = await adapter.retrieveWithReasoning(queryEmbedding, {domain: 'content',k: 20,hybridWeights: {vectorSimilarity: 0.7, // 70% weight on semantic similaritymetadataScore: 0.3, // 30% weight on metadata match},filters: {category: 'technology',recency: { $gte: Date.now() - 30 * 24 * 3600000 }, // Last 30 days},});
Multi-Database Management
Multiple Databases
// Separate databases for different domainsconst knowledgeDB = await createAgentDBAdapter({dbPath: '.agentdb/knowledge.db',});const conversationDB = await createAgentDBAdapter({dbPath: '.agentdb/conversations.db',});const codeDB = await createAgentDBAdapter({dbPath: '.agentdb/code.db',});// Use appropriate database for each taskawait knowledgeDB.insertPattern({ /* knowledge */ });await conversationDB.insertPattern({ /* conversation */ });await codeDB.insertPattern({ /* code */ });
Database Sharding
// Shard by domain for horizontal scalingconst shards = {'domain-a': await createAgentDBAdapter({ dbPath: '.agentdb/shard-a.db' }),'domain-b': await createAgentDBAdapter({ dbPath: '.agentdb/shard-b.db' }),'domain-c': await createAgentDBAdapter({ dbPath: '.agentdb/shard-c.db' }),};// Route queries to appropriate shardfunction getDBForDomain(domain: string) {const shardKey = domain.split('-')[0]; // Extract shard keyreturn shards[shardKey] || shards['domain-a'];}// Insert to correct shardconst db = getDBForDomain('domain-a-task');await db.insertPattern({ /* ... */ });
MMR (Maximal Marginal Relevance)
Retrieve diverse results to avoid redundancy:
// Without MMR: Similar results may be redundantconst standardResults = await adapter.retrieveWithReasoning(queryEmbedding, {k: 10,useMMR: false,});// With MMR: Diverse, non-redundant resultsconst diverseResults = await adapter.retrieveWithReasoning(queryEmbedding, {k: 10,useMMR: true,mmrLambda: 0.5, // Balance relevance (0) vs diversity (1)});
MMR Parameters:
mmrLambda = 0: Maximum relevance (may be redundant)mmrLambda = 0.5: Balanced (default)mmrLambda = 1: Maximum diversity (may be less relevant)
Use Cases:
- Search result diversification
- Recommendation systems
- Avoiding echo chambers
- Exploratory search
Context Synthesis
Generate rich context from multiple memories:
const result = await adapter.retrieveWithReasoning(queryEmbedding, {domain: 'problem-solving',k: 10,synthesizeContext: true, // Enable context synthesis});// ContextSynthesizer creates coherent narrativeconsole.log('Synthesized Context:', result.context);// "Based on 10 similar problem-solving attempts, the most effective// approach involves: 1) analyzing root cause, 2) brainstorming solutions,// 3) evaluating trade-offs, 4) implementing incrementally. Success rate: 85%"console.log('Patterns:', result.patterns);// Extracted common patterns across memories
Production Patterns
Connection Pooling
// Singleton pattern for shared adapterclass AgentDBPool {private static instance: AgentDBAdapter;static async getInstance() {if (!this.instance) {this.instance = await createAgentDBAdapter({dbPath: '.agentdb/production.db',quantizationType: 'scalar',cacheSize: 2000,});}return this.instance;}}// Use in applicationconst db = await AgentDBPool.getInstance();const results = await db.retrieveWithReasoning(queryEmbedding, { k: 10 });
Error Handling
async function safeRetrieve(queryEmbedding: number[], options: any) {try {const result = await adapter.retrieveWithReasoning(queryEmbedding, options);return result;} catch (error) {if (error.code === 'DIMENSION_MISMATCH') {console.error('Query embedding dimension mismatch');// Handle dimension error} else if (error.code === 'DATABASE_LOCKED') {// Retry with exponential backoffawait new Promise(resolve => setTimeout(resolve, 100));return safeRetrieve(queryEmbedding, options);}throw error;}}
Monitoring and Logging
// Performance monitoringconst startTime = Date.now();const result = await adapter.retrieveWithReasoning(queryEmbedding, { k: 10 });const latency = Date.now() - startTime;if (latency > 100) {console.warn('Slow query detected:', latency, 'ms');}// Log statisticsconst stats = await adapter.getStats();console.log('Database Stats:', {totalPatterns: stats.totalPatterns,dbSize: stats.dbSize,cacheHitRate: stats.cacheHitRate,avgSearchLatency: stats.avgSearchLatency,});
CLI Advanced Operations
Database Import/Export
# Export with compressionnpx agentdb@latest export ./vectors.db ./backup.json.gz --compress# Import from backupnpx agentdb@latest import ./backup.json.gz --decompress# Merge databasesnpx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite
Database Optimization
# Vacuum database (reclaim space)sqlite3 .agentdb/vectors.db "VACUUM;"# Analyze for query optimizationsqlite3 .agentdb/vectors.db "ANALYZE;"# Rebuild indicesnpx agentdb@latest reindex ./vectors.db
Environment Variables
# AgentDB configurationAGENTDB_PATH=.agentdb/reasoningbank.dbAGENTDB_ENABLED=true# Performance tuningAGENTDB_QUANTIZATION=binary # binary|scalar|product|noneAGENTDB_CACHE_SIZE=2000AGENTDB_HNSW_M=16AGENTDB_HNSW_EF=100# Learning pluginsAGENTDB_LEARNING=true# Reasoning agentsAGENTDB_REASONING=true# QUIC synchronizationAGENTDB_QUIC_SYNC=trueAGENTDB_QUIC_PORT=4433AGENTDB_QUIC_PEERS=host1:4433,host2:4433
Troubleshooting
Issue: QUIC sync not working
# Check firewall allows UDP port 4433sudo ufw allow 4433/udp# Verify peers are reachableping host1# Check QUIC logsDEBUG=agentdb:quic node server.js
Issue: Hybrid search returns no results
// Relax filtersconst result = await adapter.retrieveWithReasoning(queryEmbedding, {k: 100, // Increase kfilters: {// Remove or relax filters},});
Issue: Memory consolidation too aggressive
// Disable automatic optimizationconst result = await adapter.retrieveWithReasoning(queryEmbedding, {optimizeMemory: false, // Disable auto-consolidationk: 10,});
Learn More
- QUIC Protocol: docs/quic-synchronization.pdf
- Hybrid Search: docs/hybrid-search-guide.md
- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
- Website: https://agentdb.ruv.io
Category: Advanced / Distributed Systems Difficulty: Advanced Estimated Time: 45-60 minutes