乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > Claude Code源码解密:智能体循环与记忆系统的最佳实践

Claude Code源码解密:智能体循环与记忆系统的最佳实践

当前时间： 2026-04-08 00:46:35 更新时间： 2026-04-08 分类：软件教程 评论(0)

Claude Code源码解密:智能体循环与记忆系统的最佳实践

一、事件回放

正常情况下，你下载的 Claude Code 安装包里只包含编译后的 .js 文件，这种文件经过了代码混淆，机器能跑、人看不懂，无法逆向工程。

而 2026 年 3 月 31 日，被推送到 npm 公共仓库的 @anthropic-ai/claude-code 2.1.88 版本，随包附带了一个 59.8 MB 的 .map 文件。

.map 文件是 Bun 为 JavaScript 项目生成的源码映射文件，用于方便调试。这类文件在发布正式 npm 包时应通过 .npmignore 或者在 package.json 的 files 字段排除。

如果安装文件中忘记排除 .map 文件，任何人只要运行 npm install，就能在本地硬盘上找到原始代码文件。比如，本次 .map 文件里面包含完整的可读 TypeScript 源码，约 1,900 个文件，512,000 行代码。

因为 Claude Code 是目前非常成功的一个 Agent 产品，因此这个事给了开发者研究 Claude Code 的一个机会，本文是对 Claude Code 源码的一个解读。特别关注，Claude Code 的智能体循环和记忆系统部分。

二、智能体循环（Agent Loop）

首先，通过源码分析，我们可以确定一件事，Claude Code没有任何魔法，所有的核心都是建立在下面这个Agent Loop之上的。其他的代码都是在做辅助工作（Harness Engeneering），让Agent Loop发挥的更好。某种程度上，可以认为 Harness = Agent – Model。

上面这段代码通过一个无限循环，持续将当前对话上下文与可用工具列表发送给大模型，根据模型的停止原因判断是否需要继续操作：若模型需要调用工具获取信息，则执行对应的工具函数，并将执行结果追加到对话上下文中，供下一轮模型推理使用；若模型已生成最终答案、无需再调用工具，则跳出循环，完成任务。整个流程形成了 “模型推理→工具执行→结果反馈→再推理” 的闭环，让 AI 能够自主完成复杂的多步骤任务。

  • Agent Loop执行前

此时，消息列表（messages）是空的。

  • Agent Loop执行后

这里执行了两次tool_use（read_file、edit_file）。消息列表一共产生了6条消息。当assistant没有进一步的tool_use（stop_reason=”end_turn”），本次Loop终止。

系统提示词（System Prompt）

Agent Loop中系统提示词非常重要。Claude Code 的 System Prompt 包含下述4个部分。

  • CLAUDE.md ：由用户手动编写的项目级配置文件，是 Claude Code 针对当前项目的「宪法级」指令，优先级最高。
  • Tools（40）：Claude Code 内置的 40+ 可调用工具，让能直接操作你的本地项目环境：读文件、改代码、跑命令、查错误，这是 Claude Code 能替代人工写项目的核心。
  • Memory：Claude Code 维护的持久化记忆系统，解决大模型「上下文窗口有限、对话遗忘」的痛点。所有记忆文件都会在每次你向 Claude Code 提问时，自动被加载进 System Prompt。
  • Context：当前会话的动态实时上下文，是 Claude 每次推理的「输入素材」，随对话持续更新。核心包含内容：用户提问与历史对话、工具执行结果、项目实时状态、系统环境信息等。

总之，CLAUDE.md 定规则 → Tools 给能力 → Memory 存经验 → Context 做输入，四者联动，让 Claude Code 成为能自主完成复杂开发任务的「AI 编程助手」。

三、记忆系统

记忆系统是Agent最难设计的部分，我们深入考察下Claude Code是如何设计记忆系统的。Claude Code 的记忆管理涉及三个部分：Memory Extraction（记忆提取）、Session Memory（会话记忆）、Auto Dream（自动整理）。其中，记忆提取和自动整理维护的是长期记忆，会话记忆维护的是临时记忆。

  • 记忆提取（Memory Extraction）：会话时，在后台实时提取的碎片记忆信息
  • 会话记忆（Session Memory）：Token长度超限时，（自动/手动）触发压缩生成的摘要
  • 自动整理（Auto Dream）：会话结束后进行的总结与归纳

记忆类别

为避免长期记忆漂移并保证高质量召回，Claude Code将长期记忆分为四大类。每个大类可以有多个记忆文件。

  • 用户记忆（User）：个人偏好、角色设定
  • 反馈记忆（Feedback）：来自用户的修正、建议或肯定
  • 项目记忆（Project）：项目相关的信息，背景、目标、进度等
  • 参考记忆（Reference）：外部文档的获取路径等

