Claude Code Auto-Memory 功能解读：告别 Session 失忆，实现项目级上下文记忆

用 Claude Code 处理过稍微复杂项目的开发者，大概都有过类似的经历：每次开启新会话（Session）后，第一件事往往不是直接写代码，而是花费大量时间提供项目背景（Context）。你需要向 AI 助手解释这个项目是什么、采用了什么架构、测试环境有哪些已知的坑、团队的命名规范是什么等等。

交代完这些背景信息，快则五分钟，慢的可能要十几分钟。直到 Claude Code 回复一句“好的，我理解了”，真正的编程工作才算开始。这个重复交代上下文的过程，无疑降低了开发效率。

开源社区也曾尝试通过外挂方案解决这一痛点，但实际体验往往不尽如人意。例如，claude-mem 等项目试图通过捕捉工具使用情况自动生成摘要，并将信息带到后续会话。想法虽好，实际使用中却问题频发：安装依赖复杂、内存占用高、查询速度慢，且稳定性较差。

如今，这个核心痛点终于被官方正视并解决了。近日，Anthropic 工程师 Thariq 发布公告，宣布 Claude Code 正式推出 Auto-Memory（自动记忆） 功能。简而言之，Claude Code 现在能够跨会话记住关键信息。你的项目上下文、调试习惯、偏好的解决方案，在开启新会话时将自动载入，无需任何手动配置。

Auto Memory 是如何工作的？

其工作机制并不复杂。

在编程过程中，Claude Code 会自动将认为值得记忆的内容写入一个本地文件，路径通常为：

~/.claude/projects/<project-hash>/memory/MEMORY.md

那么，它会记什么、又按照什么规则来记呢？通过查看其系统提示词，我们可以一窥究竟：

# auto memory

You have a persistent auto memory directory at `~/.claude/projects/<project-hash>/memory/`.
Its contents persist across conversations.
As you work, consult your memory files to build on previous experience.

## How to save memories:
- Organize memory semantically by topic, not chronologically
- Use the Write and Edit tools to update your memory files
- MEMORY.md is always loaded into your conversation context
  — lines after 200 will be truncated, so keep it concise
- Create separate topic files (e.g., debugging.md, patterns.md)
  for detailed notes and link to them from MEMORY.md
- Update or remove memories that turn out to be wrong or outdated
- Do not write duplicate memories. First check if there is an
  existing memory you can update before writing a new one.

## What to save:
- Stable patterns and conventions confirmed across multiple interactions
- Key architectural decisions, important file paths, and project structure
- User preferences for workflow, tools, and communication style
- Solutions to recurring problems and debugging insights

## What NOT to save:
- Session-specific context (current task details, in-progress work)
- Information that might be incomplete
  — verify against project docs before writing
- Anything that duplicates or contradicts existing CLAUDE.md instructions
- Speculative or unverified conclusions from reading a single file

## Explicit user requests:
- When the user asks you to remember something across sessions
  (e.g., “always use bun”, “never auto-commit”), save it
  — no need to wait for multiple interactions
- When the user asks to forget or stop remembering something,
  find and remove the relevant entries from your memory files

这段提示词揭示了几项值得注意的设计：

1. 记忆不限于单个文件：MEMORY.md 是主索引文件，其前 200 行会自动加载到会话上下文中。但 Claude Code 还可以创建诸如 debugging.md、patterns.md 等主题文件，并通过 MEMORY.md 中的链接引用。这就像一本带有目录的笔记本，需要时再翻阅具体章节。
2. 克制的记忆原则：在“What NOT to save”部分，Anthropic 展现了相当的克制。与许多试图记忆一切的设计不同，它明确划定了边界：不记临时状态、不记未经验证的信息、不重复 CLAUDE.md 已有的内容、不记基于单一文件的推测性结论。
3. 响应用户显式指令：“Explicit user requests”部分非常实用。你可以直接告诉 Claude “以后都用 bun 安装依赖”或“永远不要自动提交”，它会立即写入记忆，无需等待多次交互来总结。反之，要求“忘记某件事”，它也会找到对应条目删除。
4. 本地化与隔离：所有记忆文件均存储在本地，并按项目哈希值进行隔离。这意味着信息不会上传至云端，且不同项目间的记忆完全独立，保障了隐私与安全性。

/memory 命令：记忆的控制中心

记忆功能的操作核心是 /memory 命令。

输入此命令，你可以查看 Claude Code 自动记录的所有内容，可以编辑特定条目，删除你认为无用的记忆，甚至完全关闭该功能。这个设计体现了 透明与可控 的理念。毕竟，AI 的判断并非总是准确，它可能将一个临时的调试方案误判为重要经验。此时，手动干预和清理就显得非常必要。

