agentdb-advanced-features

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese


LIBRARY-FIRST PROTOCOL (MANDATORY)

库优先协议(强制遵循)

Before writing ANY code, you MUST check:
在编写任何代码之前,你必须完成以下检查:

Step 1: Library Catalog

步骤1:库目录检查

  • Location:
    .claude/library/catalog.json
  • If match >70%: REUSE or ADAPT
  • 位置:
    .claude/library/catalog.json
  • 若匹配度>70%:复用或适配现有代码

Step 2: Patterns Guide

步骤2:模式指南检查

  • Location:
    .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
  • If pattern exists: FOLLOW documented approach
  • 位置:
    .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
  • 若已有对应模式:遵循文档中记录的实现方式

Step 3: Existing Projects

步骤3:现有项目检查

  • Location:
    D:\Projects\*
  • If found: EXTRACT and adapt
  • 位置:
    D:\Projects\*
  • 若找到类似实现:提取并适配

Decision Matrix

决策矩阵

MatchAction
Library >90%REUSE directly
Library 70-90%ADAPT minimally
Pattern existsFOLLOW pattern
In projectEXTRACT
No matchBUILD (add to library after)

匹配度操作
库匹配度>90%直接复用
库匹配度70-90%最小程度适配
已有对应模式遵循模式
现有项目存在提取适配
无匹配项重新构建(完成后添加到库中)

When NOT to Use This Skill

不适用场景

  • Local-only operations with no vector search needs
  • Simple key-value storage without semantic similarity
  • Real-time streaming data without persistence requirements
  • Operations that do not require embedding-based retrieval
  • 无向量搜索需求的纯本地操作
  • 无需语义相似度的简单键值存储
  • 无需持久化的实时流数据处理
  • 不需要基于嵌入向量检索的操作

Success Criteria

成功指标

  • Vector search query latency: <10ms for 99th percentile
  • Embedding generation: <100ms per document
  • Index build time: <1s per 1000 vectors
  • Recall@10: >0.95 for similar documents
  • Database connection success rate: >99.9%
  • Memory footprint: <2GB for 1M vectors with quantization
  • 向量搜索查询延迟:99%的请求延迟<10ms
  • 嵌入向量生成:单文档处理时间<100ms
  • 索引构建时间:每1000个向量耗时<1s
  • 召回率@10:相似文档召回率>0.95
  • 数据库连接成功率:>99.9%
  • 内存占用:100万条量化向量内存占用<2GB

Edge Cases & Error Handling

边缘场景与错误处理

  • Rate Limits: AgentDB local instances have no rate limits; cloud deployments may vary
  • Connection Failures: Implement retry logic with exponential backoff (max 3 retries)
  • Index Corruption: Maintain backup indices; rebuild from source if corrupted
  • Memory Overflow: Use quantization (4-bit, 8-bit) to reduce memory by 4-32x
  • Stale Embeddings: Implement TTL-based refresh for dynamic content
  • Dimension Mismatch: Validate embedding dimensions (384 for sentence-transformers) before insertion
  • 速率限制:AgentDB本地实例无速率限制;云端部署可能存在限制
  • 连接失败:实现带指数退避的重试逻辑(最多3次重试)
  • 索引损坏:维护备份索引;若损坏则从源数据重建
  • 内存溢出:使用量化(4位、8位)将内存占用降低4-32倍
  • 嵌入向量过期:为动态内容实现基于TTL的刷新机制
  • 维度不匹配:插入前验证嵌入向量维度(sentence-transformers默认384维)

Guardrails & Safety

安全防护规则

  • NEVER expose database connection strings in logs or error messages
  • ALWAYS validate vector dimensions before insertion
  • ALWAYS sanitize metadata to prevent injection attacks
  • NEVER store PII in vector metadata without encryption
  • ALWAYS implement access control for multi-tenant deployments
  • ALWAYS validate search results before returning to users
  • 绝对不要在日志或错误信息中暴露数据库连接字符串
  • 插入前必须验证向量维度
  • 必须清理元数据以防止注入攻击
  • 未加密情况下绝对不要在向量元数据中存储PII(个人可识别信息)
  • 多租户部署必须实现访问控制
  • 返回给用户前必须验证搜索结果

Evidence-Based Validation

