Claude Code 深度拆解：记忆系统 1 — 四类记忆与文件存储引擎

Hi，大家好，欢迎来到维元码簿。

本文属于《Claude Code 源码 Deep Dive》系列。前面我们拆解了上下文编排（模型看到了什么）、工具系统（模型能做什么）、多 Agent 协作（模型怎么分工）。本文切入一个新命题：模型记住了什么。如果你想了解整个系列，可以先看系列开篇 | Claude Code 源码架构概览：51万行代码的模块地图。

本文聚焦一件事：Claude Code 的记忆系统如何存储和分类 Agent 自己积累的知识。

读完全文，你将能回答这几个问题：

• CLAUDE.md 和 MEMORY.md 都是 .md 文件，有什么本质不同？前者是用户写的规则，后者是 Agent 自己积累的知识。一个是被动加载的指令，一个是主动沉淀的经验。
• Claude Code 的记忆都有哪些种类？当前版本分为 user（画像）/ feedback（行为纠偏）/ project（动态事实）/ reference（外部指针）四类——先按"时效"（管多久），再按"记忆的主体"（关于谁的）划分。不同版本类别可能会增减，但时效 + 主体这个分类框架是稳定的。
• 哪些东西 Agent 不会帮你记？记忆系统的大多数内容会被沉淀下来，但 What NOT to save 明确列出了 5 类不该保存的内容——即使用户明确要求保存，也会先追问"什么让你意外"，再决定留什么。

「记忆系统」命题还会继续拆解两个主题：记忆的注入与存取管线——记忆怎么进入上下文、怎么保存、怎么被召回；会话记忆与三阶段压缩——会话笔记怎么记、上下文爆了怎么分级压缩。感兴趣的朋友欢迎关注维元码簿，或订阅《Claude Code 源码 Deep Dive》专栏，持续追更。

本篇覆盖的源码范围

在看细节之前，先给一个全局地图。本篇涉及的源码分布：

总计约 1050 行核心代码，横跨 4 个文件。本篇逐层拆解这些代码。

"记忆"到底指什么：CLAUDE.md、MEMORY 与会话笔记的关系

在深入细节之前，先把几个容易混淆的概念摆清楚。

我们日常说的 Agent “记忆”，其实是一个笼统的说法。在 Claude Code 里，它至少对应三种不同的东西：用户手写的规则（CLAUDE.md）、Agent 自己沉淀的知识（MEMORY，也就是 MEMORY.md + topic 文件）、以及单次会话内的笔记与压缩摘要。三者的维护者、生命周期、作用范围都不一样，但在模型眼里它们都是"上下文的一部分"，所以对外统称"记忆"。

把这三种东西摊开，就是下面这张全景表——从存储介质和作用域来看，Claude Code 的"记忆"可以拆成四个层次：

如上图所示，这四个层次从"用户显式指令"到"Agent 自动压缩"，形成了一个完整的记忆管线。CLAUDE.md 是用户手写的"入职手册"，Auto Memory 是 Agent 自己积累的"工作笔记"，Session Memory 是单次对话的"会议记录"，Compaction 则是"笔记整理"——把臃肿的聊天历史压缩成精炼摘要。

本文聚焦前两个层次：指令层与持久层。会话层和压缩层将在姊妹篇中详细展开。

记忆 vs 指令：CLAUDE.md 与 MEMORY.md 的本质区别

首先是概念澄清。Claude Code 中有两类看似相似、实则本质不同的.md文件。

CLAUDE.md：用户写的规则

CLAUDE.md（按src/utils/claudemd.ts加载）是用户/团队手动编辑的指令文件。它告诉 Agent"你应该怎么做"——编码规范、项目约定、团队偏好。它的加载有严格的优先级：

Managed CLAUDE.md（/etc/claude-code/） ← 全局，所有用户 ↓ 覆盖 User CLAUDE.md（~/.claude/） ← 用户级，所有项目 ↓ 覆盖 Project CLAUDE.md（项目目录 ./CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md） ↓ 覆盖 Local CLAUDE.md（项目目录 ./CLAUDE.local.md）← 私有，最高优先级

CLAUDE.md 的核心特征：它是"外部输入的约束"——Agent 不能修改它（除非用户要求），只能读取并遵守。

MEMORY.md：Agent 自己积累的知识

