Claude Code 上下文管理深度解读：源码视角下的 Agent 记忆机制

背景

在构建基于 LLM 的 Coding Agent（如 Claude Code）时，上下文管理（Context Management）是决定系统稳定性、响应速度及成本效率的核心模块。随着会话轮数的增加，用户与 AI 的交互消息、工具调用结果会迅速填满 Context Window。这不仅受限于 Transformer 模型的注意力机制特性（长上下文易导致注意力分散和噪音污染），还受到实际 Context Window 容量的硬性约束。

尽管网上存在大量关于 Claude Code 源码的分析文章，但许多内容被指出为 AI 生成或追逐热点，缺乏深度且准确性存疑。为了获得可信的技术洞察，本文基于对 Claude Code 泄露源码的亲自研读，重点解析其上下文管理的实现逻辑。作者借助 CodeX 辅助阅读源码，通过梳理 src 目录下的关键文件，整理出一套关于会话恢复、工具结果处理及多种压缩策略的学习笔记。这些内容不仅用于个人理解，还将作为 Prompt 输入给 Coding Agent 项目，用于重新设计 feature/context 分支。

核心内容

Claude Code 的上下文管理旨在解决长会话中的信息过载问题，其核心机制围绕 Canonical Transcript（权威抄本）、工具结果预算控制以及多层级的压缩策略展开。

Canonical Transcript：会话的唯一真源

Canonical Transcript 是会话恢复的唯一信息来源，通常以 JSONL 格式存储于 ~/.claude/projects/{project_name}/{session_id}.jsonl。每一轮对话或工具执行都会记录在此文件中。除了 JSONL 文件外，同名的会话 ID 文件夹下还包含 subagents 和 tool-results 子文件夹，用于存储更细粒度的数据。

在 JSONL 结构中，工具结果的处理尤为精妙，主要涉及两个字段：

1. message.content：实际发送给 LLM 的内容。经过加工，可能包含行号、安全提醒、压缩标记（如 <persisted-output>）等。
2. toolUseResult：工具调用的结构化原始结果，用于前端 UI 渲染和会话恢复。例如，当工具消息被压缩后，UI 仍需根据原始结果统计读取行数，而非压缩后的内容。

工具结果预算控制（Tool Result Budget）

为了防止单个工具产生过大的结果导致上下文溢出，Claude Code 引入了基于阈值的持久化机制。

1. 阈值定义与持久化逻辑 每个工具内置声明了 maxResultSizeChars。当结果超过阈值时，内容会被持久化到 ~/.claude/projects/{project_name}/{session_id}/tool-results/{tool_use_id}.txt，最大保留 64MB，超出则截断。前端不再渲染具体结果，而是显示标记。

不同类别的工具阈值如下：

• Shell 工具 (Bash, PowerShell): 30,000 字符
• 搜索工具 (Grep): 20,000 字符
• 认证工具 (McpAuth): 10,000 字符
• 其他普通工具: 50,000 字符
• Read 工具: 特殊处理

2. Read 工具的特殊处理 由于读取超大文件若直接外置会导致 .txt 文件依然巨大，Read 工具采用了分段读取策略：

• 默认限制 maxSizeBytes 为 256KB，maxTokens 为 25K。
• 通过 offset 和 limit 参数控制读取起始行和行数。
• 若参数相同且文件未修改，直接返回 file_unchanged。
• 结果写入 JSONL 时，message.content 包含带行号的文本（进入上下文），而 toolUseResult 保留结构化元数据（用于 UI 渲染）。

3. 聚合逻辑 若单个工具未超阈值，但同一轮次多个并行工具结果合并后超过 MAX_TOOL_RESULTS_PER_MESSAGE_CHARS（200K 字符），系统会从最新、最大的结果开始外置，并在 JSONL 中写入 content-replacement metatdata 标记。

上下文压缩策略

Claude Code 采用多种压缩策略来应对上下文压力，主要模块包括 Tool Result Budget、History Snip、Microcompact 和 Auto-Compact。其中，Auto-Compact 是检测上下文压力并执行最终压缩的核心，分为 Session Memory Compact 和 Full Compact。

1. Microcompact：微压缩 Microcompact 旨在通过清理过时或冗余的工具结果来减少上下文体积，分为两种路径：

• Time-based Microcompact（基于时间）

  • 触发条件：当前时间与最后一条 assistant message 的时间戳差距超过阈值（默认 60 分钟，即 gapThresholdMinutes）。
  • 原理：LLM API 服务端通常对 Prompt 有缓存机制（TTL）。若时间过久，缓存失效，重新计算所有 Context 的开销巨大。因此，在发送请求前，主动清理旧的工具结果，以减少需要重新计算的内容量。
  • 白名单机制：仅对可通过结构化参数重新获取或信息量较低的工具生效，包括 Read, Shell, Grep, Glob, WebSearch, WebFetch, Edit, Write。
  • 保留策略：保留最近的 5 个工具结果（keepRecent = 5），其余替换为 [Old tool result content cleared]。此操作仅影响发送给 LLM 的上下文，不修改 Canonical Transcript。

• Cached Microcompact（基于缓存编辑）

  • 原理：利用 API 服务端的缓存编辑能力，在缓存仍存在时，直接删除缓存中旧的上下文部分。这是 Claude Code 独占的高级特性，旨在进一步降低 API 调用成本。

2. 其他压缩模块

• History Snip：通过 feature('HISTORY_SNIP') 控制，具体实现未在本文源码分析中详述。
• Context Collapse：通过 feature('CONTEXT_COLLAPSE') 控制，具体实现未知。
• Auto-Compact：检测上下文压力，执行 Session Memory Compact 或 Full Compact，确保上下文窗口始终处于可控状态。源码中预留了 MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20,000 的空间，以保证压缩摘要的正常生成。

关键要点

• 单一真源：Canonical Transcript（JSONL）是会话恢复和数据一致性的基石，区分了“给 LLM 看的加工内容”和“给 UI/恢复用的原始内容”。
• 精细化的工具结果管理：不同工具类型拥有不同的字符阈值（10K-50K），超限结果自动外置为 .txt 文件，避免污染上下文窗口。
• Read 工具的优化：针对大文件读取，采用分段读取（Offset/Limit）和元数据分离策略，既保证 LLM 获取关键信息，又避免上下文爆炸。
• Time-based Microcompact 的成本意识：通过清理旧工具结果，减少因 API 缓存失效导致的重复计算开销，体现了对 LLM 推理成本（Token 计算量）的深刻理解。
• 白名单机制：微压缩并非对所有工具生效，仅针对可复现或低信息密度的工具，确保关键上下文不被误删。
• 预留压缩空间：系统预留 20,000 Tokens 用于生成摘要，确保在上下文接近上限时仍能执行压缩操作。

意义与影响

Claude Code 的上下文管理设计为构建高效的 Coding Agent 提供了重要的工程实践参考：

1. 从“被动存储”到“主动管理”：传统的 Agent 往往被动地将所有历史消息堆叠，而 Claude Code 通过预算控制和微压缩，主动管理上下文的生命周期，显著提升了长会话的稳定性。
2. 成本与性能的平衡：通过 Time-based Microcompact 和 Cached Microcompact，系统不仅减少了 Token 消耗，还优化了 API 调用延迟，证明了在 Agent 系统中，上下文管理不仅是功能需求，更是成本优化的关键手段。
3. 数据结构的解耦：将