Agent 记忆架构选型实战：从场景到方案

不同场景需要不同的记忆架构------理解三大编码 Agent 的记忆设计，掌握 Agent 与 RAG 的记忆处理分界线

一、记忆架构：没有银弹

上一篇文章我们梳理了 Agent 记忆的三代演进和六大架构流派。但一个更实际的问题摆在面前：我的场景该用哪种？

答案不是"选最好的"，而是"选最匹配的"。原因很简单------不同场景对记忆的需求维度完全不同：

智能客服需要跨会话记住用户偏好，但每个用户的记忆量很小（几 KB），用户量巨大（百万级）
研究报告 Agent 需要跨数十轮对话保持推理链，但用户量小，单次记忆量极大（MB 级）
编码 Agent 需要跨会话记住项目约定，但记忆的消费者是模型自身，不是检索系统

当我们观察当前主流的三个编码 Agent------Claude Code、Codex CLI、CodeWhale------它们的记忆设计截然不同，却都在各自场景下工作良好。这说明记忆架构的选择，本质上是一个工程权衡问题，而非技术优劣问题。

二、不同编码 Agent 为什么选择了截然不同的记忆设计？

2.1 Claude Code：四层认知架构，模拟人类记忆流程

Claude Code 的记忆系统是对人类"工作记忆 → 长期记忆 → 记忆巩固"认知流程的直接模拟，共四层：

层级	名称	存储位置	谁写入	生命周期	核心功能
L1	CLAUDE.md	项目根目录 / `~/.claude/`	开发者手写	永久（随 Git 提交）	项目硬规则：编码规范、架构说明、部署命令
L2	Auto Memory	`~/.claude/projects/<slug>/memory/`	Claude 自动	永久（跨会话）	交互中沉淀的信息：用户纠正、偏好、架构决策
L3	Session Memory	本地对话记录	Claude 自动	单次会话	当前会话上下文：提问、代码片段、工具结果
L4	Auto Dream	修改 L2 层文件	Claude 子代理	周期性（24h + 5 次会话）	后台整理：去重、合并、解决矛盾、修剪过期条目

关键设计细节：

Auto Memory 的索引机制 ：所有记忆文件由一个 MEMORY.md 索引文件管理，每行是一个指向 topic 文件的链接（≤150 字符）。只有前 200 行会被加载到每次会话。超出部分不可见------这是一个硬约束。

Auto Memory 的四类分类法：

user：角色和偏好（"后端工程师，擅长 Go，刚学 React"）
feedback：用户纠正（"集成测试必须用真实数据库，不要 mock"）
project：项目决策（"认证重写是合规驱动的，不是技术债"）
reference：资源位置（"Pipeline bug 在 Linear INGEST 项目里"）

Auto Dream 的整理逻辑：当超过 24 小时且累积 5+ 次会话后触发。将模糊时间引用替换为精确日期（"昨天的部署问题" → "2026-03-28 部署问题"），解决矛盾（PostgreSQL 笔记 + MySQL 笔记 → 保留当前事实），删除过期条目。

上下文压缩（Compaction） ：当上下文窗口接近 1M Token 上限时，Claude Code 自动将早期对话压缩为摘要，保留关键决策和文件路径，丢弃逐字对话。用户也可通过 /compact 手动触发。

设计哲学：让 Agent 像人类一样"记住"项目------入职手册（CLAUDE.md）+ 工作笔记（Auto Memory）+ 短期便签（Session Memory）+ 睡眠整理（Auto Dream）。

Claude Code 的方案是"模拟人类认知"，但 Codex CLI 走了一条完全不同的路------它不模拟人类，而是用工程化的异步管道来生成"机构知识"。

2.2 OpenAI Codex CLI：两阶段管道，从会话到机构知识

Codex CLI 的记忆系统在 2026 年 4 月作为"Codex for (almost) everything"更新的一部分发布，采用完全不同的架构------两阶段异步管道：

