我翻遍了Claude Code的system prompt，发现它的\"记忆\"就是一个200行的markdown文件

id: 2026-03-03-claude-code-auto-memory-deep-dive
title: 我翻遍了Claude Code的system prompt，发现它的"记忆"就是一个200行的markdown文件
slug: claude-code-auto-memory-deep-dive
status: draft
content_type: article
channels:
language: zh-CN
source_urls:

• "https: //blakecrosley.com/en/blog/context-window-management"
assets:
cover_image: 05-assets/claude-code-auto-memory-deep-dive/01-infographic-memory-system-overview.png
template: article
owner: content-forge
created_at: 2026-03-03T00:00:00+08:00
updated_at: 2026-03-04T00:00:00+08:00
style: lizi_kk
audience: Claude Code 用户、AI 编程从业者、开发者
tags:
source_notes:

说实话，用 Claude Code 的人都有一个抓狂时刻——每次新开会话，它对你的项目一无所知。

你得重新说一遍：“我们用 FastAPI + Next.js，后端端口 9801，状态管理用 Zustand，上次那个 bug 根因是连接池耗尽……”

烦不烦？

2026 年 2 月 5 日，Anthropic 发布了 Opus 4.6。大多数人只看到了“更强的模型”。但真正改变日常开发体验的，是三个不起眼的底层能力：

• Auto Memory——跨会话持久记忆
• Agent Teams——多智能体并行协作
• Context Compaction——上下文智能压缩

内部测试数据：智能体性能提升 39%，100 轮对话 token 消耗降低 84%，支持 30 小时无人值守。

这篇文章，我把 Auto Memory 的底层机制逐层拆开——system prompt 注入原文、200 行硬截断的真实含义、5 个我全踩过的坑，以及它和 Agent Teams、Context Compaction 之间怎么配合。

如果你每天都在用 Claude Code，这篇值得收藏。

01 Claude Code 的记忆到底有几层

先看全貌。

Claude Code 的记忆不是一坨东西，是分层的：

┌──────────────────────────────────────────────────────┐
│  Layer 0: Enterprise Rules（最高优先级）              │
│  └─ 组织管理员的全局规则，所有用户强制生效            │
│                                                      │
│  Layer 1: CLAUDE.md 文件族（静态指令 · 人工维护）     │
│  ├─ ~/.claude/CLAUDE.md        ← 用户级，所有项目    │
│  ├─ <project>/CLAUDE.md        ← 项目级，入库共享    │
│  ├─ <project>/CLAUDE.local.md  ← 项目级，本地私有    │
│  └─ <subdir>/CLAUDE.md         ← 子目录级，按需加载  │
│                                                      │
│  Layer 2: Auto Memory（动态知识 · Claude 自主维护）   │
│  ├─ MEMORY.md  ← 主索引，自动加载（200行上限）       │
│  └─ *.md       ← 主题文件，按需读取（无行数限制）    │
│                                                      │
│  Layer 3: Subagent Memory（子代理记忆 · 独立隔离）    │
│                                                      │
│  Layer 4: Session Context（会话上下文 · 临时）        │
└──────────────────────────────────────────────────────┘

一句话说清楚 Layer 1 和 Layer 2 的关系：

Layer 1 是项目手册——你写的规则、命令、规范，入 Git，团队共享。

Layer 2 是个人笔记——Claude 自己记的调试心得、踩坑经验，不入 Git，纯本地。

一个是宪法，一个是草稿纸。互补，不是替代。

	CLAUDE.md（手册）	Auto Memory（笔记）
谁写	人工维护	Claude 主动写入
内容	编码规范、构建命令、禁止事项	陷阱、失败模式、调试经验
入 Git	是（团队共享）	否（个人本地）
上限	无硬限制	200 行（主索引）
更新频率	低（架构变更才改）	高（每次会话可能更新）
典型内容	“始终使用 pytest 运行测试”	“检查 A 必须在 B 之前，否则测试 X 挂”

搞清楚这两层的区别，后面的东西才看得懂。

02 从 # 前缀到 Auto Memory：三个阶段

Auto Memory 不是凭空冒出来的。

阶段 1: # 前缀时代（已弃用）
    └─ 用户在对话中用 # 标记重要信息
    └─ Claude 被动记录，能力有限
    └─ 问题：完全依赖用户主动标记，Claude 不会判断
         │
         ▼