基于证据的验证

  • Verify database health: Check connection status and index integrity
  • Validate search quality: Measure recall/precision on test queries
  • Monitor performance: Track query latency, throughput, and memory usage
  • Test failure recovery: Simulate connection drops and index corruption
  • Benchmark improvements: Compare against baseline metrics (e.g., 150x speedup claim)
  • 验证数据库健康状态:检查连接状态和索引完整性
  • 验证搜索质量:在测试查询上衡量召回率/精确率
  • 监控性能:跟踪查询延迟、吞吐量和内存使用情况
  • 测试故障恢复:模拟连接中断和索引损坏场景
  • 基准性能提升:与基线指标对比(例如,150倍加速的声明)

AgentDB Advanced Features

AgentDB高级功能

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.
涵盖AgentDB针对分布式系统、多数据库协调、自定义距离度量、混合搜索(向量+元数据)、QUIC同步和生产部署模式的高级能力。支持构建具备亚毫秒级跨节点通信和高级搜索功能的复杂AI系统。
性能表现:<1ms的QUIC同步、带过滤的混合搜索、自定义距离度量。

Prerequisites

前置要求

  • Node.js 18+
  • AgentDB v1.0.7+ (via agentic-flow)
  • Understanding of distributed systems (for QUIC sync)
  • Vector search fundamentals

  • Node.js 18+
  • AgentDB v1.0.7+(通过agentic-flow安装)
  • 具备分布式系统相关知识(用于QUIC同步)
  • 掌握向量搜索基础

QUIC Synchronization

QUIC同步

What is QUIC Sync?

什么是QUIC同步?

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
QUIC(Quick UDP Internet Connections)通过自动重试、多路复用和加密机制,实现跨网络边界的AgentDB实例间亚毫秒级延迟的同步。
优势:
  • 节点间延迟<1ms
  • 多路复用流(可同时执行多个操作)
  • 内置加密(TLS 1.3)
  • 自动重试与恢复
  • 基于事件的广播

Enable QUIC Sync

启用QUIC同步

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
typescript
import { createAgentDBAdapter } from 'agentic-flow/reasoningbank';

// 初始化并启用QUIC同步
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',
  ],
});

// 模式会自动同步到所有节点
await adapter.insertPattern({
  // ... 模式数据
});

// 约1ms内即可在所有节点上访问

QUIC Configuration

QUIC配置

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
});
typescript
const adapter = await createAgentDBAdapter({
  enableQUICSync: true,
  syncPort: 4433,              // QUIC服务器端口
  syncPeers: ['host1:4433'],   // 节点地址
  syncInterval: 1000,          // 同步间隔(毫秒)
  syncBatchSize: 100,          // 每批同步的模式数量
  maxRetries: 3,               // 同步失败重试次数
  compression: true,           // 启用压缩
});

Multi-Node Deployment

多节点部署

bash
undefined
bash
undefined

Node 1 (192.168.1.10)

节点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
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)

节点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
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)

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

---
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
undefined
最适合归一化向量、语义相似度场景:
bash
undefined

CLI

CLI命令

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

API

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)
const result = await adapter.retrieveWithReasoning(queryEmbedding, { metric: 'cosine', k: 10, });

**适用场景**:
- 文本嵌入向量(BERT、GPT等)
- 语义搜索
- 文档相似度
- 大多数通用场景

**公式**:`cos(θ) = (A · B) / (||A|| × ||B||)`
**取值范围**:[-1, 1](1=完全相同,-1=完全相反)

Euclidean Distance (L2)

欧氏距离(L2)

Best for spatial data, geometric similarity:
bash
undefined
最适合空间数据、几何相似度场景:
bash
undefined

CLI

CLI命令

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

API

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)
const result = await adapter.retrieveWithReasoning(queryEmbedding, { metric: 'euclidean', k: 10, });

**适用场景**:
- 图像嵌入向量
- 空间数据
- 计算机视觉
- 向量长度有意义的场景

**公式**:`d = √(Σ(ai - bi)²)`
**取值范围**:[0, ∞](0=完全相同,∞=差异极大)

Dot Product

点积

Best for pre-normalized vectors, fast computation:
bash
undefined
最适合预归一化向量、快速计算场景:
bash
undefined

CLI

CLI命令

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

API

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)
const result = await adapter.retrieveWithReasoning(queryEmbedding, { metric: 'dot', k: 10, });

**适用场景**:
- 预归一化嵌入向量
- 快速相似度计算
- 向量已为单位长度的场景

**公式**:`dot = Σ(ai × bi)`
**取值范围**:[-∞, ∞](值越高越相似)

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)

typescript
// 实现自定义距离函数
function customDistance(vec1: number[], vec2: number[]): number {
  // 加权欧氏距离
  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);
}

// 在搜索中使用(需要自定义实现)

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
  },
});
结合向量相似度与元数据过滤:
typescript
// 存储带元数据的文档
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(),
});