层级	名称	存储位置	谁写入	生命周期	核心功能
L1	AGENTS.md	项目根目录 / `~/.codex/`	开发者手写	永久（随 Git 提交）	团队级项目规则：编码标准、测试命令、部署约定
L2	Memories	`~/.codex/memories/`	Codex 自动	永久（跨会话，30 天老化）	从历史会话中提取的偏好、修正、模式

关键设计细节：

两阶段管道：

复制代码

Phase 1: Rollout Extraction（并行）
  会话空闲 6h+ → 认领任务 → LLM 提取结构化记忆 → 秘密脱敏 → 存入 SQLite

Phase 2: Global Consolidation（串行）
  获取全局锁 → 加载 Phase 1 输出 → 生成合并子代理 → 更新 MEMORY.md + skills/ → 修剪过期条目

Phase 1 可以并行处理多个会话，Phase 2 串行执行以保证全局一致性。这种分离是刻意设计的：提取可以水平扩展，合并必须串行以维护状态一致性。

记忆的磁盘布局：

复制代码

~/.codex/memories/
├── MEMORY.md              ← 长格式合并记忆，按需 grep
├── memory_summary.md      ← 会话启动时首先读取的摘要视图
├── raw_memories.md        ← Phase 1 的原始提取输出
├── skills/<name>/SKILL.md ← 特定技能的记忆
└── rollout_summaries/     ← 每个会话的摘要

加载机制 ：会话启动时，完整读取 memory_summary.md，截断到 5,000 Token 预算 ，注入开发者指令。不在摘要中的内容，Agent 通过 grep MEMORY.md 按需检索。没有向量嵌入、没有相似性搜索、没有重排序------纯文本和子字符串匹配。

老化与遗忘 ：max_rollout_age_days（默认 30）限制可提取记忆的会话年龄；max_unused_days（默认 30）使超过 30 天未被召回的记忆在下次合并中被淘汰。

速率限制感知 ：min_rate_limit_remaining_percent（默认 25%）确保后台记忆工作不会饿死前台请求。

设计哲学：记忆是异步管道的产物，不是实时写入的日志。用可预测性和零检索延迟，换取无法找到表述不共享关键词的事实。

Claude Code 和 Codex CLI 都选择了"独立记忆层"的路线，但 CodeWhale 的思路完全不同------它干脆不建记忆层，而是让模型自己"看"文件系统。

2.3 CodeWhale（DeepSeek-TUI）：Constitution + RLM，开卷考试模式

CodeWhale 的记忆架构与前两者截然不同------它不依赖独立的记忆层，而是利用 DeepSeek V4 的 1M Token 上下文窗口 + 前缀缓存，将所有必要信息保持在上下文内：

层级	名称	存储位置	谁写入	生命周期	核心功能
L1	Constitution	项目配置文件	开发者手写	永久	项目规则与约束，类似 CLAUDE.md / AGENTS.md
L2	RLM（Recursive Language Model）	上下文内 + 文件系统	Agent 实时查询	单次会话	通过递归调用 LLM 查询文件系统获取项目上下文
L3	Side-Git 快照	`.codewhale/` 目录	系统自动	单次会话	每轮操作前后的工作区快照，支持一键回滚

关键设计细节：

Constitution 机制 ：类似 CLAUDE.md / AGENTS.md，但 CodeWhale 的 Constitution 更长更详细------它包含九层权威排序（最新的用户指令高于过时的项目说明，工具的真实输出高于模型的假设，验证高于自信）。由于 DeepSeek V4 的前缀缓存机制，长 Constitution 一旦缓存后，每轮调用的边际成本极低------比首次冷读便宜约 100 倍。

RLM（Recursive Language Model）：RLM 不是一次性加载所有文件到上下文，而是让 Agent 通过 file、shell、git、web、MCP 等工具递归查询文件系统------按需获取信息，而非预加载。模型像做开卷考试一样，需要时翻书，而不是把整本书背下来。

