agentdb-advanced-features
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLIBRARY-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
决策矩阵
| Match | Action |
|---|---|
| Library >90% | REUSE directly |
| Library 70-90% | ADAPT minimally |
| Pattern exists | FOLLOW pattern |
| In project | EXTRACT |
| No match | BUILD (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 ~1mstypescript
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
undefinedbash
undefinedNode 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_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
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_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
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_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
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
undefinedCLI
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
undefinedCLI
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
undefinedCLI
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:
- : Maximum relevance (may be redundant)
mmrLambda = 0 - : Balanced (default)
mmrLambda = 0.5 - : Maximum diversity (may be less relevant)
mmrLambda = 1
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
undefinedbash
undefinedExport 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
undefinednpx agentdb@latest merge ./db1.sqlite ./db2.sqlite ./merged.sqlite
undefinedDatabase Optimization
数据库优化
bash
undefinedbash
undefinedVacuum 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
undefinedbash
undefinedAgentDB 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
undefinedbash
undefinedCheck 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
undefinedDEBUG=agentdb:quic node server.js
undefinedIssue: Hybrid search returns no results
问题:混合搜索无结果返回
typescript
// Relax filters
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
k: 100, // Increase k
filters: {
// Remove or relax filters
},
});typescript
undefinedIssue: 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: {
// 移除或放宽过滤条件
},
});
undefinedLearn 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
typescript
undefinedCore 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)
- QUIC协议:docs/quic-synchronization.pdf
- 混合搜索:docs/hybrid-search-guide.md
- GitHub:https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
- 官网:https://agentdb.ruv.io
分类:高级 / 分布式系统
难度:高级
预计学习时间: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-Pattern | Problem | Solution |
|---|---|---|
| Synchronous QUIC Sync | Blocking operations wait for sync completion, causing 10-100ms latency spikes | Enable async sync with configurable intervals (1s), batch sync operations (100 patterns), use fire-and-forget pattern |
| Over-Filtering Hybrid Search | Too many metadata filters return empty results despite semantic matches | Start with k=100 for vector search, then apply filters; progressively relax filters if results <5 |
| Single Monolithic Database | One database for all domains causes index bloat, slow queries, and cross-domain contamination | Shard 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同步,需要复杂过滤时启用混合搜索,仅当遇到性能或隔离限制时再实现分片。