宜博 / lemonboss

Commit 90527823ec33117237a2a6c63cffb0329105686b

Authored by yibo
1 parent db172833

docs: add agent memory system architecture plan (22-agent-memory-system.md)

Inline Side-by-side
Showing 1 changed file with 282 additions and 0 deletions
docs/system-design/22-agent-memory-system.md 0 → 100644
  View file @9052782
  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，旧文件清理