上下文压缩（Compaction）：与 Claude Code 类似，支持手动和自动压缩（500K Token 压缩阈值）。状态栏实时显示 Token 消耗和成本追踪。

Side-Git 快照 ：每轮对话前后通过 side-git 做快照，但不影响项目的 .git。如果 AI 改坏了代码，用 /restore 一键回滚。

设计哲学：用超大上下文窗口 + 前缀缓存替代独立记忆层。记忆不在外部存储里，而在 Agent 的"视野"里------它随时可以"看到"文件系统中的任何内容。

2.4 三者对比：设计哲学的差异

维度	Claude Code	Codex CLI	CodeWhale
记忆哲学	模拟人类认知流程	异步管道 → 机构知识	超大上下文 + 开卷考试
跨会话记忆	Auto Memory（200 行索引）	Memories（5K Token 摘要）	无专门记忆提取层（依赖上下文窗口 + 会话持久化）
记忆检索	关键词匹配 + 文件读取	grep MEMORY.md	RLM 递归查询文件系统
记忆整理	Auto Dream（24h + 5 会话）	Phase 2 合并（6h 空闲）	无（上下文内即时可见）
上下文管理	自动 Compaction（1M 窗口）	自动 Compaction（272K 默认，可扩至 1M）	自动 Compaction（1M 窗口）
回滚机制	无内置	Thread 级别（SQLite）	Side-Git 快照
向量检索	无	无	无
核心权衡	记忆量受 200 行索引限制	纯文本匹配，无语义检索	依赖模型上下文窗口大小

核心洞察：三个最成功的编码 Agent 都没有使用向量检索或知识图谱 。它们选择了更简单但更可控的方案------Markdown 文件 + 关键词匹配 + 上下文压缩。这说明在编码场景下，记忆的可靠性和可控性比检索精度更重要。

但编码场景只是众多 Agent 场景之一。当场景切换到客服、研究、RAG 时，记忆的需求维度完全不同------选错架构的代价是什么？

三、不同场景该选哪种记忆架构？

3.1 智能客服：百万用户，KB 级记忆

场景特征：

用户量大（百万级），每个用户记忆量小（几 KB）
需要跨渠道（电话、聊天、邮件）记住用户偏好和历史
延迟要求高（< 100ms），成本敏感
合规要求严格（GDPR、数据留存策略）

推荐架构：Mem0 / Zep + 滑动窗口

记忆类型	实现方式	目的
工作记忆	滑动窗口（最近 3-5 轮）	低延迟响应
情景记忆	Mem0 向量 + 图双引擎	跨会话记住"上次讨论了什么"
语义记忆	Mem0 实体级知识图谱	"用户偏好深色主题"、"用户是 VIP"
程序性记忆	预定义规则库	"退款流程先查订单再查支付"

我们来解读这张表：工作记忆 用滑动窗口保证低延迟------客服场景下用户等不了 500ms 以上的响应；情景记忆 用 Mem0 的向量+图双引擎解决"上次聊了什么"的跨会话问题；语义记忆 用实体级知识图谱存储结构化的用户属性（偏好、等级、历史投诉），这些属性需要精确匹配而非模糊检索；程序性记忆是硬编码的业务规则，不需要 LLM 推理。

选错架构的后果：如果客服场景用了纯 RAG（向量检索文档库），会发生什么？

❌ 纯 RAG：每次对话从文档库检索相关段落，但无法记住"这个用户上次投诉过物流问题"------用户换了客服就要重新说一遍
✅ Mem0 + 滑动窗口：用户偏好和历史自动提取并持久化，任何客服 Agent 都能看到完整的用户画像

关键设计决策：

集中式记忆：所有客服 Agent 共享同一份用户记忆，避免"换个客服就要重新说一遍"
主动提取：LLM 从对话中自动提取用户偏好、投诉历史、解决方案，而非被动存储原始对话
自动过期：GDPR 要求的"被遗忘权"------用户请求删除后，记忆系统必须能精确清除该用户的所有记忆
Token 效率：Mem0 新算法用 ~7K Token/查询达到 92.5 LoCoMo 分数，全上下文方案需要 25K+ Token

