reasoningbank-with-agentdb

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倍加速的宣称)

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

Initialize 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
undefined
npx agentdb@latest mcp claude mcp add agentdb npx agentdb@latest mcp
undefined

Migrate from Legacy ReasoningBank

从旧版ReasoningBank迁移

bash
undefined
bash
undefined

Automatic 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
undefined
bash
undefined

Export 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

显示:模式总数、领域数量、置信度分布

undefined
undefined

Migration

迁移

bash
undefined
bash
undefined

Migrate 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
undefined
bash
undefined

Check 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
undefined
DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db
undefined

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

更多学习资源


Category: Machine Learning / Reinforcement Learning Difficulty: Intermediate Estimated Time: 20-30 minutes

分类:机器学习 / 强化学习 难度:中等 预计学习时间:20-30分钟

Core Principles

核心原则

  1. 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.
  2. 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.
  3. 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.
  1. 向量语义检索优于精确匹配:基于AgentDB的ReasoningBank通过语义嵌入实现比传统快150倍的向量搜索(100微秒 vs 15毫秒),即使关键词不同也能检索到相似轨迹,让Agent能够从描述不同但上下文一致的经验中学习。
  2. 自适应记忆整合:记忆蒸馏功能可将100+条细粒度经验(如"修复UserService中的NPE"、"为AuthService添加空值检查")整合为高层级模式(如"防御性空值检查可避免指针异常"),在保留学习到的知识的同时减少内存占用,避免模式冗余。
  3. 基于置信度的经验回放:结果判定功能会筛选出置信度>0.8且成功率高的模式,优先使用已验证的轨迹而非实验性方案,同时在明确需要时仍允许探索置信度为0.5-0.8的中等置信度策略,避免Agent重复失败的方法。

Anti-Patterns

反模式

Anti-PatternWhy It FailsCorrect Approach
Storing raw text without embeddingsPattern 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 distillation10,000+ micro-experiences (every bug fix stored separately) bloat database to >2GB, slowing retrieval to >500msRun automatic consolidation (optimizeMemory: true) or manual distillation after 100+ experiences in same domain
Using trajectory outcomes without confidence scoresAgent treats single successful case (confidence 0.6) as proven pattern, repeating approaches that succeeded by luckOnly 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倍。