Ruflo 中的 ReasoningBank 与 AgentDB用自适应学习让 Agent 从轨迹中沉淀可复用经验【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo本篇围绕 ReasoningBank with AgentDB 技能文档 展开讲解如何在 ruflo 项目中落地 ReasoningBank 自适应学习体系通过 AgentDB 高性能向量后端完成轨迹追踪Trajectory Tracking、结果裁决Verdict Judgment与记忆蒸馏Memory Distillation并接入 PatternMatcher、ContextSynthesizer、MemoryOptimizer、ExperienceCurator 四个推理模块。读完本文你将掌握初始化 AgentDB 库、迁移旧版 ReasoningBank、调用insertPattern/retrieveWithReasoningAPI 的完整流程并能对照仓库源码理解 MMR 检索、HNSW 索引、短期/长期记忆晋升等底层机制。一、技能定位为什么 ReasoningBank 需要 AgentDB该技能文档定义了一套让 Agent 从经验中学习的实现模式Agent 执行任务后记录轨迹、判定成败、把成功经验蒸馏为高层模式并在后续相似任务中检索复用。技能选择 AgentDB 作为后端文档给出的动机与指标引自技能文档原文包括模式检索提速 150x批量操作提速 500x带缓存时内存访问 1ms与旧版legacyReasoningBank 保持 100% 向后兼容。前提条件方面文档要求 Node.js 18、通过 agentic-flow 安装的 AgentDB v1.0.7强化学习背景知识为可选项。这一兼容层定位在仓库源码中同样成立ruflo 的 hooks 包在 AgentDB 不可用时会自动降级为纯内存模式技能文档描述的 CLI/迁移能力因此构成完整的兜底路径。前提要求运行时Node.js 18AgentDBv1.0.7经 agentic-flow 提供背景知识强化学习概念可选二、CLI 快速上手初始化、MCP 接入与迁移技能文档给出的 CLI 操作分三类初始化、MCP 集成、迁移。2.1 初始化 ReasoningBank 数据库# Initialize AgentDB for ReasoningBank npx agentdblatest init ./.agentdb$reasoningbank.db --dimension 1536 # Start MCP server for Claude Code integration npx agentdblatest mcp claude mcp add agentdb npx agentdblatest mcp--dimension 1536对应 OpenAI 系嵌入向量维度而 ruflo 源码中 ReasoningBank 的默认维度是 384MiniLM-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 agentdblatest migrate --source .swarm$memory.db # Verify migration npx agentdblatest stats ./.agentdb$reasoningbank.db迁移时也可显式指定目标库npx agentdblatest migrate --source .swarm$memory.db --target .agentdb$reasoningbank.db npx agentdblatest 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 });参数含义参数说明dbPathAgentDB 数据库文件路径enableLearning启用学习插件蒸馏、巩固等enableReasoning启用推理模块四个 reasoning modulescacheSize模式缓存容量示例取 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/principlepattern_data是序列化 JSON内嵌向量与结构化载荷confidence、usage_count、success_count是后续裁决与蒸馏的核心依据。对照仓库源码ReasoningBankPattern 接口 表达了相同的数据契约patternData.source记录taskId、agentId、outcomeSuccess/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返回条数全部useMMRMMR 保证结果多样性PatternMatchersynthesizeContext合成富上下文叙述ContextSynthesizeroptimizeMemory自动合并与剪枝MemoryOptimizerminConfidence置信度下限过滤ExperienceCurator四、三大核心机制轨迹、裁决与蒸馏技能文档把 ReasoningBank 的工作流拆成三个概念每个都配有可复制的 TypeScript 示例。4.1 轨迹追踪Trajectory Tracking记录一次任务执行的动作序列与结果// Record trajectory (sequence of actions) const trajectory { task: optimize-api-endpoint, steps: [ { action: analyze-bottleneck, result: found N1 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→SuccessqualityScore 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 N1 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}); });MMRMaximal Marginal Relevance在 ruflo 源码中有具体实现mmrSelect 方法 按score λ × relevance − (1 − λ) × maxSimilarityToSelected迭代挑选λ默认 0.7retrieve 方法即相关性权重 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 方法 执行三步去重余弦相似度 ≥duplicateThreshold默认 0.95的保留usageCount × confidence更高的一条矛盾检测相似度 ≥contradictionThreshold默认 0.85但 outcome 不同的记为矛盾仅告警不自动删除剪枝超过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 → CONSOLIDATEReasoningBankAdapter 的文件头注释明确声明其实现了 agentic-flow 兼容的四步管线并列出性能目标模式检索 5ms、裁决 10ms、蒸馏 50ms、巩固 100ms。关键配置默认值构造函数配置项默认值含义dbPath.agentdb/reasoningbank.db数据库路径sonaModebalancedSONA 运行模式duplicateThreshold0.95去重相似度阈值contradictionThreshold0.85矛盾检测阈值pruneAgeDays30剪枝年龄上限天minConfidenceKeep0.3剪枝保留的最低置信度consolidateTriggerThreshold100触发巩固的新模式数maxItemsSuccess/maxItemsFailure5 / 3单条轨迹蒸馏条数上限confidencePriorSuccess/confidencePriorFailure0.8 / 0.5蒸馏置信度先验6.2 hooks 中的 ReasoningBankHNSW、双档记忆与嵌入兜底hooks 包的 ReasoningBank 是技能文档中150x 加速论断的落点之一其文件头注释写明使用真实 HNSW 索引M16, efConstruction200实现 150x 检索加速。默认配置DEFAULT_CONFIG配置项默认值dimensions384MiniLM-L6OpenAI 为 1536hnswM/hnswEfConstruction/hnswEfSearch16 / 200 / 100maxShortTerm/maxLongTerm1000 / 5000promotionThreshold3使用次数qualityThreshold0.6dedupThreshold0.95dbPath.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-v2cacheSize: 1000不可用时经 FallbackEmbeddingService 调用npx agentic-flowalpha 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 Search150x 提速100µs vs 15msMemory Retrieval1ms带缓存Batch Insert500x 提速100 条 2ms vs 1sTrajectory Judgment5ms含检索 分析Memory Distillation50ms巩固 100 条模式源码侧给出了一致的工程目标区间ReasoningBankAdapter 文件头检索 5ms、裁决 10ms、蒸馏 50ms、巩固 100mshooks 侧则用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 agentdblatest export ./.agentdb$reasoningbank.db .$backup.json # Import experiences npx agentdblatest import .$experiences.json # Get statistics npx agentdblatest stats ./.agentdb$reasoningbank.db # Shows: total patterns, domains, confidence distributionstats输出的维度总模式数、域分布、置信度分布与源码中 getStats 返回的totalPatterns/byDomain/byOutcome/avgConfidence结构相对应可用于迁移前后的对账校验。十一、故障排查技能文档列出的三个典型问题及处理方式迁移失败先确认源库存在再开调试日志重跑。# Check source database exists ls -la .swarm$memory.db # Run with verbose logging DEBUGagentdb:* npx agentdblatest 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 而中断。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考