Agent 为什么一定需要 Memory？------ 从业界主流设计到 Claude Code 实现原理深度解析
Claude Code / LangGraph / Hybrid Memory / 2026 年最新方案 ------ 一次讲透。
掘金发布说明：本文中 3 张架构图已导出为 PNG 图片。请把图片上传到掘金图床，然后将 Markdown 中的图片路径替换为掘金 CDN 地址。
一、为什么 Agent 一定需要 Memory？
先从两个真实场景说起
我用 Claude Code 调一个并发 Bug，调了两天，解释了三四次项目架构、告诉它「用 pnpm 不用 npm」。第二天早上打开终端，Claude 跟失忆一样问：「这个项目的入口文件是什么？」那一瞬间血压上来了。
团队里用 Cursor 的同事也差不多------明明 .cursorrules 写了「Controller 不写业务逻辑」，每次开新对话它又在 Controller 里塞业务代码，你还得再纠正一次。
问题出在哪？Agent 没有 Memory。
没 Memory 的 Agent 长什么样？
- 重复提问：「项目入口文件是什么？」------问了三遍。
- 重复规划：每次重走一遍项目分析流程，Token 全花在重复工作上。
- 重复调 Tool：同一个文件反复读、同一个 API 反复查。
- 上下文丢失：聊到 30 轮，前 10 轮的关键决策全忘。这不是模型笨，是 Context Window 管理的必然。
- 跨 Session 任务无法完成：修一个三天的 Bug？第二天从零开始。
Reddit 上有个获 200+ 赞的评论说得很直接：
每开一个新 Session 就要把同样的架构决策再解释一遍。如果你的 AI 过了 30 条消息就忘了核心模式，那它不是智能------是个贵的记事本。
Memory 是基础设施，不是加分项
Memory 解决的不是「让 Agent 更聪明」，而是「让 Agent 能持续工作」。一个靠谱的 Agent 的 Memory 必须回答三个问题：
- 我是谁？ ------ 身份、能力边界、工作规则
- 我在做什么？ ------ 进度、状态、中间结果
- 我学到了什么？ ------ 比如我的 Claude Code 项目里设了「用 pnpm 不用 npm」「前端测试用 Vitest」「Controller 不写业务逻辑」------但第二天开新 Session 全忘了，又得从头纠正。
三个问题中任何一个答不上来，Agent 就干不了真正的生产任务。
二、Memory 到底是什么？
三个常见误解
误解 1：Memory = Context Window
Context Window 是「工作台」，内容是临时的。Memory 是「笔记本」，跨会话持久化。便签纸 vs 知识库。
误解 2：Memory = Prompt
固定 Prompt 不是 Memory。真 Memory 是动态的------会随着工作过程不断更新。有些教程拿 RAG 当 Memory，但那只是实现手段，不是完整方案。
Memory 的六个核心动作
| 动作 | 说明 |
|---|---|
| 写入 | 新信息持久化存储 |
| 检索 | 根据上下文召回相关信息 |
| 更新 | 修正或补充已有记忆 |
| 遗忘 | 删除过期或错误的记忆（很多时候比写入更重要------缓存满了不清理，检索精度就降） |
| 合并 | 零散信息 → 结构化知识 |
| 排序 | 决定哪些记忆更重要 |
把这六个动作记住就够了，后面你看任何 Agent Memory 方案都能对上号。
三、Agent Memory 的五种类型
1. Short-term Memory（短期/工作记忆）
当前会话内的对话历史、工具调用记录、中间结果。ChatGPT 翻页到第 40 轮忘记第 10 轮内容------这就是短期记忆窗口不够。
| 系统 | 实现 |
|---|---|
| LangGraph | Checkpoint ------ 每个 SuperStep 自动保存图状态 |
| OpenAI SDK | Session ------ 自动维护 input/output 列表 |
| OpenHands | ConversationMemory + Condenser 压缩 |
| Mastra | lastMessages ------ 保留最近 N 条 |
什么时候失效？ 上下文窗口满（通常是 128K-200K tokens，有效注意力在 64K 之后显著衰减）、会话结束、长对话早期信息被挤出。
2. Long-term Memory（长期记忆）
跨会话持久化的用户信息、项目知识、历史经验。不用每次开头解释你项目叫啥、用啥框架------Claude Code 有 CLAUDE.md 才算真正持久的。
3. Semantic Memory（语义记忆）
通过 Embedding 将知识转为高维向量，用向量数据库做语义检索。一度以为向量搜索很牛，后来发现你要找「docker 配置」这种精确规则，grep 比你等 30 个向量结果更快。
什么时候比文件好？ 数据量成千上万、需要模糊语义匹配。
什么时候不如文件？ 数据量小（几十条规则）、需要精确匹配、需要人类审查（向量不可 cat）、需要版本控制（无法 git diff）。
4. Episodic Memory（情景记忆）
记录「经历过什么」而不只是「知道什么」。做 Research Agent 的都知道------查了 15 个文档，已经跑了 8 个 API，不写下来的话三天后回来又问一遍。OpenHands 的 Condenser 把事件流压缩为结构化的情景摘要，包含代码状态、测试结果、变更记录、版本控制状态。
5. Procedural Memory（程序性记忆）
行为规则和工作流程。Claude Code 的 .claude/rules/ 就是答案------不用向量、不用 JSON，按主题拆分的 Markdown 文件，通过 paths frontmatter 按需加载，比什么都实在。语义记忆回答「是什么」，情景记忆回答「发生了什么」，程序性记忆回答「怎么做」。
干了两年 Agent 项目后我真想说------没有哪种 Memory 能解决所有问题，这也是 Hybrid Memory 成为主流的原因。
四、业界主流 Memory 方案对比
LangChain → LangGraph Store
LangChain 最早期的 Memory 就是在 Prompt 里拼对话历史，进程结束就没了。2025 年后引入了基于 LangGraph Store 的长期记忆------层级化键值存储 + 语义搜索，支持 PostgresStore（pgvector）和 Redis 后端。走的是「渐进增强」路线------就像从手动档到自动档升级，老车型能开但修起来麻烦，兼容但有包袱。
LangGraph：Checkpoint + Store 双层体系
Checkpoint 管图状态快照和时间旅行调试；Store 管跨会话 JSON 文档存储和语义搜索。两层分离，职责清晰。
OpenAI Agents SDK：Session + 自动压缩
自动在每次运行前后获取存储对话历史。号称支持 10 种存储后端（SQLite 到 MongoDB），但选型越多越难决策------大部分时候你只需要 PostgreSQL 和 SQLite 二选一。OpenAIResponsesCompactionSession 提供自动压缩。强调开箱即用，灵活性受限。
CrewAI：统一 Memory API
2025 年重构为单一 Memory 类，LLM 自动推断 scope 和重要性。复合评分 = 语义相似度 × 0.5 + 时间衰减 × 0.3 + 重要性 × 0.2。层次化作用域（类似文件系统树）天然适合 Multi-Agent。
OpenHands：Condenser + ConversationMemory
核心问题：CodeAct Agent 的事件流太长怎么办？Condenser 通过 LLM 摘要压缩历史，把事件流转为结构化的五个维度（用户上下文、任务追踪、已完成、待处理、当前状态），在有限 Context Window 内最大化信息密度。
Letta（前 MemGPT）：三层次 Memory OS
Letta 让 Agent 自己管理记忆，类似操作系统管理虚拟内存。Core Memory（~2K tokens，即时）、Recall Memory（向量搜索，中等快）、Archival Memory（索引查询，慢但无限）。2026 年推出 Context Repositories，对记忆做 Git 式版本控制。
Mem0：Memory-as-a-Service
极简 API（add() + search()），把记忆作为独立微服务。高级版提供 Graph Memory（知识图谱），自动构建实体关系。LoCoMo 基准测试中，单跳事实回忆 82.3%、延迟 P95 120ms。适合已有 Agent 想快速加记忆的场景。
Mem0 vs Letta 实战数据（LoCoMo Benchmark 2026）
| 指标 | MEM0 | LETTA |
|---|---|---|
| 单跳事实回忆 | 82.3% | 79.1% |
| 多跳推理 | 71.5% | 76.8% |
| 时序理解 | 68.2% | 74.5% |
| 记忆更新一致性 | 85.1% | 80.3% |
| 延迟 P95 | 120ms | 340ms |
Mem0 赢在速度和简单召回，Letta 赢在复杂推理和时序理解。
我在实际用的时候最大的感觉不是延迟差异------是 Mem0 太简单，复杂时序推演做不了；Letta 太复杂，简单召回还用不上。选的时候想清楚你是做聊天还是做研究。
腾讯云 Agent Memory（2026 新方案）
2026 年 4 月发布的四层渐进式记忆架构：L0 原始对话全量保存 → L1 原子记忆自动提取 → L2 场景分块聚类 → L3 用户画像。印象中腾讯云的评测结果显示提升幅度很高，但公开文档目前还很少，这里不作具体断言。
框架对比速览
| 框架 | 短期记忆 | 长期记忆 | 语义搜索 | 文件式 | 自动压缩 | 最佳场景 |
|---|---|---|---|---|---|---|
| LangGraph | Checkpoint | Store + pgvector | ✅ | ❌ | ❌ | 有状态工作流 |
| Claude Code | Context Window | CLAUDE.md + MEMORY.md | ❌ | ✅ | ❌ | Coding Agent |
| OpenAI SDK | Session | Session + Compaction | ❌ | ❌ | ✅ | 聊天应用 |
| CrewAI | 统一 Memory | 统一 Memory + 向量 | ✅ | ❌ | ✅ 合并 | Multi-Agent |
| OpenHands | ConversationMemory | Condenser 摘要 | ❌ | ❌ | ✅ LLM | CodeAct Agent |
| Letta | Core Memory | Recall + Archival | ✅ | ❌ | ❌ | 长期个性化 Agent |
| Mem0 | add/search API | Graph Memory | ✅ | ❌ | ❌ | 快速接入记忆 |
| LlamaIndex | ChatMemoryBuffer | Memory 类 | ✅ | ❌ | ❌ | RAG Agent |
这八个方案里：想用最简单的选 Mem0；想搞深度 Agent 选 LangGraph Store；做开发工具类的直接抄 Claude Code 的 Markdown 思路。
五、重点解析：Claude Code Memory 设计
这个章节我会写得很细，因为 Claude Code 是目前 Coding Agent 里 Memory 做得最好的参考案例------而且用的是文档而不是向量，思路完全不一样。
5.1 为什么不用向量数据库？
Claude Code 是 Coding Agent，用户是开发者。Memory 需要：可审计（队友能看懂 AI 决策）、可版本控制（进 Git）、可协作（共享给团队）。向量数据库的强大是不可见的------你写完代码让别人来 review，他能看 Markdown 但看不懂向量------就是这么简单的道理。
5.2 六层记忆架构
越具体的层级优先级越高。公司设基线，团队补约定，个人加偏好------互不冲突。
5.3 CLAUDE.md vs MEMORY.md：宪法 vs 笔记
| 维度 | CLAUDE.MD | MEMORY.MD |
|---|---|---|
| 谁写 | 人 | Claude 自动 |
| 内容 | 指令、规则、约定 | 学到的经验、模式 |
| 加载 | 全量 | 前 200 行或 25KB |
Claude Code 负责人 Thariq 的定义很精准：「CLAUDE.md 是你对 Claude 的指令，MEMORY.md 是 Claude 自己的记忆草稿本。」
实际工作中 MEMORY.md 经常拉胯------Claude 会往里面塞一些「我调通了某个包版本」这种废话。有个社区脚本专门用来清理 MEMORY.md 里的杂质。
5.4 加载策略：向上急加载，向下惰性加载
在 monorepo 中，frontend/CLAUDE.md 只在处理前端代码时加载，backend/CLAUDE.md 只在处理后端代码时加载。不浪费 Context Window。
5.5 .claude/rules/：路径匹配的模块化规则
lua
---
paths:
- "src/api/**/*.ts"
---
# API 开发规范
- 所有端点包含输入验证
- 标准错误响应格式Claude 在改 src/api/users.ts 时这条规则自动注入，在改前端样式时不占上下文。本质是「按需加载的规则系统」。
5.6 新功能：@import 语法
CLAUDE.md 支持 @path/to/file 引用其他文件：
java
See @README for project overview
git workflow @docs/git-instructions.md把 CLAUDE.md 变成轻量索引，不用复制粘贴已有文档。支持递归（最多 5 层），代码块中的 @ 不会被误解析。
5.7 Auto Memory：复利效应与记忆污染
Auto Memory 是社区讨论最激烈的功能。
正面：复利效应
有用户反馈，跨 Session 持久化后，体感 token 消耗减少 20-50%。更有意思的是，把 CLAUDE.md 从 427 行精简到 96 行后，token 消耗降了 78%，回答质量反而上升------噪音少了，信号就清晰了。
负面：记忆污染
当 Claude 走错方向时，也会把错误假设写进 MEMORY.md。未来的 Session 从错误前提开始。有开发者专门发布了记忆清理脚本，号称能去掉 70% 的无用记忆。
我个人觉得 Auto Memory 的污染问题是这个产品最大的软肋------信息量增多但精度降低，反而让 Claude 更蠢。
工具锁定
记忆在 ~/.claude/ 下，切换到 Codex 或 Gemini CLI 就丢失了。社区呼声：「记忆应该属于用户，不是属于工具。」
5.8 60% 规则：上下文窗口管理
2026 年社区实践总结出的最佳阈值：
| 阈值 | 行动 |
|---|---|
| 50% | 准备保存关键决策摘要 |
| 60% | 立即执行 /compact |
| 65%+ | 质量开始退化，不应等待 |
Transformer 在所有 token 上分配注意力，窗口越满，早期 token（包含需求约束）获得的注意力就越低。在 60% 时压缩能保留关键早期上下文，在 95% 时压缩等于压缩已经退化的内容。实际用的时候我是用快捷键 /compact，不是按百分比算------大概感觉到 Claude 开始重复写文件或忘记项目结构时就按。
掌握上下文管理的开发者每天合并的 PR 数量比普通用户高出 67%。
5.9 上下文成本：每一行都烧钱
ini
假设 CLAUDE.md 2000 tokens，每会话 50 轮：
消耗 = 2000 × 50 = 100,000 tokens
每天 5 个会话 = 500,000 tokens/天结构化上下文（编号列表、标注的决策）比非结构化解释段落压缩效率高得多。
推荐写法：
sql
CONSTRAINT: payments 模块使用同步回调------异步重构被遗留供应商 SDK 阻止5.10 局限
- 全量加载的成本------每轮对话都重新消耗
- 规模上限------适合数百条规则，不适合百万级
- 缺少语义搜索------grep 做不了语义关联
- 工具锁定------
~/.claude/下的记忆不跨工具 - 记忆污染------Auto Memory 无质量保证
Claude Code 的这个选择本质是取舍------不是 Markdown 技术不够好，是可以版本控制的需求太重，向量满足不了。如果哪天 MCP 标准和 Git 都能管向量了，那优先顺序可能反过来。
六、为什么要 Hybrid Memory？
单一方案的天花板
见过太多 Demo 试过只向量的，结果发现 deploy 配置这种精确信息找不到。也见过只 Markdown 的，项目文档一多就 grep 不过来了。总结下来就是------
| 方案 | 擅长 | 不擅长 |
|---|---|---|
| 纯 Markdown | 可读、版本控制、规则 | 海量语义搜索 |
| 纯向量库 | 语义搜索、海量数据 | 精确匹配、人类审查 |
| 纯 SQL | 结构化查询、时间过滤 | 语义理解 |
| 纯 Checkpoint | 状态恢复 | 跨会话知识 |
| 纯 LLM 摘要 | 压缩去噪 | 精确性和完整性 |
没有任何一种能全包。Agent 有时要精确匹配（「CLAUDE.md 第 3 行」），有时要语义搜索（「数据库选型讨论」），有时要时间范围查询（「上周的对话」）------ 不同查询需要不同存储。
四层融合架构
objectivec
第一层: 文件层
├── 项目规则（CLAUDE.md, .cursorrules）
└── 工作流程（Skills）
第二层: 向量层
├── 用户历史交互（嵌入 + 语义搜索）
└── 存储: Qdrant / pgvector / FAISS
第三层: SQL 层
├── 时间戳索引、元数据过滤
└── 存储: PostgreSQL / SQLite
第四层: 知识图谱层
├── 实体关系、依赖链路
└── 存储: Neo4j / Kuzu实际应用中不需要四层全上------小项目文件 + 向量就够了，大型 Multi-Agent 系统才需要知识图谱层。
Mem0 的向量 + Graph Memory 双引擎是目前最成熟的实践；腾讯云 Agent Memory 的四层渐进方案（对话 → 原子 → 场景 → 画像）则代表了记忆分层沉淀的工程方向。
七、不同 Agent 怎么选 Memory？
| AGENT 类型 | 推荐组合 | 原因 |
|---|---|---|
| 聊天 Agent | Session + 语义记忆 + LLM 摘要 | 对话自动管理 + 跨会话知识召回 + 长对话压缩 |
| Coding Agent | Markdown 文件 + Checkpoint + 有限语义 | 规则需审计和 Git；Checkpoint 保长任务可恢复 |
| Research Agent | 情景 + 语义 + 文件 | 需记录「发现/排除」过程；语义做跨文档关联 |
| Workflow Agent | Checkpoint + 程序性记忆 + SQL | 状态图 + 断点恢复；结构化查询追踪进度 |
| Multi-Agent | 统一 API + 作用域隔离 | CrewAI scope 式隔离 + 共享 scope 交换知识 |
就记住一个原则------如果你的 Agent 是给开发者用的，优先 Markdown + Git；如果是给一般用户的，优先向量 + 自动压缩。
写代码的要选 Markdown，做研究的要选向量，做审批流的要选 Checkpoint。混合使用是常态。
八、未来趋势
1. 记忆压缩 ------ 从 LLM 摘要到结构化压缩
Claude Code 的 /compact 和 SimpleMem 的语义无损压缩（压缩到原对话的 20-30%）正走向精细化。
2. 记忆排序 ------ 超越余弦相似度
ini
score = α × similarity + β × recency + γ × importance + δ × context_relevanceCrewAI 的复合评分引擎已落地，不同场景调不同权重。
3. 记忆遗忘 ------ 不清理的 Memory 会污染检索
指数衰减模型（情感记忆快速衰减、事实记忆慢速衰减）+ 定时过期（偏好 365 天、情景 90 天）。
4. 知识图谱 ------ 让 Agent 理解「关系」而非只是「相似」
向量找「相似」，图找「关系」。Mem0 Pro 的 Graph Memory 和 Kuzu 嵌入式图数据库让图存储部署变得轻量。
5. 自进化记忆
从零散事实归纳规则、从失败总结模式、从行为推断偏好变化。Letta 的三层自主记忆管理是这个方向的先行者。
6. MCP 生态的标准化
MCP Memory Server 让记忆跨工具共享------同一套记忆可以被 Claude Code、Cursor、Gemini CLI 共用。记忆不再绑定到特定工具。
7. Agent 竞争的本质是 Memory 竞争
AI Agent 的火药味越来越浓，但我现在的感受------不是谁模型更强，是谁能在你的项目上记住得更多、更准、更快。有时候一个简单的 SUMMARY 比一个复杂的向量更好用。
模型本身就像一台法拉利，但你的 Agent 要在实际项目上跑，燃料和水箱（Memory）才是决定跑多远的东西。不是漂亮的 demo，是你明天开新 Session 还能接着干活。