// 混合搜索:向量相似度 + 元数据过滤
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'research-papers',
  k: 20,
  filters: {
    year: { $gte: 2023 },          // 2023年及以后发表
    category: 'machine-learning',   // 仅机器学习领域
    citations: { $gte: 50 },       // 高引用量
  },
});

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
  },
});
typescript
// 复杂元数据查询
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'products',
  k: 50,
  filters: {
    price: { $gte: 10, $lte: 100 },      // 价格范围
    category: { $in: ['electronics', 'gadgets'] },  // 多个类别
    rating: { $gte: 4.0 },                // 高评分
    inStock: true,                        // 有库存
    tags: { $contains: 'wireless' },      // 包含指定标签
  },
});

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
  },
});

结合向量和元数据得分:
typescript
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'content',
  k: 20,
  hybridWeights: {
    vectorSimilarity: 0.7,  // 语义相似度占70%权重
    metadataScore: 0.3,     // 元数据匹配度占30%权重
  },
  filters: {
    category: 'technology',
    recency: { $gte: Date.now() - 30 * 24 * 3600000 },  // 最近30天
  },
});

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 */ });
typescript
// 为不同领域创建独立数据库
const knowledgeDB = await createAgentDBAdapter({
  dbPath: '.agentdb/knowledge.db',
});

const conversationDB = await createAgentDBAdapter({
  dbPath: '.agentdb/conversations.db',
});

const codeDB = await createAgentDBAdapter({
  dbPath: '.agentdb/code.db',
});

// 为不同任务使用对应的数据库
await knowledgeDB.insertPattern({ /* 知识数据 */ });
await conversationDB.insertPattern({ /* 对话数据 */ });
await codeDB.insertPattern({ /* 代码数据 */ });

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({ /* ... */ });

typescript
// 按领域分片实现水平扩展
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' }),
};

// 将查询路由到对应的分片
function getDBForDomain(domain: string) {
  const shardKey = domain.split('-')[0];  // 提取分片键
  return shards[shardKey] || shards['domain-a'];
}

// 插入到正确的分片
const db = getDBForDomain('domain-a-task');
await db.insertPattern({ /* ... */ });

MMR (Maximal Marginal Relevance)

MMR(最大边际相关性)

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

检索多样化结果以避免冗余:
typescript
// 不使用MMR:相似结果可能存在冗余
const standardResults = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 10,
  useMMR: false,
});

// 使用MMR:结果多样化且无冗余
const diverseResults = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 10,
  useMMR: true,
  mmrLambda: 0.5,  // 平衡相关性(0)与多样性(1)
});
MMR参数:
  • mmrLambda = 0
    : 最大相关性(可能存在冗余)
  • mmrLambda = 0.5
    : 平衡模式(默认)
  • mmrLambda = 1
    : 最大多样性(相关性可能降低)
适用场景:
  • 搜索结果多样化
  • 推荐系统
  • 避免信息茧房
  • 探索性搜索

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

从多个记忆片段生成丰富上下文:
typescript
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  domain: 'problem-solving',
  k: 10,
  synthesizeContext: true,  // 启用上下文合成
});

// ContextSynthesizer生成连贯的描述
console.log('合成上下文:', result.context);
// "基于10次类似的问题解决尝试,最有效的方法包括:1) 分析根本原因,2) 头脑风暴解决方案,
//  3) 评估权衡,4) 增量式实施。成功率:85%"

console.log('模式:', result.patterns);
// 提取的多个记忆片段中的通用模式

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 });
typescript
// 单例模式实现共享适配器
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;
  }
}

// 在应用中使用
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;
  }
}
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('查询嵌入向量维度不匹配');
      // 处理维度错误
    } else if (error.code === 'DATABASE_LOCKED') {
      // 带指数退避的重试
      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,
});

typescript
// 性能监控
const startTime = Date.now();
const result = await adapter.retrieveWithReasoning(queryEmbedding, { k: 10 });
const latency = Date.now() - startTime;

if (latency > 100) {
  console.warn('检测到慢速查询:', latency, 'ms');
}

// 记录统计信息
const stats = await adapter.getStats();
console.log('数据库统计:', {
  totalPatterns: stats.totalPatterns,
  dbSize: stats.dbSize,
  cacheHitRate: stats.cacheHitRate,
  avgSearchLatency: stats.avgSearchLatency,
});

CLI Advanced Operations

CLI高级操作

Database Import/Export

数据库导入/导出

bash
undefined
bash
undefined

Export with compression

带压缩导出

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

Import from backup

