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 synchronization

const 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 peers

await adapter.insertPattern({

  // ... pattern data

});

// Available on all peers within ~1ms

QUIC Configuration

const adapter = await createAgentDBAdapter({

  enableQUICSync: true,

  syncPort: 4433,              // QUIC server port

  syncPeers: ['host1:4433'],   // Peer addresses

  syncInterval: 1000,          // Sync interval (ms)

  syncBatchSize: 100,          // Patterns per batch

  maxRetries: 3,               // Retry failed syncs

  compression: 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:

# CLI

npx agentdb@latest query .$vectors.db "[0.1,0.2,...]" -m cosine

# API

const 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:

# CLI

npx agentdb@latest query .$vectors.db "[0.1,0.2,...]" -m euclidean

# API

const 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:

# CLI

npx agentdb@latest query .$vectors.db "[0.1,0.2,...]" -m dot

# API

const 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 function

function customDistance(vec1: number[], vec2: number[]): number {

  // Weighted Euclidean distance

  const 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 metadata

await 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 filters

const result = await adapter.retrieveWithReasoning(queryEmbedding, {

  domain: 'research-papers',

  k: 20,

  filters: {

    year: { $gte: 2023 },          // Published 2023 or later

    category: 'machine-learning',   // ML papers only

    citations: { $gte: 50 },       // Highly cited

  },

});

Advanced Filtering

// Complex metadata queries

const result = await adapter.retrieveWithReasoning(queryEmbedding, {

  domain: 'products',

  k: 50,

  filters: {

    price: { $gte: 10, $lte: 100 },      // Price range

    category: { $in: ['electronics', 'gadgets'] },  // Multiple categories

    rating: { $gte: 4.0 },                // High rated

    inStock: true,                        // Available

    tags: { $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 similarity

    metadataScore: 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 domains

const 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 task

await knowledgeDB.insertPattern({ /* knowledge */ });

await conversationDB.insertPattern({ /* conversation */ });

await codeDB.insertPattern({ /* code */ });

Database Sharding

// Shard by domain for horizontal scaling

const 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 shard

function getDBForDomain(domain: string) {

  const shardKey = domain.split('-')[0];  // Extract shard key

  return shards[shardKey] || shards['domain-a'];

}

// Insert to correct shard

const db = getDBForDomain('domain-a-task');

await db.insertPattern({ /* ... */ });

MMR (Maximal Marginal Relevance)

Retrieve diverse results to avoid redundancy:

// Without MMR: Similar results may be redundant

const standardResults = await adapter.retrieveWithReasoning(queryEmbedding, {

  k: 10,

  useMMR: false,

});

// With MMR: Diverse, non-redundant results

const 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 narrative

console.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 adapter

class 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 application

const 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 backoff

      await new Promise(resolve => setTimeout(resolve, 100));

      return safeRetrieve(queryEmbedding, options);

    }

    throw error;

  }

}

Monitoring and Logging

// Performance monitoring

const 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 statistics

const 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 compression

npx agentdb@latest export .$vectors.db .$backup.json.gz --compress

# Import from backup

npx agentdb@latest import .$backup.json.gz --decompress

# Merge databases

npx agentdb@latest merge .$db1.sqlite .$db2.sqlite .$merged.sqlite

Database Optimization

# Vacuum database (reclaim space)

sqlite3 .agentdb$vectors.db "VACUUM;"

# Analyze for query optimization

sqlite3 .agentdb$vectors.db "ANALYZE;"

# Rebuild indices

npx agentdb@latest reindex .$vectors.db

Environment Variables

# AgentDB configuration

AGENTDB_PATH=.agentdb$reasoningbank.db

AGENTDB_ENABLED=true

# Performance tuning

AGENTDB_QUANTIZATION=binary     # binary|scalar|product|none

AGENTDB_CACHE_SIZE=2000

AGENTDB_HNSW_M=16

AGENTDB_HNSW_EF=100

# Learning plugins

AGENTDB_LEARNING=true

# Reasoning agents

AGENTDB_REASONING=true

# QUIC synchronization

AGENTDB_QUIC_SYNC=true

AGENTDB_QUIC_PORT=4433

AGENTDB_QUIC_PEERS=host1:4433,host2:4433

Troubleshooting

Issue: QUIC sync not working

# Check firewall allows UDP port 4433

# NOTE: Requires administrator privileges - for reference only

sudo ufw allow 4433/udp

# Verify peers are reachable

ping host1

# Check QUIC logs

DEBUG=agentdb:quic node server.js

Issue: Hybrid search returns no results

// Relax filters

const result = await adapter.retrieveWithReasoning(queryEmbedding, {

  k: 100,  // Increase k

  filters: {

    // Remove or relax filters

  },

});

Issue: Memory consolidation too aggressive

// Disable automatic optimization

const result = await adapter.retrieveWithReasoning(queryEmbedding, {

  optimizeMemory: false,  // Disable auto-consolidation

  k: 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