Agent系列：
编程智能体为何能让LLM在实际工作中表现更好

书接上回

Claude Code的三层记忆架构，藏着Agent设计的底层逻辑

事情是这样的。

前两天我在用Claude Code干活，做完一个比较复杂的任务之后，我习惯性地说了一句，“总结下这次的执行任务经验和心得，以便下次更好的完成任务”。

然后我就看到它开始写文件了。

不是写在对话里，是真的写到了一个叫memory.md的文件里。

我当时就愣住了。

因为这个行为跟我之前理解的"AI记忆"完全不一样。我印象里的记忆，要么是塞在context window里的对话历史，要么是某种神秘的黑盒数据库。但Claude Code直接把经验写成了文件，而且结构很清晰。

这让我开始好奇，它到底是怎么组织这些记忆的。

然后我找到了那篇解析Claude Code源码泄露的文章，看完之后，说实话，我被震撼到了。

不是因为技术有多复杂，恰恰相反，是因为它太简单了，但又太对了。

---

聊这个之前，先说一个问题。

AI Agent有个天坑，就是记不住事。

你可能觉得200K token的context window够用了，但你真的跑过一个长期项目就知道了，对话历史、文件内容、工具输出、中间推理，这些东西堆在一起，context很快就炸了。

更麻烦的是，一旦session结束，所有东西都没了。

下次你再打开，它又从零开始。

你跟它说过的话、它踩过的坑、它积累的经验，全都白费。

这就是为什么很多Agent用起来感觉很"傻"，它永远在重复学习同一件事。

那个naive的解决方案是把所有东西塞进prompt，但这样既贵又慢，而且还是会撞墙。

所以真正的问题不是context够不够大，而是记忆到底应该怎么组织。

Claude Code的答案是一套三层架构。

---

先说第一层，In-Context Memory。

这个最直观，就是你当前对话窗口里能看到的所有东西——对话历史、最近的工具输出、正在编辑的文件、系统prompt里注入的指令。

这层记忆的特点是快，即时可用，但也最脆弱。

Session一结束就没了，甚至session还在继续的时候，context满了，前面的内容就会被挤出去或者压缩掉。

所以这层记忆在Claude Code的设计里定位很清楚，它就是一个working scratchpad，做活跃推理的地方，不是存知识的地方。

这个定位很重要。

很多人误以为context window就是Agent的全部记忆空间，然后把什么都往里塞，结果就是效率极低、cost极高、效果极差。

Claude Code的做法是，把这层当成工作台，真正有价值的东西，写到下一层去。

---

第二层才是泄露文档里最核心的设计。

它用memory.md作为索引，指向一堆domain-specific的记忆文件。

不是把所有东西塞进一个文件，而是memory.md只存指针，真正的记忆分散在不同文件里。

比如，memory/project-context.md存的是项目目标和约束，memory/decisions.md存的是架构决策和原因，memory/code-patterns.md存的是代码规范，memory/user-preferences.md存的是用户习惯。

当Claude Code需要回忆某件事，它先读memory.md找到指针，然后加载对应的文件。

这个设计的妙处在于，它把"要回忆什么"和"回忆的内容在哪"分开了。

索引很小，加载很快，真正的记忆体可以无限增长。

而且它让记忆变得模块化了。你在做认证模块的工作，不需要加载数据库schema的记忆。你在debug一个问题，不需要加载项目背景的上下文。

这叫token效率。

---

但我觉得真正聪明的设计，是所谓的"self-healing memory"。

这个词听着有点玄乎，其实就是Agent自己维护记忆文件的准确性。

比如，Claude Code之前记了一个架构决策，说"用Redis做缓存"。后来项目改了，不用Redis了，改用Memcached。

按传统设计，这个信息要么靠人工更新，要么就永远错着。

但Claude Code的做法是，它在对话里意识到这个决策变了，就会主动去rewrite对应的记忆文件，把"用Redis做缓存"改成"用Memcached做缓存"。

不需要人插手。

这就是为什么我在让它"总结经验和心得"的时候，它会主动写文件——因为它在更新自己的知识库。

这个机制让Agent真正具备了"学习"的能力。

不是学习模型参数，那个是预训练阶段的事。Agent层面的学习，就是持续维护一个准确的、project-specific的知识库。

用多了，它就越来越懂你的项目，越来越懂你的习惯。

这才是Agent应该有的样子。

---

第三层是CLAUDE.md。

这个和memory.md不一样，它不是动态的记忆，是静态的项目"宪法"。

它放在项目根目录，存的是一些稳定的东西——项目架构、代码风格、哪些文件不能动、测试怎么跑。

每次session开始，Claude Code先读这个文件。

这让它不需要你每次都重新交代一遍"这是什么项目"、“我们用什么框架”、“不要动config目录”。

它自动就有situation awareness。

我觉得这个设计很优雅，因为它区分了"项目层面不变的context"和"session层面动态积累的context"。