生产案例：根据第三方实践报告，一个客服平台从无状态 Agent 迁移到基于 AWS AgentCore 的记忆增强 Agent 后，客服解决时间从 8.3 分钟降至 3.1 分钟，首次解决率从 68% 升至 91%。

3.2 研究报告与分析：少用户，MB 级记忆

场景特征：

用户量小，单次任务记忆量极大（数十篇论文、数百页报告）
需要跨数十轮对话保持推理链的一致性
时序推理关键------"上个月的数据显示 X，但最新数据显示 Y"
对延迟容忍度高，对准确性要求极高

推荐架构：Graphiti/Zep 时序知识图谱 + 摘要压缩

记忆类型	实现方式	目的
工作记忆	当前分析上下文（最近 5-10 轮）	保持推理链连贯
情景记忆	时序知识图谱	"3 月讨论了 A 假设，5 月用新数据验证了 B 假设"
语义记忆	知识图谱三元组	"X 技术的成熟度是 TRL 7"、"Y 公司的市场份额是 23%"
程序性记忆	分析流程模板	"行业分析先看市场规模，再看竞争格局，最后看技术趋势"

解读：工作记忆 保留最近 5-10 轮的推理链，确保分析不跑偏；情景记忆 用时序知识图谱而非普通向量库，因为研究场景的核心需求是"3 月的假设和 6 月的验证之间的关系"------普通向量库只能按语义相似度检索，无法表达时序因果；语义记忆 用知识图谱三元组存储结构化事实，支持多跳推理；程序性记忆是分析模板，确保研究流程的完整性。

选错架构的后果：

❌ 纯向量检索：能找到"3 月讨论过 A 假设"和"6 月验证了 B 假设"的片段，但无法建立"A 和 B 之间的推理链"------研究 Agent 会丢失推理连贯性
✅ 时序知识图谱 + 摘要压缩：保留事实之间的时序和因果关系，同时用摘要压缩控制上下文长度

关键设计决策：

时序知识图谱是核心------"用户从北京搬到了上海"不是简单覆盖，而是保留两个事实 + 一个迁移关系。研究场景中，"3 月数据显示增长 5%，6 月数据显示下降 2%"同样需要保留时序信息
摘要压缩定期提炼冗长对话------30 轮对话后，前 20 轮的详细推理过程可以压缩为结论性摘要
Agent 推理检索优于向量检索------研究问题通常需要多跳推理（"A 影响 B，B 影响 C，所以 A 间接影响 C"），向量检索只能找到语义相似的片段，无法做关系推理

3.3 编码 Agent：项目约定，跨会话持续

场景特征：

记忆内容以项目约定、编码风格、架构决策为主
记忆的消费者是模型自身，不需要复杂的检索管线
跨会话一致性比检索精度更重要
记忆量中等（几 KB 到几十 KB）

推荐架构：CLAUDE.md / AGENTS.md + Auto Memory / Memories

记忆类型	实现方式	目的
工作记忆	上下文窗口（1M Token）	当前编辑会话
情景记忆	Auto Memory / Memories	"上次重构时决定用 Zod 而不是 Yup"
语义记忆	CLAUDE.md / AGENTS.md	"项目使用 TypeScript strict mode"、"测试命令是 `pnpm test`"
程序性记忆	CLAUDE.md 规则 + Auto Memory 反馈	"部署前先跑测试"、"不要用 unwrap()"

解读：编码场景的记忆分配最简单------工作记忆 直接用上下文窗口（1M Token 足够覆盖大多数编辑会话）；情景记忆 和语义记忆 都用 Markdown 文件，因为编码场景的记忆是结构化的（命令、路径、规则），不需要语义模糊匹配；程序性记忆来自手写规则和自动反馈的叠加。

选错架构的后果：

