AI编程 on Yison's Blog

Claude Code 的记忆系统是怎么工作的？源码级拆解

Tue, 12 May 2026 00:00:00 +0000

Claude Code 的记忆系统是怎么工作的？源码级拆解

你周五用 Claude Code 调 bug 到凌晨两点，周一打开新会话，它张嘴就说：“上次那个 auth 模块的 bug 修好了吗？测试记得起 Redis。“你愣住了——你没告诉过它这些。

一、一个细思极恐的瞬间

用过 Claude Code 的开发者大概都经历过这个瞬间：

你关掉终端，第二天重新打开，开始一个新对话。Claude 什么都没问，直接开始干活。它知道你的项目用 pnpm 而不是 npm，知道测试需要本地 Redis，知道你讨厌 verbose 的输出。

你仔细回想：我什么时候告诉它这些的？

答案是：你没有直接告诉它。是它自己"记住"的。

Claude Code 每次启动都是一个全新的上下文窗口，不携带任何历史对话。所有它"知道"的东西，都必须在第一轮对话之前从磁盘加载。

我花了一周时间读 Claude Code 的 TypeScript 源码（是的，它是开源的），发现它的记忆系统比官方文档描述的复杂得多。今天来拆解一下。

二、两套记忆系统：你写的 vs AI 写的

Claude Code 有两套完全独立的记忆系统，各司其职：

graph TB
 subgraph "Claude Code 记忆全景"
 subgraph "CLAUDE.md（你写的）"
 A1[手动维护]
 A2[指令/规则/偏好]
 A3[通过 git 同步]
 A4[加载后不变化]
 end
 
 subgraph "Auto Memory（AI 写的）"
 B1[自动提取]
 B2[用户画像/行为纠正]
 B3[项目状态/外部引用]
 B4[每轮对话可能更新]
 end
 
 A1 --> C[启动时加载到上下文]
 B1 --> C
 end
 
 style A1 fill:#0f3460,stroke:#e94560,color:#fff
 style A2 fill:#0f3460,stroke:#e94560,color:#fff
 style A3 fill:#0f3460,stroke:#e94560,color:#fff
 style A4 fill:#0f3460,stroke:#e94560,color:#fff
 style B1 fill:#533483,stroke:#e94560,color:#fff
 style B2 fill:#533483,stroke:#e94560,color:#fff
 style B3 fill:#533483,stroke:#e94560,color:#fff
 style B4 fill:#533483,stroke:#e94560,color:#fff
 style C fill:#e94560,stroke:#fff,color:#fff

关键区别：

维度	CLAUDE.md	Auto Memory
谁写的	你手动写	Claude 自动写
存储位置	项目目录 / 用户目录	`~/.claude/projects/` 下
同步方式	Git（可提交）	本地（不同步）
更新频率	你改才变	每轮对话可能更新
大小限制	40KB（建议）	索引 200 行 / 25KB
加载方式	启动时全部加载	索引全加载，topic 按需

2.1 CLAUDE.md 的加载链

优先级（高→低）：

1. 管理级 /etc/claude-code/CLAUDE.md ← IT 管理员写的，无法覆盖
2. 用户级 ~/.claude/CLAUDE.md ← 你的个人偏好
3. 项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md ← 团队共享（git 提交）
4. 本地级 ./CLAUDE.local.md ← 你的个人覆盖（不提交）

加载顺序：
 工作目录 → 向上遍历目录树 → 加载沿途所有 CLAUDE.md
 离工作目录近的优先级高

一个细节： CLAUDE.local.md 不在官方文档里，但源码中存在。它在项目 CLAUDE.md 之后、Auto Memory 之前加载。适合放个人的数据库密码、调试开关之类的——不提交到 git，但本地有效。

2.2 Auto Memory 的四种类型

Auto Memory 不是随意的笔记，而是有严格的分类：

