Loading...
Loading...
Compare original and translation side by side
.claude/library/catalog.json.claude/library/catalog.json.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.mdD:\Projects\*D:\Projects\*| 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% | 最小程度适配 |
| 已有对应模式 | 遵循模式 |
| 现有项目存在 | 提取适配 |
| 无匹配项 | 重新构建（完成后添加到库中） |
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 ~1msimport { 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内即可在所有节点上访问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
});const adapter = await createAgentDBAdapter({
enableQUICSync: true,
syncPort: 4433, // QUIC服务器端口
syncPeers: ['host1:4433'], // 节点地址
syncInterval: 1000, // 同步间隔（毫秒）
syncBatchSize: 100, // 每批同步的模式数量
maxRetries: 3, // 同步失败重试次数
compression: true, // 启用压缩
});undefinedundefined
---
---undefinedundefined
**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)
**适用场景**:
- 文本嵌入向量（BERT、GPT等）
- 语义搜索
- 文档相似度
- 大多数通用场景
**公式**：`cos(θ) = (A · B) / (||A|| × ||B||)`
**取值范围**：[-1, 1]（1=完全相同，-1=完全相反）undefinedundefined
**Use Cases**:
- Image embeddings
- Spatial data
- Computer vision
- When vector magnitude matters
**Formula**: `d = √(Σ(ai - bi)²)`
**Range**: [0, ∞] (0 = identical, ∞ = very different)
**适用场景**:
- 图像嵌入向量
- 空间数据
- 计算机视觉
- 向量长度有意义的场景
**公式**：`d = √(Σ(ai - bi)²)`
**取值范围**：[0, ∞]（0=完全相同，∞=差异极大）undefinedundefined
**Use Cases**:
- Pre-normalized embeddings
- Fast similarity computation
- When vectors are already unit-length
**Formula**: `dot = Σ(ai × bi)`
**Range**: [-∞, ∞] (higher = more similar)
**适用场景**:
- 预归一化嵌入向量
- 快速相似度计算
- 向量已为单位长度的场景
**公式**：`dot = Σ(ai × bi)`
**取值范围**：[-∞, ∞]（值越高越相似）// 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)// 实现自定义距离函数
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);
}
// 在搜索中使用（需要自定义实现）// 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
},
});// 存储带元数据的文档
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 }, // 高引用量
},
});// 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
},
});// 复杂元数据查询
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' }, // 包含指定标签
},
});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
},
});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天
},
});// 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 */ });// 为不同领域创建独立数据库
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({ /* 代码数据 */ });// 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({ /* ... */ });// 按领域分片实现水平扩展
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({ /* ... */ });// 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)
});mmrLambda = 0mmrLambda = 0.5mmrLambda = 1// 不使用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）
});mmrLambda = 0mmrLambda = 0.5mmrLambda = 1const 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 memoriesconst 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);
// 提取的多个记忆片段中的通用模式// 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 });// 单例模式实现共享适配器
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 });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;
}
}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;
}
}// 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,
});// 性能监控
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,
});undefinedundefinedundefinedundefinedundefinedundefined
---
---undefinedundefined
---
---undefinedundefinedundefinedundefined// Relax filters
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
k: 100, // Increase k
filters: {
// Remove or relax filters
},
});undefined// Disable automatic optimization
const result = await adapter.retrieveWithReasoning(queryEmbedding, {
optimizeMemory: false, // Disable auto-consolidation
k: 10,
});undefinedundefined
---| 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 |
| 反模式 | 问题 | 解决方案 |
|---|---|---|
| 同步QUIC同步 | 阻塞操作等待同步完成，导致10-100ms的延迟峰值 | 启用带可配置间隔（1s）的异步同步，批量同步操作（100个模式），使用"发后即忘"模式 |
| 过度过滤的混合搜索 | 过多元数据过滤导致即使存在语义匹配也返回空结果 | 向量搜索先设k=100，再应用过滤；若结果少于5个则逐步放宽过滤条件 |
| 单一单体数据库 | 一个数据库用于所有领域导致索引膨胀、查询缓慢和跨领域污染 | 按领域或租户分片；使用独立数据库，每个数据库有独立索引和优化策略 |