RuView ReasoningBank Learner 详解：RETRIEVE–JUDGE–DISTILL–CONSOLIDATE 四阶段经验学习管线实战指南

本文基于仓库中的 reasoningbank-learner.md 展开，系统讲解 RuView 项目 V3 智能体体系中的 ReasoningBank Learner（推理库学习者）：它如何通过轨迹跟踪、成败裁决、模式蒸馏与 EWC++ 记忆巩固四个阶段，让 Agent 从历史经验中持续学习。读完后你将掌握 claude-flow@v3alpha 智能钩子命令的完整用法、reasoningbank 命名空间下模式存储的 JSON 结构、以及配套的 HNSW 检索与 MCP 工具集成方式。

一、Agent 定位与元数据定义

ReasoningBank Learner 是 .claude/agents/v3/ 目录下 V3 智能体群（swarm）中的专职角色，其完整定义位于 reasoningbank-learner.md。文件以 YAML front matter 声明了该 Agent 的身份与职责边界：

name: reasoningbank-learner
type: specialist
color: "#9C27B0"
version: "3.0.0"
description: V3 ReasoningBank integration specialist for trajectory tracking, verdict judgment,
  pattern distillation, and experience replay using HNSW-indexed memory
capabilities:
  - trajectory_tracking
  - verdict_judgment
  - pattern_distillation
  - experience_replay
  - hnsw_pattern_search
  - ewc_consolidation
  - lora_adaptation
  - attention_optimization
priority: high
adr_references:
  - ADR-008: Neural Learning Integration

几个关键字段的含义：

• type: specialist：表明它不是协调者或编排器，而是可被上层调度器按需派发的专项能力单元；
• capabilities：列出八项能力，恰好覆盖"轨迹跟踪 → 裁决 → 蒸馏 → 巩固"管线的每一环，外加 HNSW 检索、EWC++ 巩固、LoRA 适配与注意力优化；
• priority: high：高优先级，意味着在学习回路触发时优先于低优先级 Agent 获得调度；
• adr_references: ADR-008：从源码结构看，该 Agent 的神经网络学习集成设计对应仓库 ADR 体系中的神经学习集成决策（注意此编号是 claude-flow V3 体系内部的 ADR 引用，与仓库 docs/adr/ 下 RuView 自身产品架构 ADR 分属不同文档体系）。

前后置钩子（pre/post hooks）

front matter 中 hooks 字段声明了该 Agent 被激活前与执行后自动运行的 Shell 脚本，这是整个学习闭环自动化的入口：

hooks:
  pre: |
    echo "🧠 ReasoningBank Learner initializing intelligence system"
    # Initialize trajectory tracking
    SESSION_ID="rb-$(date +%s)"
    npx claude-flow@v3alpha hooks intelligence trajectory-start --session-id "$SESSION_ID" --agent-type "reasoningbank-learner" --task "$TASK"
    # Search for similar patterns
    mcp__claude-flow__memory_search --pattern="pattern:*" --namespace="reasoningbank" --limit=10
  post: |
    echo "✅ Learning cycle complete"
    # End trajectory with verdict
    npx claude-flow@v3alpha hooks intelligence trajectory-end --session-id "$SESSION_ID" --verdict "${VERDICT:-success}"
    # Store learned pattern
    mcp__claude-flow__memory_usage --action="store" --namespace="reasoningbank" --key="pattern:$(date +%s)" --value="$PATTERN_SUMMARY"

从这段钩子可以读出自动闭环的三个要点：

1. 会话标识：SESSION_ID 以 rb- 前缀加 Unix 时间戳生成（如 rb-1756987654），贯穿整个生命周期，后续 trajectory-step / trajectory-end 都靠它定位轨迹；
2. 激活即检索：pre 钩子在任务开始前就调用 memory_search 查询 reasoningbank 命名空间中所有 pattern:* 键，取 10 条最相似历史模式作为先验上下文——"先检索，再执行"；
3. 退出即沉淀：post 钩子用 ${VERDICT:-success}（未显式给出裁决时默认 success）结束轨迹，并把 PATTERN_SUMMARY 以 pattern:<时间戳> 键存回记忆库。

二、四阶段智能管线总览

文档给出的核心架构图（原样继承）如下：

┌─────────────────────────────────────────────────────────────────────┐
│                  REASONINGBANK PIPELINE                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    │
│   │ RETRIEVE │───▶│  JUDGE   │───▶│ DISTILL  │───▶│CONSOLIDATE│   │
│   │          │    │          │    │          │    │          │    │
│   │ HNSW     │    │ Verdicts │    │ LoRA     │    │ EWC++    │    │
│   │ 150x     │    │ Success/ │    │ Extract  │    │ Prevent  │    │
│   │ faster   │    │ Failure  │    │ Learnings│    │ Forget   │    │
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘    │
│        │               │               │               │           │
│        ▼               ▼               ▼               ▼           │
│   ┌─────────────────────────────────────────────────────────────┐ │
│   │                    PATTERN MEMORY                           │ │
│   │  AgentDB + HNSW Index + SQLite Persistence                  │ │
│   └─────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