graph TB
 subgraph "四种记忆类型"
 subgraph "user（用户画像）"
 U1[角色/偏好/知识水平]
 U2[始终私有]
 end
 
 subgraph "feedback（行为纠正）"
 F1[验证过的模式]
 F2[默认私有]
 end
 
 subgraph "project（项目状态）"
 P1[工作进展/决策]
 P2[倾向团队共享]
 end
 
 subgraph "reference（外部引用）"
 R1[系统指针]
 R2[通常团队共享]
 end
 end
 
 style U1 fill:#0f3460,stroke:#e94560,color:#fff
 style U2 fill:#0f3460,stroke:#e94560,color:#fff
 style F1 fill:#533483,stroke:#e94560,color:#fff
 style F2 fill:#533483,stroke:#e94560,color:#fff
 style P1 fill:#16213e,stroke:#e94560,color:#fff
 style P2 fill:#16213e,stroke:#e94560,color:#fff
 style R1 fill:#1a1a2e,stroke:#e94560,color:#fff
 style R2 fill:#1a1a2e,stroke:#e94560,color:#fff

为什么这样分？ 因为团队协作时，你的编码偏好（user）不应该泄露给队友，但项目进度（project）应该共享。这种分类直接影响记忆的加载和同步策略。

三、三个时间尺度：实时 / 会话 / 梦境

这是整套系统最精妙的部分。Auto Memory 不是"Claude 注意到什么就随手记下来”，而是有三个独立的后台进程，在不同时间尺度上提取信息：

graph LR
 subgraph "时间轴"
 A[Per-Turn
实时提取] -->|每轮对话| B[Per-Session
会话记忆]
 B -->|每个会话| C[autoDream
梦境整合]
 end
 
 subgraph "成本"
 D[极低
共享cache] 
 E[低
偶尔触发]
 F[中
24h+5会话门槛]
 end
 
 A --- D
 B --- E
 C --- F
 
 style A fill:#e94560,stroke:#fff,color:#fff
 style B fill:#533483,stroke:#fff,color:#fff
 style C fill:#0f3460,stroke:#fff,color:#fff
 style D fill:transparent,stroke:#e94560,color:#e94560
 style E fill:transparent,stroke:#533483,color:#533483
 style F fill:transparent,stroke:#0f3460,color:#0f3460

3.1 Per-Turn：实时提取（每轮对话后）

触发：每次完整查询循环结束
方式：fork 一个子 Agent 在后台运行
成本：极低（共享父 Agent 的 prompt cache）
权限：只读项目文件，只写记忆目录

一个细节： 如果主 Agent 在本轮已经写过记忆（你明确说"记住这个”），提取步骤会跳过那个范围，避免重复。

3.2 Per-Session：会话记忆（上下文增长时）

这是一个独立于 Auto Memory 的系统，目的是让当前会话的上下文在压缩后还能保留。

触发条件（三个同时满足）：

✅ 总上下文 ≥ 10,000 tokens
✅ 上下文增长 ≥ 5,000 tokens（自上次提取后）
✅ 工具调用 ≥ 3 次

提取的结构化笔记：

┌─────────────────────────────────────────┐
│ Session Memory 模板 │
├─────────────────────────────────────────┤
│ ## Current State │
│ 当前正在做什么，进展到哪一步 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Files and Functions │
│ 涉及的文件、函数、关键代码位置 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Errors & Corrections │
│ 遇到的错误、尝试过的方案、最终解决方案 │
│ （上限 ~2000 tokens） │
├─────────────────────────────────────────┤
│ ## Worklog │
│ 工作日志：做了什么、还剩什么 │
│ （上限 ~2000 tokens） │
└─────────────────────────────────────────┘
总计上限 ~12,000 tokens

为什么需要这个？ 当对话太长需要压缩时，有这些结构化笔记，auto-compact 可以复用它们，而不是从头重新摘要整个对话。效果好很多——因为笔记是增量提取的，上下文还完整时就记录了关键信息。

3.3 autoDream：梦境整合（每天/每几天）

这是最让人惊讶的部分。源码中明确把这叫做 “DreamTask”，UI 中会显示进度条。