MEMORY.md（按src/memdir/memdir.ts加载）是 Agent 自己创建和维护的记忆索引。它的每一行都是 Agent 在之前对话中通过buildMemoryLines指令学会保存的。

MEMORY.md 的核心特征：它是"内生积累的知识"——Agent 主动判断什么值得记、主动写文件、主动维护索引。

用一个类比来理解这个区别：

• CLAUDE.md是老板发给你的"入职手册"——“我们这个项目用 Go 1.22、测试不要 mock DB、代码规范见 CONTRIBUTING.md”。
• MEMORY.md是你自己写的"工作笔记"——“这个用户是数据科学家，对 React 不熟但对后端很了解”、“上次那个 auth 中间件的重构是因为法律合规，不是技术债”。

为什么不把这两者合并成一个文件？因为维护者不同。CLAUDE.md 的维护者是用户（人），MEMORY.md 的维护者是 Agent（模型）。如果混在一起，Agent 修改自己记忆时可能误改用户的规则——这是 Claude Code 设计者明确避免的问题。

MEMORY 的四种类型：按时效与主体分类

聊完 CLAUDE.md 与 MEMORY 的边界之后，接下来这一节专门看MEMORY 内部的分类——Agent 自己沉淀下来的知识，在代码里被细分成几种，各自承担什么角色。

src/memdir/memoryTypes.ts定义了四种记忆类型（memoryTypes.tsL14-19）：

user | feedback | project | reference

怎么记住这四种？先别急着背名字，先看"管多久"。四类记忆首先按时效区分——长期 / 中期 / 短期，再按记忆的主体（关于谁的？）细分。时效这个维度比类型名字更直观，它决定了一条记忆的"保质期"和价值密度。

下面逐一展开每种类型的设计意图。

user——“你是谁”

user 类型记录的是用户的画像信息。memoryTypes.ts中对 user 类型的when_to_save是：

When you learn any details about the user’s role, preferences, responsibilities, or knowledge

设计意图：让 Agent 在不同对话中保持一致的行为模式。一个数据科学家和一个 React 初学者，应该得到完全不同的代码解释。

核心规则：避免写负面判断。系统提示明确指出——“Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work”。这不是道德说教，而是工程考量：负面标签会污染 Agent 后续所有交互。

feedback——“怎么做才对”

feedback 类型是最精妙的设计。它不仅记录"纠正"（“不要做 X”），也记录"确认"（“对，就这样做”）。

Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.

这是反直觉的。直觉上，我们只需要记住"别干什么"（纠错）。但如果只记纠错、不记确认，Agent 的行为会越来越保守——"上次这样做没有被纠正"和"上次这样做被确认是对的"是两种完全不同的信号。

feedback 的内容结构也经过精心设计——body_structure要求每条反馈都包含：

• 规则本身：“集成测试必须连真实数据库”
• Why：原因（“上次 mock 测试通过但生产迁移失败”）
• How to apply：适用条件（知道 Why 才能判断边界情况）

project——“正在发生什么”

project 类型记录的是代码和 git 历史无法推导的动态事实。它的时效性最短——“截止日期”、"谁在做什么"这些信息衰减极快。

关键设计：总是把相对日期转换为绝对日期——“下周四"变成"2026-04-30”。这是工程实践中的细节：一个月后回看，"下周四"没有意义，"2026-04-30"有。

reference——“去哪找”

reference 类型最轻量——它只存指针，不存内容。因为外部系统的内容会变化，存指针比存快照更有用。

反直觉设计：What NOT to save

如果"该存什么"是设计的上半场，那"不该存什么"就是下半场——而且更加反直觉。

memoryTypes.tsL183-195 定义了 5 类禁止保存的内容：

1. 代码模式、架构、文件路径 → 可通过读代码推导 2. Git 历史、谁改了谁 → git log/blame 是权威源 3. Debug 方案、修复秘诀 → 修正在代码里，commit message 有上下文 4. CLAUDE.md 里已有的内容 → 避免冗余 5. 临时任务细节 → 只对当前会话有意义

这不是一份随便写的清单。每一条的背后都有一个原则：记忆应该存储"不可推导的知识"，而不是"当前状态下可获取的信息"。

