reasoningbank-with-agentdb
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倍加速的宣称)
ReasoningBank with AgentDB
基于AgentDB的ReasoningBank
What This Skill Does
功能概述
Provides ReasoningBank adaptive learning patterns using AgentDB's high-performance backend (150x-12,500x faster). Enables agents to learn from experiences, judge outcomes, distill memories, and improve decision-making over time with 100% backward compatibility.
Performance: 150x faster pattern retrieval, 500x faster batch operations, <1ms memory access.
借助AgentDB高性能后端(速度提升150-12500倍)提供ReasoningBank自适应学习模式,支持Agent从经验中学习、判断结果、蒸馏记忆并持续优化决策,同时保持100%向后兼容。
性能表现:模式检索速度提升150倍,批量操作速度提升500倍,内存访问耗时<1ms。
Prerequisites
前置条件
- Node.js 18+
- AgentDB v1.0.7+ (via agentic-flow)
- Understanding of reinforcement learning concepts (optional)
- Node.js 18+
- AgentDB v1.0.7+(通过agentic-flow安装)
- 了解强化学习概念(可选)
Quick Start with CLI
CLI快速开始
Initialize ReasoningBank Database
初始化ReasoningBank数据库
bash
undefinedbash
undefinedInitialize AgentDB for ReasoningBank
为ReasoningBank初始化AgentDB
npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536
npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536
Start MCP server for Claude Code integration
启动MCP服务器以集成Claude Code
npx agentdb@latest mcp
claude mcp add agentdb npx agentdb@latest mcp
undefinednpx agentdb@latest mcp
claude mcp add agentdb npx agentdb@latest mcp
undefinedMigrate from Legacy ReasoningBank
从旧版ReasoningBank迁移
bash
undefinedbash
undefinedAutomatic migration with validation
带验证的自动迁移
npx agentdb@latest migrate --source .swarm/memory.db
npx agentdb@latest migrate --source .swarm/memory.db
Verify migration
验证迁移结果
npx agentdb@latest stats ./.agentdb/reasoningbank.db
---npx agentdb@latest stats ./.agentdb/reasoningbank.db
---Quick Start with API
API快速开始
typescript
import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
// Initialize ReasoningBank with AgentDB
const rb = await createAgentDBAdapter({
dbPath: '.agentdb/reasoningbank.db',
enableLearning: true, // Enable learning plugins
enableReasoning: true, // Enable reasoning agents
cacheSize: 1000, // 1000 pattern cache
});
// Store successful experience
const query = "How to optimize database queries?";
const embedding = await computeEmbedding(query);
await rb.insertPattern({
id: '',
type: 'experience',
domain: 'database-optimization',
pattern_data: JSON.stringify({
embedding,
pattern: {
query,
approach: 'indexing + query optimization',
outcome: 'success',
metrics: { latency_reduction: 0.85 }
}
}),
confidence: 0.95,
usage_count: 1,
success_count: 1,
created_at: Date.now(),
last_used: Date.now(),
});
// Retrieve similar experiences with reasoning
const result = await rb.retrieveWithReasoning(embedding, {
domain: 'database-optimization',
k: 5,
useMMR: true, // Diverse results
synthesizeContext: true, // Rich context synthesis
});
console.log('Memories:', result.memories);
console.log('Context:', result.context);
console.log('Patterns:', result.patterns);typescript
import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
// 用AgentDB初始化ReasoningBank
const rb = await createAgentDBAdapter({
dbPath: '.agentdb/reasoningbank.db',
enableLearning: true, // 启用学习插件
enableReasoning: true, // 启用推理Agent
cacheSize: 1000, // 1000条模式缓存
});
// 存储成功经验
const query = "How to optimize database queries?";
const embedding = await computeEmbedding(query);
await rb.insertPattern({
id: '',
type: 'experience',
domain: 'database-optimization',
pattern_data: JSON.stringify({
embedding,
pattern: {
query,
approach: 'indexing + query optimization',
outcome: 'success',
metrics: { latency_reduction: 0.85 }
}
}),
confidence: 0.95,
usage_count: 1,
success_count: 1,
created_at: Date.now(),
last_used: Date.now(),
});
// 结合推理检索相似经验
const result = await rb.retrieveWithReasoning(embedding, {
domain: 'database-optimization',
k: 5,
useMMR: true, // 获取多样化结果
synthesizeContext: true, // 生成丰富上下文
});
console.log('Memories:', result.memories);
console.log('Context:', result.context);
console.log('Patterns:', result.patterns);Core ReasoningBank Concepts
ReasoningBank核心概念
1. Trajectory Tracking
1. 轨迹追踪
Track agent execution paths and outcomes:
typescript
// Record trajectory (sequence of actions)
const trajectory = {
task: 'optimize-api-endpoint',
steps: [
{ action: 'analyze-bottleneck', result: 'found N+1 query' },
{ action: 'add-eager-loading', result: 'reduced queries' },
{ action: 'add-caching', result: 'improved latency' }
],
outcome: 'success',
metrics: { latency_before: 2500, latency_after: 150 }
};
const embedding = await computeEmbedding(JSON.stringify(trajectory));
await rb.insertPattern({
id: '',
type: 'trajectory',
domain: 'api-optimization',
pattern_data: JSON.stringify({ embedding, pattern: trajectory }),
confidence: 0.9,
usage_count: 1,
success_count: 1,
created_at: Date.now(),
last_used: Date.now(),
});追踪Agent的执行路径和结果:
typescript
// 记录轨迹(动作序列)
const trajectory = {
task: 'optimize-api-endpoint',
steps: [
{ action: 'analyze-bottleneck', result: 'found N+1 query' },
{ action: 'add-eager-loading', result: 'reduced queries' },
{ action: 'add-caching', result: 'improved latency' }
],
outcome: 'success',
metrics: { latency_before: 2500, latency_after: 150 }
};
const embedding = await computeEmbedding(JSON.stringify(trajectory));
await rb.insertPattern({
id: '',
type: 'trajectory',
domain: 'api-optimization',
pattern_data: JSON.stringify({ embedding, pattern: trajectory }),
confidence: 0.9,
usage_count: 1,
success_count: 1,
created_at: Date.now(),
last_used: Date.now(),
});2. Verdict Judgment
2. 结果判定
Judge whether a trajectory was successful:
typescript
// Retrieve similar past trajectories
const similar = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'api-optimization',
k: 10,
});
// Judge based on similarity to successful patterns
const verdict = similar.memories.filter(m =>
m.pattern.outcome === 'success' &&
m.similarity > 0.8
).length > 5 ? 'likely_success' : 'needs_review';
console.log('Verdict:', verdict);
console.log('Confidence:', similar.memories[0]?.similarity || 0);判断轨迹执行是否成功:
typescript
// 检索相似的历史轨迹
const similar = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'api-optimization',
k: 10,
});
// 基于与成功模式的相似度判定结果
const verdict = similar.memories.filter(m =>
m.pattern.outcome === 'success' &&
m.similarity > 0.8
).length > 5 ? 'likely_success' : 'needs_review';
console.log('Verdict:', verdict);
console.log('Confidence:', similar.memories[0]?.similarity || 0);3. Memory Distillation
3. 记忆蒸馏
Consolidate similar experiences into patterns:
typescript
// Get all experiences in domain
const experiences = await rb.retrieveWithReasoning(embedding, {
domain: 'api-optimization',
k: 100,
optimizeMemory: true, // Automatic consolidation
});
// Distill into high-level pattern
const distilledPattern = {
domain: 'api-optimization',
pattern: 'For N+1 queries: add eager loading, then cache',
success_rate: 0.92,
sample_size: experiences.memories.length,
confidence: 0.95
};
await rb.insertPattern({
id: '',
type: 'distilled-pattern',
domain: 'api-optimization',
pattern_data: JSON.stringify({
embedding: await computeEmbedding(JSON.stringify(distilledPattern)),
pattern: distilledPattern
}),
confidence: 0.95,
usage_count: 0,
success_count: 0,
created_at: Date.now(),
last_used: Date.now(),
});将相似经验整合为模式:
typescript
// 获取领域内所有经验
const experiences = await rb.retrieveWithReasoning(embedding, {
domain: 'api-optimization',
k: 100,
optimizeMemory: true, // 自动整合
});
// 提炼为高层级模式
const distilledPattern = {
domain: 'api-optimization',
pattern: 'For N+1 queries: add eager loading, then cache',
success_rate: 0.92,
sample_size: experiences.memories.length,
confidence: 0.95
};
await rb.insertPattern({
id: '',
type: 'distilled-pattern',
domain: 'api-optimization',
pattern_data: JSON.stringify({
embedding: await computeEmbedding(JSON.stringify(distilledPattern)),
pattern: distilledPattern
}),
confidence: 0.95,
usage_count: 0,
success_count: 0,
created_at: Date.now(),
last_used: Date.now(),
});Integration with Reasoning Agents
与推理Agent的集成
AgentDB provides 4 reasoning modules that enhance ReasoningBank:
AgentDB提供4个推理模块以增强ReasoningBank功能:
1. PatternMatcher
1. PatternMatcher(模式匹配器)
Find similar successful patterns:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'problem-solving',
k: 10,
useMMR: true, // Maximal Marginal Relevance for diversity
});
// PatternMatcher returns diverse, relevant memories
result.memories.forEach(mem => {
console.log(`Pattern: ${mem.pattern.approach}`);
console.log(`Similarity: ${mem.similarity}`);
console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
});查找相似的成功模式:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'problem-solving',
k: 10,
useMMR: true, // 最大化边际相关性以获取多样化结果
});
// PatternMatcher返回多样化的相关记忆
result.memories.forEach(mem => {
console.log(`Pattern: ${mem.pattern.approach}`);
console.log(`Similarity: ${mem.similarity}`);
console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
});2. ContextSynthesizer
2. ContextSynthesizer(上下文合成器)
Generate rich context from multiple memories:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'code-optimization',
synthesizeContext: true, // Enable context synthesis
k: 5,
});
// ContextSynthesizer creates coherent narrative
console.log('Synthesized Context:', result.context);
// "Based on 5 similar optimizations, the most effective approach
// involves profiling, identifying bottlenecks, and applying targeted
// improvements. Success rate: 87%"从多个记忆生成丰富上下文:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'code-optimization',
synthesizeContext: true, // 启用上下文合成
k: 5,
});
// ContextSynthesizer生成连贯的描述
console.log('Synthesized Context:', result.context);
// "基于5个相似优化案例,最有效的方法
// 包括性能分析、识别瓶颈并应用针对性改进。成功率:87%"3. MemoryOptimizer
3. MemoryOptimizer(记忆优化器)
Automatically consolidate and prune:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'testing',
optimizeMemory: true, // Enable automatic optimization
});
// MemoryOptimizer consolidates similar patterns and prunes low-quality
console.log('Optimizations:', result.optimizations);
// { consolidated: 15, pruned: 3, improved_quality: 0.12 }自动整合和修剪记忆:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'testing',
optimizeMemory: true, // 启用自动优化
});
// MemoryOptimizer整合相似模式并修剪低质量内容
console.log('Optimizations:', result.optimizations);
// { consolidated: 15, pruned: 3, improved_quality: 0.12 }4. ExperienceCurator
4. ExperienceCurator(经验筛选器)
Filter by quality and relevance:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'debugging',
k: 20,
minConfidence: 0.8, // Only high-confidence experiences
});
// ExperienceCurator returns only quality experiences
result.memories.forEach(mem => {
console.log(`Confidence: ${mem.confidence}`);
console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
});按质量和相关性筛选:
typescript
const result = await rb.retrieveWithReasoning(queryEmbedding, {
domain: 'debugging',
k: 20,
minConfidence: 0.8, // 仅保留高置信度经验
});
// ExperienceCurator仅返回高质量经验
result.memories.forEach(mem => {
console.log(`Confidence: ${mem.confidence}`);
console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
});Legacy API Compatibility
旧版API兼容性
AgentDB maintains 100% backward compatibility with legacy ReasoningBank:
typescript
import {
retrieveMemories,
judgeTrajectory,
distillMemories
} from 'agentic-flow/reasoningbank';
// Legacy API works unchanged (uses AgentDB backend automatically)
const memories = await retrieveMemories(query, {
domain: 'code-generation',
agent: 'coder'
});
const verdict = await judgeTrajectory(trajectory, query);
const newMemories = await distillMemories(
trajectory,
verdict,
query,
{ domain: 'code-generation' }
);AgentDB与旧版ReasoningBank保持100%向后兼容:
typescript
import {
retrieveMemories,
judgeTrajectory,
distillMemories
} from 'agentic-flow/reasoningbank';
// 旧版API可直接使用(自动基于AgentDB后端运行)
const memories = await retrieveMemories(query, {
domain: 'code-generation',
agent: 'coder'
});
const verdict = await judgeTrajectory(trajectory, query);
const newMemories = await distillMemories(
trajectory,
verdict,
query,
{ domain: 'code-generation' }
);Performance Characteristics
性能特性
- Pattern Search: 150x faster (100µs vs 15ms)
- Memory Retrieval: <1ms (with cache)
- Batch Insert: 500x faster (2ms vs 1s for 100 patterns)
- Trajectory Judgment: <5ms (including retrieval + analysis)
- Memory Distillation: <50ms (consolidate 100 patterns)
- 模式搜索:速度提升150倍(100微秒 vs 15毫秒)
- 记忆检索:耗时<1ms(带缓存)
- 批量插入:速度提升500倍(插入100条模式耗时2毫秒 vs 1秒)
- 轨迹判定:耗时<5ms(含检索+分析)
- 记忆蒸馏:耗时<50ms(整合100条模式)
Advanced Patterns
高级模式
Hierarchical Memory
分层记忆
Organize memories by abstraction level:
typescript
// Low-level: Specific implementation
await rb.insertPattern({
type: 'concrete',
domain: 'debugging/null-pointer',
pattern_data: JSON.stringify({
embedding,
pattern: { bug: 'NPE in UserService.getUser()', fix: 'Add null check' }
}),
confidence: 0.9,
// ...
});
// Mid-level: Pattern across similar cases
await rb.insertPattern({
type: 'pattern',
domain: 'debugging',
pattern_data: JSON.stringify({
embedding,
pattern: { category: 'null-pointer', approach: 'defensive-checks' }
}),
confidence: 0.85,
// ...
});
// High-level: General principle
await rb.insertPattern({
type: 'principle',
domain: 'software-engineering',
pattern_data: JSON.stringify({
embedding,
pattern: { principle: 'fail-fast with clear errors' }
}),
confidence: 0.95,
// ...
});按抽象级别组织记忆:
typescript
// 低层级:具体实现
await rb.insertPattern({
type: 'concrete',
domain: 'debugging/null-pointer',
pattern_data: JSON.stringify({
embedding,
pattern: { bug: 'NPE in UserService.getUser()', fix: 'Add null check' }
}),
confidence: 0.9,
// ...
});
// 中间层:相似场景的通用模式
await rb.insertPattern({
type: 'pattern',
domain: 'debugging',
pattern_data: JSON.stringify({
embedding,
pattern: { category: 'null-pointer', approach: 'defensive-checks' }
}),
confidence: 0.85,
// ...
});
// 高层级:通用原则
await rb.insertPattern({
type: 'principle',
domain: 'software-engineering',
pattern_data: JSON.stringify({
embedding,
pattern: { principle: 'fail-fast with clear errors' }
}),
confidence: 0.95,
// ...
});Multi-Domain Learning
跨领域学习
Transfer learning across domains:
typescript
// Learn from backend optimization
const backendExperience = await rb.retrieveWithReasoning(embedding, {
domain: 'backend-optimization',
k: 10,
});
// Apply to frontend optimization
const transferredKnowledge = backendExperience.memories.map(mem => ({
...mem,
domain: 'frontend-optimization',
adapted: true,
}));在不同领域间迁移学习成果:
typescript
// 从后端优化领域获取经验
const backendExperience = await rb.retrieveWithReasoning(embedding, {
domain: 'backend-optimization',
k: 10,
});
// 应用到前端优化领域
const transferredKnowledge = backendExperience.memories.map(mem => ({
...mem,
domain: 'frontend-optimization',
adapted: true,
}));CLI Operations
CLI操作
Database Management
数据库管理
bash
undefinedbash
undefinedExport trajectories and patterns
导出轨迹和模式
npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json
npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json
Import experiences
导入经验
npx agentdb@latest import ./experiences.json
npx agentdb@latest import ./experiences.json
Get statistics
获取统计数据
npx agentdb@latest stats ./.agentdb/reasoningbank.db
npx agentdb@latest stats ./.agentdb/reasoningbank.db
Shows: total patterns, domains, confidence distribution
显示:模式总数、领域数量、置信度分布
undefinedundefinedMigration
迁移
bash
undefinedbash
undefinedMigrate from legacy ReasoningBank
从旧版ReasoningBank迁移
npx agentdb@latest migrate --source .swarm/memory.db --target .agentdb/reasoningbank.db
npx agentdb@latest migrate --source .swarm/memory.db --target .agentdb/reasoningbank.db
Validate migration
验证迁移结果
npx agentdb@latest stats .agentdb/reasoningbank.db
---npx agentdb@latest stats .agentdb/reasoningbank.db
---Troubleshooting
故障排查
Issue: Migration fails
问题:迁移失败
bash
undefinedbash
undefinedCheck source database exists
检查源数据库是否存在
ls -la .swarm/memory.db
ls -la .swarm/memory.db
Run with verbose logging
启用 verbose 日志重新运行
DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db
undefinedDEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db
undefinedIssue: Low confidence scores
问题:置信度分数低
typescript
// Enable context synthesis for better quality
const result = await rb.retrieveWithReasoning(embedding, {
synthesizeContext: true,
useMMR: true,
k: 10,
});typescript
// 启用上下文合成以提升质量
const result = await rb.retrieveWithReasoning(embedding, {
synthesizeContext: true,
useMMR: true,
k: 10,
});Issue: Memory growing too large
问题:内存占用过大
typescript
// Enable automatic optimization
const result = await rb.retrieveWithReasoning(embedding, {
optimizeMemory: true, // Consolidates similar patterns
});
// Or manually optimize
await rb.optimize();typescript
// 启用自动优化
const result = await rb.retrieveWithReasoning(embedding, {
optimizeMemory: true, // 整合相似模式
});
// 或手动执行优化
await rb.optimize();Learn More
更多学习资源
- AgentDB Integration: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
- GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
- MCP Integration:
npx agentdb@latest mcp - Website: https://agentdb.ruv.io
Category: Machine Learning / Reinforcement Learning
Difficulty: Intermediate
Estimated Time: 20-30 minutes
- AgentDB集成文档:node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
- GitHub仓库:https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
- MCP集成命令:
npx agentdb@latest mcp - 官方网站:https://agentdb.ruv.io
分类:机器学习 / 强化学习
难度:中等
预计学习时间:20-30分钟
Core Principles
核心原则
-
Vector Semantic Retrieval Over Exact Matching: ReasoningBank with AgentDB leverages 150x faster vector search (100us vs 15ms) through semantic embeddings, retrieving similar trajectories even when keywords differ, enabling agents to learn from experiences described differently but contextually identical.
-
Adaptive Memory Consolidation: Memory distillation consolidates 100+ granular experiences (e.g., "fixed NPE in UserService", "added null check to AuthService") into higher-level patterns ("defensive null checks prevent pointer exceptions"), reducing memory footprint while preserving learned knowledge and avoiding pattern redundancy.
-
Confidence-Weighted Experience Replay: Verdict judgment retrieves patterns filtered by confidence (>0.8) and success rate, prioritizing proven trajectories over experimental ones, preventing agents from repeating failed approaches while still allowing exploration of medium-confidence strategies (0.5-0.8) when explicitly needed.
-
向量语义检索优于精确匹配:基于AgentDB的ReasoningBank通过语义嵌入实现比传统快150倍的向量搜索(100微秒 vs 15毫秒),即使关键词不同也能检索到相似轨迹,让Agent能够从描述不同但上下文一致的经验中学习。
-
自适应记忆整合:记忆蒸馏功能可将100+条细粒度经验(如"修复UserService中的NPE"、"为AuthService添加空值检查")整合为高层级模式(如"防御性空值检查可避免指针异常"),在保留学习到的知识的同时减少内存占用,避免模式冗余。
-
基于置信度的经验回放:结果判定功能会筛选出置信度>0.8且成功率高的模式,优先使用已验证的轨迹而非实验性方案,同时在明确需要时仍允许探索置信度为0.5-0.8的中等置信度策略,避免Agent重复失败的方法。
Anti-Patterns
反模式
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Storing raw text without embeddings | Pattern retrieval becomes keyword search, missing semantically similar experiences ("optimize query" vs "speed up database") | Always compute embeddings via computeEmbedding() before insertion, enabling semantic similarity matching |
| Skipping memory distillation | 10,000+ micro-experiences (every bug fix stored separately) bloat database to >2GB, slowing retrieval to >500ms | Run automatic consolidation (optimizeMemory: true) or manual distillation after 100+ experiences in same domain |
| Using trajectory outcomes without confidence scores | Agent treats single successful case (confidence 0.6) as proven pattern, repeating approaches that succeeded by luck | Only apply patterns with confidence >0.8 and usage_count >3, mark experimental patterns as "needs validation" |
| 反模式 | 失败原因 | 正确做法 |
|---|---|---|
| 存储原始文本而不生成嵌入向量 | 模式检索退化为关键词搜索,会错过语义相似的经验(如"优化查询" vs "加速数据库") | 插入前始终通过computeEmbedding()生成嵌入向量,实现语义相似度匹配 |
| 跳过记忆蒸馏 | 10000+条微经验(每个bug修复单独存储)会导致数据库膨胀至>2GB,检索速度变慢至>500ms | 当同一领域的经验达到100+条时,启用自动整合(optimizeMemory: true)或手动执行蒸馏 |
| 使用轨迹结果但不考虑置信度分数 | Agent会将单次成功的案例(置信度0.6)视为已验证模式,重复因运气成功的方法 | 仅应用置信度>0.8且使用次数>3的模式,将实验性模式标记为"需要验证" |
Conclusion
总结
ReasoningBank with AgentDB transforms agent learning from ephemeral task execution to persistent experience accumulation, enabling agents to judge new trajectories against historical patterns (verdict judgment), consolidate granular learnings into reusable strategies (memory distillation), and retrieve contextually relevant experiences through 150x faster vector search. This creates a flywheel effect - each task improves the pattern library, making future similar tasks faster and more accurate.
The key to production success is maintaining the 70% survival threshold for pattern updates: adversarial validation must challenge new learnings (e.g., "does this null check pattern apply to async contexts?") and only accept patterns that survive scrutiny. Without this rigor, confident drift accumulates - the agent becomes certain of incorrect patterns, degrading performance over time. When tracking learning delta, measure not just task completion rate, but pattern quality (success_rate / usage_count) - a high-quality ReasoningBank enables 10x faster task execution through proven trajectory reuse.
基于AgentDB的ReasoningBank将Agent学习从临时任务执行转变为持久化经验积累,让Agent能够对照历史模式判断新轨迹的结果(结果判定)、将细粒度学习成果整合为可复用策略(记忆蒸馏),并通过快150倍的向量搜索检索上下文相关的经验。这会形成飞轮效应——每个任务都会优化模式库,让未来的相似任务执行得更快、更准确。
生产环境成功的关键是为模式更新维持70%的留存阈值:对抗性验证必须挑战新的学习成果(如"这种空值检查模式是否适用于异步场景?"),仅接受通过检验的模式。若缺乏这种严谨性,会出现置信度漂移——Agent会对错误的模式产生确定性,导致性能随时间下降。追踪学习增量时,不仅要衡量任务完成率,还要衡量模式质量(成功率/使用次数)——高质量的ReasoningBank可通过复用已验证轨迹让任务执行速度提升10倍。