graph TB
 subgraph "autoDream 触发条件"
 G1[Gate 1: 时间检查
≥ 24小时] -->|✅| G2[Gate 2: 会话检查
≥ 5个会话修改]
 G2 -->|✅| G3[Gate 3: 锁检查
.consolidate-lock 未占用]
 G3 -->|✅| EXEC[执行整合]
 
 G1 -->|❌| SKIP[跳过]
 G2 -->|❌| SKIP
 G3 -->|❌| SKIP
 end
 
 style G1 fill:#0f3460,stroke:#e94560,color:#fff
 style G2 fill:#0f3460,stroke:#e94560,color:#fff
 style G3 fill:#0f3460,stroke:#e94560,color:#fff
 style EXEC fill:#e94560,stroke:#fff,color:#fff
 style SKIP fill:#1a1a2e,stroke:#533483,color:#533483

整合流程（四阶段）：

Phase 1: 定向
 ├── 读取 MEMORY.md 索引
 └── 浏览现有 topic 文件
 目的：了解当前记忆状态

Phase 2: 发现
 └── 搜索日志和会话记录中的新知识
 目的：找到需要整合的信息

Phase 3: 写入
 ├── 写入/更新 topic 文件
 ├── 合并新信号到现有文件
 └── 相对日期 → 绝对日期（"昨天" → "2026-05-11"）
 目的：持久化新知识

Phase 4: 清理
 ├── 修剪 MEMORY.md 至 200 行以下
 ├── 移除过期指针
 └── 解决新旧事实矛盾
 目的：保证记忆质量

一个有趣的细节： 如果你杀掉整合进程，锁的修改时间会回滚，让下一个会话可以重试。这个错误处理很体贴。

它什么时候运行？ 不是等你关掉电脑或睡觉，而是在一次对话结束时——只要满足那三个 Gate。只是因为 24 小时和 5 个会话的门槛，大多数时候不会触发。

四、记忆召回：Sonnet 替你选

记忆存下来了，但怎么在需要的时候找到正确的记忆？

Claude Code 的方案是：让 Sonnet 替你选，不是关键词匹配。

graph TB
 subgraph "记忆召回流程"
 START[启动时] --> A[读取 MEMORY.md 索引
前 200 行]
 A --> B[扫描 topic 文件 frontmatter]
 B --> C[构建 manifest
filename + description]
 
 C --> D[每轮对话]
 D --> E[用户输入 + 工具结果]
 E --> F[调用 Sonnet 选择相关文件
最多 5 个]
 F --> G[读取选中文件
每文件 4KB 限制]
 G --> H[注入到 prompt]
 end
 
 subgraph "限制"
 L1[每轮最多 5 个文件]
 L2[每文件 4KB]
 L3[每轮预算 20KB]
 L4[会话累计 60KB]
 end
 
 style START fill:#e94560,stroke:#fff,color:#fff
 style A fill:#0f3460,stroke:#e94560,color:#fff
 style B fill:#0f3460,stroke:#e94560,color:#fff
 style C fill:#0f3460,stroke:#e94560,color:#fff
 style D fill:#533483,stroke:#fff,color:#fff
 style E fill:#533483,stroke:#fff,color:#fff
 style F fill:#533483,stroke:#fff,color:#fff
 style G fill:#533483,stroke:#fff,color:#fff
 style H fill:#e94560,stroke:#fff,color:#fff
 style L1 fill:transparent,stroke:#e94560,color:#e94560
 style L2 fill:transparent,stroke:#e94560,color:#e94560
 style L3 fill:transparent,stroke:#e94560,color:#e94560
 style L4 fill:transparent,stroke:#e94560,color:#e94560

为什么用 Sonnet 而不是关键词？ 因为语义理解更好。比如用户问"怎么跑测试"，关键词匹配可能找不到 feedback_testing.md，但 Sonnet 能理解这个意图。

但这里有一个结构性缺陷： 没有向量搜索，没有语义索引。如果 MEMORY.md 中的描述写得不好，或者 topic 文件太多（最多扫描 200 个，按修改时间排序），记忆就可能被"遗忘"。

五、什么能活过压缩？

长对话会被压缩。压缩后，什么能保留？

