Commit 90527823ec33117237a2a6c63cffb0329105686b
1 parent
db172833
docs: add agent memory system architecture plan (22-agent-memory-system.md)
Showing
1 changed file
with
282 additions
and
0 deletions
docs/system-design/22-agent-memory-system.md
0 → 100644
| 1 | +# 22. Agent Memory System — 自动记忆读写架构 | |
| 2 | + | |
| 3 | +> **版本**: v1.0 (设计稿) | |
| 4 | +> **日期**: 2026-03-25 | |
| 5 | +> **状态**: 规划中 | |
| 6 | +> **前置**: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分 | |
| 7 | + | |
| 8 | +--- | |
| 9 | + | |
| 10 | +## 一、核心问题 | |
| 11 | + | |
| 12 | +当前 Agent 每次新对话都是**完全失忆**的。 | |
| 13 | +memory 目录结构已就位，但读写机制全是空壳。 | |
| 14 | + | |
| 15 | +**需要解决**： | |
| 16 | +1. Agent 如何**自动记住**做过什么、学到什么、犯过什么错 | |
| 17 | +2. Agent 接到新任务时如何**自动想起**相关经验 | |
| 18 | +3. 好方案如何**自动固化**，下次遇到同类任务直接复用 | |
| 19 | + | |
| 20 | +--- | |
| 21 | + | |
| 22 | +## 二、目录结构（已就位） | |
| 23 | + | |
| 24 | +``` | |
| 25 | +data/agents/{agent-id}/memory/ | |
| 26 | +├── memory.md ← 核心记忆索引（注入 prompt，≤2000字） | |
| 27 | +├── hippocampus.md ← 海马体：情景→方案 映射索引 | |
| 28 | +├── cerebellum/ ← 小脑：固化的执行方案（.md 步骤 / .js 脚本） | |
| 29 | +│ ├── handle-okr-task.md | |
| 30 | +│ └── create-agent.md | |
| 31 | +├── short-term/ ← 短期记忆：近期 session 摘要 | |
| 32 | +│ ├── session-2026-03-25-001.md | |
| 33 | +│ └── session-2026-03-25-002.md | |
| 34 | +├── long-term/ ← 长期记忆：沉淀的经验 & 事实 | |
| 35 | +│ ├── patterns.md ← 反复验证的模式 | |
| 36 | +│ ├── lessons.md ← 失败教训 | |
| 37 | +│ └── facts.md ← 重要事实 | |
| 38 | +├── daily/ ← 日报 | |
| 39 | +│ └── 2026-03-25.md | |
| 40 | +└── sessions/ ← 按 session 存的原始快照（可选） | |
| 41 | +``` | |
| 42 | + | |
| 43 | +--- | |
| 44 | + | |
| 45 | +## 三、数据流全景 | |
| 46 | + | |
| 47 | +``` | |
| 48 | +┌─────────────────────────────────────────────────────────┐ | |
| 49 | +│ 新对话开始 │ | |
| 50 | +│ │ │ | |
| 51 | +│ ┌───────────────────▼──────────────────┐ │ | |
| 52 | +│ │ 1. READ: 加载记忆 │ │ | |
| 53 | +│ │ ├── memory.md (全量注入 prompt) │ │ | |
| 54 | +│ │ ├── 海马体匹配(关键词→方案) │ │ | |
| 55 | +│ │ ├── 短期记忆(最近 N 个 session) │ │ | |
| 56 | +│ │ └── 小脑方案(如果匹配到) │ │ | |
| 57 | +│ └───────────────────┬──────────────────┘ │ | |
| 58 | +│ │ │ | |
| 59 | +│ ▼ │ | |
| 60 | +│ [ Agent 执行任务 ] │ | |
| 61 | +│ │ │ | |
| 62 | +│ ┌───────────────────▼──────────────────┐ │ | |
| 63 | +│ │ 2. WRITE: 自动存储记忆 │ │ | |
| 64 | +│ │ ├── 生成 session 摘要 → short-term│ │ | |
| 65 | +│ │ ├── 提取关键事实 → memory.md │ │ | |
| 66 | +│ │ ├── 好方案 → cerebellum/ + 索引 │ │ | |
| 67 | +│ │ └── 教训/模式 → memory.md │ │ | |
| 68 | +│ └───────────────────┬──────────────────┘ │ | |
| 69 | +│ │ │ | |
| 70 | +│ ┌───────────────────▼──────────────────┐ │ | |
| 71 | +│ │ 3. CONSOLIDATE (定时整理) │ │ | |
| 72 | +│ │ ├── short-term 过期 → 合并 long-term │ │ | |
| 73 | +│ │ ├── memory.md 超长 → 摘要压缩 │ │ | |
| 74 | +│ │ ├── daily/ 日报生成 │ │ | |
| 75 | +│ │ └── hippocampus 索引更新 │ │ | |
| 76 | +│ └──────────────────────────────────────┘ │ | |
| 77 | +└─────────────────────────────────────────────────────────┘ | |
| 78 | +``` | |
| 79 | + | |
| 80 | +--- | |
| 81 | + | |
| 82 | +## 四、实现计划 — Todo List | |
| 83 | + | |
| 84 | +### Phase 1: 最小可行记忆 (MVP) 🎯 | |
| 85 | + | |
| 86 | +> 目标：Agent 不再失忆，每次对话的关键信息自动留存 | |
| 87 | + | |
| 88 | +- [ ] **1.1 对话结束自动生成 session 摘要** | |
| 89 | + - 位置: `server/routes/agent-chat.js` → `result` 事件处理 | |
| 90 | + - 触发: 对话 status 变为 `completed` 时 | |
| 91 | + - 输出: `memory/short-term/session-{timestamp}.md` | |
| 92 | + - 内容: 任务描述、执行结果、工具调用数、关键产出文件 | |
| 93 | + - 实现: 从 `messages.log` 提取（无需额外 LLM 调用） | |
| 94 | + ```javascript | |
| 95 | + // 伪代码 | |
| 96 | + function autoSaveSessionSummary(agentId, convId, meta) { | |
| 97 | + const summary = { | |
| 98 | + timestamp: new Date().toISOString(), | |
| 99 | + task: extractTaskFromFirstMessage(convId), | |
| 100 | + result: meta.lastAssistantMessage?.substring(0, 500), | |
| 101 | + toolCalls: meta.stats.toolCallCount, | |
| 102 | + duration: meta.duration, | |
| 103 | + files: extractCreatedFiles(convId), | |
| 104 | + }; | |
| 105 | + writeFile(`memory/short-term/session-${Date.now()}.md`, formatSummary(summary)); | |
| 106 | + } | |
| 107 | + ``` | |
| 108 | + | |
| 109 | +- [ ] **1.2 短期记忆注入 system prompt** | |
| 110 | + - 位置: `buildSystemPrompt()` 函数 | |
| 111 | + - 逻辑: 读取最近 5 个 `short-term/session-*.md`，拼接注入 | |
| 112 | + - 大小限制: 最近 5 个 session 摘要，每个 ≤300 字 | |
| 113 | + ``` | |
| 114 | + # 近期记忆（最近 5 次对话） | |
| 115 | + | |
| 116 | + ## 2026-03-25 10:00 — 训练 CEO 技能 | |
| 117 | + - 结果: 完成 Hunt→Digest→Evolve，最终分数 92/100 | |
| 118 | + - 产出: workspace/ceo/hunt/, workspace/ceo/digest/, workspace/ceo/evolve/ | |
| 119 | + | |
| 120 | + ## 2026-03-25 09:30 — 创建 Poet Agent | |
| 121 | + - 结果: 成功创建，SKILL.md 已就绪 | |
| 122 | + - 产出: data/agents/poet/ | |
| 123 | + ``` | |
| 124 | + | |
| 125 | +- [ ] **1.3 memory.md 自动追加关键事实** | |
| 126 | + - 触发: 对话结束 + toolCallCount > 0 | |
| 127 | + - 逻辑: 从 session 摘要中提取"关键事实"条目 | |
| 128 | + - 追加到 memory.md 的对应章节（关键事实/已验证模式/失败教训） | |
| 129 | + - 大小控制: memory.md 超过 2000 字时触发压缩 | |
| 130 | + | |
| 131 | +- [ ] **1.4 memory.md 大小控制** | |
| 132 | + - 当 memory.md > 2000 字: | |
| 133 | + - 移除最旧的条目 | |
| 134 | + - 或合并同类条目 | |
| 135 | + - 确保 prompt 不会因记忆过多而爆掉 | |
| 136 | + | |
| 137 | +--- | |
| 138 | + | |
| 139 | +### Phase 2: 海马体检索 + 小脑固化 | |
| 140 | + | |
| 141 | +> 目标：Agent 能检索相关经验，好方案自动复用 | |
| 142 | + | |
| 143 | +- [ ] **2.1 海马体索引结构定义** | |
| 144 | + ```markdown | |
| 145 | + # hippocampus.md | |
| 146 | + | # | 情景模式 | 匹配关键词 | 方案文件 | 置信度 | 使用次数 | | |
| 147 | + |---|---------|-----------|---------|--------|---------| | |
| 148 | + | 1 | 创建新 Agent | agent,create,创建 | cerebellum/create-agent.md | 0.9 | 5 | | |
| 149 | + | 2 | OKR 任务分解 | okr,goal,分解,plan | cerebellum/okr-decompose.md | 0.8 | 3 | | |
| 150 | + ``` | |
| 151 | + | |
| 152 | +- [ ] **2.2 海马体匹配引擎 (关键词 MVP)** | |
| 153 | + - 新建: `server/services/memory-service.js` | |
| 154 | + - 函数: `retrieveRelevantMemory(task, agentDir)` | |
| 155 | + - 逻辑: | |
| 156 | + 1. 解析 hippocampus.md 索引 | |
| 157 | + 2. 从 task 文本提取关键词（分词 + 停用词过滤） | |
| 158 | + 3. 计算关键词命中率 | |
| 159 | + 4. 返回命中的小脑方案列表 | |
| 160 | + - 注入: 在 `buildSystemPrompt()` 中调用，匹配到的方案追加到 prompt | |
| 161 | + | |
| 162 | +- [ ] **2.3 小脑方案写入** | |
| 163 | + - 触发: Agent 在反思中标记"这个方案效果好" | |
| 164 | + - 或: 管理员手动标记某个 session 为"好方案" | |
| 165 | + - 格式: | |
| 166 | + ```markdown | |
| 167 | + # 方案: 创建新 Agent | |
| 168 | + | |
| 169 | + ## 适用条件 | |
| 170 | + - 需要创建新的 Agent 角色 | |
| 171 | + - 需要定义 agent.md + soul.md + identity.md + SKILL.md | |
| 172 | + | |
| 173 | + ## 执行步骤 | |
| 174 | + 1. 确认 Agent 角色定义（名称、类型、能力） | |
| 175 | + 2. 调用 scaffold API 创建目录结构 | |
| 176 | + 3. 依次填写 agent.md, soul.md, identity.md | |
| 177 | + 4. 创建 .claude/skills/main_skill/SKILL.md | |
| 178 | + 5. 验证 config.json 配置 | |
| 179 | + | |
| 180 | + ## 注意事项 | |
| 181 | + - identity.md 必须包含 名称 字段 | |
| 182 | + - config.json 的 type 要正确设置 | |
| 183 | + ``` | |
| 184 | + | |
| 185 | +- [ ] **2.4 海马体索引自动更新** | |
| 186 | + - 当小脑新增方案时，自动追加索引行 | |
| 187 | + - 每次方案被成功使用，更新"使用次数"和"置信度" | |
| 188 | + | |
| 189 | +--- | |
| 190 | + | |
| 191 | +### Phase 3: 反思引擎 + 长期记忆 | |
| 192 | + | |
| 193 | +> 目标：Agent 能自主学习，经验自动沉淀 | |
| 194 | + | |
| 195 | +- [ ] **3.1 反思引擎实现** | |
| 196 | + - 位置: `Agent.js` 的 `reflect()` 方法 | |
| 197 | + - 触发条件（不是每次都反思）: | |
| 198 | + - toolCallCount ≥ 3 (有实质操作) | |
| 199 | + - 或 duration > 60s (较长时间的任务) | |
| 200 | + - 或 task 包含"训练/调试/修复"等关键词 | |
| 201 | + - 反思 prompt: | |
| 202 | + ``` | |
| 203 | + 请反思这次任务执行： | |
| 204 | + 1. 做得好的是什么？有什么可复用的模式？ | |
| 205 | + 2. 做得不好的是什么？有什么教训？ | |
| 206 | + 3. 这类任务的情景特征是什么？下次遇到类似任务应该怎么做？ | |
| 207 | + | |
| 208 | + 输出格式： | |
| 209 | + - pattern: (可复用的模式) | |
| 210 | + - lesson: (教训) | |
| 211 | + - scenario_keywords: (情景关键词列表) | |
| 212 | + - plan_summary: (如果方案好，写出步骤摘要) | |
| 213 | + ``` | |
| 214 | + | |
| 215 | +- [ ] **3.2 反思结果自动写入** | |
| 216 | + - pattern → memory.md "已验证的模式" | |
| 217 | + - lesson → memory.md "失败教训" | |
| 218 | + - plan_summary → cerebellum/ 新方案文件 | |
| 219 | + - scenario_keywords → hippocampus.md 新索引行 | |
| 220 | + | |
| 221 | +- [ ] **3.3 短期记忆合并到长期记忆** | |
| 222 | + - 触发: CronCreate 每天凌晨 2 点 | |
| 223 | + - 逻辑: | |
| 224 | + 1. 扫描 short-term/ 中超过 7 天的 session 摘要 | |
| 225 | + 2. 提取反复出现的模式 → long-term/patterns.md | |
| 226 | + 3. 提取重要事实 → long-term/facts.md | |
| 227 | + 4. 删除已合并的 short-term 文件 | |
| 228 | + - 输出: 更新 long-term/ 目录 | |
| 229 | + | |
| 230 | +- [ ] **3.4 日报自动化** | |
| 231 | + - 触发: CronCreate 每天 23:00 | |
| 232 | + - 内容: 当天的 session 数、任务完成数、关键成果 | |
| 233 | + - 输出: `memory/daily/YYYY-MM-DD.md` | |
| 234 | + | |
| 235 | +- [ ] **3.5 记忆遗忘机制** | |
| 236 | + - long-term 中连续 30 天未被引用的条目，降低权重 | |
| 237 | + - hippocampus 中置信度 < 0.3 且使用次数 = 0 的条目，标记为"已遗忘" | |
| 238 | + - 防止记忆无限膨胀 | |
| 239 | + | |
| 240 | +--- | |
| 241 | + | |
| 242 | +## 五、关键技术决策 | |
| 243 | + | |
| 244 | +| # | 问题 | 决策 | 说明 | | |
| 245 | +|---|------|------|------| | |
| 246 | +| 1 | session 摘要生成方式 | **无 LLM，纯提取** (MVP) | 从 meta.json + messages.log 提取，不消耗 API 配额 | | |
| 247 | +| 2 | 海马体匹配算法 | **关键词匹配** (MVP) | 后续按需升级向量检索 | | |
| 248 | +| 3 | memory.md 注入方式 | **全量 + 最近 5 session** | memory.md ≤2000字 + 5 个 session 摘要 ≤1500字 | | |
| 249 | +| 4 | 反思触发条件 | **有实质操作的对话才反思** | toolCallCount ≥ 3 或 duration > 60s | | |
| 250 | +| 5 | 反思执行者 | **Agent 自己** | 通过追加一条 prompt 让 Agent 反思并输出 JSON | | |
| 251 | +| 6 | 长期合并频率 | **每天凌晨** | cron 触发，不影响白天使用 | | |
| 252 | + | |
| 253 | +--- | |
| 254 | + | |
| 255 | +## 六、代码改动点 | |
| 256 | + | |
| 257 | +| 文件 | 改动 | Phase | | |
| 258 | +|------|------|-------| | |
| 259 | +| `server/routes/agent-chat.js` | `result` 事件中调用 MemoryWriter | 1 | | |
| 260 | +| `server/routes/agent-chat.js` | `buildSystemPrompt()` 加载 short-term | 1 | | |
| 261 | +| `server/services/memory-service.js` | **新建**: session摘要、记忆检索、索引更新 | 1+2 | | |
| 262 | +| `packages/agent-core/Agent.js` | `reflect()` 实现 | 3 | | |
| 263 | +| `packages/agent-core/base/common/capabilities.md` | 增加记忆使用说明 | 1 | | |
| 264 | + | |
| 265 | +--- | |
| 266 | + | |
| 267 | +## 七、验证标准 | |
| 268 | + | |
| 269 | +### Phase 1 验收 | |
| 270 | +- [ ] 与 CEO Agent 对话一次 → `short-term/` 出现新 session 文件 | |
| 271 | +- [ ] 第二次对话 → system prompt 中能看到"近期记忆"段 | |
| 272 | +- [ ] 多次对话后 → memory.md 有新追加的关键事实 | |
| 273 | + | |
| 274 | +### Phase 2 验收 | |
| 275 | +- [ ] 手动添加一条 hippocampus 索引 | |
| 276 | +- [ ] 给 Agent 分配匹配的任务 → prompt 中出现小脑方案内容 | |
| 277 | +- [ ] Agent 使用方案完成任务 → 索引的使用次数 +1 | |
| 278 | + | |
| 279 | +### Phase 3 验收 | |
| 280 | +- [ ] Agent 完成复杂任务 → 自动触发反思 | |
| 281 | +- [ ] 反思结果写入 memory.md 和 cerebellum/ | |
| 282 | +- [ ] 7 天后 → short-term 合并到 long-term，旧文件清理 | ... | ... |