阶段 2: Research Preview
    └─ 需要手动开启：settings.json 加 autoMemoryEnabled: true
    └─ Claude 开始有"自主写入"能力
    └─ 问题：默认关闭，大多数人根本不知道
         │
         ▼
阶段 3: 正式发布（v2.1.32+，当前）
    └─ 默认开启，无需配置
    └─ 可用环境变量关闭：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
    └─ 与 Opus 4.6 的 Agent Teams / Context Compaction 协同

还在用 # 前缀标记的，该换了。

说实话，大部分人连阶段 2 都没用过。这功能藏得太深，如果不是我挨个翻 settings.json 的字段，根本发现不了。

但真正有意思的不是这个演进历史——是 Auto Memory 的底层实现，朴素得超乎想象。

03 底层真相：没有向量数据库，没有 RAG，就是读写文件

先说结论：就是 Claude 被允许在你电脑上的一个文件夹里读写 markdown 文件。

没有向量数据库。没有语义检索。没有 RAG。

每次开新会话，主文件塞进 system prompt。完事。

零依赖，纯文件 I/O。

~/.claude/projects/<project-path-hash>/memory/
├── MEMORY.md          ← 主索引，每次自动加载（上限200行）
├── debugging.md       ← 主题文件（按需创建，不自动加载）
├── patterns.md
├── architecture.md
└── ...

你可能觉得“就这？”

对，就这。这就是 Anthropic 的风格——用最简单的机制解决 80% 的问题。不过度工程化，不引入额外依赖。

拆开 system prompt：Claude 到底看到了什么

大多数文章不会讲这部分。以下是我从实际运行环境中提取的完整 system prompt 注入内容：

You have a persistent auto memory directory at
`~/.claude/projects/<project>/memory/`.
Its contents persist across conversations.

## 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.

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

## What NOT to save:
- Session-specific context
- Information that might be incomplete
- Anything that duplicates CLAUDE.md instructions
- Speculative conclusions from reading a single file

Auto Memory 的全部“智能”就来自这段指令。

Claude 没有特殊的记忆模块，没有额外的神经网络组件。它只是被告知“你有个文件夹可以读写，按规则来”——跟你在 CLAUDE.md 里写“遇到 bug 先跑测试”是完全同一个机制。

这也解释了一个很多人困惑的问题：为什么 Claude 的记忆写入行为这么不稳定？

答案很简单。忙着干活的时候，这段指令的优先级自然被压低。不是不想记，是顾不上。

但我觉得这恰恰是好的工程品味。你见过很多方案搞 embedding + vector store + semantic search，链路一长，出 bug 的概率翻倍。Anthropic 选了最朴素的路，反而最稳。

不过“朴素”不代表“没限制”。接下来这部分，才是整篇文章最关键的。

04 200 行限制：比你想的更硬

MEMORY.md 有 200 行的硬截断。

注意，是硬截断——第 201 行开始直接消失。不是“存在但优先级低”，是 Claude 完全看不到：

MEMORY.md 总共 250 行
    ├─ 前 200 行 → 注入 system prompt ✓
    └─ 第 201-250 行 → 硬截断，Claude 完全看不到 ✗
        └─ Claude 收到截断警告，建议你精简内容

主题文件（debugging.md 等）没有行数限制。但它们不自动加载——Claude 得自己用 Read 工具去读。

这里有个容易忽略的连锁反应：MEMORY.md 的索引质量决定了整个记忆系统的有效性。

如果里面没提某个主题文件，Claude 压根不知道它存在。你精心写的 debugging.md 可能永远不会被读到。

所以 MEMORY.md 只能当目录用：

# Memory Index

## 调试经验
- [后端连接池问题](./debugging.md) - 根因和修复方案

## 架构决策
- [消息工厂设计](./architecture.md) - 分层逻辑

## 用户偏好
- [工作流](./user-preferences.md) - 测试、部署、风格

简洁，只做索引，别超 200 行。这 200 行是你的“记忆预算”，花在刀刃上。

数据流：三个阶段看完

