Ruflo 中的 ReasoningBank 与 AgentDB：用自适应学习让 Agent 从轨迹中沉淀可复用经验

本篇围绕 ReasoningBank with AgentDB 技能文档 展开，讲解如何在 ruflo 项目中落地 ReasoningBank 自适应学习体系：通过 AgentDB 高性能向量后端完成轨迹追踪（Trajectory Tracking）、结果裁决（Verdict Judgment）与记忆蒸馏（Memory Distillation），并接入 PatternMatcher、ContextSynthesizer、MemoryOptimizer、ExperienceCurator 四个推理模块。读完本文，你将掌握初始化 AgentDB 库、迁移旧版 ReasoningBank、调用 insertPattern / retrieveWithReasoning API 的完整流程，并能对照仓库源码理解 MMR 检索、HNSW 索引、短期/长期记忆晋升等底层机制。

一、技能定位：为什么 ReasoningBank 需要 AgentDB

该技能文档定义了一套"让 Agent 从经验中学习"的实现模式：Agent 执行任务后记录轨迹、判定成败、把成功经验蒸馏为高层模式，并在后续相似任务中检索复用。技能选择 AgentDB 作为后端，文档给出的动机与指标（引自技能文档原文）包括：

• 模式检索提速 150x，批量操作提速 500x，带缓存时内存访问 <1ms；
• 与旧版（legacy）ReasoningBank 保持 100% 向后兼容。

前提条件方面，文档要求 Node.js 18+、通过 agentic-flow 安装的 AgentDB v1.0.7+；强化学习背景知识为可选项。这一"兼容层"定位在仓库源码中同样成立：ruflo 的 hooks 包在 AgentDB 不可用时会自动降级为纯内存模式，技能文档描述的 CLI/迁移能力因此构成完整的兜底路径。

前提	要求
运行时	Node.js 18+
AgentDB	v1.0.7+（经 agentic-flow 提供）
背景知识	强化学习概念（可选）

二、CLI 快速上手：初始化、MCP 接入与迁移

技能文档给出的 CLI 操作分三类：初始化、MCP 集成、迁移。

2.1 初始化 ReasoningBank 数据库

# Initialize AgentDB for ReasoningBank
npx agentdb@latest init ./.agentdb$reasoningbank.db --dimension 1536

# Start MCP server for Claude Code integration
npx agentdb@latest mcp
claude mcp add agentdb npx agentdb@latest mcp

--dimension 1536 对应 OpenAI 系嵌入向量维度；而 ruflo 源码中 ReasoningBank 的默认维度是 384（MiniLM-L6），见 ReasoningBank 默认配置 中 dimensions: 384 的注释"MiniLM-L6 / 1536 for OpenAI"。两个维度各有所指：CLI 示例面向通用嵌入模型，hooks 内置实现面向本地 ONNX 模型，实际项目中应保持初始化维度与嵌入服务一致。

claude mcp add 一行把 AgentDB 注册为 Claude Code 的 MCP 服务，使对话侧可以直接调用向量库能力。

2.2 从旧版 ReasoningBank 迁移

# Automatic migration with validation
npx agentdb@latest migrate --source .swarm$memory.db

# Verify migration
npx agentdb@latest stats ./.agentdb$reasoningbank.db

迁移时也可显式指定目标库：

npx agentdb@latest migrate --source .swarm$memory.db --target .agentdb$reasoningbank.db
npx agentdb@latest stats .agentdb$reasoningbank.db

三、TypeScript API：写入经验与带推理的检索

技能文档的 API 部分以 agentic-flow$reasoningbank 模块为入口，核心是 createAgentDBAdapter 工厂函数。

3.1 初始化适配器

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

参数含义：

参数	说明
dbPath	AgentDB 数据库文件路径
enableLearning	启用学习插件（蒸馏、巩固等）
enableReasoning	启用推理模块（四个 reasoning modules）
cacheSize	模式缓存容量，示例取 1000

值得注意的是，ruflo 内置的 V3 适配器 ReasoningBankAdapter 提供了同名的 enableLearning / enableReasoning 配置项，默认值均为 true，与技能文档语义一致，说明两者是同一套接口的不同封装。

