Initial standalone memabra release

docs/reward_spec.md

@@ -0,0 +1,191 @@
+# Reward Specification
+
+## 目标
+
+memabra 的 reward 不是简单判断“任务做成没”，而是评估：
+- 是否选对了 memory / skill / tool
+- 是否高效
+- 是否稳定
+- 是否减少了用户重复输入和纠正
+- 是否控制了工具成本与上下文成本
+
+reward 的作用不是直接美化分数，而是给路由策略提供可归因、可优化的训练信号。
+
+## Reward 组成
+
+总奖励记为：
+
+```text
+R = ws*S + wr*H - we*E - wc*C - wl*L - wx*X + wu*U
+```
+
+其中：
+- `S` = task success
+- `H` = retrieval hit quality
+- `E` = execution/tool error penalty
+- `C` = user correction penalty
+- `L` = latency penalty
+- `X` = context cost penalty
+- `U` = useful reuse bonus
+
+## 1. Task Success (`S`)
+
+定义：任务最终是否完成，以及完成质量如何。
+
+建议取值：
+- `1.0`：完整达成目标
+- `0.5`：部分达成
+- `0.0`：未完成
+- `-0.5`：明显误导或做错方向
+
+数据来源：
+- 自动任务验收器
+- 用户显式反馈
+- 回放对比规则
+
+## 2. Retrieval Hit Quality (`H`)
+
+定义：是否命中对任务真正有帮助的 memory / skill / tool。
+
+建议拆分：
+- `Hm`：memory hit
+- `Hs`：skill hit
+- `Ht`：tool hit
+
+取值思路：
+- 命中高价值候选并帮助减少步骤：正奖励
+- 召回很多但没用：低奖励或 0
+- 漏掉关键候选：负奖励
+
+## 3. Execution / Tool Error Penalty (`E`)
+
+定义：是否出现无效调用、错误调用、明显多余调用。
+
+示例：
+- 调了不该调的工具
+- 工具参数明显错
+- 重复调用同一无效动作
+- 本可以直接答，却走了长链路
+
+建议取值：
+- 每次轻微错误：`0.1` 到 `0.3`
+- 严重错误：`0.5` 到 `1.0`
+
+## 4. User Correction Penalty (`C`)
+
+定义：用户是否需要补充本应已知的信息，或纠正错误动作。
+
+示例：
+- 用户重复说明偏好
+- 用户指出调用了错误工具
+- 用户要求撤回错误记忆
+
+解释：
+这项对长期系统非常关键，因为它直接代表“系统到底有没有真正学会”。
+
+## 5. Latency Penalty (`L`)
+
+定义：系统完成任务消耗的时间和步骤是否过长。
+
+建议包括：
+- wall-clock latency
+- action count
+- retry count
+
+思路：
+- 少量额外推理可以接受
+- 大量无效绕路必须惩罚
+
+## 6. Context Cost Penalty (`X`)
+
+定义：是否过度膨胀上下文。
+
+包括：
+- 注入了太多无关 memory
+- 加载了不必要的 skill
+- 输出了过大的中间内容
+
+原因：
+agent 很容易“为了保险多塞一点”，结果把上下文拖死。
+这个成本必须显式进 reward。
+
+## 7. Useful Reuse Bonus (`U`)
+
+定义：是否复用了正确的长期信息，并确实提升了效率或质量。
+
+例子：
+- 成功复用用户偏好，避免再次确认
+- 复用已验证的 skill，减少试错
+- 复用相似 episode，加速完成任务
+
+## 初始权重建议
+
+可先用一个朴素版本：
+
+```text
+ws = 1.0
+wr = 0.35
+we = 0.30
+wc = 0.40
+wl = 0.15
+wx = 0.20
+wu = 0.25
+```
+
+解释：
+- success 最高
+- user correction 罚得较重，因为它直接暴露系统没学会
+- retrieval hit 有明显价值，但不能盖过结果
+- latency/context 重要，但初期不该过重
+
+## 信号来源
+
+reward 可来自三类来源：
+
+### A. 显式信号
+- 用户说“对/不对”
+- 用户纠正
+- 用户二次要求重做
+
+### B. 隐式信号
+- 是否减少步骤
+- 是否触发错误
+- 是否重复问同样的问题
+- 是否超时
+
+### C. 程序性验收
+- 测试是否通过
+- 目标文件是否生成
+- 指定字段是否匹配
+- 工具执行是否成功
+
+## 反事实记录要求
+
+为后续训练，必须记录：
+- 候选集有哪些
+- 最终选了谁
+- 哪些高分候选没有被选
+- 每个动作的局部 outcome
+
+否则 reward 只能打给“整个过程”，无法学习具体路由策略。
+
+## 初期策略
+
+Phase 0 / Phase 1 不建议直接把 reward 用于大模型权重更新。
+先用于：
+- 路由规则评估
+- 样本打标
+- 候选排序优化
+- bandit / reranker 训练
+
+## 风险
+
+- 只看 success，会奖励瞎猫碰死耗子
+- 只看效率，会让系统不敢探索
+- 只看用户反馈，会受用户表达噪声影响
+- 不记录反事实，训练会非常盲
+
+## 当前结论
+
+reward 在 memabra 中不是附属件，而是学习闭环的核心基础设施。
+如果 reward 设计不清，后面所有“根据结果更新权重”都会变成伪学习。