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

> **版本**: v1.1 (已实现 / 生产可用)
> **日期**: 2026-03-25
> **状态**: ✅ 已完成 (Phase 1, 2, 3 全部上线，E2E测试 27/27 通过)
> **前置**: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分

---

## 一、核心问题与解决方案

当前 Agent 每次新对话都是**完全失忆**的。
为此，我们设计并实现了一套包含 **MVP基础记忆**、**海马体&小脑检索**、**自动反思与长期合并** 的三阶段进化架构，真实解决：
1. Agent **自动记住**做过什么、学到什么、犯过什么错。
2. Agent 接到新任务时**自动想起**相关经验（按关键词计算关联度）。
3. 好的多步方案**自动固化**到小脑，下次遇到同类任务精准触发复用。

---

## 二、目录结构

每个 Agent 的记忆文件严格按以下结构持久化在 `data/agents/{agent-id}/memory/` 下：

```
memory/
├── memory.md              ← 核心记忆（关键事实/已验证模式/失败教训），每次全量注入 prompt
├── hippocampus.md         ← 海马体：情景→方案的映射（Markdown，人类可读）
├── hippocampus-index.json ← 海马体机器索引，用于关键词匹配检索和分值计算
├── cerebellum/            ← 小脑：固化的执行方案（.md 步骤指导）
├── short-term/            ← 短期记忆：近期 session 的纯文本摘要，包含执行数据
├── long-term/             ← 长期记忆：合并过期的短期记忆提取的 keyword 频率与长文归档
├── reflections/           ← 反思日志：每次高复杂度任务自动提取的模式与教训存放处
└── daily/                 ← 日报：汇总当天的对话、反思和新生方案
```

---

## 三、数据流全景

```
┌─────────────────────────────────────────────────────────┐
│                     新对话开始                            │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  1. READ: 挂载记忆(buildSystemPrompt) │              │
│    │     ├── memory.md (全量注入 prompt)   │              │
│    │     ├── 海马体精准匹配(用户输入+todo) │              │
│    │     ├── 短期记忆(最近 N 个 session)   │              │
│    │     └── 小脑方案(如果匹配到海马体)    │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│                        ▼                                 │
│              [ Agent 执行任务 ]                           │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  2. WRITE: 自动存储记忆(Chat 完成后)  │              │
│    │     ├── 生成 session 摘要 → short-term│              │
│    │     ├── 提取关键事实 → memory.md      │              │
│    │     ├── 高复杂度任务自动触发 Reflection │              │
│    │     └── 好方案自固化 → cerebellum/    │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  3. CONSOLIDATE (长期沉淀 API)        │              │
│    │     ├── 短期摘要过期 → 合并 long-term │             │
│    │     ├── 提取高频关键词 → patterns.md  │              │
│    │     ├── daily/ 日报生成               │              │
│    │     └── 遗忘机制及索引整理              │              │
│    └──────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────┘
```

---

## 四、实现复盘 — Todo List 全部点亮

### Phase 1: 最小可行记忆 (MVP) 🎯

> **目标**：Agent 不再失忆，每次对话的关键信息自动留存
> **结果**：完美运行，自动提取生成轻量摘要

- [x] **1.1 对话结束自动生成 session 摘要**
  - 在 `agent-chat.js` 内捕获对话完毕事件，提取 `meta.json` 里的基本信息结合对话产出生成 Markdown 概要，存入 `short-term/session-{timestamp}.md`。
- [x] **1.2 短期记忆注入 system prompt**
  - `buildSystemPrompt()` 会反向加载最新的 5 个 `session-*.md` 摘要。
- [x] **1.3 memory.md 自动追加关键事实**
  - ToolCallCounts > 0 时，自动从任务文本和最终回应抓取一两句话，追加为 `[时间] 任务 → 结果` 写入 `memory.md` 的“关键事实”段落。
- [x] **1.4 memory.md 大小控制**
  - 自带 2000 字符控制，如果超过会安全截断旧记录。

---

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

> **目标**：Agent 能检索相关经验，好方案自动复用
> **结果**：实现基于自研评分机制与语境保护的轻量检索系统

- [x] **2.1 海马体索引结构定义**
  - 数据结构存储于 `hippocampus-index.json`，并每次变动都会用 `syncHippocampusMd` 同步至人类友好版表格 `hippocampus.md`，追踪使用次数(useCount)与置信度。