当然，如果你不希望启用自动记忆功能，也可以通过一行命令全局禁用：

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

与 CLAUDE.md 是何关系？

许多 Claude Code 的资深用户都接触过 CLAUDE.md 文件。你可以将项目规范、禁止行为、常用命令写入其中，使其在所有会话中生效。

Auto Memory 与 CLAUDE.md 是互补而非替代的关系，两者功能互不覆盖。

• CLAUDE.md：是你主动编写的、希望 AI 严格遵守的静态规则手册，记录那些不变的、预设的约定。
• Auto Memory：是 Claude Code 在工作过程中自动观察和积累的动态经验笔记，包括项目模式、你的个人习惯、已解决的难题等。

两者结合使用效果最佳。可以这样比喻：CLAUDE.md 是你为新员工编写的《入职手册》，而 Auto Memory 则是员工自己记录的《工作心得》。新会话开启时，AI 先阅读手册了解规则，再翻阅笔记获取经验，从而更快、更准确地投入工作。

使用前需要注意的几个问题

从设计哲学上看，这个功能几乎无可挑剔：零配置、透明可控、与现有工作流无缝互补。但在实际使用中，仍有几点需要留意：

1. 200 行的限制：这是当前实现的一个天花板。系统采用简单的前缀加载机制，即只读取 MEMORY.md 文件的前 200 行放入上下文。它不像基于 人工智能 的向量数据库能进行语义检索，只是按顺序读取。因此，当记忆内容不断积累，超出 200 行的部分实际上不会被新会话加载。
   对策：需要养成定期使用 /memory 命令进行整理的习惯，保留精华，删除过时内容，类似于管理书签。

2. 记忆过期问题：并非所有被记住的东西都值得永久保留。例如，两个月前为解决一个特定 Bug 采用的临时方案，如今代码早已重构，但旧的记忆可能依然存在。这可能导致 AI 在遇到类似问题时，优先推荐已过时的方案。有时，陈旧的记忆比没有记忆更麻烦。
   目前，官方尚未引入自动过期或衰减机制，因此记忆的“保鲜”完全依赖于手动管理。

不过，从另一个角度看，Anthropic 的选择很有意思。他们没有引入复杂的向量检索，而是采用了纯粹的本地 Markdown 文件方案。这与其一贯的 “简约有效” 设计哲学一脉相承：先用最简单的方案跑通核心体验，不够用再迭代升级。对于追求效率和轻量化的 开源实战 开发者而言，这种思路往往更受欢迎。

体验与展望

在该功能发布前，许多用户的解决方案是在 CLAUDE.md 中手动写入关键背景，并在每个新会话的首条消息中再次补充任务详情。这相当于开发者自己在充当AI的记忆介质。

例如，曾有一个耗时较长的任务，Claude Code 花了半小时梳理项目的测试文件，找出问题接口并整理出一套处理边界情况的思路。然而，当上下文窗口触达极限被压缩后，新会话接手的“新手”对之前那套成熟的思路一无所知，导致大量工作被重复。那半小时的“思考”成果基本白费。

Auto Memory 瞄准的正是这类痛点。Claude Code 在工作过程中发现的有价值模式和经验，不应随着会话结束而消失。在多智能体（Agent）协作的场景下，该功能的价值可能更加凸显：一个 Agent 发现的解决方案被写入记忆，其他 Agent 在开始时就能共享这一认知。

看到 Claude Code 的 Auto Memory，很容易让人联想到近期火爆的 OpenClaw。OpenClaw 能迅速获得大量关注，其强大的持久记忆能力功不可没。它不仅能记住对话历史，甚至在此基础上集成了向量搜索，相当于为智能体内置了一套 RAG（检索增强生成）系统，体验上了一个台阶。

相比之下，Claude Code 的 Auto Memory 走了更轻量的路线：纯本地 Markdown、前缀加载、无复杂检索。从功能完备度上说，它与 OpenClaw 的记忆系统尚有差距。但这很符合 Anthropic 的风格。

可以期待的是下一步的演进。当前 200 行的前缀加载天花板很快会被触及，届时很可能会引入某种形式的语义检索。如果再结合自动记忆质量评估与过期机制，Claude Code 的记忆系统将更具竞争力。

如果你想了解更多前沿的 AI 开发工具与最佳实践，欢迎来 云栈社区 与其他开发者交流探讨。

相关链接参考：

• Auto Memory 官方文档：https://code.claude.com/docs/en/memory
• Thariq 的公告：https://x.com/trq212