1. 问题Agent 面临两大核心困境进程级失忆Agent 的记忆仅存于会话内存中进程重启后一切归零跨会话需重新认知。有损压缩不可逆受限于上下文窗口历史对话必须被压缩但压缩会导致关键细节如“用 Tab”退化为“有代码偏好”永久丢失且摘要无法跨会话传递。2. 核心解法Harness 层的“四层记忆架构”为了解决“关掉重开全不知”Claude Code 建立了独立于会话进程的持久化文件仓库~/.claude/projects/.../memory/。其核心逻辑是“索引常驻 按需加载 永不压缩”。第一层永久索引MEMORY.md机制项目根目录下的.memory/MEMORY.md文件。它不存细节只存指针每行一个链接限制 200 行 / 25KB。 Claude Code自动记录和学习的“经验”比如你的调试过程、架构决策或特定偏好。它的设计是与项目Git 仓库强绑定的路径结构如下~/.claude/projects/项目名/memory/加载每次会话启动时该索引自动注入 System Prompt利用 Prompt Cache 缓存不额外消耗大量 token。MEMORY.md 有⼀个硬性限制前 200 ⾏或前 25KB以先到者为准。超过这个阈值的内容不会⾃动加载。为什么要限制因为每次会话都要加载 MEMORY.md如果它膨胀到 5000 ⾏光索引就要吃掉⼤量上下⽂窗⼜——这就又回到了把百科全书塞进⼜袋的⽼路。作用让 Agent 每次启动时至少知道“有哪些事是重要的”。使用方法系统自动维护通过用户在聊天过程中的偏好表达自动存储。例如当你说“请记住这个项目使用 TypeScript 5.0”、“我喜欢用双引号而不是单引号”或“这个函数应该总是返回 Promise”时Claude 会自动提取这些偏好创建对应的记忆文件并更新 MEMORY.md 索引。第二层按需深度加载Topic Files Skill机制每个记忆是一个独立的.md文件带 YAML frontmatter包含name/description/type。加载逻辑Side-query每轮用户提问时Agent 通过一次轻量级 LLM 调用根据当前对话内容从索引中筛选出最相关的≤5 个记忆文件读取完整内容注入到当前user turn而非注入 System Prompt避免破坏缓存。Skill 加载技能同样遵循分层注入。System Prompt 只放技能名称Layer 1约 100 token/个只有当 Agent 主动调用load_skill时才返回完整的技能 Markdown 正文Layer 2。使用方法https://blog.csdn.net/m0_73980980/article/details/161300753?spm1001.2014.3001.5501第三层项目实时配置CLAUDE.md机制区别于长期记忆CLAUDE.md用户级、项目级、目录级属于环境上下文。特点在每轮对话前动态重新加载包含当前 Git 分支、最近的 commit 信息。修改该文件无需重启会话即时生效告诉 Agent “在这个项目里当下该怎么工作”。使用方法/init 命令在新项目中使用/initClaude 会扫描代码库并自动生成一个初始的 CLAUDE.md 文件。这是一次性的、由用户主动发起的操作。自然语言指令你可以直接通过对话要求 Claude 更新记忆。例如输入“更新 CLAUDE.md在这个项目中永远使用 bun 而不是 npm”Claude 便会代为修改文件。/memory 命令手动编辑当前项目的 CLAUDE.md 文件进行精细化的配置管理。第四层Transcripts——只搜不加载的档案机制历史对话记录的完整存档。这些 Transcripts 文件存储在~/.claude/projects/项目名/transcripts/目录下按会话和时间戳组织。加载策略永远不加载到上下文中。Transcripts 层采用“只搜不加载”原则只能通过grep、ag等搜索工具进行检索。工作流程当 Agent 需要回忆“三天前我们讨论过什么”或“上次关于某个函数的讨论”时它会搜索 Transcripts 目录但搜索结果只以摘要形式返回完整的历史文本不会进入上下文。设计原理为什么这一层这么严格因为历史对话的体量可能是天文数字——一周的高频使用可能产生几十万 token 的对话记录。如果允许直接加载上下文窗口瞬间就满了。通过“搜索→摘要”模式Agent 既能获取历史信息又不会耗尽宝贵的上下文资源。使用场景追溯历史决策过程查找之前讨论过的技术方案回顾项目演进历程验证某个功能是否曾经实现过3. 永久索引MEMORY.md记忆的写入与提取Extract Memories解决了“读”的问题还要解决“写”的问题。用户不会总说“请记住”偏好常散落在正常对话中。触发时机在 Agent 循环结束时触发即一轮对话结束。执行逻辑去重与纪律截取最近的对话。读取现有的记忆列表防止重复。调用 LLM 提取新的偏好、约束或项目事实返回 JSON 数组{name, type, description, body}。每种类型都配有详细的 XML 格式描述包含 when_to_save 何时保存、 how_to_use如何使⽤和 ⽰例对话——这些描述直接注⼊到系统提⽰词中指导 Agent 的记忆⾏为。写入纪律工业级要求先写入具体的.md文件再更新MEMORY.md索引。防止索引指向一个未成功写入的“幽灵文件”。使用前验证记忆是“提示Hint”而非“真理Truth”。Agent 在使用记忆中的路径或函数名前必须先通过ls或grep确认其当前是否存在防止记忆老化导致误操作。4. 永久索引MEMORY.md记忆的整理与巩固Auto Dream记忆文件会随使用越来越多且可能产生矛盾或过时信息。Claude Code 通过Auto Dream类似人类 REM 睡眠解决认知熵增。触发机制四层门控时间门控距上次整理 ≥ 24 小时。节流门控避免频繁扫描文件系统。会话门控自上次整理以来已修改了 ≥ 5 个会话。锁门控确保没有其他进程正在整理通过.consolidate-lock文件。执行过程Fork 一个独立的子 Agent上下文与主 Agent 完全隔离。该子 Agent 处于“只读梦境”状态受限权限只能读写记忆文件不能修改项目代码。执行 6 项认知整理工作审查全貌 →强化有效信息 →删除过时内容 →解决矛盾保留最新 →转化模糊洞察为确定事实 →重组索引。安全兜底梦境不会污染现实Auto Dream ⼦ Agent 的⼯具访问是受限的。它可以读写记忆⽂件但不能执⾏ bash 命令、不能修改项⽬代码、不能发起⽹络请求。。即使 Dream 误判删除了某个记忆Agent 在实际使用时依然会通过工具验证现实环境而非盲目相信记忆。总结维度自动记忆 (Auto Memory)CLAUDE.mdSkill核心定位Agent 的“长期工作经验”自动记录对话中的偏好、决策与项目事实Agent 的“员工手册”静态的项目规则、编码规范与上下文说明Agent 的“专业知识库”按需加载的专项领域操作指南存储位置~/.claude/projects/项目名/memory/按 Git 项目隔离分层存储• 用户级~/.claude/CLAUDE.md• 项目级./CLAUDE.md• 本地级./CLAUDE.local.md./.claude/skills/*/SKILL.md项目内或全局技能目录写入/更新方式系统自动每轮对话结束时由extract_memories()自动提取并写入用户手动通过/init生成或用户/Claude 主动编辑或#指令追加用户手动开发者预先编写好技能文件Claude 按需读取是否自动更新✅是每轮结束后静默自动提取新记忆❌否必须用户发起指令才会修改❌否静态文件内容固定加载方式索引常驻 正文按需•MEMORY.md索引注入 System Prompt• 正文通过 Side-query 检索 Top-K 注入当前轮次全量常驻所有层级的CLAUDE.md内容在每轮对话前自动加载到 System Prompt渐进式披露• Layer 1名称描述常驻 System Prompt• Layer 2完整内容通过load_skill工具按需注入作用域项目隔离不同 Git 仓库的记忆互不可见分层叠加用户级所有项目共享 项目级当前项目 本地级个人覆盖项目绑定技能目录通常位于项目内特定项目可用内容类型动态的、对话中涌现的信息如“用户偏好 Tab 缩进”、“auth 重写是合规驱动”静态的、预先定义好的规则如“用 pnpm 安装”、“测试用 Vitest”结构化的长文本指南如“PDF 处理完整步骤”、“代码审查检查清单”典型用途• 记住用户偏好• 追踪项目当前状态• 积累历史决策• 设定编码规范• 说明项目架构• 提供常用命令• 提供专业领域知识• 执行复杂多步骤流程• 封装专家经验记忆是否可被压缩永不压缩独立存储不参与上下文压缩确保细节无损永不压缩作为 System Prompt 的一部分不参与压缩永不压缩按需加载不占用常驻上下文窗口用户可见性低黑盒运行但可通过/memory查看高直接可见的 Markdown 文件中技能列表可见内容调用后可见维护成本低系统自动维护定期由 Auto Dream 整理中需手动维护但使用频率高高需预先编写和测试技能内容 三者协作关系在实际工作流中三者互补协作场景谁在起作用“这个项目用 Vitest 而不是 Jest”→CLAUDE.md项目规则“用户上次说偏好 Tab 而非空格”→自动记忆跨会话召回“怎么对 PDF 进行加密签名”→Skill按需加载专业知识“根据用户偏好为新文件使用 Tab 缩进”→自动记忆提供约束 CLAUDE.md提供代码风格规则简单记忆口诀记忆记偏好自动手册定规则CLAUDE.md技能存方法Skill——三者各司其职共同构筑 Agent 的完整知识体系。