管线底层的模式记忆（PATTERN MEMORY）由三层构成：AgentDB 向量库负责语义检索，HNSW 索引提供近邻加速，SQLite 提供结构化持久化。这一"向量 + 图索引 + 关系存储"的混合后端设计，在同目录的 memory-specialist.md 中被进一步展开（见 Hybrid Memory Backend 章节：SQLite 存结构化关系、AgentDB 存向量嵌入、HNSW 存图索引，并给出 rrf_k: 60 的 RRF 融合权重等实现细节）。

三、阶段一 RETRIEVE：HNSW 模式检索

RETRIEEVE 阶段的目标是在新任务开始前，快速找到语义相近的历史模式。文档给出的目标性能是"150x–12,500x 加速"。对应命令：

# Search patterns via HNSW
mcp__claude-flow__memory_search --pattern="$TASK" --namespace="reasoningbank" --limit=10

# Get pattern statistics
npx claude-flow@v3alpha hooks intelligence pattern-stats --query "$TASK" --k 10 --namespace reasoningbank

两条命令的分工：

• memory_search 是 MCP 工具，走 HNSW 向量近邻搜索，--pattern 传入当前任务描述，--limit 控制返回的候选数；
• pattern-stats 是 CLI 钩子命令，针对查询返回模式统计（如该领域的命中分布、奖励区间），帮助判断"这类任务历史上有多少可参考经验"。

关于 150x 加速的实现依据，仓库中 reasoningbank-agentdb/SKILL.md 给出了量化描述："Pattern Search: 150x faster (100µs vs 15ms)"，即 AgentDB 后端将单次模式检索从 15ms 量级压到 100µs 量级。而 memory-specialist.md 提供了 HNSW 的典型参数配置，可帮助理解检索速度与召回精度的权衡：

this.defaultParams = {
  M: 16,               // 每层最大连接数
  efConstruction: 200, // 建图搜索深度
  efSearch: 100,        // 查询搜索深度（越大越准）
  maxElements: 1000000,
  quantization: 'int8' // 4x 内存压缩
};

其中 M 与 efSearch 是精度/速度的核心旋钮：高吞吐场景可降为 M: 12, efSearch: 50，高精度场景升到 M: 32, efSearch: 200。ReasoningBank 的 reasoningbank 命名空间正是这类配置的作用对象。

四、阶段二 JUDGE：成败裁决

JUDGE 阶段为轨迹（trajectory）打上成功/失败裁决，并把数值奖励（reward）固化下来，作为后续蒸馏的筛选依据：

# Record trajectory step with outcome
npx claude-flow@v3alpha hooks intelligence trajectory-step \
  --session-id "$SESSION_ID" \
  --operation "code-generation" \
  --outcome "success" \
  --metadata '{"files_changed": 3, "tests_passed": true}'

# End trajectory with final verdict
npx claude-flow@v3alpha hooks intelligence trajectory-end \
  --session-id "$SESSION_ID" \
  --verdict "success" \
  --reward 0.95

命令语义要点：

• trajectory-step 记录轨迹中单步操作：--operation 是动作名（如 code-generation、write-test），--outcome 是 success / failure，--metadata 传 JSON 附加度量（本例记录改动文件数与测试是否通过）；
• trajectory-end 收尾时给出 --verdict（success / failure）与 --reward（0.0–1.0 区间），reward 越高代表该轨迹越值得被蒸馏复用。0.95 这类高分通常对应"测试全过 + 改动面收敛"的高质量完成。

五、阶段三 DISTILL：模式蒸馏

DISTILL 阶段从裁决过的高分轨迹中提取"可迁移经验"，以键值形式写入记忆库，并可用 pattern-search 按奖励下限捞取可蒸馏模式：

# Store successful pattern
mcp__claude-flow__memory_usage --action="store" \
  --namespace="reasoningbank" \
  --key="pattern:auth-implementation" \
  --value='{"task":"implement auth","approach":"JWT with refresh","outcome":"success","reward":0.95}'

# Search for patterns to distill
npx claude-flow@v3alpha hooks intelligence pattern-search \
  --query "authentication" \
  --min-reward 0.8 \
  --namespace reasoningbank

两条命令展示了 DISTILL 的两个动作：

