learnNote

主题

深度解析 Claude Code 的 Memory 策略与演进路径

角色（Role） ​

你是一位资深的 AI Coding Agent 架构师，长期跟踪 Anthropic Claude Code、Cursor、Codex CLI、Cline、Aider 等主流 Coding Agent 的设计与演进。你擅长从**上下文工程（Context Engineering）**视角拆解 Agent 的记忆机制，并能将抽象的设计理念转化为可落地的工程实践。

任务（Task） ​

请围绕 Claude Code 的 Memory 策略，输出一份深度、系统、可追溯的研究报告。报告需要满足两个核心要求：

  1. 深度而详细：完整呈现 Claude Code 当前的 Memory 体系（包含分层结构、加载机制、写入触发、压缩策略、与工具调用的交互等），不能停留在 README 级别的描述。
  2. 演进视角：清晰展现 Claude Code 的 Memory 方案是如何一步一步迭代优化的——每一次变化解决了什么痛点、引入了什么新问题、又是如何被下一版方案弥补的。

上下文与边界（Context） ​

  • 关注对象：Anthropic 官方的 Claude Code（CLI / IDE 插件 / Cloud Agent 形态均可涉及）。
  • 时间范围：从 Claude Code 早期发布到当前最新版本的公开信息。
  • 信息来源：Anthropic 官方文档、官方博客、CHANGELOG、社区逆向分析、对比同类产品（Cursor、Codex CLI、Cline 等）作为参照。
  • 若存在未公开或不确定的细节，请明确标注 [推测] 或 [未公开]，不要编造具体版本号或 API 名称。

输出结构（Output Format） ​

请严格按以下章节组织，使用 Markdown 输出：

1. 概览：什么是 Claude Code 的 Memory ​

  • 一句话定义
  • 与 "Context Window"、"Session State"、"RAG"、"Persistent Memory" 的边界区分
  • 一张 Mermaid 架构图（展示记忆的分层与数据流向）

2. 当前 Memory 体系的完整拆解 ​

按以下维度逐项展开（每项都要给出作用、存储位置、生命周期、加载时机、写入方式、典型示例）：

  • 项目级记忆：CLAUDE.md / AGENTS.md
  • 用户级记忆：~/.claude/CLAUDE.md 等全局配置
  • 子目录/模块级记忆（嵌套 CLAUDE.md 的合并规则）
  • 会话级记忆（对话历史、TodoWrite、临时上下文）
  • 工具级记忆（MCP、Skills、Hooks 与记忆的协同）
  • 长期记忆与外部知识（如 /memory 命令、# 快捷写入等交互）

3. 演进时间线（核心章节） ​

用阶段化叙事呈现 Memory 方案的迭代过程，每个阶段必须包含四要素：

【阶段 N】方案名称

  • 痛点：上一阶段暴露了什么问题？
  • 方案：本阶段引入了什么新机制？关键设计决策是什么？
  • 取舍：为此付出了什么代价（性能、复杂度、用户心智负担）？
  • 遗留问题：为下一阶段埋下了什么伏笔？

建议覆盖（但不限于）以下演进阶段：

  1. 纯 Prompt 注入阶段（无持久化记忆）
  2. 单文件 CLAUDE.md 项目记忆
  3. 分层记忆（用户级 + 项目级 + 子目录级）
  4. 快捷写入与 /memory 命令
  5. 与 Skills / Subagents / Hooks 的协同
  6. 上下文压缩（Auto-Compact）与会话续接
  7. 跨会话/跨设备的云端记忆（如 Cloud Agent 场景）
  8. [推测] 未来可能的方向（向量化、结构化记忆图谱等）

4. 关键设计原则提炼 ​

从演进过程中归纳 3–5 条可复用的设计原则，例如：

  • "显式优于隐式" 在记忆写入上的体现
  • "用户可读、可改、可版本化" 的工程约束
  • 上下文窗口预算的优先级管理
  • ……

5. 与同类产品的横向对比 ​

用表格对比 Claude Code、Cursor、Codex CLI、Cline 在 Memory 维度上的差异：

维度Claude CodeCursorCodex CLICline
项目记忆载体…………
全局记忆…………
写入触发方式…………
上下文压缩策略…………
跨会话续接…………

6. 落地启示 ​

如果我要为自己的 Coding Agent 设计 Memory 系统，从 Claude Code 的演进中可以直接借鉴的 5 条工程实践是什么？请给出具体到"文件命名 / 加载顺序 / 优先级冲突解决"的可执行建议。

7. 参考资料 ​

列出引用的官方文档、博客、CHANGELOG 链接；社区分析文章单独标注 [社区]。

质量要求（Quality Bar） ​

  • 深度：每个机制至少回答 "What / Why / How / Trade-off" 四个问题，避免泛泛而谈。
  • 可追溯：所有非常识性结论都要给出来源或标注 [推测]。
  • 结构化：多用表格、Mermaid 图、对比清单，少用大段散文。
  • 批判性：不只描述"是什么"，更要分析"为什么这样设计"以及"它的局限"。
  • 篇幅：不少于 3000 字，不为了凑字数堆砌。

禁止事项（Don'ts） ​

  • 不要编造具体的 API 名称、配置项或版本号。
  • 不要把 "CLAUDE.md 是一个 Markdown 文件" 这类常识反复展开。
  • 不要简单复述官方文档，必须有你自己的拆解和归纳。