你的 Agent 为什么总失忆？—— Memory 设计从入门到 Claude Code并不只看表面做法，关键还要理解相关条件、限制和后续影响。

Agent 为什么一定需要 Memory？—— 从业界主流设计到 Claude Code 实现原理深度解析

一、为什么 Agent 一定需要 Memory？

先从两个真实场景说起

我用 Claude Code 调一个并发 Bug，调了两天，解释了三四次项目架构、告诉它「用 pnpm 不用 npm」。第二天早上打开终端，Claude 跟失忆一样问：「这个项目的入口文件是什么？」那一瞬间血压上来了。

团队里用 Cursor 的同事也差不多——明明 .cursorrules 写了「Controller 不写业务逻辑」，每次开新对话它又在 Controller 里塞业务代码，你还得再纠正一次。

问题出在哪？Agent 没有 Memory。

没 Memory 的 Agent 长什么样？

1. 重复提问：「项目入口文件是什么？」——问了三遍。
2. 重复规划：每次重走一遍项目分析流程，Token 全花在重复工作上。
3. 重复调 Tool：同一个文件反复读、同一个 API 反复查。
4. 上下文丢失：聊到 30 轮，前 10 轮的关键决策全忘。这不是模型笨，是 Context Window 管理的必然。
5. 跨 Session 任务无法完成：修一个三天的 Bug？第二天从零开始。

Reddit 上有个获 200+ 赞的评论说得很直接：

Memory 是基础设施，不是加分项

Memory 解决的不是「让 Agent 更聪明」，而是「让 Agent 能持续工作」。一个靠谱的 Agent 的 Memory 必须回答三个问题：

0. 我是谁？ —— 身份、能力边界、工作规则
1. 我在做什么？ —— 进度、状态、中间结果
2. 我学到了什么？ —— 比如我的 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 轮内容——这就是短期记忆窗口不够。

什么时候失效？ 上下文窗口满（通常是 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 按需加载，比什么都实在。语义记忆回答「是什么」，情景记忆回答「发生了什么」，程序性记忆回答「怎么做」。

四、业界主流 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 赢在复杂推理和时序理解。

我在实际用的时候最大的感觉不是延迟差异——是 Mem0 太简单，复杂时序推演做不了；Letta 太复杂，简单召回还用不上。选的时候想清楚你是做聊天还是做研究。

腾讯云 Agent Memory（2026 新方案）

2026 年 4 月发布的四层渐进式记忆架构：L0 原始对话全量保存 → L1 原子记忆自动提取 → L2 场景分块聚类 → L3 用户画像。印象中腾讯云的评测结果显示提升幅度很高，但公开文档目前还很少，这里不作具体断言。

框架对比速览

这八个方案里：想用最简单的选 Mem0；想搞深度 Agent 选 LangGraph Store；做开发工具类的直接抄 Claude Code 的 Markdown 思路。

五、重点解析：Claude Code Memory 设计

5.1 为什么不用向量数据库？

Claude Code 是 Coding Agent，用户是开发者。Memory 需要：可审计（队友能看懂 AI 决策）、可版本控制（进 Git）、可协作（共享给团队）。向量数据库的强大是不可见的——你写完代码让别人来 review，他能看 Markdown 但看不懂向量——就是这么简单的道理。

5.2 六层记忆架构

越具体的层级优先级越高。公司设基线，团队补约定，个人加偏好——互不冲突。

5.3 CLAUDE.md vs MEMORY.md：宪法 vs 笔记

Claude Code 负责人 Thariq 的定义很精准：「CLAUDE.md 是你对 Claude 的指令，MEMORY.md 是 Claude 自己的记忆草稿本。」

实际工作中 MEMORY.md 经常拉胯——Claude 会往里面塞一些「我调通了某个包版本」这种废话。有个社区脚本专门用来清理 MEMORY.md 里的杂质。

5.4 加载策略：向上急加载，向下惰性加载

