Initial standalone memabra release

docs/ARCHITECTURE.md

@@ -0,0 +1,219 @@
+# Architecture
+
+## 1. 问题定义
+
+我们要解决的不是“怎样让模型记住更多”，而是：
+当 agent 遇到一个任务时，怎样在有限上下文、有限工具预算和有限时间下，快速决定是否要调用 memory、skill、tool，并让这个决策过程能够被训练和修正。
+
+## 2. 系统总览
+
+系统采用四层架构。
+
+### 2.1 Retrieval Layer（候选召回层）
+输入：
+- 当前用户任务
+- 对话短摘要
+- 当前环境状态
+- 失败历史 / 最近修正
+
+输出：
+- top-k memory candidates
+- top-k skill candidates
+- top-k tool candidates
+
+职责：
+- 从不同来源召回候选对象
+- 统一为标准候选格式
+- 不做最终决策，只做缩小搜索空间
+
+### 2.2 Policy Layer（直觉 / 路由层）
+输入：
+- 当前任务表示
+- 候选对象集合
+- 历史选择特征
+- 成本与风险信号
+
+输出：
+- 直接回答
+- 读取某条 memory
+- 加载某个 skill
+- 调用某个 tool
+- 组合动作（如先 skill 后 tool）
+- 请求澄清
+
+职责：
+- 模拟“直觉”
+- 先做快速动作选择
+- 后续可从规则逐步升级到分类器、reranker、bandit、RL policy
+
+### 2.3 Execution Layer（执行层）
+职责：
+- 注入记忆到上下文
+- 加载 skill 指令
+- 调用真实工具
+- 记录执行步骤、耗时、报错、产出
+
+### 2.4 Evaluation Layer（反馈 / 归因层）
+职责：
+- 判断任务是否成功
+- 分析步骤数、重试数、错误率、用户修正次数
+- 拆解 reward
+- 产生可训练轨迹
+
+没有这一层，就没有真正的“学习”，只有玄学调参。
+
+## 3. 统一对象模型
+
+虽然 memory、skill、tool 性质不同，但在召回和路由阶段可以统一成候选对象：
+
+```json
+{
+  "id": "string",
+  "type": "memory|skill|tool",
+  "title": "string",
+  "summary": "string",
+  "triggers": ["string"],
+  "cost": 0.0,
+  "confidence": 0.0,
+  "success_rate": 0.0,
+  "freshness": 0.0,
+  "risk": 0.0,
+  "embedding": "vector-ref",
+  "tags": ["string"],
+  "source": "user|system|generated|external"
+}
+```
+
+注意：统一的是候选接口，不是语义本体。
+三类对象必须保持边界：
+- memory 存事实
+- skill 存程序
+- tool 存动作能力
+
+## 4. 记忆系统分层
+
+### 4.1 Semantic Memory（事实记忆）
+例如：
+- 用户偏好
+- 机器环境
+- 项目约定
+- API 限制
+
+### 4.2 Procedural Memory（程序性记忆）
+即 skill：
+- 某类任务的处理流程
+- 踩坑经验
+- 验证步骤
+
+### 4.3 Episodic Memory（情景记忆）
+- 某次任务的具体轨迹
+- 当时用了什么资源
+- 为什么成功或失败
+
+### 4.4 Working Memory（工作记忆）
+- 当前任务临时状态
+- 本轮推理中间产物
+- 不应直接沉淀为长期记忆
+
+## 5. 训练策略：先外部策略，后端到端
+
+### 5.1 Phase A：不改基础模型权重
+先训练一个小型策略器，决定：
+- 要不要查记忆
+- 查哪类记忆
+- 要不要 skill
+- 先用哪个工具
+
+可选实现：
+- 规则 + 分数融合
+- 轻量分类器
+- reranker
+- contextual bandit
+
+### 5.2 Phase B：从轨迹中学 reranking / routing
+训练输入：
+- 任务上下文
+- 候选对象集合
+- 实际动作
+- 结果 reward
+
+训练目标：
+- 最大化任务完成率
+- 最小化无效调用
+- 减少用户重复提供信息
+- 减少不必要的上下文膨胀
+
+### 5.3 Phase C：端到端实验
+只有当以下条件成立，才值得考虑：
+- 已有高质量轨迹数据
+- 能做 credit assignment
+- 有稳定的离线评估环境
+- 能控制灾难性遗忘
+
+## 6. Feedback & Reward 设计
+
+reward 不能只看任务是否成功。要拆成多项：
+- task_success：最终是否完成
+- efficiency：用了多少步
+- retrieval_hit：是否命中关键 memory/skill/tool
+- user_correction_penalty：用户是否纠正
+- tool_error_penalty：是否触发无效工具调用
+- context_cost_penalty：上下文是否膨胀过度
+- latency_penalty：是否过慢
+
+可组合为：
+
+```text
+R = a*task_success + b*retrieval_hit - c*tool_error - d*user_correction - e*latency - f*context_cost
+```
+
+## 7. 关键难点
+
+### 7.1 Credit Assignment
+成功了，到底是谁的功劳？
+要记录候选集、最终选择、未选备选项，才能做反事实分析。
+
+### 7.2 False Reinforcement
+错误记忆被反复命中，会自我强化。
+需要：
+- 置信度
+- 可撤销
+- 最近验证时间
+- 来源追踪
+
+### 7.3 Exploitation vs Exploration
+老选最稳的对象会变保守，永远学不到新模式。
+需要安全探索机制。
+
+### 7.4 Type Boundary Collapse
+如果把 memory、skill、tool 混成一个大向量池，系统会越来越糊。
+
+## 8. 推荐 MVP
+
+### MVP-1：可观测系统
+- 定义对象 schema
+- 定义事件 schema
+- 统一记录轨迹
+- 做基础检索
+- 用规则路由
+
+### MVP-2：轻量学习型路由
+- 加入候选打分器
+- 从优秀轨迹训练动作选择器
+- 做离线回放评估
+
+### MVP-3：在线自适应
+- 使用 bandit / preference updates
+- 根据任务结果微调路由策略
+
+### MVP-4：端到端试验场
+- 小规模实验性训练
+- 与分层方案对比
+- 验证是否真有收益
+
+## 9. 核心原则
+
+1. 先可观测，再可学习
+2. 先学路由，再学大脑
+3. 先做分层归因，再做端到端优化
+4. 优化“何时依赖什么”，而不是盲目优化“模型看起来更聪明”