22-agent-memory-system.md 11.8 KB

Edit Raw Blame History


22. Agent Memory System — 自动记忆读写架构

版本: v1.0 (设计稿)
日期: 2026-03-25
状态: 规划中
前置: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分


一、核心问题
当前 Agent 每次新对话都是完全失忆的。
memory 目录结构已就位，但读写机制全是空壳。

需要解决：


Agent 如何自动记住做过什么、学到什么、犯过什么错
Agent 接到新任务时如何自动想起相关经验
好方案如何自动固化，下次遇到同类任务直接复用


二、目录结构（已就位）
data/agents/{agent-id}/memory/
├── memory.md              ← 核心记忆索引（注入 prompt，≤2000字）
├── hippocampus.md         ← 海马体：情景→方案 映射索引
├── cerebellum/            ← 小脑：固化的执行方案（.md 步骤 / .js 脚本）
│   ├── handle-okr-task.md
│   └── create-agent.md
├── short-term/            ← 短期记忆：近期 session 摘要
│   ├── session-2026-03-25-001.md
│   └── session-2026-03-25-002.md
├── long-term/             ← 长期记忆：沉淀的经验 & 事实
│   ├── patterns.md        ← 反复验证的模式
│   ├── lessons.md         ← 失败教训
│   └── facts.md           ← 重要事实
├── daily/                 ← 日报
│   └── 2026-03-25.md
└── sessions/              ← 按 session 存的原始快照（可选）


三、数据流全景
┌─────────────────────────────────────────────────────────┐
│                     新对话开始                            │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  1. READ: 加载记忆                    │              │
│    │     ├── memory.md (全量注入 prompt)   │              │
│    │     ├── 海马体匹配(关键词→方案)       │              │
│    │     ├── 短期记忆(最近 N 个 session)   │              │
│    │     └── 小脑方案(如果匹配到)          │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│                        ▼                                 │
│              [ Agent 执行任务 ]                           │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  2. WRITE: 自动存储记忆               │              │
│    │     ├── 生成 session 摘要 → short-term│              │
│    │     ├── 提取关键事实 → memory.md      │              │
│    │     ├── 好方案 → cerebellum/ + 索引   │              │
│    │     └── 教训/模式 → memory.md         │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  3. CONSOLIDATE (定时整理)             │              │
│    │     ├── short-term 过期 → 合并 long-term │           │
│    │     ├── memory.md 超长 → 摘要压缩     │              │
│    │     ├── daily/ 日报生成               │              │
│    │     └── hippocampus 索引更新          │              │
│    └──────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────┘


四、实现计划 — Todo List
Phase 1: 最小可行记忆 (MVP) 🎯

目标：Agent 不再失忆，每次对话的关键信息自动留存


[ ] 1.1 对话结束自动生成 session 摘要


位置: server/routes/agent-chat.js → result 事件处理
触发: 对话 status 变为 completed 时
输出: memory/short-term/session-{timestamp}.md
内容: 任务描述、执行结果、工具调用数、关键产出文件
实现: 从 messages.log 提取（无需额外 LLM 调用）
javascript
// 伪代码
function autoSaveSessionSummary(agentId, convId, meta) {
const summary = {
timestamp: new Date().toISOString(),
task: extractTaskFromFirstMessage(convId),
result: meta.lastAssistantMessage?.substring(0, 500),
toolCalls: meta.stats.toolCallCount,
duration: meta.duration,
files: extractCreatedFiles(convId),
};
writeFile(`memory/short-term/session-${Date.now()}.md`, formatSummary(summary));
}


[ ] 1.2 短期记忆注入 system prompt


位置: buildSystemPrompt() 函数
逻辑: 读取最近 5 个 short-term/session-*.md，拼接注入
大小限制: 最近 5 个 session 摘要，每个 ≤300 字
```
# 近期记忆（最近 5 次对话）


## 2026-03-25 10:00 — 训练 CEO 技能


结果: 完成 Hunt→Digest→Evolve，最终分数 92/100
产出: workspace/ceo/hunt/, workspace/ceo/digest/, workspace/ceo/evolve/


## 2026-03-25 09:30 — 创建 Poet Agent


结果: 成功创建，SKILL.md 已就绪
产出: data/agents/poet/
```


[ ] 1.3 memory.md 自动追加关键事实


触发: 对话结束 + toolCallCount > 0
逻辑: 从 session 摘要中提取"关键事实"条目
追加到 memory.md 的对应章节（关键事实/已验证模式/失败教训）
大小控制: memory.md 超过 2000 字时触发压缩

[ ] 1.4 memory.md 大小控制


当 memory.md > 2000 字:
移除最旧的条目
或合并同类条目
确保 prompt 不会因记忆过多而爆掉


Phase 2: 海马体检索 + 小脑固化

目标：Agent 能检索相关经验，好方案自动复用


[ ] 2.1 海马体索引结构定义
# hippocampus.md
| # | 情景模式 | 匹配关键词 | 方案文件 | 置信度 | 使用次数 |
|---|---------|-----------|---------|--------|---------|
| 1 | 创建新 Agent | agent,create,创建 | cerebellum/create-agent.md | 0.9 | 5 |
| 2 | OKR 任务分解 | okr,goal,分解,plan | cerebellum/okr-decompose.md | 0.8 | 3 |