┌──────────────────────────────────────────────────────┐
│  阶段一：会话启动                                     │
│  Claude Code 读 MEMORY.md 前 200 行 → 塞进 prompt    │
│  其他 memory/*.md 不自动加载                          │
└────────────────────────┬─────────────────────────────┘
                         ▼
┌──────────────────────────────────────────────────────┐
│  阶段二：会话进行中                                   │
│  Claude 可能记录：                                    │
│  ├─ gotchas——"检查 A 必须在 B 之前，否则测试 X 挂"  │
│  ├─ 失败模式——"该 API 并发 > 100 时返回 429"        │
│  ├─ 项目模式——"所有 router 必须用 API_PREFIX 注册"   │
│  └─ 用户偏好——"用户偏好 pnpm 而非 npm"              │
│                                                      │
│  写入时机：                                           │
│  ├─ 你说"记住这个" → 立即写入（最靠谱）              │
│  └─ Claude 自己觉得有用 → 看心情（不靠谱）           │
└────────────────────────┬─────────────────────────────┘
                         ▼
┌──────────────────────────────────────────────────────┐
│  阶段三：会话结束                                     │
│  文件留在磁盘，下次自动可用                           │
│  ⚠️ 没有"会话结束时自动总结"——社区方案存在的根因     │
└──────────────────────────────────────────────────────┘

第三阶段是关键设计取舍。

官方方案完全依赖 Claude 在会话过程中的“自觉性”。 你聊了两小时发现三个重要结论，但 Claude 没记——那就真没了。

这也是社区方案（claude-mem、AutoMem）存在的根本原因。后面会讲到怎么选。

05 三板斧协同：一套组合拳

Opus 4.6 同时上线的三个能力，不是各干各的，是一套组合拳：

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│ Auto Memory  │   │ Agent Teams  │   │   Context    │
│ 跨会话记忆   │   │ 多智能体协作 │   │  Compaction  │
├──────────────┤   ├──────────────┤   ├──────────────┤
│ 解决：       │   │ 解决：       │   │ 解决：       │
│ "每次重新    │   │ "一个人干    │   │ "聊久了就    │
│  介绍项目"   │   │  不过来"     │   │  忘事"       │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                  ┌───────▼───────┐
                  │  30小时无人   │
                  │  值守自主运行 │
                  └───────────────┘

token 降 84%、性能升 39%——就是这三者组合的效果。

但有几个细节，踩过坑才知道：

子代理记忆是隔离的。 Agent Teams 的子代理有独立记忆空间，读不到主会话的 Auto Memory，也不会污染主记忆。好处是干净，坏处是子代理对你的项目上下文一无所知。你得在 prompt 里手动交代背景。

Context Compaction 会吃掉记忆。 最新版在上下文使用率 64-75% 时就触发压缩——比以前的 90%+ 激进得多。MEMORY.md 的细节可能在压缩中被摘要化。你以为 Claude 记着呢，其实早忘了。

Adaptive Thinking 省 token。 Claude 根据问题复杂度自动调整思考深度，简单问题不浪费 token，把预算留给真正需要深度推理的场景。这个倒是好消息。

说到踩坑，接下来这部分我全经历过。

06 5 个必踩的坑

坑 1：聊久了记忆被压缩掉

会话开始: MEMORY.md 内容完整 ✓
    ▼ （对话越来越长）
上下文压缩触发（64-75% 容量时）
    ▼
MEMORY.md 的细节被摘要化 ✗

发现 Claude 开始“忘事”了？用 /clear 开新会话。记忆会重新完整加载。

坑 2：Claude 经常忘记写笔记

写入完全靠 Claude“自觉”。实际用下来：

• 忙着干活时根本想不起来记
• 写入质量参差不齐，有时太笼统，有时写了不该写的
• 不同模型版本的写入倾向还不一样

最靠谱的办法就一个字：你自己说“把这个记下来”。 别指望它自觉。我现在养成了习惯，每次调试出重要结论，直接说“写到 memory 里”。

坑 3：换路径打开项目，记忆就断了

记忆目录按项目路径哈希生成。同一个项目换个路径打开，就是两套独立记忆：

/home/user/apps/my-project  → memory-A
/mnt/disk/my-project        → memory-B

多台机器或多个挂载点工作的，注意了。这个坑很隐蔽，你可能很久才会发现“怎么之前记的东西全没了”。

坑 4：.claude.json 越来越胖

GitHub issue #5024：.claude.json 持续累积会话历史，文件越来越大。不是 Auto Memory 的锅，但会拖慢整体体验。定期清理一下。

坑 5：旧记忆比没记忆更危险

这个是最致命的。

Claude 不会主动清理过时记忆。项目架构改了，记忆还是旧的，Claude 就会基于错误信息做决策。

过时的记忆不是“没用”，是“有害”。 就像你手机导航用的三年前的地图——不是找不到路，是找到一条已经拆了的路。

得你自己定期去看看，删掉过时的。我每周花 2 分钟扫一眼 memory 目录，这个习惯帮我躲过好几次大坑。

07 官方够用吗？看项目规模

官方 Auto Memory 不够用时，社区有两个主流替代。先看对比：

                官方 Auto Memory    claude-mem         AutoMem
                ──────────────     ──────────         ───────
存储            纯 markdown 文件    压缩后的文本        图DB + 向量DB
写入触发        Claude 自主判断     Hook 自动捕获       Hook 自动捕获
会话结束        啥也不干            自动捕获+压缩       自动捕获+向量化
压缩            无                  ~200:1 压缩率       向量化
依赖            零                  Bun + uv            Docker 全家桶
可靠性          看 Claude 心情      自动化，稳定         自动化，稳定

怎么选？别纠结，看项目大小：

• 个人项目、小团队——官方够了。零配置零依赖，能跑就行。
• 中等复杂度——上 claude-mem。自动捕获 + AI 压缩，1 万 token 的会话内容压到约 50 token，200:1 的压缩率。靠谱。
• 大型长期项目——考虑 AutoMem。图数据库做关系推理，但得跑 Docker，部署成本不低。

6 条你现在就能用的建议

1. MEMORY.md 只当目录用。 只放链接和一句话摘要。200 行限制逼你这么做，别跟它较劲。
2. 按主题建文件，别按时间排。 debugging.md、architecture.md、user-preferences.md。语义组织，不是流水账。
3. 重要的事主动说“记住”。 “把这个调试结论写到 memory 里”——这句话比什么技巧都靠谱。别等 Claude 自觉，它不会的。
4. 每周扫一眼 memory 文件夹。 打开 ~/.claude/projects/ 下的 memory 目录，过时的删掉。2 分钟的事。旧记忆比没记忆更危险，前面说过了。
5. 聊天太长就 /clear。 Context Compaction 会吃记忆，/clear 让记忆重新完整加载。代价是丢失当前会话上下文，但总比 Claude 基于残缺记忆做决策强。
6. 不想用可以关。 环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1，完事。

安全：别让记忆变成攻击面

2026 年 2 月 26 日，The Register 报道了 Claude Code 的安全漏洞（CVE）：攻击者可以在仓库中注入恶意配置文件，实现远程代码执行和 API Key 窃取。

这和记忆系统直接相关。如果有人能操纵你的 MEMORY.md 或 CLAUDE.md，就能影响 Claude 的行为——它每次启动都无条件信任这些文件的内容。

三个基本防护：

• 定期看看 memory 目录，确认没被注入奇怪指令
• 别在 memory 文件里存 API Key、密码
• clone 陌生仓库后，先看看有没有 CLAUDE.md 或 .claude/ 目录

这不是吓你。攻击面就在那里。

写在最后

Auto Memory 的技术实现朴素到令人意外。没有向量数据库，没有 RAG 管线——system prompt + 文件读写，完事。

但这恰恰是好的工程品味。用最少的复杂度解决最核心的问题。

不过说到底，真正的记忆管理责任在你身上。 Auto Memory 给了工具，效果取决于你怎么用——MEMORY.md 的索引质量、主题文件的组织方式、定期审查的纪律性。

记忆系统的本质不是让 AI 变聪明。是让 AI 在正确的上下文中工作。

这才是 Context Engineering 真正在做的事。

下一篇我打算拆 Agent Teams 的多智能体协作机制——怎么让多个 Claude 同时干活还不打架。点关注不迷路。

栗子KK，一个在 AI 浪潮中游泳的 AI 产品 Founder
欢迎点赞、在看、关注，一起聊科技、聊产品、聊未来 🚀

参考来源：
• Anthropic 官方 Opus 4.6 发布
• Claude Code Changelog
• The Quiet Features That Shipped With Opus 4.6
• Claude Code's quiet power play
• How Claude Code Got Better by Protecting More Context
• Claude Code 安全漏洞 - The Register
• claude-mem GitHub
• AutoMem
• Anthropic Introduces Auto Memory System
• .claude.json 膨胀 Issue #5024
• Context Window Management 实测