代码模式可以通过grep推导，Git 历史可以通过git log查询。如果把这些都存进记忆，不仅浪费 token，还会引入信息过时问题——代码改了，记忆没更新，Agent 就会基于过期信息做决策。

最反直觉的是第 5 条的补充说明（memoryTypes.tsL194）：

“These exclusions apply even when the user explicitly asks you to save. If they ask you to save a PR list or activity summary, ask what was surprising or non-obvious about it — that is the part worth keeping.”

翻译：即使用户说"把这个 PR 列表保存下来"，Agent 也不应该照做——它应该反问"这周有什么让你意外的事情吗？"然后只保存意外的那部分。

为什么？因为记忆系统不是活动日志。日志的价值是"所有事情我都记录了"，记忆的价值是"下次我需要知道的事情都在这里"。两者目标不同——日志追求完整性，记忆追求信息密度。

MEMORY.md 的索引机制：为什么是文件 + Markdown，而不是向量库

聊完分类模型，再看实际的存储机制。但在讲"两步保存"和"硬上限"这些工程细节之前，值得先花一段讲清楚为什么整套记忆系统被设计成这个样子——因为两步保存、索引文件、硬上限这些看起来零散的规则，底下其实是同一套设计哲学。

Claude Code 没有把记忆塞进向量数据库，而是把它拆成一堆.md文件。这不是工程取巧，而是三条明确的设计原则。

原则一：按 topic 划分，不按时间

memdir.tsL214 的保存指令里有一句关键约束：

Organize memory semantically by topic, not chronologically

topic 文件被命名为user_role.md、feedback_testing.md、project_auth_migration.md——按"这是关于什么的"来组织，而不是"这是什么时候发生的"。同一主题的新信息会更新同一个文件（保存指令 L216：First check if there is an existing memory you can update before writing a new one），而不是追加到日志末尾。这让每个 topic 文件始终保持在"当下有效"的状态，避免变成活动流水账。

原则二：全文件存储，召回靠 grep

整个系统被明确定义为persistent, file-based memory system（memdir.tsL239）——没有 embedding，没有向量相似度，没有外部服务。

那"要找上次提过的 auth 约定"怎么办？memdir.tsL375-407 的buildSearchingPastContextSection给出的召回指令就是一条 shell 命令：

grep-rn"<search term>"~/.claude/projects/<slug>/memory--include="*.md"

这个选择看起来朴素，但对应三个很实用的好处：

• 可读：用户随时能打开文件看 Agent 到底记了什么，不是一堆黑盒向量；
• 可审计：记忆变化可以git diff、团队可以共享同一份 MEMORY.md（这也是teamMemPaths.ts存在的前提）；
• 零依赖：不需要 embedding 模型，也不需要跑一个向量数据库进程。

更关键的是，Agent 本身最熟练的工具就是 Read 和 Grep——用它已经有的能力去召回，比引入一个新的检索层更自然，也更可靠。

原则三：索引与内容分离

MEMORY.md 不是记忆本身，而是一份目录——一行一条 topic 指针，带一句 150 字以内的 hook 描述。真正的内容在 topic 文件里。

这么做的理由在memdir.tsL229 写得很直白：

`${ENTRYPOINT_NAME}` is always loaded into your conversation context — lines after 200 will be truncated

MEMORY.md 是常驻上下文的，每次对话都会被完整注入；topic 文件则是按需加载，Agent 扫一遍索引判断"哪些条目跟当前任务相关"，再 Read 具体 topic 文件拿完整内容。这是典型的"目录卡片 + 档案库"双层架构：常驻的只有薄薄一层索引，厚重的正文按需展开。这也解释了为什么下面会有 200 行 / 25KB 的硬上限——索引层一旦膨胀，所有会话都要付出成本。

有了这三条原则打底，接下来的"两步保存"和"硬上限"就不是孤立的工程细节了，而是这套哲学的具体落地。

两步保存流程

MEMORY.md 的保存指令（memdir.tsL221-227）明确规定了两步：

Step 1：用 Write 工具写一个 topic 文件。文件名如user_role.md，必须带 frontmatter：

--- name: {{memory name}} description: {{one-line description}} type: {{user, feedback, project, reference}} --- {{memory content}}

Step 2：在 MEMORY.md 里添加一行索引：

- [Title](file.md) — one-line hook (under ~150 characters)

