05. 上下文与记忆管理¶
Claude Code 的上下文不是一个单一提示词，而是多层材料的编排。每一层都有不同的来源、刷新时机和可信度。本地运行时会在有限上下文窗口里选择当前任务最有用、最一致、最可恢复的信息。
模型回答质量不只取决于模型能力，还取决于本地运行时把哪些事实、规则、工具结果和长期记忆放进本次采样。上下文过少，模型会失去现场；上下文过多，模型会被旧输出、噪声和过期规则干扰。Claude Code 将上下文拆成层，再按任务阶段重新编排。
最底层是系统提示。默认系统提示描述智能体的基本行为、工具使用规范、交互约束和输出风格。入口可以追加自定义系统提示。自定义提示会改变默认提示是否注入，因此查询引擎在构造上下文时会先判断提示来源，再决定是否加入默认行为描述、记忆机制提示和额外系统段落。
项目规则和用户规则通常来自 CLAUDE.md 系列文件。本地运行时会从当前工作目录向上查找项目级和本地级规则，也会读取用户级、托管级和额外目录中的规则。规则有优先级：越接近当前项目、越明确的规则通常越靠近模型注意力位置。文件还支持 @include，运行时会解析 Markdown 文本中的包含指令，限制递归深度，避免循环，并跳过代码块里的包含指令。带 frontmatter paths 的规则可以按路径条件启用，而不是在所有任务里无条件注入。
系统上下文与用户上下文不是同一层。用户上下文主要承载用户和项目给智能体的长期指令，例如 CLAUDE.md、当前日期、某些用户记忆。系统上下文更像运行环境快照，例如当前 git 分支、主分支、git 用户、工作区状态和最近提交。git 状态在会话开始时快照化，避免每次采样都把变化中的环境重新解释为全新事实。
长期记忆又分几种。CLAUDE.md 更像显式规则，用户或项目直接维护；AutoMem、TeamMem 或 MEMORY.md 体系更像可更新的经验库。文件型记忆通常会有入口文件和分文件结构，入口文件保存索引或指针，具体记忆按主题写入其他文件。这样模型不必每次读取全部长期记忆，而是先通过入口理解有哪些记忆，再在需要时读取更细的内容。记忆提示会告诉模型什么适合保存、如何分类、什么时候读取、哪些内容不应该写入长期记忆。
历史消息是动态上下文的主干。用户输入、助手回复、工具调用、工具结果、压缩摘要都会进入历史。但查询循环每次发请求前不会盲目使用完整转录记录。它会从压缩边界之后选择有效消息，处理过大的工具结果，必要时对旧上下文做压缩。工具输出特别容易撑爆上下文，所以本地运行时会根据工具的最大结果大小、总 token 预算和当前窗口压力做截断或摘要。
已读文件状态是另一种重要记忆。模型读取文件后，本地运行时不只是把文件内容作为一次工具结果发给模型，还会记录哪些文件被读过、哪些内容可能需要在压缩后恢复。发生压缩时，历史中的大量细节会被摘要替代，但运行时会尽量把最近读过且仍有价值的文件片段重新作为附件注入。这样压缩后模型不会只剩一段抽象摘要，而还能重新看到关键代码上下文。
压缩是上下文管理的核心恢复机制。当 token 接近窗口阈值时，自动压缩会构造摘要请求，让模型把旧对话压缩成新的摘要消息。压缩不是简单删除历史：它会运行压缩前后钩子，生成边界标记，保存转录路径，清理已读文件状态，重新附加计划、已调用技能、异步智能体结果、动态工具差异、MCP 指令差异等材料。压缩后的消息列表更短，但运行时会尽量保留继续任务所需的工作记忆。
恢复和分叉依赖转录记录。恢复会话时，运行时会读取 JSONL，沿父子关系重建主线，跳过已删除标记或被压缩取代的片段，并恢复文件历史、归因、任务、智能体元数据和内容替换记录。分叉技能或子智能体会产生自己的转录分支，但仍保留与父会话的关联。这样主智能体可以把子任务结果作为附件或工具结果带回主线，而不必把子智能体的全部过程塞进当前上下文。
上下文丢失时，系统会优先保住任务目标、最近工具结果、已读关键文件和仍需遵守的规则。摘要遗漏用户限制时，模型可能在压缩后偏离原约束；工具输出截断过多时，模型可能重复已经失败的路径；长期记忆注入过多时，旧经验会污染当前任务。因此 Claude Code 把规则、历史、已读文件、压缩摘要和长期记忆分成不同通道，分别控制刷新和恢复。
Claude Code 的“记忆”不是一个数据库字段，而是一组进入模型上下文的通道。CLAUDE.md 决定规则，MEMORY.md 决定长期经验，转录记录决定会话连续性，已读文件缓存决定代码观察，压缩决定窗口压力下保留什么，恢复/分叉决定这些材料如何重新组合。下一章会继续说明模型流式采样如何消费这些上下文。