3.2 存入一条成功经验

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

字段约定值得注意：id 传空串时由后端生成；type 区分经验层级（experience / trajectory / distilled-pattern，高级用法中还有 concrete / pattern / principle）；pattern_data 是序列化 JSON，内嵌向量与结构化载荷；confidence、usage_count、success_count 是后续裁决与蒸馏的核心依据。

对照仓库源码，ReasoningBankPattern 接口 表达了相同的数据契约：patternData.source 记录 taskId、agentId、outcome（Success/Failure/Partial）与 evidence 证据列表，nUses 与 confidence 构成质量信号——这正是技能文档中 usage_count/confidence 字段的内化形式。

3.3 带推理的检索

// 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);

retrieveWithReasoning 的选项贯穿整个技能文档，汇总如下：

选项	作用	关联模块
domain	限定检索域	全部
k	返回条数	全部
useMMR	MMR 保证结果多样性	PatternMatcher
synthesizeContext	合成富上下文叙述	ContextSynthesizer
optimizeMemory	自动合并与剪枝	MemoryOptimizer
minConfidence	置信度下限过滤	ExperienceCurator

四、三大核心机制：轨迹、裁决与蒸馏

技能文档把 ReasoningBank 的工作流拆成三个概念，每个都配有可复制的 TypeScript 示例。

4.1 轨迹追踪（Trajectory Tracking）

记录一次任务执行的动作序列与结果：

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

ruflo 的浏览器插件对轨迹有更严格的定义：BrowserTrajectory 由 goal、startUrl、带 input/result/timestamp 的 steps 以及 success/verdict 组成，其测试还验证了一条关键规则——少于 2 步的轨迹不会被提炼为模式（单步轨迹测试），这解释了为什么技能文档示例中的轨迹都至少包含 3 步。

4.2 结果裁决（Verdict Judgment）

技能文档给出的裁决思路是"基于与成功模式的相似度投票"：

// 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);

仓库内的 V3 适配器实现了更量化的裁决逻辑。judge 方法 基于轨迹的 qualityScore 与平均 reward 给出三档结论：

• qualityScore >= 0.8 且 avgReward >= 0.7 → Success；
• qualityScore < 0.4 或 avgReward < 0.3 → Failure；
• 其余 → Partial。

同时返回结构化证据（质量分、平均奖励、步数、末步动作与奖励）和文字推理，即 ReasoningBankVerdict。裁决阈值的具体权衡在 ADR ADR-347-trajectory-quality-judge-scoring 中有专门讨论，可作为延伸阅读。

4.3 记忆蒸馏（Memory Distillation）

把一批相似经验压缩为高层模式：

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

蒸馏产物以 distilled-pattern 类型入库，usage_count 从 0 开始重新累积——它不是"事实经验"，而是统计出的规律，置信度取决于 success_rate 与 sample_size。

源码侧的 distill 方法 体现了这一过程的默认策略：Success 裁决最多提取 maxItemsSuccess（默认 5）条记忆，Failure 最多 maxItemsFailure（默认 3）条，且置信度先验分别为 0.8 / 0.5（见配置默认值）。也就是说，成功经验会被更慷慨地沉淀，失败经验只保留少量警示信号，这与技能文档"从成功轨迹蒸馏模式"的表述一致。

五、四个推理模块如何增强检索

技能文档说明 AgentDB 提供 4 个推理模块，全部通过 retrieveWithReasoning 的选项激活。

5.1 PatternMatcher：多样性的相似模式匹配

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

MMR（Maximal Marginal Relevance）在 ruflo 源码中有具体实现：mmrSelect 方法 按 score = λ × relevance − (1 − λ) × maxSimilarityToSelected 迭代挑选，λ 默认 0.7（retrieve 方法），即相关性权重 0.7、多样性权重 0.3。没有 MMR 时退化为简单 top-k 排序。

5.2 ContextSynthesizer：多记忆上下文合成

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%"

hooks 包中已有对应的工程化输出：generateGuidance 方法 会把域检测结果、Top-3 模式（带百分比匹配度）拼装成 context 字符串，并按 DOMAIN_GUIDANCE 模板 附带最多 5 条建议，例如 performance 域的"Use HNSW for vector search (not brute-force)"。