MEMORY.md 是索引，不是内容本身。这个设计很巧妙：索引行足够短（一行约 150 字符），加载成本低；内容按需访问（Read topic 文件读取完整内容）。这是一种"目录卡片 + 档案库"的双层架构。

硬上限：200 行 / 25KB

但索引也会膨胀。memdir.tsL34-38 定义了两个硬上限：

MAX_ENTRYPOINT_LINES = 200 // 最多 200 行索引 MAX_ENTRYPOINT_BYTES = 25_000 // 最多 25KB（约 125 chars/line）

超出后，truncateEntrypointContent()执行两阶段截断（memdir.tsL57-103）：

1. 先按行截断：保留前 200 行，丢弃其余
2. 再按字节截断：如果剩余内容仍超 25KB，在最后一个换行符处切断（保证不切到行中间）

截断后会附加警告：

> WARNING: MEMORY.md is 250 lines and 28.5KB. Only part of it was loaded. > Keep index entries to one line under ~200 chars; move detail into topic files.

这个警告不是给用户看的，是给 Agent 看的——提醒 Agent 要精简索引行，把细节放到 topic 文件里。

路径决议：不是"记忆放哪"，而是"信谁给的路径"

路径决议表面上是算出一个存储路径字符串，但拆解paths.ts会发现：这 280 行代码里真正的内容不是怎么"算"，而是怎么"信"。env var、settings.json、projectSettings、git root——每一类输入都对应不同的信任等级，优先级链本身只是结果，它背后有三条明确的安全哲学。

先看决议链的骨架（paths.tsL210-235）：

优先级 1：CLAUDE_COWORK_MEMORY_PATH_OVERRIDE 环境变量 ← SDK/Cowork 注入 优先级 2：settings.json 的 autoMemoryDirectory ← 用户配置 优先级 3：<memoryBase>/projects/<sanitized-git-root>/memory/ ← 算法派生

链本身很简洁，但每一层为什么这样排、为什么这样验证，背后是下面这三件事。

哲学一：输入从哪来，就信多少

这套体系里最能看出"零信任"思想的是getAutoMemPathSetting()（paths.tsL179-186）：

constdir=getSettingsForSource('policySettings')?.autoMemoryDirectory??getSettingsForSource('flagSettings')?.autoMemoryDirectory??getSettingsForSource('localSettings')?.autoMemoryDirectory??getSettingsForSource('userSettings')?.autoMemoryDirectory

注意这里没有projectSettings——明明.claude/settings.json是项目里最常见的配置入口，但它被故意排除了。注释把动机写得毫不含糊：

a malicious repo could otherwise set autoMemoryDirectory: "~/.ssh" and gain silent write access

一个恶意仓库只要在自己的 settings.json 里写一行，就能把记忆目录重定向到~/.ssh——而 filesystem.ts 对"记忆目录"开了写入特权。这个口子如果让 projectSettings 也能触发，后果是灾难性的。

同样的分级还体现在：环境变量 override 也不享受写入特权（paths.tsL267-268）。Cowork 场景的挂载点能读写，但仍要走完整的权限检查。一句话——来源不同 → 权限不同，不是"设进来就顶格"。

哲学二：默认安全优先于用户方便

validateMemoryPath()（paths.tsL109-150）对任何外部来的路径做 6 项拒绝，命中任意一项即拒：

最后一项尤其能说明问题。~/是几乎所有 Unix 工具都支持的用户便利特性，但paths.tsL117-133 做了一件特别克制的事：只接受~/<实名子目录>，拒绝所有"退化形式"——~、~/、~/.、~/..、~/foo/..，只要展开后等于 $HOME 或它的父目录，一律返回undefined：

constrestNorm=normalize(rest||'.')if(restNorm==='.'||restNorm==='..'){returnundefined}

这不是对用户不够宽容，而是把"能拒就拒"设为默认值——宁可让用户补一个显式子目录名，也不允许潜在地对 $HOME 整个目录打开写入权限。安全系统的默认倒向“不允许”，是比弹性更重要的工程原则。

哲学三：身份稳定 > 路径灵活

第 3 层默认路径里藏着一个关键细节——记忆目录的 key 不是cwd、不是$PWD、不是进程 pid，而是findCanonicalGitRoot()（paths.tsL203-205）：