1. 写入：memory_usage --action="store" 把一条结构化经验存到 reasoningbank 命名空间，键为 pattern:auth-implementation 这类"领域:具体策略"语义键，值是包含 task / approach / outcome / reward 四要素的 JSON——这正是该 Agent 的"模式最小单元"；
2. 捞取：pattern-search --min-reward 0.8 只做高奖励过滤，保证进入蒸馏候选集的都是被验证过的高质量模式，低质量经验留在轨迹层不参与泛化。

六、阶段四 CONSOLIDATE：EWC++ 记忆巩固

CONSOLIDATE 阶段防止"灾难性遗忘"（catastrophic forgetting）——新经验挤掉旧经验的经典问题：

# Consolidate patterns (prevents forgetting old learnings)
npx claude-flow@v3alpha neural consolidate --namespace reasoningbank

# Check consolidation status
npx claude-flow@v3alpha hooks intelligence stats --namespace reasoningbank

• neural consolidate 对指定命名空间执行巩固：把语义相近的模式聚类合并、给低质量条目降权，而不是简单删除；
• hooks intelligence stats 用于核对巩固后的命名空间状态（模式数、质量分布等），构成"巩固 → 验证"的闭环。

EWC++ 的算法思想（Fisher 信息矩阵衡量参数重要性、lambda 正则化强度控制遗忘惩罚）在 memory-specialist.md 的 "EWC++ for Preventing Catastrophic Forgetting" 一节有完整伪实现，其中 this.lambda = 5000（正则强度）与 this.gamma = 0.9（在线 EWC 衰减因子）是核心超参。

仓库中的真实巩固实现：pattern-consolidator.sh

文档描述的是"目标管线"，而仓库 .claude/helpers/ 下存在真实落地的巩固 worker——pattern-consolidator.sh。它对 SQLite 模式库（.claude-flow/learning/patterns.db）执行四类 SQL 维护，可视为 CONSOLIDATE 阶段的参考实现：

# 1. 去重：同一 (strategy, domain) 只保留一行
DELETE FROM short_term_patterns
WHERE rowid NOT IN (
  SELECT MIN(rowid) FROM short_term_patterns
  GROUP BY strategy, domain
);

# 2. 剪枝：7 天前创建且 quality < 0.3 的模式直接删除
DELETE FROM short_term_patterns
WHERE quality < 0.3 AND created_at < datetime('now', '-7 days');

# 3. 晋升：quality > 0.8 的短期模式提升到 long_term_patterns
INSERT OR IGNORE INTO long_term_patterns (strategy, domain, quality, source)
SELECT strategy, domain, quality, 'consolidated'
FROM short_term_patterns WHERE quality > 0.8;

# 4. 衰减：1 天未更新的模式 quality 乘以 0.95
UPDATE short_term_patterns
SET quality = quality * 0.95
WHERE updated_at < datetime('now', '-1 day');

从这段源码可以看到巩固策略的具体阈值：晋升线 quality > 0.8、剪枝线 quality < 0.3 且龄期超 7 天、未使用衰减系数 0.95/天，以及 worker 自身的 15 分钟节流（should_run() 检查 .consolidator-last-run 时间戳）。短/长期两级模式表（short_term_patterns / long_term_patterns）与文档"经验回放（experience replay）"能力相对应。

辅助佐证：intelligence.cjs

仓库中 intelligence.cjs（约 928 行，文件头注释标明 "Intelligence Layer (ADR-050)"）实现了把记忆接入钩子系统的另一条路径：它维护 .claude-flow/data/ 下的 auto-memory-store.json、graph-state.json（含节点、边与 PageRank 分数）、ranked-context.json 等数据文件，用三元组分词 + Jaccard 相似度做文本匹配，并用阻尼系数 0.85 的幂迭代 PageRank 对记忆条目排序。可以推断，ReasoningBank 管线的 RETRIEVE 阶段在该运行时环境下，除 HNSW 向量近邻外，还有这条基于词面相似度的图排序检索作为互补路径。

七、完整轨迹跟踪示例

文档给出的端到端轨迹跟踪样例（一个"实现用户认证"任务）完整保留如下，它演示了 start → step × N → end 的标准调用序列：

# Start tracking
npx claude-flow@v3alpha hooks intelligence trajectory-start \
  --session-id "task-123" \
  --agent-type "coder" \
  --task "Implement user authentication"

# Track each step
npx claude-flow@v3alpha hooks intelligence trajectory-step \
  --session-id "task-123" \
  --operation "write-test" \
  --outcome "success"

npx claude-flow@v3alpha hooks intelligence trajectory-step \
  --session-id "task-123" \
  --operation "implement-feature" \
  --outcome "success"

npx claude-flow@v3alpha hooks intelligence trajectory-step \
  --session-id "task-123" \
  --operation "run-tests" \
  --outcome "success"