前者放CLAUDE.md，后者放**memory/**目录。

两者用不同的频率更新，有不同的生命周期，但都服务于同一个目标——让Agent不是每次都从零开始。

---

把三层合在一起看，整个架构的逻辑是这样的。

In-Context Memory是工作台，活跃推理用的，用完就扔。

memory.md层是笔记本，记录经验、决策、用户偏好，动态增长，Agent自己维护。

CLAUDE.md层是项目手册，稳定的背景知识，session开始就加载。

三层配合，Agent就有了真正的"记忆"。

不是塞在context里的临时记忆，是存在文件系统里的持久记忆。

而且这个记忆系统是透明的——你随时可以打开文件看它在记什么，也可以手动改。

没有黑盒。

---

但我觉得这个架构最值得说的，不是技术细节，而是背后的设计哲学。

它折射出一种对Agent能力的边界认知。

就是，Agent不需要"记住一切"，它只需要"在需要的时候能找到需要的信息"。

这听起来是废话，但很多人在设计Agent的时候，真的会试图把所有信息塞进一个统一的记忆系统，然后指望模型自己能在里面找到答案。

Claude Code的做法完全相反，它把记忆拆成了domain，然后用索引来导航。

这更像人的记忆模式。

你想想看，人的记忆也不是一个巨大的桶，而是分块的。你记得"上次项目踩的坑"存在某个脑区，"这个用户的习惯"存在另一个脑区。当你需要回忆的时候，你先定位是哪类信息，然后调取对应的内容。

三层架构其实就是把这个认知模型落地了。

索引就是导航，domain文件就是分块的存储。

这个设计不一定是最优的，但它很"human-aligned"。

---

当然，这个架构也有问题。

文章里提到了几个，我觉得都挺真实的。

一是多Agent并发写冲突。如果你跑好几个Claude Code实例在同一个项目，它们可能会抢着更新同一个记忆文件。

二是没有语义检索。索引模式适合你知道大概哪个domain relevant，但如果需要跨domain语义搜索，纯文件指针不太管用，得加embedding层。

三是记忆漂移。时间长了，记忆文件里可能积累过时或矛盾的信息，self-healing机制能缓解，但依赖Agent自己注意到矛盾，subtle的漂移可能会持续很久。

四是存储开销。如果你的记忆系统依赖远程API调用来读写，那指针索引的结构会增加latency。

这些都不是致命伤，但如果你要把这个模式移植到自己的Agent系统，得提前想清楚怎么处理。

---

说到移植，我觉得这个三层架构其实是一个通用的设计模式。

不一定要用Claude Code，任何Agent都可以用。

核心就是三点，定义清晰的memory domain，建一个只存指针的索引文件，给Agent显式的读写工具。

domain怎么分，取决于你的Agent做什么。

如果是客服Agent，你可以分customer-history、product-knowledge、open-issues、escalation-rules。

如果是coding Agent，就分project-context、decisions、code-patterns、user-preferences。

关键是，索引文件要"写保护"，不要每次学点什么新东西都去改索引，只在添加新domain或指针失效的时候才动。

真正的知识增长，发生在domain文件里。

然后给Agent真正的读写能力，不是让它"想象"自己能写，是给它read_memory(domain)、**write_memory(domain, content)**这样的实际函数。

这些函数里要加校验逻辑，写之前检查格式，更新索引之前检查指针是不是指向真实文件。

再加一个静态配置层，类似CLAUDE.md，存那些每个session都必须加载的稳定context。

最后，如果你的Agent要长期跑，加一个周期性的reconciliation步骤，让它定期审查记忆文件，清理过时和矛盾的内容。

这套东西不需要什么特殊技术栈，只要你的模型支持tool use就行。

---

我有时候觉得，Agent这个领域，大家太关注模型能力了，反而忽略了系统设计。

三层记忆架构之所以好用，不是因为Claude模型有多聪明，是因为这个结构本身就是对的问题拆解方式。

它把"记忆"从一个模糊的概念，拆成了三个具体的层次，每个层次有明确的职责、明确的生命周期、明确的读写规则。

这种结构化思维，才是Agent能真正干活的关键。

模型能力当然重要，但模型能力之上，还得有对的scaffolding。

没有好的架构，聪明的模型也只是在一个混乱的系统里瞎转。

有了对的架构，模型才能把能力落到具体的任务上，并且持续积累。

---

回到我开头说的那个瞬间。

当我看到Claude Code开始写memory.md的时候，我突然意识到，它不是在"假装"有记忆，是真的在维护一个持久的知识库。

而且这个知识库就在我本地的文件系统里，我能看到，能改，能审计。

那一刻我觉得，这才是Agent该有的样子。

不是每次都从零开始的对话机器，是一个能记住、能学习、能跟你一起长大的协作伙伴。

三层架构不一定完美，但它指出了一个方向。

Agent的记忆，不应该是一个黑盒，应该是一个透明的、结构化的、Agent自己维护的系统。

这个方向，我觉得是对的。

---

谢谢你看我的文章，我们下次再见。

小明的IT世界
​

​