❌ 向量检索 ：为编码 Agent 配一套向量数据库来检索项目约定------看起来更"先进"，但编码场景的记忆是精确的（"测试命令是 pnpm test"），向量检索反而可能返回语义相似但不精确的结果（"测试相关的配置"），引入不确定性
✅ Markdown 文件 + 关键词匹配：精确、可控、可审计------三个最成功的编码 Agent 都做了这个选择

关键设计决策：

Markdown 文件 + 关键词匹配就够了------三个最成功的编码 Agent 都没用向量检索。编码场景的记忆是结构化的（命令、路径、规则），不需要语义模糊匹配
分层加载------CLAUDE.md / AGENTS.md 每次会话自动加载，Auto Memory / Memories 按需检索
定期整理------Claude Code 的 Auto Dream、Codex 的 Phase 2 合并，都解决了记忆碎片化和矛盾问题
Token 预算控制------Claude Code 的 200 行索引、Codex 的 5K Token 摘要上限，都是硬约束，防止记忆膨胀挤占上下文空间

但编码 Agent 的记忆是"记住约定"，而 RAG 系统的记忆是"找到答案"------这是两种完全不同的认知模式。

3.4 RAG 系统：静态知识，精确检索

场景特征：

知识库以文档为主，更新频率低
查询模式以"找答案"为主，不需要跨会话推理
检索精度和召回率是核心指标
不需要记忆"演化"------知识是静态的

推荐架构：向量检索 + 知识图谱（混合 RAG）

记忆类型	实现方式	目的
工作记忆	当前查询 + 检索结果	回答用户问题
语义记忆	向量数据库 + 知识图谱	从文档库中检索相关段落
程序性记忆	查询改写规则	"当用户问 X 时，实际检索 Y"

解读：RAG 系统的记忆分配最轻------工作记忆 只需要当前查询和检索结果；语义记忆 是核心，用向量数据库做语义检索、知识图谱做结构化查询；程序性记忆是查询改写规则，弥补用户表述和文档表述之间的语义鸿沟。注意 RAG 不需要情景记忆------因为不需要"记住上次聊了什么"。

关键判断：如果你的系统需要"记住用户说了什么"，用 Agent 记忆；如果只需要"从文档中找答案"，用 RAG。 很多生产系统是混合架构------Agent 记忆负责动态认知，RAG 负责静态知识检索。

当系统从单 Agent 扩展到多 Agent 协作时，记忆的共享和隔离又成了一个新问题。

3.5 Multi-Agent 协作：共享记忆 vs 分布式记忆

场景特征：

多个 Agent 需要共享部分信息，但各有专长
一致性 vs 可用性的权衡
Agent 间通信可能成为瓶颈

推荐架构：集中式记忆池 + Agent 专有记忆

记忆类型	实现方式	目的
共享语义记忆	集中式知识图谱	所有 Agent 可见的公共知识
Agent 专有记忆	各 Agent 独立的 Auto Memory	每个 Agent 的专业领域知识
协作情景记忆	共享执行轨迹	"Agent A 完成了数据库迁移，Agent B 可以开始 API 适配"

解读：Multi-Agent 记忆的核心矛盾是共享 vs 隔离 。共享语义记忆 让所有 Agent 看到公共知识（项目结构、API 文档），避免重复查询；Agent 专有记忆 让每个 Agent 保留自己的专业领域知识（数据库 Agent 知道 schema 细节，前端 Agent 知道组件结构），避免信息过载；协作情景记忆是最关键的------Agent 之间需要知道"谁做了什么"，否则会重复工作或互相覆盖。

关键设计决策：

共享完整的 Agent 执行轨迹，而不仅仅是 Agent 间的消息------MAST 研究表明，协作失调是 Multi-Agent 失败的主要来源之一，而共享轨迹比共享消息更能减少误解
将 Agent 间消息视为不可信输入------OWASP LLM Top 10 指出 Agent 通信通道注入是常见攻击面，需要对跨 Agent 消息做输入校验
设置 Token 预算和熔断器------Multi-Agent 系统的 Token 消耗显著高于单 Agent（多个 Agent 并发调用），需要预算控制防止成本失控