5.3 MemoryOptimizer：自动合并与剪枝

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 }

源码中对应的 consolidate 方法 执行三步：

1. 去重：余弦相似度 ≥ duplicateThreshold（默认 0.95）的保留 usageCount × confidence 更高的一条；
2. 矛盾检测：相似度 ≥ contradictionThreshold（默认 0.85）但 outcome 不同的记为矛盾，仅告警不自动删除；
3. 剪枝：超过 pruneAgeDays（默认 30 天）、置信度低于 minConfidenceKeep（默认 0.3）且 usageCount < 3 的模式被移除。

当新增模式数达到 consolidateTriggerThreshold（默认 100）时，蒸馏会自动触发一次巩固（shouldConsolidate）。

5.4 ExperienceCurator：质量过滤

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

六、源码纵深：四步流水线与 HNSW 后端

技能文档描述的是"接口层"，仓库中的两处实现揭示了"引擎层"。

6.1 四步流水线：RETRIEVE → JUDGE → DISTILL → CONSOLIDATE

ReasoningBankAdapter 的文件头注释明确声明其实现了 agentic-flow 兼容的四步管线，并列出性能目标：模式检索 <5ms、裁决 <10ms、蒸馏 <50ms、巩固 <100ms。关键配置默认值（构造函数）：

配置项	默认值	含义
dbPath	.agentdb/reasoningbank.db	数据库路径
sonaMode	balanced	SONA 运行模式
duplicateThreshold	0.95	去重相似度阈值
contradictionThreshold	0.85	矛盾检测阈值
pruneAgeDays	30	剪枝年龄上限（天）
minConfidenceKeep	0.3	剪枝保留的最低置信度
consolidateTriggerThreshold	100	触发巩固的新模式数
maxItemsSuccess / maxItemsFailure	5 / 3	单条轨迹蒸馏条数上限
confidencePriorSuccess / confidencePriorFailure	0.8 / 0.5	蒸馏置信度先验

6.2 hooks 中的 ReasoningBank：HNSW、双档记忆与嵌入兜底

hooks 包的 ReasoningBank 是技能文档中"150x 加速"论断的落点之一，其文件头注释写明使用真实 HNSW 索引（M=16, efConstruction=200）实现 150x+ 检索加速。默认配置（DEFAULT_CONFIG）：

配置项	默认值
dimensions	384（MiniLM-L6；OpenAI 为 1536）
hnswM / hnswEfConstruction / hnswEfSearch	16 / 200 / 100
maxShortTerm / maxLongTerm	1000 / 5000
promotionThreshold	3（使用次数）
qualityThreshold	0.6
dedupThreshold	0.95
dbPath	.claude-flow/memory.db

其检索与晋升机制值得逐条说明：

• 写入去重：storePattern 先做 top-1 相似度检查，超过 0.95 则更新已有模式而非新建；
• HNSW 优先、暴力兜底：searchPatterns 先走 HNSW，异常时回退 brute-force，并把两类耗时分别计入指标（getStats 会输出 hnswSpeedup）；
• 短期→长期晋升：模式 usageCount ≥ 3 且 quality ≥ 0.6 时由 promotePattern 移入长期记忆；质量分由 calculateQuality 按 0.3 + 成功率 × 0.7 计算；
• 嵌入三级兜底：优先 @claude-flow/embeddings 的 ONNX 服务（Xenova/all-MiniLM-L6-v2，cacheSize: 1000）；不可用时经 FallbackEmbeddingService 调用 npx agentic-flow@alpha embeddings generate；再失败则退化为归一化哈希向量，保证链路永不中断。

初始化时若 AgentDB 依赖缺失，整体会降级为 in-memory 模式并打警告（initialize），这与技能文档"迁移 + 兼容"的兜底叙事相呼应。此外该文件尾部还挂了 ADR-049 的会话生命周期桥接：onSessionStart 导入历史学习、onSessionEnd 同步与整理索引、onPostTask 把任务 learnings 记录为 project-patterns 洞察（会话桥接）。

七、Legacy API 兼容性