[ ] 2.2 海马体匹配引擎 (关键词 MVP)


新建: server/services/memory-service.js
函数: retrieveRelevantMemory(task, agentDir)
逻辑:
解析 hippocampus.md 索引
从 task 文本提取关键词（分词 + 停用词过滤）
计算关键词命中率
返回命中的小脑方案列表
注入: 在 buildSystemPrompt() 中调用，匹配到的方案追加到 prompt

[ ] 2.3 小脑方案写入


触发: Agent 在反思中标记"这个方案效果好"
或: 管理员手动标记某个 session 为"好方案"
格式:
```markdown
# 方案: 创建新 Agent


## 适用条件


需要创建新的 Agent 角色
需要定义 agent.md + soul.md + identity.md + SKILL.md


## 执行步骤


确认 Agent 角色定义（名称、类型、能力）
调用 scaffold API 创建目录结构
依次填写 agent.md, soul.md, identity.md
创建 .claude/skills/main_skill/SKILL.md
验证 config.json 配置


## 注意事项


identity.md 必须包含 名称 字段
config.json 的 type 要正确设置
```


[ ] 2.4 海马体索引自动更新


当小脑新增方案时，自动追加索引行
每次方案被成功使用，更新"使用次数"和"置信度"


Phase 3: 反思引擎 + 长期记忆

目标：Agent 能自主学习，经验自动沉淀


[ ] 3.1 反思引擎实现


位置: Agent.js 的 reflect() 方法
触发条件（不是每次都反思）:
toolCallCount ≥ 3 (有实质操作)
或 duration > 60s (较长时间的任务)
或 task 包含"训练/调试/修复"等关键词
反思 prompt:
```
请反思这次任务执行：
1. 做得好的是什么？有什么可复用的模式？
2. 做得不好的是什么？有什么教训？
3. 这类任务的情景特征是什么？下次遇到类似任务应该怎么做？


输出格式：


pattern: (可复用的模式)
lesson: (教训)
scenario_keywords: (情景关键词列表)
plan_summary: (如果方案好，写出步骤摘要)
```


[ ] 3.2 反思结果自动写入


pattern → memory.md "已验证的模式"
lesson → memory.md "失败教训"
plan_summary → cerebellum/ 新方案文件
scenario_keywords → hippocampus.md 新索引行

[ ] 3.3 短期记忆合并到长期记忆


触发: CronCreate 每天凌晨 2 点
逻辑:
扫描 short-term/ 中超过 7 天的 session 摘要
提取反复出现的模式 → long-term/patterns.md
提取重要事实 → long-term/facts.md
删除已合并的 short-term 文件
输出: 更新 long-term/ 目录

[ ] 3.4 日报自动化


触发: CronCreate 每天 23:00
内容: 当天的 session 数、任务完成数、关键成果
输出: memory/daily/YYYY-MM-DD.md

[ ] 3.5 记忆遗忘机制


long-term 中连续 30 天未被引用的条目，降低权重
hippocampus 中置信度 
防止记忆无限膨胀


五、关键技术决策


#
问题
决策
说明


1
session 摘要生成方式
无 LLM，纯提取 (MVP)
从 meta.json + messages.log 提取，不消耗 API 配额


2
海马体匹配算法
关键词匹配 (MVP)
后续按需升级向量检索


3
memory.md 注入方式
全量 + 最近 5 session
memory.md ≤2000字 + 5 个 session 摘要 ≤1500字


4
反思触发条件
有实质操作的对话才反思
toolCallCount ≥ 3 或 duration > 60s


5
反思执行者
Agent 自己
通过追加一条 prompt 让 Agent 反思并输出 JSON


6
长期合并频率
每天凌晨
cron 触发，不影响白天使用


六、代码改动点


文件
改动
Phase


server/routes/agent-chat.js
result 事件中调用 MemoryWriter
1


server/routes/agent-chat.js
buildSystemPrompt() 加载 short-term
1


server/services/memory-service.js
新建: session摘要、记忆检索、索引更新
1+2


packages/agent-core/Agent.js
reflect() 实现
3


packages/agent-core/base/common/capabilities.md
增加记忆使用说明
1


七、验证标准
Phase 1 验收

[ ] 与 CEO Agent 对话一次 → short-term/ 出现新 session 文件
[ ] 第二次对话 → system prompt 中能看到"近期记忆"段
[ ] 多次对话后 → memory.md 有新追加的关键事实

Phase 2 验收

[ ] 手动添加一条 hippocampus 索引
[ ] 给 Agent 分配匹配的任务 → prompt 中出现小脑方案内容
[ ] Agent 使用方案完成任务 → 索引的使用次数 +1

Phase 3 验收

[ ] Agent 完成复杂任务 → 自动触发反思
[ ] 反思结果写入 memory.md 和 cerebellum/
[ ] 7 天后 → short-term 合并到 long-term，旧文件清理