Claude Skill

AgentDB Advanced Features

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.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download spencermarx-open-code-review-.claude_skills_agentdb-advanced-a793b05.zip · 4 KB

Install

skills CLI npx skills add https://github.com/spencermarx/open-code-review/tree/main/.claude/skills/agentdb-advanced
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install spencermarx-open-code-review@llmmart
Git git clone https://github.com/spencermarx/open-code-review.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole spencermarx/open-code-review collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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


Category: Advanced / Distributed Systems Difficulty: Advanced Estimated Time: 45-60 minutes

Files (open-code-review)
  • SKILL.md 12.8 KB
    ---
    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
    
    ```typescript
    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
    
    ```typescript
    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
    
    ```bash
    # 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:
    
    ```bash
    # 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:
    
    ```bash
    # 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:
    
    ```bash
    # 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
    
    ```typescript
    // 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:
    
    ```typescript
    // 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
    
    ```typescript
    // 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:
    
    ```typescript
    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
    
    ```typescript
    // 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
    
    ```typescript
    // 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:
    
    ```typescript
    // 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:
    
    ```typescript
    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
    
    ```typescript
    // 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
    
    ```typescript
    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
    
    ```typescript
    // 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
    
    ```bash
    # 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
    
    ```bash
    # 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
    
    ```bash
    # 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
    
    ```bash
    # Check firewall allows UDP port 4433
    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
    
    ```typescript
    // Relax filters
    const result = await adapter.retrieveWithReasoning(queryEmbedding, {
      k: 100,  // Increase k
      filters: {
        // Remove or relax filters
      },
    });
    ```
    
    ### Issue: Memory consolidation too aggressive
    
    ```typescript
    // 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
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.