四、选型决策树：5 个关键问题

在选型之前，先回答这 5 个问题：

Q1：记忆是静态的还是动态演化的？

静态（文档库、知识库）→ RAG
动态（用户偏好、项目约定、交互历史）→ Agent 记忆

Q2：需要跨会话持久化吗？

不需要（单次任务完成即可）→ 上下文窗口 + Compaction
需要（用户会回来继续）→ Auto Memory / Mem0 / 知识图谱

Q3：记忆量级有多大？

KB 级（用户偏好、项目约定）→ Markdown 文件 + 关键词匹配（Claude Code / Codex 模式）
MB 级（研究资料、长对话历史）→ 向量 + 图双引擎（Mem0 / Graphiti 模式）
GB 级（企业知识库）→ RAG + 知识图谱混合

Q4：需要时序推理吗？

需要（"从 A 变成了 B"、"3 月的数据 vs 6 月的数据"）→ 时序知识图谱（Graphiti / Zep）
不需要（"X 是什么"）→ 向量检索 或 Markdown 文件

Q5：延迟和成本的容忍度？

低延迟、低成本 → 滑动窗口 + 摘要压缩（Mem0 新算法 ~7K Token/查询）
可接受较高延迟 → Agent 推理检索（GAM 的深度研究模式）
成本极度敏感 → 文件系统 + grep（Letta/MemGPT 在 LongMemEval 上达到 83.2% R@5，纯文件方案也能达到可观效果）

五、一个常被忽视的选项：AgentMemory（MCP 跨 Agent 共享记忆）

前面讨论的方案都是"一个 Agent 一套记忆"。但实际工作中，开发者经常同时使用 Claude Code、Cursor、Codex CLI 等多个编码工具------它们之间的记忆是割裂的。在 Claude Code 中学到的项目约定，Cursor 完全不知道。

AgentMemory（GitHub 9,361 星，2026 年 5 月 trending #1）试图解决这个问题：一个本地记忆服务器，通过 MCP 协议被所有编码 Agent 共享。

核心特性：

95.2% R@5（LongMemEval-S），高于 Mem0（68.5%）和 Letta/MemGPT（83.2%）
~170K Token/年，对比全上下文方案的 ~19.5M Token/年
BM25 + 向量 + 知识图谱三路融合检索（Reciprocal Rank Fusion）
51 个 MCP 工具 ：memory_smart_search、memory_save、memory_sessions 等
12 个自动捕获钩子（Claude Code）、6 个（Codex CLI）
零外部依赖 ：本地 SQLite + iii-engine，不需要 Qdrant 或 Postgres

适用场景：同时使用多个编码 Agent 的开发者，希望跨工具共享项目上下文。

六、总结

没有"最好的记忆架构"，只有"最匹配场景的架构"。三大编码 Agent 的记忆设计截然不同，却都在各自场景下工作良好------Claude Code 模拟人类认知流程，Codex CLI 用异步管道生成机构知识，CodeWhale 用超大上下文做开卷考试。
编码 Agent 的共同选择：不用向量检索。三个最成功的编码 Agent 都选择了 Markdown 文件 + 关键词匹配 + 上下文压缩。在编码场景下，记忆的可靠性和可控性比检索精度更重要。
Agent 记忆 vs RAG 不是替代关系，而是互补关系。Agent 记忆负责动态认知（"记住用户说了什么"），RAG 负责静态知识检索（"从文档中找答案"）。生产系统通常是混合架构。
选型的 5 个关键问题：静态 vs 动态？跨会话？记忆量级？时序推理？延迟/成本容忍度？回答完这 5 个问题，架构选择基本就明确了。
跨 Agent 共享记忆是下一个前沿。AgentMemory 通过 MCP 协议让多个编码 Agent 共享同一份记忆，解决了当前最大的痛点------工具间的记忆割裂。

Agent 记忆架构选型实战：从场景到方案