技能文档强调旧接口零改动迁移：

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

三个函数构成最小闭环：retrieveMemories（按域 + Agent 检索）、judgeTrajectory（裁决）、distillMemories（按裁决结果蒸馏新记忆）。旧代码无需感知后端从 JSON 文件切换到 AgentDB 向量库。

八、性能特征

技能文档标注的性能特征（属文档声明值，供容量规划参考）：

操作	指标
Pattern Search	150x 提速（100µs vs 15ms）
Memory Retrieval	<1ms（带缓存）
Batch Insert	500x 提速（100 条 2ms vs 1s）
Trajectory Judgment	<5ms（含检索 + 分析）
Memory Distillation	<50ms（巩固 100 条模式）

源码侧给出了一致的工程目标区间（ReasoningBankAdapter 文件头：检索 <5ms、裁决 <10ms、蒸馏 <50ms、巩固 <100ms），hooks 侧则用 hnswSpeedup 指标在运行时自证加速比（getStats）。

九、进阶模式：分层记忆与跨域迁移

9.1 分层记忆（Hierarchical Memory）

按抽象层级组织三种记忆类型——低层 concrete（具体修复）、中层 pattern（同类归纳）、高层 principle（通用原则）：

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

这一"具体→归纳→原则"的三层结构与 4.3 节蒸馏流程自然衔接：蒸馏产物（distilled-pattern）就是中层记忆的生成方式。

9.2 多域迁移学习（Multi-Domain Learning）

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

跨域迁移的做法是：以源域经验为底，改写 domain 并打 adapted: true 标记后重新入库，让目标域在真实使用中逐步建立自己的置信度统计。

十、数据库管理 CLI 操作

# Export trajectories and patterns
npx agentdb@latest export ./.agentdb$reasoningbank.db .$backup.json

# Import experiences
npx agentdb@latest import .$experiences.json

# Get statistics
npx agentdb@latest stats ./.agentdb$reasoningbank.db
# Shows: total patterns, domains, confidence distribution

stats 输出的维度（总模式数、域分布、置信度分布）与源码中 getStats 返回的 totalPatterns / byDomain / byOutcome / avgConfidence 结构相对应，可用于迁移前后的对账校验。

十一、故障排查

技能文档列出的三个典型问题及处理方式：

迁移失败：先确认源库存在，再开调试日志重跑。

# Check source database exists
ls -la .swarm$memory.db

# Run with verbose logging
DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm$memory.db

置信度偏低：开启上下文合成与 MMR 提升检索质量。

const result = await rb.retrieveWithReasoning(embedding, {
  synthesizeContext: true,
  useMMR: true,
  k: 10,
});

记忆库膨胀：启用自动优化或手动触发巩固。

const result = await rb.retrieveWithReasoning(embedding, {
  optimizeMemory: true,  // Consolidates similar patterns
});

// Or manually optimize
await rb.optimize();

从源码看，膨胀治理是双保险：写入期靠 0.95 去重阈值（storePattern），运行期靠巩固时的去重 + 剪枝 + 矛盾检测（consolidate）。

十二、验证路径与延伸资料

技能的行为边界在仓库测试中有直接验证：

• ReasoningBankAdapter 测试：验证单例、轨迹存入后统计非空、单步轨迹不生成模式、重复成功会累加 usageCount、目标无关查询返回空数组；
• hooks 包 ReasoningBank 测试 与 guidance-provider 测试：覆盖 hooks 集成路径；
• ADR 延伸：ADR-347 轨迹质量裁决打分、ADR-344 为 ReasoningBank 建知识图谱索引；
• 同一能力在 plugin 目录下还有配套技能文档：reasoningbank-agentdb 插件技能 与 reasoningbank-intelligence 插件技能，可作为本文技能文档的姊妹篇阅读。

技能文档标注的分类与学习成本为：Machine Learning / Reinforcement Learning、Intermediate 难度、预计 20–30 分钟上手。需要再次说明适用前提：CLI 命令依赖 Node.js 18+ 与 agentic-flow 提供的 AgentDB v1.0.7+；仓库内的 hooks/neural 实现则在依赖缺失时自动降级，不会因缺少 AgentDB 而中断。