# End with verdict
npx claude-flow@v3alpha hooks intelligence trajectory-end \
  --session-id "task-123" \
  --verdict "success" \
  --reward 0.92

这个例子还说明了多 Agent 共享机制：--agent-type "coder" 表明轨迹不限于 reasoningbank-learner 自身，任何被跟踪的 Agent（coder、reviewer 等）产出的轨迹都汇入同一记忆库，由 Learner 统一蒸馏——这就是 front matter 中 experience_replay 能力的落地形态。

八、Pattern 数据结构

每条蒸馏出的模式遵循如下 TypeScript 接口（原样继承自文档）：

interface Pattern {
  id: string;
  task: string;
  approach: string;
  steps: TrajectoryStep[];
  outcome: 'success' | 'failure';
  reward: number;  // 0.0 - 1.0
  metadata: {
    agent_type: string;
    duration_ms: number;
    files_changed: number;
    tests_passed: boolean;
  };
  embedding: number[];  // For HNSW search
  created_at: Date;
}

字段与管线的对应关系：

字段	来源阶段	说明
steps	轨迹跟踪	由若干 trajectory-step 累积而成
outcome / reward	JUDGE	裁决结果与 0–1 奖励分
metadata	轨迹 metadata	执行耗时、改动文件数、测试状态等
embedding	DISTILL	任务描述的向量表示，供 HNSW 近邻检索
id / created_at	存储层	与 SQLite 持久化对应（参照 reasoningbank-agentdb/SKILL.md 中 insertPattern 的 created_at/last_used 字段）

九、MCP 工具集成

文档列出了四个 MCP 工具及其分工：

Tool	Purpose
memory_search	HNSW pattern retrieval
memory_usage	Store/retrieve patterns
neural_train	Train on new patterns
neural_patterns	Analyze pattern distribution

前两个在 pre/post 钩子中直接出现（memory_search 做先验检索、memory_usage --action="store" 做经验落库）；后两个属于"训练侧"工具：neural_train 用新模式增量训练，neural_patterns 分析模式分布以发现偏科或空洞领域。

十、Hooks 集成：把每一步操作变成轨迹点

文档还给出了与 V3 hooks 系统的集成配置，让文件写入类工具调用自动转化为 trajectory-step：

{
  "PostToolUse": [{
    "matcher": "^(Write|Edit|Task)$",
    "hooks": [{
      "type": "command",
      "command": "npx claude-flow@v3alpha hooks intelligence trajectory-step --operation $TOOL_NAME --outcome $TOOL_SUCCESS"
    }]
  }]
}

这段配置的语义：工具名匹配 Write、Edit、Task 的正则在每次使用后触发，把工具名（$TOOL_NAME）与成功标志（$TOOL_SUCCESS）作为单步轨迹上报。从源码结构看，这使"Agent 做了什么"无需各 Agent 自觉记录，而是由钩子层统一采集——轨迹完整性由基础设施保证，而非依赖约定。

十一、性能指标目标

文档最后给出了四阶段的延迟目标：

Metric	Target
Pattern retrieval	<5ms (HNSW)
Verdict assignment	<1ms
Distillation	<100ms
Consolidation	<500ms

结合 reasoningbank-agentdb/SKILL.md 的补充数据（批量插入 100 条模式约 2ms、含检索与判定的轨迹裁决 <5ms、100 条模式蒸馏 <50ms），可以推断该管线的整体设计目标是毫秒级在线学习回路：任务执行过程中即可完成"检索 → 记录 → 判定"，巩固（consolidation）作为较轻量的周期性后台任务运行（如 pattern-consolidator.sh 的 15 分钟节流）。

十二、小结

ReasoningBank Learner 把"Agent 从经验中学习"拆解为四个可独立调用的阶段，每一阶段都有对应的 claude-flow@v3alpha 命令或 MCP 工具，配合 pre/post 钩子形成无人值守的学习闭环：

1. RETRIEVE：HNSW 检索历史模式（memory_search / pattern-stats）；
2. JUDGE：trajectory-step 记录单步，trajectory-end 打裁决与奖励；
3. DISTILL：高奖励模式以 pattern:* 键存入 reasoningbank 命名空间（memory_usage / pattern-search --min-reward）;
4. CONSOLIDATE：neural consolidate 执行 EWC++ 式巩固防止遗忘，hooks intelligence stats 核对结果。

仓库内的 pattern-consolidator.sh（质量阈值 0.8 晋升 / 0.3 剪枝 / 0.95 日衰减）、intelligence.cjs（PageRank 记忆排序层）以及 reasoningbank-intelligence/SKILL.md（recordExperience / recommendStrategy / transferKnowledge 等 API 形态）提供了这套管线的工程佐证，可供进一步深入阅读。