1. 从工作目录向上遍历到根目录上的所有 CLAUDE.md → 启动时全部加载
2. 子目录里的 CLAUDE.md → 只有读取该目录文件时才按需注入
3. MEMORY.md → 只自动加载前 200 行

在 monorepo 中，frontend/CLAUDE.md 只在处理前端代码时加载，backend/CLAUDE.md 只在处理后端代码时加载。不浪费 Context Window。

5.5 .claude/rules/：路径匹配的模块化规则

---paths: - "src/api//*.ts"---# API 开发规范- 所有端点包含输入验证- 标准错误响应格式

Claude 在改 src/api/users.ts 时这条规则自动注入，在改前端样式时不占上下文。本质是「按需加载的规则系统」。

5.6 新功能：@import 语法

CLAUDE.md 支持 @path/to/file 引用其他文件：

See @READMEfor project overviewgit 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 年社区实践总结出的最佳阈值：

Transformer 在所有 token 上分配注意力，窗口越满，早期 token（包含需求约束）获得的注意力就越低。在 60% 时压缩能保留关键早期上下文，在 95% 时压缩等于压缩已经退化的内容。实际用的时候我是用快捷键 /compact，不是按百分比算——大概感觉到 Claude 开始重复写文件或忘记项目结构时就按。

5.9 上下文成本：每一行都烧钱

假设 CLAUDE.md 2000 tokens，每会话 50 轮：消耗 = 2000 × 50 = 100,000 tokens每天 5 个会话 = 500,000 tokens/天

结构化上下文（编号列表、标注的决策）比非结构化解释段落压缩效率高得多。

推荐写法：

CONSTRAINT: payments 模块使用同步回调——异步重构被遗留供应商 SDK 阻止

5.10 局限

1. 全量加载的成本——每轮对话都重新消耗
2. 规模上限——适合数百条规则，不适合百万级
3. 缺少语义搜索——grep 做不了语义关联
4. 工具锁定——~/.claude/ 下的记忆不跨工具
5. 记忆污染——Auto Memory 无质量保证

六、为什么要 Hybrid Memory？

单一方案的天花板

见过太多 Demo 试过只向量的，结果发现 deploy 配置这种精确信息找不到。也见过只 Markdown 的，项目文档一多就 grep 不过来了。总结下来就是——

没有任何一种能全包。Agent 有时要精确匹配（「CLAUDE.md 第 3 行」），有时要语义搜索（「数据库选型讨论」），有时要时间范围查询（「上周的对话」）—— 不同查询需要不同存储。

四层融合架构

第一层: 文件层├── 项目规则（CLAUDE.md, .cursorrules）└── 工作流程（Skills）第二层: 向量层├── 用户历史交互（嵌入 + 语义搜索）└── 存储: Qdrant / pgvector / FAISS第三层: SQL 层├── 时间戳索引、元数据过滤└── 存储: PostgreSQL / SQLite第四层: 知识图谱层├── 实体关系、依赖链路└── 存储: Neo4j / Kuzu

实际应用中不需要四层全上——小项目文件 + 向量就够了，大型 Multi-Agent 系统才需要知识图谱层。

Mem0 的向量 + Graph Memory 双引擎是目前最成熟的实践；腾讯云 Agent Memory 的四层渐进方案（对话 → 原子 → 场景 → 画像）则代表了记忆分层沉淀的工程方向。

七、不同 Agent 怎么选 Memory？

就记住一个原则——如果你的 Agent 是给开发者用的，优先 Markdown + Git；如果是给一般用户的，优先向量 + 自动压缩。

写代码的要选 Markdown，做研究的要选向量，做审批流的要选 Checkpoint。混合使用是常态。

八、未来趋势

1. 记忆压缩 —— 从 LLM 摘要到结构化压缩

Claude Code 的 /compact 和 SimpleMem 的语义无损压缩（压缩到原对话的 20-30%）正走向精细化。

2. 记忆排序 —— 超越余弦相似度

score = α × similarity + β × recency + γ × importance + δ × context_relevance

CrewAI 的复合评分引擎已落地，不同场景调不同权重。

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 比一个复杂的向量更好用。