记忆的存储

从权限范围看，Claude Code将长期记忆分为私人记忆和团队记忆。

  • 私人记忆 ：存储路径为 ~/.claude/memory，作用范围当前用户（存在你电脑本地，别人看不到）。
  • 团队记忆：存储路径为project/memory/team，作用范围为所有用户（存在项目文件夹里，提交 Git 后团队都能用）。

每个记忆存储里都有一个 MEMORY.md 文件，这是记忆的索引。

  • 私人记忆（~/.claude/memory）
memory/├── MEMORY.md           私人总索引├── user.md             你的习惯├── feedback.md         你的偏好├── conventions.md      你的代码风格└── ...其他私人主题文件




    

  • 

    团队记忆（project/memory/team）
    

    • 



team/├── MEMORY.md           团队总索引├── project.md          项目架构├── team.md             团队规范├── tech-stack.md       项目技术栈├── issues.md           项目坑点└── ...其他团队主题文件




记忆提取（Memory Extraction）


Claude Code 内置一套 记忆系统，让智能体能够持续学习用户习惯、项目偏好与高频模式。与普通会话日志不同，记忆会被保存为结构化的 Markdown 文件，在未来会话中直接被系统提示词读取使用。


记忆提取过程通常以后台子智能体的形式运行，使用 extractMemories 提示词执行。记忆提取模块会启动一个专用子智能体，它是主对话模型的 “完整复刻分支”，专门用于记忆梳理。该子智能体分析最近的对话轮次，并自动更新：MEMORY.md（记忆索引文件）和各主题独立记忆文件（user.md、feedback.md等）。


会话记忆（Session Memory）


会话记忆仅在当前会话有效，会话结束即失效。会话记忆的保存地址为~/.claude/session-memory.md，并且有固定的模版，包括标题、当前状态、任务说明、文件和函数、工作流程、错误和修正、代码库和系统文档、经验总结、关键结果、工作记录。


当会话接近Token长度上限时，Claude Code 会进行记忆压缩以保留关键上下文。主要逻辑如下：


    

  1. 

    微压缩（Micro-Compact）
    

    2. 



每次对话都会出发，将较早的工具返回结果替换为简短摘要。自动执行，模型无感。


    

  1. 

    自动压缩（Auto-Compact）
    

    2. 



将完整对话总结为一个精简块，在达到Token长度上限时自动触发。Auto-Compact 在需要时，直接使用已经准备好的结构化摘要session-memory.md（并且，不主动更新长期记忆）。


注意，session-memory.md 不是等 Auto-Compact时才产生，而是「会话一开始就创建，每一轮对话都实时增量更新」。会话记忆由主流程实时进行，没有独立的子Agent。


    

  • 

    Token长度超限的上下文窗口
    

    • 





    

  • 

    压缩后的上下文窗口
    

    • 





    

  1. 

    手动压缩（/compact）
    

    2. 



用户任何时候都可以主动触发压缩（/compact）。使用 /compact会重新生成、强化、补全 session-memory.md，让它更完整、更结构化，相当于主动做一次高质量会话总结。然后，/compact 会主动触发Memory Extraction 从刚更新好的 session-memory.md 里提取知识 去重、归类、写入长期记忆文件。


自动整理（Auto Dream）


Auto Dream是一个跨会话运行的整合服务，通过 “梦境式梳理”（总结、归纳、结构化），将累积的对话记录提炼为更高层次的认知与洞察。


Auto Dream默认是不开启的。开启后，在会话结束后，AI 会回顾对话内容，并对学到的信息进行整理归纳。每次会话结束后，Auto Dream作为会话结束后的后置钩子运行，自动梳理整段对话，提取出有价值、值得保留的信息，并写入记忆目录中。


AutoDream 整理后的记忆，保存在私人记忆目录～/.claude/memory/ 中，与记忆提取系统共享同一套 Markdown 存储结构，不会创建新的文件夹或格式，只会对现有记忆文件进行归纳、精炼与整合，让 AI 拥有更清晰、更高质量的长期记忆。


四、总结


本文对Clause Code的关键部分 智能体循环、记忆系统 进行了揭秘。通过对Claude Code源码研究和学习，我们可以吸收智能体构建的最佳实践，从而设计好自己的Agent系统（智能客服等）。这再很大程度上也可以缓解我们的AI焦虑。


总的来说，几个经验是值得借鉴的。首先，我们应该优先使用Agent Loop自主规划工具使用，而不是用传统的意图分发。这要求工具的整理必须清晰，提示词的设计必须全面。最后，为了理解当前的状态和用户的下一步意图，一个非常好的记忆系统也是必须的。