AI Agent 记忆系统设计：从零到生产可用的完整架构

标签：AI Agent、LLM、Agent Memory、OpenClaw

背景

我在用 OpenClaw 运行一个 6 人 AI Agent 团队，负责内容创作、社媒运营、技术开发等全链路工作。

这个系统跑了 19 天后，我发现最大的工程挑战不是模型选型、不是提示词调优——而是让 Agent 记住事情。

这篇文章是 19 天踩坑后的系统性总结，重点讲 Memory 系统的架构设计：分层存储、检索机制、更新触发，以及我在真实运营中踩过的所有坑。

第一个坑：LLM 是金鱼记忆

直接上问题：

Day 1：告诉 Agent A → 飞书不能用 <img> 标签，要用原生 API
Day 2：Agent A 犯同样的错误
Day 3：再次告诉。"收到，我记住了。"
Day 4：同样的错误，第三次。

这不是 Bug，这是 LLM 的本质：没有外部存储，每次对话都是白板。

问题很清楚：需要给 Agent 装上持久记忆。

架构设计：五层记忆模型

经过多轮迭代，我们在 OpenClaw 里实现了以下五层记忆架构：

L0  context window          ← 当前对话，自动注入，对话结束消失
L1  memory/YYYY-MM-DD.md   ← 日志，今天+昨天自动注入，21天衰减
L2  MEMORY.md              ← 核心事实，每个 session 启动时注入（≤2000 字节）
L3  memory/bank/*.md       ← 知识库，semantic 检索按需注入
L4  /shared-knowledge/     ← 跨 Agent 共享，extraPaths 只读挂载

L2：温记忆（MEMORY.md）

这是整个系统最关键的层。每个 Agent 都有一个 MEMORY.md，在 session 启动时自动注入 context。

# Agent 核心记忆

## 身份
- 微信公众号运营 Agent，隶属 CEO 管理
- 职责：养虾主题深度长文创作 + 发布

## 关键规则
- 发布工具：wenyan-mcp → Markdown → 草稿箱
- 发布前必须通过六项内审清单
- 飞书图片不能用 <img> 标签，必须用飞书原生 API

## 知识库引用
- memory/bank/tooling.md      ← 工具使用经验
- memory/bank/incidents.md    ← 事故记录
- shared-knowledge/standards/ ← 跨 Agent 规范

硬约束：MEMORY.md ≤ 2000 字节。 超出则触发 P2 告警并强制精简。原因：LLM 对”中间信息”的注意力会随长度衰减，越长越容易被忽略。

L3：Knowledge Bank

memory/bank/
├── decisions.md      ← 重要决策（日期 + 内容 + 理由）
├── incidents.md      ← 事故记录
├── tooling.md        ← 工具经验
├── sop/              ← 标准操作流程
├── strategy/         ← 策略文档
└── reference/        ← 参考资料

文件名规则：不以日期开头，确保 temporal decay 算法视其为常青文件，不会衰减。

L4：跨 Agent 共享知识库

shared-knowledge/
├── standards/
│   ├── team-architecture.md    ← 团队路由表（单一真相源）
│   ├── memory-protocol.md      ← 记忆协议规范
│   ├── feishu-api-guide.md     ← 平台 API 规范
│   └── platform-facts.md      ← 平台限制事实
├── runbooks/
│   ├── xhs-publish-guard.md   ← 防重复发布
│   └── xhs-interaction-rules.md
└── history/
    ├── decisions-log.md        ← 重要决策存档
    └── incidents.md            ← 事故日志

核心设计：Agent 不能直接读其他 Agent 的 memory/，共享知识只通过 L4 单向挂载。这解决了知识孤岛问题，同时避免了跨 Agent 的记忆污染。

检索配置

OpenClaw 的记忆检索使用 hybrid 模式：

retrieval:
  mode: hybrid
  bm25_weight: 0.65
  vector_weight: 0.35
  mmr_enabled: true       # 最大边际相关，避免检索结果重复
  mmr_lambda: 0.75
  temporal_decay:
    enabled: true
    half_life_days: 21    # 普通 Agent
    ceo_half_life: 14     # CEO Agent 衰减更快（更新鲜）
  cache:
    enabled: true
    max_entries: 30000

Temporal Decay 的意义：越老的日志，检索权重越低。避免三周前的过时信息干扰当前决策。

Daily Log 规范：Retain 格式

每天的日志文件（L1）需要在末尾写 Retain 格式，这是记忆系统的”输入端”：

## Retain
- W @platform: 飞书图片 API v2 接口需要 image_key，不是 URL
- B @wechat-mp: 发布了「记忆系统」长文，阅读量 312
- O(c=0.85) @system: 早上 10 点发布的打开率比晚上高约 40%

格式说明：

W (World) — 客观发现，高置信度
B (Behavior) — 自己做了什么
O(c=0.x) — 观点/推断，附带信心度

这个格式的价值：SRE Agent 会定期扫描 Retain 块，把高价值的条目升级到 L2 或 L3，形成记忆蒸馏。

踩坑一：记了但找不到

第 7 天：memory/ 目录里有 42 个文件，每个几千字，没有索引。我需要一条飞书 API 规范，翻了 20 分钟没找到。

根因：L1 日志只适合”今天发生了什么”，不适合存”结构化知识”。把规范写进日志，等于把文件归档进了碎纸机。

解法：重要的规范直接写进 memory/bank/ 或 shared-knowledge/，日志只记录事件流水。

踩坑二：更新闭环失败

第 19 天：

上午 10 点：告诉 CEO Agent "任务A完成了，任务B取消了"
CEO Agent："收到，明白了。"

下午 3 点：CEO Agent 读 active-tasks.md
active-tasks.md 里：任务A=进行中，任务B=进行中
CEO Agent 开始追问进度...

根因：收到 ≠ 写入持久存储。

教训：

记忆 = 存储 + 检索 + 更新。存了不更新，比没存更危险。

解法：定义强制更新触发器：

踩坑三：Context Compaction 导致记忆丢失

第 10 天：一个 Agent 的 session 被系统自动压缩（context 过长）。压缩前它记录了一段操作规范，压缩后这段内容消失了——Agent 自己都不知道它曾经知道什么。

解法：Memory Flush 机制。在 context window 接近上限时，自动触发 Retain 写入：

# 在 SOUL.md 或 AGENTS.md 中配置：
## Memory Flush 协议
当 context 接近压缩阈值时：
1. 写 Retain 块到当日日志
2. 更新 MEMORY.md（如有重要新规则）
3. 然后允许压缩发生

健康监控

记忆系统也需要监控，否则你不知道它什么时候悄悄坏掉了：

| 监控项 | 阈值 | 告警级别 | | MEMORY.md 大小 | > 2000 字节 | P2 | | memory/ 文件数 | > 90 | P3 | | 重复规则条目 | 检测到 | P3 | | L3 文件未被检索超过 30 天 | — | P3（可能过时） |

SRE Agent 负责每周扫描一次，超规则发飞书告警。

分级检索优先级

当 Agent 需要回答”我应该怎么做？“时，检索优先级：

1. 当前对话内容（最高优先，实时）
2. MEMORY.md + SOUL.md（每次 session 注入）
3. active-tasks.md（心跳/任务判断前读）
4. memory/bank/ + shared-knowledge/（按需 semantic 检索）

关键规则：当用户实时说了新信息，立即写入持久存储，不要只依赖 context window。

总结：五个核心维度

这套系统目前运行在 OpenClaw 上，是开源的。如果你在搭建自己的 Agent 系统，这些踩坑经历希望能帮你省点时间。

微信搜索「Wesley AI 日记」，每天更新。