- [x] **2.2 海马体匹配引擎 (自研提词匹配器)**
  - 实现于 `memory-service.js:retrieveRelevantPlans`。
  - **关键修复**：由于历史任务的英文 JSON 记录容易截断最新的中文分词，提词引擎 (`extractKeywords`) 已升级为“截取前1500字符 + 优先保护中文短词提取 + 容量扩大至 50 词汇”，同时在 prompt 拼接时让新的 `userMessage` 置顶，精准保证任何海马体历史都能被识别和唤起。
- [x] **2.3 小脑方案写入与索引自动更新**
  - 实现 `saveCerebellumPlan` 接口和后端逻辑。存储 MD 方案进入 `cerebellum/` 并安全覆盖和递增 `hippocampus` 表的使用次数。

---

### Phase 3: 反思引擎 + 长期沉淀 🧬

> **目标**：Agent 能自主学习，经验自动沉淀
> **结果**：实现了免唤起 LLM 的“规则型反思引擎”，大幅度降低了 API Cost，但又完美提取并分类总结了信息。

- [x] **3.1 反思引擎 (`autoReflect`)**
  - 不做毫无意义的次次反思。仅在：`toolCallCount ≥ 3`，或 `duration ≥ 60s` 时自动触发。
  - 成功任务 → 提取到 patterns（模式），5 次及以上 tool calls 更是会触发**自动写入小脑执行步骤**。
  - 失败任务 (status='failed') → 提取到 lessons（教训）。
  - 所有原始细节封存进 `reflections/` 作为 JSON 参考。
- [x] **3.2 反思结果自动反馈给当前 Prompt**
  - 新学习到的 patterns 和 lessons 会立刻被追加回 `memory.md` 的对应栏位里，下一次回答时 Agent 即可利用。
- [x] **3.3 短期记忆合并到长期记忆 (`consolidateMemory`)**
  - 通过 `/api/agent/:agentId/memory/consolidate` API 触发。
  - 自动扫除 > 7天以上的 `short-term` 记录，统合写入 `long-term/consolidate-{date}.md` 并通过关键词聚合提取模式。
- [x] **3.4 日报与统计 (`generateDailyReport`)**
  - 每天生成 `daily/YYYY-MM-DD.md` 包含对话量、反思数及新知识增幅。

---

## 五、关键技术决策（最新版）

| # | 问题 | 决策 | 收益/说明 |
|---|------|------|------|
| 1 | session 摘要生成方式 | **无 LLM，纯逻辑提取** | 不增加任何 Token 和耗时开销，完全透明。 |
| 2 | 海马体匹配算法 | **中英双优 ngram 关键词打分** | 以 `hits / keywords` 定比率。免装向量库。通过拦截前排中文字段保证了召回率 (> 0.3 即命中)。 |
| 3 | memory.md 注入方式 | **全量 + 最近 5 session** | 整体记忆控制在最佳窗口容差内，避免爆掉模型的 Attention 机制。 |
| 4 | 反思引擎实现 | **纯代码规则引擎** | 旧设计想用 LLM 生成，但考虑到海量废话，现改为通过对话信息解析直接生成结构化数据，速度瞬间出结果并准确反馈。 |

---

## 六、验证标准及结果

以下 E2E 自动化测试用例位于 `server/scripts/test-memory-e2e.js` 并在 `2026-03-25` 完成验证。

### Phase 1 验收 (✅ Pass)
- [x] 与 Agent 对话一次 → `short-term/` 出现新 session 文件
- [x] 第二次对话 → system prompt 中能看到"近期记忆"段并成功被 Agent 引述
- [x] 多次对话后 → `memory.md` 有新追加的关键事实

### Phase 2 验收 (✅ Pass)
- [x] 使用 API 保存小脑方案，JSON 索引建立。
- [x] 派发强关键词匹配任务 → 海马体引擎拦截命中，Prompt 体积扩大，被方案包围。
- [x] 成功命中后，后端日志展现 `🐴 海马体命中`，海马体 UseCount 累增。

### Phase 3 验收 (✅ Pass)
- [x] 伪造高工具调用对话 → 触发反思引擎，`memory.md` 写入已验证模式。
- [x] 伪造报错退出对话 → 触发反思引擎，写入失败教训。
- [x] POST 触发 `/consolidate` → 短期记忆消失，清算存入 Long-Term。
- [x] POST 触发 `/daily-report` → 生成包含了当天统计和反思日志指引的日报 Markdown。

🎉 **[E2E Suite]: ALL PASSED (27/27) - 核心模块生产就绪！**