graph TB
 subgraph "压缩后存活分析"
 subgraph "✅ 能活过的（从磁盘重新加载）"
 A1[CLAUDE.md 文件]
 A2[Auto Memory 文件]
 A3[Session Memory 文件]
 end
 
 subgraph "❌ 活不过的"
 B1[只在对话中说过
没有保存到记忆系统的内容]
 end
 end
 
 style A1 fill:#0f3460,stroke:#e94560,color:#fff
 style A2 fill:#0f3460,stroke:#e94560,color:#fff
 style A3 fill:#0f3460,stroke:#e94560,color:#fff
 style B1 fill:#1a1a2e,stroke:#e94560,color:#e94560

源码中的清理代码：

// 压缩时，强制清除所有缓存，从磁盘重新加载
getUserContext.cache.clear()
resetGetMemoryFilesCache('compact')
clearSystemPromptSections()

教训： 如果你在对话中告诉 Claude 什么重要的东西，确保它写入了记忆。否则压缩后就没了。

六、与其他工具的对比

维度	Claude Code	Aider	Cursor	DeepSeek-TUI
记忆系统	✅ 三层架构	❌ 无	⚠️ 简单 rules	✅ 基础记忆
自动提取	✅ per-turn	❌	❌	⚠️ 手动
梦境整合	✅ autoDream	❌	❌	❌
记忆分类	✅ 4 种类型	❌	❌	❌
模型辅助召回	✅ Sonnet 选择	❌	❌	❌
团队同步	⚠️ feature flag	❌	❌	❌
记忆持久化	✅ 文件系统	❌	⚠️ 配置文件	✅ 文件系统

结论： Claude Code 的记忆系统是目前 AI 编程工具中最完善的。Aider 完全没有记忆，Cursor 只有简单的 rules 文件，DeepSeek-TUI 有基础记忆但没有自动提取和整合。

七、这套系统的局限

读完源码，我认为有几个结构性局限：

7.1 记忆是 per-repo 的

你在项目 A 教 Claude 的偏好，不会自动带到项目 B。用户级的 ~/.claude/CLAUDE.md 可以处理一部分，但它是静态的——Claude 不能在会话中自动更新它。

7.2 记忆是 machine-local 的

项目目录名经过 sanitize（非字母数字替换为连字符），但不同机器、不同用户名、不同挂载点会产生不同的目录名。同一项目，不同机器，不同记忆。

7.3 没有记忆衰减

所有记忆都是平等的。一个月前的偏好和今天的偏好权重一样。没有"热度"概念，没有自动遗忘机制。

7.4 依赖 Sonnet 的选择能力

如果 Sonnet 选错了记忆文件，或者描述写得不好，记忆就"丢了"。没有 fallback 机制。

八、对我们的启示

这套系统给我们什么启发？

8.1 记忆是 AI 工具的核心差异化

目前市面上的开源 AI 编程工具（Aider、OpenCode、Continue），没有一个有真正意义上的记忆系统。这是差异化机会。

8.2 梦境整合是一个优雅的设计

不是每次对话都提取记忆（太频繁，噪音多），也不是完全不提取（会丢失）。三个时间尺度的设计——实时、会话、梦境——是一个很好的平衡。

8.3 模型辅助召回比关键词匹配更好

让 Sonnet 选择相关的记忆文件，而不是 grep 关键词。这在语义理解上好很多，但成本也更高。

对于开源工具，可以考虑一个折中方案：先用关键词过滤缩小范围，再用小模型选择。

8.4 记忆质量 > 记忆数量

Claude Code 严格限制记忆的大小（200 行索引、4KB 单文件、60KB 会话累计）。这不是偷懒，而是有意为之——太多记忆反而会干扰。

九、写在最后

读完 Claude Code 的记忆系统源码，我最大的感受是：

好的 AI 工具不是模型能力的比拼，而是工程设计的比拼。

同样的 Claude 模型，有记忆系统和没有记忆系统，用户体验天差地别。记忆系统本身不需要更强大的模型，它需要的是精心的工程设计——什么时候提取、怎么存储、如何召回、何时整合。

这些工程细节，才是真正的壁垒。

本文基于 Claude Code TypeScript 源码分析。源码地址：github.com/anthropics/claude-code 参考文章：How Claude Code memory actually works

当 AI 能写 80% 的代码，剩下 20% 是什么？

Thu, 07 May 2026 00:00:00 +0000

