Initial standalone memabra release

docs/REPLAY_AND_RETRIEVAL.md

@@ -0,0 +1,60 @@
+# Replay and Retrieval
+
+## 目标
+
+把 memabra 的最小闭环接起来：
+- retrieval 负责把 memory / skill / tool 候选召回出来
+- replay 负责读取 trajectories 并汇总行为结果
+
+这两者一接上，系统就不再只是静态文档和单点 router，而是具备了：
+- 候选输入
+- 决策输出
+- 轨迹回放
+- 基础统计
+
+## 当前实现
+
+### retrieval.py
+提供：
+- `CandidateProvider` 协议
+- `InMemoryCandidateProvider`
+- `CandidateRetriever`
+- `RetrievalResult`
+
+当前策略：
+- 使用 trigger/tag 与任务文本做简单 lexical matching
+- 结合 confidence / success_rate / freshness / cost / risk 做 baseline 排序
+- 对不同 provider 输出做按类型聚合与去重
+
+### replay.py
+提供：
+- `TrajectoryReplay`
+- `ReplaySummary`
+
+当前能力：
+- 加载单个 trajectory JSON
+- 加载目录下多个 trajectory
+- 汇总 outcome counts
+- 汇总 reward、latency、steps、user corrections
+- 统计各类 decision_type 次数
+
+## 为什么这一步重要
+
+没有 retrieval，router 只能对空候选做假动作。
+没有 replay，reward 和 trajectory 只是躺在磁盘上的 JSON 标本。
+
+这一步之后，memabra 第一次拥有了最小闭环：
+任务 -> 候选 -> 决策 -> 轨迹 -> 回放统计
+
+## 当前局限
+
+- retrieval 还是词面匹配，不是 embedding 或 learned ranking
+- replay 只做汇总，不做 schema 校验和 counterfactual 对比
+- 还没有把 router 与 retriever 真正串成 end-to-end runner
+
+## 下一步
+
+1. 加 `schemas.py` 做运行时校验
+2. 做 `memory_store.py` 和 provider 接口
+3. 做 `runner.py` 把 retrieval + router + telemetry 串起来
+4. 给 replay 加基线比较和 reward breakdown 分析