functiongetAutoMemBase():string{returnfindCanonicalGitRoot(getProjectRoot())??getProjectRoot()}

用"正则化的 git 根"做身份，意味着：

• 你用git worktree拉feature-x到/tmp/project-x，记忆仍在主 repo 目录下；
• 你在子目录src/foo/开启 shell，记忆还是走 repo 根；
• 你切分支、移动 repo、改文件夹名——只要 canonical git root 没变，记忆就不丢。

注释里还挂了事故号：anthropics/claude-code#24382——这个选择是从一次"用户丢失记忆"的真实 bug 回溯出来的。记忆要服务于"用户 + 项目"的组合，而不是服务于某个具体的工作目录，这是这一行 fallback 要守住的语义。

把三条哲学拼起来，就是路径决议真正在解决的问题：让 Agent 在各种部署环境下都能找到自己的记忆，同时不会被恶意输入劫持。它不是一个字符串拼接问题，而是一个"谁有权决定记忆放哪"的权限设计问题。

KAIROS 日态模式：同一种记忆，不同的工作流

最后看一个特殊的 Feature Gate 变体：KAIROS 模式（feature('KAIROS')）。

在标准模式下，Agent 直接维护 MEMORY.md 索引。但在 KAIROS（assistant 长生命周期会话）模式下，工作流完全不同：

1. Agent 不直接编辑 MEMORY.md
2. 它只向每日日志文件追加条目（append-only）
3. 日志路径格式：<autoMemPath>/logs/YYYY/MM/YYYY-MM-DD.md（paths.tsL246-251）
4. 一个单独的夜间/dream进程从日志中蒸馏出 topic 文件 + 更新 MEMORY.md 索引

为什么需要这个变体？因为 assistant 模式的会话寿命极长——可能跨越多天、数百轮对话。如果让 Agent 在这么长的会话中维护一个实时索引，索引会迅速超过 200 行上限并被截断。改为 append-only 日志 → 夜间蒸馏的模式，Agent 只需要做最简单的事（追加一行），复杂的整理工作留给专门的进程。

这个设计的精妙之处在于：同一个存储目录、同一种文件格式、同一套四型分类——只是写入策略不同。记忆系统的存储层是统一的，而变化的是"谁在什么时候用什么方式写入"。

loadMemoryPrompt()（memdir.tsL419-507）实现了这个分发逻辑：KAIROS active → 日态提示；TEAMMEM enabled → 团队共享提示；否则 → 标准提示。三种策略、一份存储格式。

本章小结

本篇拆解了记忆系统的存储层，核心要点：

1. 记忆 ≠ 指令：CLAUDE.md 是用户写的规则（被动加载），MEMORY.md 是 Agent 积累的知识（主动维护），两者的维护者和生命周期完全不同。

2. 四型分类按两个维度划分：user（关于谁—画像）/ feedback（怎么做—纠偏）/ project（正在发生什么—动态事实）/ reference（去哪找—外部指针）。feedback 是最精妙的设计——不仅要记"纠正"，也要记"确认"，否则 Agent 会越来越保守。

3. What NOT to save 比 What to save 更重要：5 类禁止保存的内容坚守"不可推导的知识才值得记忆"的原则。最反直觉的是即使用户说"记住这个"，Agent 也应当追问"什么让你意外"——记忆不是日志。

4. MEMORY.md 是索引不是内容：两步保存 + 200 行/25KB 硬上限 + 两阶段截断。截断警告是给 Agent 看的，提醒它精简索引。

5. 路径决议 5 层优先级 + 6 项安全拒绝：从环境变量覆盖到默认路径的完整决议链，每一层都经过安全校验。projectSettings 被排除在 autoMemoryDirectory 来源之外。

6. KAIROS 日态模式展示了统一存储、不同策略的架构弹性：append-only 日志 → 夜间蒸馏，同一份存储格式适应不同场景。

下一篇将拆解记忆系统的存取管线——记忆怎么注入 System Prompt、怎么通过双路互斥机制保存、怎么用 Sonnet 选择器召回最相关的条目。

如果这篇文章对你有帮助，欢迎点赞收藏支持一下。如果你对 Claude Code 源码感兴趣，欢迎关注本系列后续更新。有任何想法或疑问，欢迎评论区留言讨论👋