当 AI 能写 80% 的代码，剩下 20% 是什么？

当 AI 能写 80% 的代码，剩下 20% 决定你值多少钱。

一、一个让人愣住的瞬间

用 AI 写代码的人，大概都有过这样的时刻：

一个功能模块，搁以前至少得写一天——定义接口、写解析逻辑、处理异常、补单元测试。现在呢？描述一下需求和数据格式，AI 噼里啪啦就生成了。review 一遍，改几个边界 case，提交。

然后你愣住了。

我刚才干了啥？我"编程"了吗？

仔细回想，做的工作是：描述需求 → 审查代码 → 修修补补。写代码的主力是 AI，开发者更像是一个"代码质检员"。

这个问题像一根刺一样扎在脑子里：当 AI 能写 80% 的代码，剩下 20% 是什么？我到底是开发者，还是 Prompt 工程师？

二、Vibe Coding 的狂欢与翻车

2025 年初，Andrej Karpathy（前 Tesla AI 总监）提出了一个概念叫 “Vibe Coding”——不看代码细节，凭感觉让 AI 写，能跑就行。

这个概念迅速流行。一时间，人人都可以用 AI 写 App，不会编程的人也能"做产品"了。社交媒体上到处是"我用 AI 一天做了个完整应用"的帖子。

然后翻车开始来了。

有数据显示，7% 的 vibe-coded 应用带着裸奔的数据库上线了。不是 AI 写得不好，是使用者根本不知道什么叫"安全"。他们能描述功能，但描述不了约束。

Karpathy 自己后来也修正了路线，提出了一个演进框架：

Vibe Coding → Context Engineering → Agentic Engineering
凭感觉写 → 精心设计上下文 → 让 AI 自主完成任务

大多数人还停留在第一阶段。而真正的价值，在第二阶段。

三、三个绕不开的场景

场景一：代码风格——没给规范，怪谁？

刚开始用 AI 写代码的时候，很多人都会犯同一个错误：直接开干。

结果呢？生成的代码风格跟团队规范完全对不上——错误处理方式不对、日志格式不对、命名约定不对。第一反应是：这 AI 也不行啊。

后来学乖了。把团队的 .cursorrules 配好，把代码规范文档喂进去，再贴几段项目里现有的代码作为示例。

输出立刻对味了。

AI 不是不懂你的风格，是你没告诉它。 这就像带新员工——你不培训就指望人家按你的规矩来，可能吗？

场景二：性能问题——能搞定，但费 Token

代码跑起来了，但性能不达标。把日志、profiling 输出、相关代码一股脑丢给 AI。

AI 确实能给出分析方向，但过程往往是这样的：

给了一段日志 → AI 说可能是锁竞争
补充了锁相关的代码 → AI 改口说可能是 GC 压力
又给了 GC 日志 → AI 说可能是内存分配模式有问题
来回好几轮……最后自己看了火焰图，一把定位到根源

Token 烧了一堆，结论是：AI 有定位能力，但效率取决于上下文的完整度。给少了它猜，给多了它准。

问题是，“给多少算够"这件事，本身就是个技术活。

场景三：业务理解——代码里藏着的隐形逻辑

让 AI 写一段数据校验逻辑，它写得又快又漂亮。但一跑，业务方说不对。

为什么？因为那段校验逻辑里藏着业务规则：某个字段在特定条件下才能为空、某个状态流转只能单向、某个阈值会随季节调整……这些规则不在技术文档里，在业务方的脑子里。

AI 不知道这些潜规则，它只能按照你给的需求字面意思写。代码逻辑里暗藏业务逻辑，业务理解不到位，写出来的代码就是不能用。

你得一条一条纠正。但有趣的是，纠正一次之后，它就能跟着对了——前提是上下文窗口还装得下。

四、一个新概念：上下文工程

这三个场景有个共同点：AI 的输出质量，取决于你给它的输入质量。

这不是什么新道理——计算机科学早就有句话叫 “Garbage In, Garbage Out”。但在 AI 编程时代，这句话有了新的含义。

Martin Fowler 的团队在 2026 年初写了一篇文章叫 “Context Engineering for Coding Agents”，给出了一个精辟的定义：

