Agent 系统整体架构
主流程图
记忆与上下文管理机制
在Claude Code中，上下文主要包括两部分
- 动态拼装的系统提示词
- 记忆系统其中记忆系统又分为短期记忆，中期记忆和长期记忆
流程图
短期记忆是 Claude CLI 的实时交互层，主要负责管理当前会话中的消息流。这一层直接对应用户与 Claude 的实时对话，所有的用户输入、助手回复、工具调用结果都在此层进行处理。它的特点是响应快速、容量有限、动态更新。
中期记忆层是整个系统的核心创新，将大量的短期记忆信息浓缩为高密度的语义表示，在保持上下文连续性的同时大幅减少Token消耗。它的特点是持久化存储、结构化组织、智能压缩和上下文连续，能大幅节省Token 。使用短期记忆后的 token 数达到 92% 的阈值后，会触发中期记忆层的逻辑
长期记忆负责用户偏好学习、配置持久化、使用模式分析等。它的特点是持久存储、智能学习、模式识别。 短期记忆和中期记忆只存在于某次会话中，为了保存重要逻辑，会话结束时的重内容持久化，这个持久话的内容就是长期记忆。当然，用户也可以主动的往长期记忆中添加内容 长期记忆触发机制
Compact
手动触发或在 context 不足时触发，会将当前上下文压缩为一个文本，并作为下一次对话的初始信息，起到 context 空间压缩的效果。 执行压缩时，system prompt 会加载 system compact prompt，并在当前 context 的末尾增加 compact prompt 指导 LLM 基于特定的格式完成压缩。
流程图
Sub Agent
Claude Code 设计了 Sub Agent 系统，实现方式是通过加载 Task Tool，通过提示词引导模型在需要执行特定的独立任务时，可以通过调用该工具，发起一个 Sub Agent。 Claude Code Sub Agent 作为一种 Multi Agent 的具体形态，有它的特殊设计：
- 始终有 Main Agent 的概念（用户最初交互的对象）。
- 发起一个 Sub Agent 时，会从 main context 提取需要处理的任务，作为 sub context 的初始提示词。
- Sub Agent 完成任务之后，会将最终结果作为 tool result 返回 main context
这样的设计让 Sub Agent 成为优化 main context 空间的一种有效方式。因为在一些独立任务中（例如「从代码库中查找特定函数的实现」），在多轮的 Agent tool call/result 中，会产生大量与最终所需结果无关的上下文（例如搜索到了无关的文件，读取后被 LLM 排除）。Sub Agent 可以让这些「脏上下文」被隔离在 sub context 中，随着 Sub Agent 任务完成而消失，而 main context 中只保留需要的结果。
流程图
TodoWrite
在复杂的软件开发项目中，常常需要完成一些耗时较长、跨越多个阶段和会话的任务。为了应对这些挑战，Claude Code 采用了一套长期任务管理系统，该系统以 TodoWrite 为核心，提供全面的任务持久化管理。TodoWrite 不仅负责维护任务清单，还负责同步任务状态、跟踪任务进度，并提供智能建议。这套系统确保了即使面对有限的上下文窗口，AI 也能始终专注于正确的目标，避免偏离方向。
流程图
在 system workflow prompt 的「Task Management」中，定义了基于 TodoWrite 工具的任务管理方法。 TodoWrite 执行时会实际向 ~/.claude/todos/ 创建一个 JSON 文件，记录当前对话中的 Todo，作为短时记忆。Todo 完成时，模型也会使用该工具更新 JSON 文件。
触发条件的具体实现：
- 复杂多步骤任务 - 通过TodoWriteTool.prompt.ts:12-17中的规则判断
- 非平凡复杂任务 - 系统提示中的"VERY frequently"指导
- 用户明确要求 - 直接调用TodoWriteTool.call()
- 多任务列表 - 通过TodoItemSchema数组处理
- 任务状态管理 - 通过状态机(pending → in_progress → completed) 提醒机制: 实时监控: 通过事件系统监听待办事项变化 智能提醒: 避免重复提醒，基于状态哈希 上下文感知: 只在有上下文时注入提醒 性能优化: 提醒缓存和批量处理