从备份导入

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

Merge databases

合并数据库

npx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite
undefined
npx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite
undefined

Database Optimization

数据库优化

bash
undefined
bash
undefined

Vacuum database (reclaim space)

清理数据库(回收空间)

sqlite3 .agentdb/vectors.db "VACUUM;"
sqlite3 .agentdb/vectors.db "VACUUM;"

Analyze for query optimization

分析数据库以优化查询

sqlite3 .agentdb/vectors.db "ANALYZE;"
sqlite3 .agentdb/vectors.db "ANALYZE;"

Rebuild indices

重建索引

npx agentdb@latest reindex ./vectors.db

---
npx agentdb@latest reindex ./vectors.db

---

Environment Variables

环境变量

bash
undefined
bash
undefined

AgentDB configuration

AgentDB配置

AGENTDB_PATH=.agentdb/reasoningbank.db AGENTDB_ENABLED=true
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
AGENTDB_QUANTIZATION=binary # binary|scalar|product|none AGENTDB_CACHE_SIZE=2000 AGENTDB_HNSW_M=16 AGENTDB_HNSW_EF=100

Learning plugins

学习插件

AGENTDB_LEARNING=true
AGENTDB_LEARNING=true

Reasoning agents

推理Agent

AGENTDB_REASONING=true
AGENTDB_REASONING=true

QUIC synchronization

QUIC同步

AGENTDB_QUIC_SYNC=true AGENTDB_QUIC_PORT=4433 AGENTDB_QUIC_PEERS=host1:4433,host2:4433

---
AGENTDB_QUIC_SYNC=true AGENTDB_QUIC_PORT=4433 AGENTDB_QUIC_PEERS=host1:4433,host2:4433

---

Troubleshooting

故障排查

Issue: QUIC sync not working

问题:QUIC同步不工作

bash
undefined
bash
undefined

Check firewall allows UDP port 4433

检查防火墙是否允许UDP端口4433

sudo ufw allow 4433/udp
sudo ufw allow 4433/udp

Verify peers are reachable

验证节点是否可达

ping host1
ping host1

Check QUIC logs

查看QUIC日志

DEBUG=agentdb:quic node server.js
undefined
DEBUG=agentdb:quic node server.js
undefined

Issue: Hybrid search returns no results

问题:混合搜索无结果返回

typescript
// Relax filters
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  k: 100,  // Increase k
  filters: {
    // Remove or relax filters
  },
});
typescript
undefined

Issue: Memory consolidation too aggressive

放宽过滤条件

typescript
// Disable automatic optimization
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
  optimizeMemory: false,  // Disable auto-consolidation
  k: 10,
});