“Context engineering is curating what the model sees so that you get a better result.” （上下文工程就是精心策划模型看到的东西，以获得更好的结果）

他们把上下文分成了两类：

Instructions：告诉 AI 做什么——“写一个 E2E 测试”
Guidance：告诉 AI 遵循什么——“测试要相互独立，不要共享状态”

我之前代码风格不对，本质是缺了 Guidance。Bug 定位低效，是 Instructions 里的信息密度不够。业务理解差，是上下文窗口的物理限制。

场景	问题根源	解法
代码风格不对	没给规范约束	喂 `.cursorrules` + 代码示例
Bug 定位低效	上下文不完整	一次性给足日志 + 代码 + 复现步骤
业务理解差	窗口装不下	分层喂知识，先给架构再给细节

核心观点：AI 的能力边界，本质上是你构建上下文的能力边界。

五、放大器效应：为什么资深开发者用 AI 更香

这里有一个很容易被忽视的点：AI 对不同水平的开发者，放大倍率是不一样的。

新手 + AI = 1 × 2 = 2
资深 + AI = 10 × 2 = 20

新手不知道该问什么、该检查什么、该约束什么。他们给 AI 的上下文是模糊的、不完整的，所以 AI 的输出也是平庸的。

资深开发者知道：这个模块的边界条件是什么、这个并发场景的坑在哪里、这个客户的合规要求有哪些。他们给 AI 的上下文是精准的、结构化的，所以 AI 的输出也是高质量的。

AI 是放大器，不是替代品。它放大你已有的能力，但没法凭空给你能力。

这也解释了一个现象：很多人用 AI 写代码，觉得"也没多厉害啊”。不是 AI 不厉害，是你给它的上下文不厉害。

六、一个前瞻：AI 友好的代码库

Martin Fowler 的文章里还提到了一个概念：AI-friendly codebase design。

意思是：你的代码本身就是给 AI 的"文档"。命名清晰、模块化、有好的注释——这些本来就是好实践，现在多了一个理由：

让 AI 更好地理解你的代码。

想想看，当你把一段代码丢给 AI，如果这段代码命名模糊、逻辑混乱、没有注释，AI 能做的就是"猜"。但如果你的代码自解释、模块边界清晰、有完善的类型定义，AI 就能精准地理解你的意图。

这是一个正向循环：

好代码 → AI 理解更准 → AI 生成更高质量的代码 → 代码库更好

反过来也成立：

烂代码 → AI 理解偏差 → AI 生成更烂的代码 → 代码库更烂

AI 会加速你的代码库演进方向——无论是向上还是向下。

七、所以，我们到底是什么？

回到开头的问题：我到底是开发者，还是 Prompt 工程师？

我觉得这个问法本身就错了。正确的问法是：你是在写 Prompt，还是在做上下文工程？

Prompt 工程师：琢磨怎么写提示词让 AI 听话
上下文工程师：设计 AI 的认知环境，让它能精准输出

区别在于，Prompt 是一次性的，上下文是系统性的。

一个好的上下文工程师，需要：

架构能力：知道系统该怎么拆，模块边界在哪
业务理解：知道需求背后的真正意图
代码审美：能看出 AI 生成的代码哪里不对劲
调试直觉：AI 搞不定的 bug，你能搞定

这些恰恰是资深开发者的核心资产。AI 没有让这些资产贬值，反而让它们更值钱了。

Andrej Karpathy 的演进路线还在继续：

Vibe Coding → Context Engineering → Agentic Engineering
凭感觉写 → 精心设计上下文 → 让 AI 自主完成任务

我们现在处在第二阶段。而能做好 Context Engineering 的人，才有资格进入第三阶段。

写在最后：

“Prompt 工程师"不是贬义词，但只会写 Prompt 的开发者是。

真正的技能不是写 Prompt，而是构建一个让 AI 能精准输出的"认知环境”。这需要架构能力、业务理解、代码审美——这些都是时间和经验换来的，AI 给不了你。

所以下次有人问你是干嘛的，别说"我写 Prompt 的"。

说"我是上下文工程师"。

参考：