const result = await adapter.retrieveWithReasoning(queryEmbedding, { k: 100, // 增大k值 filters: { // 移除或放宽过滤条件 }, });
undefined

Learn More

问题:内存合并过于激进


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

Core Principles

禁用自动优化

AgentDB Advanced Features operates on 3 fundamental principles:
const result = await adapter.retrieveWithReasoning(queryEmbedding, { optimizeMemory: false, // 禁用自动合并 k: 10, });

---

Principle 1: Distributed Consistency Through QUIC Synchronization

更多学习资源

Achieve sub-millisecond cross-node synchronization with automatic retry, multiplexing, and TLS 1.3 encryption for distributed vector databases.
In practice:
  • QUIC enables <1ms pattern synchronization across network boundaries with UDP + reliability layer
  • Multiplexed streams allow simultaneous operations (queries, inserts, syncs) without head-of-line blocking
  • Event-based broadcasting ensures eventual consistency with configurable sync intervals (1s default)

分类:高级 / 分布式系统 难度:高级 预计学习时间:45-60分钟

Principle 2: Hybrid Search Combines Vector Similarity with Metadata Filtering

核心原则

Merge semantic understanding (embeddings) with structured constraints (metadata filters) for precision retrieval beyond pure vector search.
In practice:
  • Vector search finds semantically similar documents, metadata filters enforce business rules (date ranges, categories, permissions)
  • MMR (Maximal Marginal Relevance) diversifies results to avoid redundancy while maintaining relevance
  • Custom distance metrics (cosine, Euclidean, dot product) optimize for different embedding types (text vs images)
AgentDB高级功能基于3个核心原则:

Principle 3: Multi-Database Sharding Enables Horizontal Scaling

原则1:通过QUIC同步实现分布式一致性

Partition vector data across databases by domain or tenant for independent scaling and isolation.
In practice:
  • Separate databases per domain (knowledge.db, conversations.db, code.db) prevent cross-contamination
  • Sharding by tenant or region enables geographic distribution and compliance (GDPR data residency)
  • Independent optimization per shard (different quantization, cache sizes) based on access patterns
为分布式向量数据库提供亚毫秒级跨节点同步,具备自动重试、多路复用和TLS 1.3加密能力。
实际应用:
  • QUIC通过UDP+可靠性层实现跨网络边界<1ms的模式同步
  • 多路复用流支持同时执行多个操作(查询、插入、同步),避免队头阻塞
  • 基于事件的广播确保最终一致性,同步间隔可配置(默认1s)

Common Anti-Patterns

原则2:混合搜索结合向量相似度与元数据过滤

Anti-PatternProblemSolution
Synchronous QUIC SyncBlocking operations wait for sync completion, causing 10-100ms latency spikesEnable async sync with configurable intervals (1s), batch sync operations (100 patterns), use fire-and-forget pattern
Over-Filtering Hybrid SearchToo many metadata filters return empty results despite semantic matchesStart with k=100 for vector search, then apply filters; progressively relax filters if results <5
Single Monolithic DatabaseOne database for all domains causes index bloat, slow queries, and cross-domain contaminationShard by domain or tenant; use separate databases with independent indices and optimization strategies
将语义理解(嵌入向量)与结构化约束(元数据过滤)相结合,实现超越纯向量搜索的精确检索。
实际应用:
  • 向量搜索找到语义相似的文档,元数据过滤执行业务规则(日期范围、类别、权限)
  • MMR(最大边际相关性)在保持相关性的同时使结果多样化,避免冗余
  • 自定义距离度量(余弦、欧氏、点积)针对不同嵌入类型(文本vs图像)优化

Conclusion

原则3:多数据库分片支持水平扩展

AgentDB Advanced Features unlocks production-grade distributed AI systems by extending core vector search with QUIC synchronization for multi-node deployments, hybrid search for combining semantic and structured queries, and flexible sharding for horizontal scaling. These capabilities transform AgentDB from a local vector database into a distributed platform capable of supporting multi-agent coordination, geographic distribution, and enterprise-scale applications.
Use this skill when building distributed AI systems requiring cross-node communication (<1ms QUIC sync), implementing RAG systems needing metadata filters beyond semantic search (hybrid search with date/category/permission constraints), or scaling beyond single-machine limits (multi-database sharding by domain/tenant). The key insight is architectural flexibility: QUIC enables distributed consistency, hybrid search adds precision to semantic retrieval, and sharding provides independent scaling per domain. Start with single-database deployment, add QUIC sync when distributing across nodes, enable hybrid search for complex filtering, and implement sharding only when hitting performance or isolation limits.
按领域或租户对向量数据进行分区,实现独立扩展和隔离。
实际应用:
  • 按领域拆分数据库(knowledge.db、conversations.db、code.db)避免交叉污染
  • 按租户或地域分片支持地理分布和合规性(GDPR数据驻留要求)
  • 每个分片可根据访问模式独立优化(不同的量化方式、缓存大小)

常见反模式

反模式问题解决方案
同步QUIC同步阻塞操作等待同步完成,导致10-100ms的延迟峰值启用带可配置间隔(1s)的异步同步,批量同步操作(100个模式),使用"发后即忘"模式
过度过滤的混合搜索过多元数据过滤导致即使存在语义匹配也返回空结果向量搜索先设k=100,再应用过滤;若结果少于5个则逐步放宽过滤条件
单一单体数据库一个数据库用于所有领域导致索引膨胀、查询缓慢和跨领域污染按领域或租户分片;使用独立数据库,每个数据库有独立索引和优化策略

总结

AgentDB高级功能通过为向量搜索扩展QUIC同步(用于多节点部署)、混合搜索(结合语义和结构化查询)和灵活分片(用于水平扩展),解锁了生产级分布式AI系统的能力。这些功能将AgentDB从本地向量数据库转变为支持多Agent协调、地理分布和企业级应用的分布式平台。
在以下场景中使用本技能:构建需要跨节点通信(<1ms QUIC同步)的分布式AI系统、实现需要元数据过滤的RAG系统(带日期/类别/权限约束的混合搜索)、或突破单机器限制进行扩展(按领域/租户的多数据库分片)。核心设计思路是架构灵活性:QUIC实现分布式一致性,混合搜索为语义检索增加精确性,分片支持按领域独立扩展。建议从单数据库部署开始,需要跨节点分布时添加QUIC同步,需要复杂过滤时启用混合搜索,仅当遇到性能或隔离限制时再实现分片。