Claude Code 内存系统Memory System使用指南四类记忆、保存触发机制与生命周期管理【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha本指南围绕本项目cc-hahaClaude Code 的本地优先跨平台桌面工作区所实现的文件化持久记忆系统展开完整讲解记忆的四种分类、三种触发保存的方式、磁盘上的存储结构与索引规范以及记忆从写入、检索、失效到后台整合AutoDream的完整生命周期。读完本文你将掌握如何让 Agent 跨会话记住你的身份、偏好与项目背景知道记忆文件放在哪里、如何手动编辑与禁用并理解这套系统在源码层面的实现原理。什么是内存系统Memory SystemClaude Code 的内存系统是一个基于文件的持久化知识存储Agent 在多次会话中持续积累对你的了解、你的偏好以及项目正在发生的事并将这些信息以普通 Markdown 文件的形式保存下来供未来的对话随时取用。系统遵循一条核心原则只记住那些无法从代码本身推断出来的事情。应该记住Remembered不应该记住Not Remembered你是专注于日志系统的数据科学家代码架构、文件结构不要 mock 数据库Git 历史、谁改了什么周四之后冻结非关键合并已有的 CLAUDE.md 内容Bug 跟踪在 Linear 的 INGEST 项目中调试方案修复已经写进代码里了这条边界在源码中被显式固化。在 memoryTypes.ts 的WHAT_NOT_TO_SAVE_SECTION中系统明确列出了禁止入档的内容代码模式与架构、Git 历史、调试方案、CLAUDE.md 已有内容、以及临时性的任务细节进行中的工作、当前对话上下文。值得注意的是即使用户显式要求保存这些排除规则依然生效——如果你要求保存一份本周 PR 列表模型会被引导去追问这份列表里令人惊讶或非显而易见的部分那才是值得记住的内容。内存系统总览从会话中的信息到持久化文件与索引的完整闭环。四种记忆类型Four Memory TypesClaude Code 将记忆严格划分为四种类型。在源码中这一分类通过MEMORY_TYPES常量定义memoryTypes.tsexport const MEMORY_TYPES [ user, feedback, project, reference, ] as const每种类型在系统提示词中都配有独立的type说明块包含when_to_save何时保存、how_to_use如何使用和具体示例帮助模型在保存时正确归类。User用户画像记录你的角色、目标、技能水平与偏好帮助 Claude 调整协作方式。这类记忆始终是私人的scope 为 always private。用户说我写 Go 写了十年但这是我第一次碰这个仓库的 React 部分 Claude 保存Go 经验深厚React 新手——用后端的类比来解释前端概念Feedback行为反馈你对 Claude 工作方式的纠正或肯定。这类记忆防止 Claude 重复犯同样的错误。用户说回复结尾不要再总结你做了什么我能看到 diff Claude 保存用户偏好简洁回复不要结尾总结重要不仅纠正会被记录肯定也会。当 Claude 做出一个非显而易见的选择并且你表示认可时同样会入档。源码中对此有明确说明如果只记录纠正模型会避免过去的错误却会偏离那些已经被你验证过的方法变得过度谨慎Record from failure AND success。并且 feedback 记忆在保存前会检查是否与团队级 feedback 记忆冲突。Project项目上下文无法从代码或 Git 历史中推导的项目背景谁在做什么、为什么、截止时间。用户说周四之后我们冻结所有非关键合并移动团队要切发布分支 Claude 保存合并冻结自 2026-03-05 开始此日期后的非关键 PR 工作需标记注意Claude 会将用户消息中的相对日期Thursday转换为绝对日期2026-03-05确保记忆不会随时间的流逝而变得含糊。源码的when_to_save指令也强调项目状态变化较快保存时务必把相对日期换算成绝对日期。Reference外部引用指向外部系统中信息的指针仪表盘、问题跟踪器、Slack 频道。用户说值班人员监控 grafana.internal/d/api-latency 仪表盘 Claude 保存grafana.internal/d/api-latency 是值班延迟仪表盘——修改请求路径代码时需检查四类记忆User、Feedback、Project、Reference每种都有独立的保存时机与使用指引。如何触发记忆保存记忆保存的三条触发路径对话结束后的自动提取、用户显式请求、以及命令行工具。方法一自动提取最常见Automatic Extraction这是最主要的方式。你什么都不用做——Claude 会在每一轮对话结束时自动分析对话内容提取值得记住的信息。工作流程你与 Claude 进行正常对话Claude 完成回复没有待执行的工具调用一个**记忆提取子代理memory extraction subagent**在后台启动子代理分析最近的对话内容识别值得保存的记忆写入记忆文件并更新 MEMORY.md 索引终端会显示一条通知Memory updated in ~/.claude/projects/.../memory/feedback_testing.md · /memory to edit在源码层面这个流程由executeExtractMemories()驱动extractMemories.ts完整链路包括守卫检查必须是主代理、特性开关开启、自动记忆启用、非远程模式、无并发提取→ 频率控制turnsSinceLastExtraction未达阈值则跳过→ 互斥检查主代理已自行写入则跳过→ 扫描现有记忆目录生成清单scanMemoryFilesformatMemoryManifest→ 构建提取提示词 → 通过runForkedAgent启动最多 5 轮的分叉子代理与主会话共享提示词缓存、隔离执行、工具权限受限、不记录转录→ 提取写入的文件路径 → 通知用户。这里有两处值得注意的工程细节互斥机制hasMemoryWritesSince(messages, sinceUuid)会扫描sinceUuid之后所有助手消息中的 Edit/Write 工具调用如果主代理已经写入了记忆目录后台提取就会跳过并推进游标避免重复保存。合并机制如果上一次提取仍在运行新上下文会进入队列pendingContext旧提取完成后立即启动一次尾部提取tail extraction只处理两次调用之间新增的消息。方法二显式请求直接告诉 Claude 记住这个用户记住这个项目部署前必须运行 bun test Claude[立即保存为 feedback 类型记忆]系统提示词中明确要求如果用户显式要求你记住某件事立即以最合适的类型保存它。If the user explicitly asks you to remember something, save it immediately as whichever type fits best.方法三/memory 命令在终端输入/memory打开一个文件选择器直接在你的编辑器中编辑记忆文件 /memory该命令会列出所有可编辑的记忆文件CLAUDE.md、CLAUDE.local.md、auto-memory 等并用你的$EDITOR或$VISUAL打开所选文件。方法四/remember 命令输入/remember触发记忆审查技能memory review skill它会审查所有自动记忆条目提议将合适的条目提升到 CLAUDE.md 或 CLAUDE.local.md检测重复、过期与冲突的记忆不会直接修改任何内容——所有变更都需要你的批准记忆存储在哪里目录结构~/.claude/ └── projects/ └── {project-path-hash}/ └── memory/ - 自动记忆目录 ├── MEMORY.md - 索引文件始终载入上下文 ├── user_role.md - 用户画像记忆 ├── feedback_testing.md - 行为反馈记忆 ├── project_freeze.md - 项目上下文记忆 ├── reference_linear.md - 外部引用记忆 └── team/ - 团队共享记忆如启用 ├── MEMORY.md └── ...从源码看默认路径并非简单的{project-path-hash}getAutoMemPath()paths.ts使用findCanonicalGitRoot(getProjectRoot())获取仓库规范根目录再做路径净化sanitizePath这意味着同一仓库的所有 worktree 会共享同一个自动记忆目录。路径解析优先级为CLAUDE_COWORK_MEMORY_PATH_OVERRIDE环境变量Cowork 场景的全路径覆盖settings.json中的autoMemoryDirectory用户设置支持~/展开默认计算路径{memoryBase}/projects/{sanitized-git-root}/memory/其中memoryBase由CLAUDE_CODE_REMOTE_MEMORY_DIR环境变量或~/.claude决定getAutoMemPath以项目根目录为缓存键做了 memoize避免每次工具调用渲染时重复解析设置文件。记忆文件格式每个记忆文件使用YAML frontmatter Markdown 正文--- name: Testing strategy preference description: Integration tests must use a real database, no mocking type: feedback --- Integration tests must use a real database, no mocking. **Why:** Last quarter, mocked tests passed but production migrations failed — mock/production divergence masked the issues. **How to apply:** When writing or reviewing tests, ensure database operations use real connections.frontmatter 中的type字段取值必须是四种类型之一缺失或非法值会优雅降级parseMemoryType对旧文件返回 undefined保持兼容。对于 feedback 和 project 类型正文推荐采用规则/事实 Why:原因 How to apply:应用时机的结构因为知道为什么能让模型在边界情况下做出判断而不是机械照搬规则。MEMORY.md 索引文件MEMORY.md 是索引而非内容它始终被载入上下文每个条目一行- User role — Data scientist, focused on observability/logging - Testing strategy — Integration tests use real DB, no mocking - Merge freeze — Non-critical merges frozen starting 2026-03-05 - Bug tracking — Pipeline bugs tracked in Linear INGEST project限制最多200 行或 25KB超出部分会被截断。源码中的truncateEntrypointContent()memdir.ts实现了双重限制先按行数截断到 200 行再按字节数在最后一个换行符处截断处理超长行最后追加警告 WARNING: MEMORY.md is {reason}. Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.同时系统提示词会指导模型遵循两步保存法第一步把记忆写入独立文件第二步在 MEMORY.md 中追加一行指针- Title — one-line hook建议单行 150 字符以内并明确永远不要把记忆正文直接写进 MEMORY.md。另外值得一提的是ensureMemoryDirExists()加载提示词时会递归创建记忆目录幂等吞掉 EEXIST并把目录已存在写进提示词避免模型浪费轮次去执行ls或mkdir。如何管理记忆让 Claude 忘记用户忘掉关于合并冻结的记忆 Claude[找到并删除相关记忆文件与索引条目]系统提示词同样覆盖了这条路径如果用户要求你忘记某件事找到并移除相关条目。让 Claude 忽略记忆用户忽略记忆从零开始 Claude[本次对话不使用任何记忆内容]在源码中WHEN_TO_ACCESS_SECTION对忽略语义做了非常细致的界定如果用户说ignore或not usememory模型应当像 MEMORY.md 为空一样工作——不应用记住的事实、不引用、不对比、也不提及记忆内容。这条规则是经过评估eval验证的此前模型容易把忽略误解为先承认再覆盖导致回复中仍出现如记忆所述式的引用。手动编辑直接编辑~/.claude/projects/{hash}/memory/下的文件或使用/memory命令。禁用自动记忆方法操作环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY1设置文件在settings.json中设置autoMemoryEnabled: false裸模式以--bare启动或设置CLAUDE_CODE_SIMPLE1源码中isAutoMemoryEnabled()paths.ts的完整检查链为CLAUDE_CODE_DISABLE_AUTO_MEMORY1 - 禁用 CLAUDE_CODE_SIMPLE (--bare) - 禁用 远程模式且未设置 REMOTE_MEMORY_DIR - 禁用 settings.json 的 autoMemoryEnabled - 跟随设置 默认 - 启用自定义记忆目录在~/.claude/settings.json中设置{ autoMemoryDirectory: ~/my-claude-memories }支持~/展开。出于安全考虑项目级.claude/settings.json不允许设置此选项。validateMemoryPath()paths.ts会对候选路径做严格校验拒绝以下危险路径被拒绝的路径原因../foo相对路径依赖 CWD/或/a根路径或过短路径C:\Windows 盘符根\\server\shareUNC 网络路径包含\0空字节可在系统调用中被截断此外~/展开后会拒绝规范化结果为.或..的路径如裸~、~/..防止把整个$HOME或上级目录暴露为记忆根目录。之所以禁止项目级设置是因为恶意仓库可能设置autoMemoryDirectory: ~/.ssh从而借助文件系统写入豁免获得对敏感目录的静默写权限。记忆生命周期Memory Lifecycle对话中学习到的新信息 | 自动提取 / 显式保存 | 写入记忆文件 索引 | 下一次对话加载 MEMORY.md | 智能选择相关记忆Sonnet | 注入对话上下文 | 记忆变旧使用前先验证 | 已过期更新或删除 | 经过 24h 5 个会话后 | AutoDream 在后台整合记忆记忆的读取侧智能检索与新鲜度每次用户发送查询时findRelevantMemories()findRelevantMemories.ts会触发一次回忆流程scanMemoryFiles(memoryDir)递归读取所有.md文件排除 MEMORY.md解析前 30 行 frontmatter按修改时间降序排列最多 200 个文件——采用单趟先读后排序设计避免重复 stat 系统调用过滤掉之前已经展示过的记忆alreadySurfaced格式化清单formatMemoryManifest每行形如- [type] filename (ISO时间戳): description用Sonnet 模型sideQuery做选择输出 JSON{ selected_memories: string[] }最多选 5 条返回选中记忆的{ path, mtimeMs }选择器的系统提示词要求只选择确定有用的记忆不确定就不选列表为空就返回空如果提供了最近使用的工具列表不要选那些工具的使用文档但要选关于它们的警告/坑/已知问题。返回结果会带出 mtime供调用方附加新鲜度信息。新鲜度管理由 memoryAge.ts 实现今天/昨天的记忆直接使用memoryFreshnessText返回空字符串不附加警告超过 1 天的记忆附带过期警告提醒 Claude 引用前先验证例如This memory is 47 days old. Memories are point-in-time observations, not live state — claims about code behavior or file:line citations may be outdated. Verify against current code before asserting as fact.涉及文件路径/函数名的记忆使用前通过 grep 确认其仍然存在这套先验证再断言的规则同样固化在系统提示词的TRUSTING_RECALL_SECTIONBefore recommending from memory中记忆声称某函数、文件或标志存在只是写入记忆那一刻存在的声明它可能已被重命名、删除或从未合并——记忆说 X 存在不等于X 现在存在。AutoDream——做梦整理记忆Claude Code 内置了一个隐藏的AutoDream特性类比人类大脑在睡眠中整理记忆。满足以下条件时Claude 会在后台静默启动一个做梦子代理距离上次整合至少 24 小时期间至少积累了 5 个会话在源码层面AutoDream 的触发是一套五道门five-gate机制autoDream.ts按成本从低到高依次检查#门说明成本1特性开关isAutoDreamEnabled()且非 KAIROS、非远程模式、自动记忆已启用读取内存2时间门距上次整合至少minHours默认 24h1 次 stat3扫描节流距上次扫描至少 10 分钟才重新扫描时间戳比较4会话门距上次整合至少minSessions默认 5不含当前个新会话目录扫描5锁门没有其他进程正在做梦PID 锁文件stat readconst DEFAULTS: AutoDreamConfig { minHours: 24, // 距上次整合至少 24 小时 minSessions: 5, // 期间至少积累 5 个会话 }AutoDream 的执行入口在stopHooks.ts的 stop 钩子阶段fire-and-forget不阻塞主线程。以下场景不会触发KAIROS 模式使用独立的磁盘技能做梦、远程模式、自动记忆未启用、--bare/SIMPLE 模式、以及子代理内部只有主代理触发。做梦过程包含四个阶段Orient定向→ Gather收集→ Consolidate整合→ Prune修剪Orientls记忆目录读取 MEMORY.md 索引理解现有知识结构浏览已有主题文件避免重复创建检查logs/或sessions/子目录中的近期条目Gather按优先级收集信息——① 每日日志logs/YYYY/MM/YYYY-MM-DD.md追加流日志② 漂移记忆与当前代码库状态矛盾的事实③ 会话转录搜索在 JSONL 转录文件中做窄范围 grep提示词明确要求不要穷尽阅读转录文件只找你已经怀疑重要的内容Consolidate将新信号合并进现有主题文件而非创建近重复文件、把相对日期转成绝对日期yesterday → 2026-04-03、删除已被取代的旧事实Prune and Index更新 MEMORY.md 使其保持在行数限制与 25KB 以内、移除过期记忆的指针、压缩冗长条目超过 200 字符的索引行内容移入主题文件、添加重要记忆的指针、解决冲突两个文件不一致时修正错误的那一个AutoDream 子代理受严格工具权限约束extractMemories.ts 中共享的createAutoMemCanUseTool允许Read / Grep / Glob —— 不受限 允许Bash —— 仅只读命令ls, find, grep, cat, stat, wc, head, tail 允许Edit / Write —— 仅限自动记忆目录内 拒绝MCP / Agent / 非只读 Bash / 其他写操作并发控制依靠.consolidate-lock锁文件consolidationLock.ts锁内容为持有者 PID锁文件 mtime 即上次整合时间持有超过 1 小时视为过期防止 PID 复用问题两个进程同时写入时后写者获胜、败者重读后退出失败时 mtime 回滚到获取前的值崩溃后过期 mtime 死亡 PID由下一个进程回收锁。UI 呈现运行期间底部状态栏显示dreaming标签pillLabel.ts 中case dream: return dreaming按ShiftDown可打开后台任务对话框查看实时进度审查的会话数、当前阶段starting→updating、最近助手文本与工具调用数、触达的文件路径列表按x可终止触发 abort 锁回滚。完成后若有文件被修改主会话内会出现内联通知appendSystemMessageverb: Improved。AutoDream 的开关通过settings.json控制{ autoDreamEnabled: true }显式设置时直接采用用户的值未设置时由远程 GrowthBook 特性开关tengu_onyx_plover控制可配置enabled、minHours默认 24、minSessions默认 5详见 config.ts除了自动触发还可以通过/dream命令手动触发记忆整合手动触发会调用recordConsolidation()更新锁文件时间戳。更详细的实现分析见 AutoDream Memory Consolidation系统内部的完整技术拆解路径解析、提示词注入、检索与团队同步见 Memory System Internals。快速参考操作方法让 Claude 记住记住这个项目用 bun不用 npm让 Claude 忘记忘掉关于 XXX 的记忆编辑记忆/memory命令审查与整理/remember命令忽略记忆忽略记忆 / 不要使用记忆禁用自动记忆CLAUDE_CODE_DISABLE_AUTO_MEMORY1禁用 AutoDream在settings.json中设置autoDreamEnabled: false手动整合记忆/dream命令查看记忆目录~/.claude/projects/{hash}/memory/关键源码索引文件职责src/memdir/paths.ts记忆目录路径解析、~/展开与安全校验、启用条件src/memdir/memdir.ts系统提示词注入、MEMORY.md 截断策略、目录自动创建src/memdir/memoryTypes.ts四类记忆的定义、保存/使用规则与提示词模板src/memdir/memoryScan.ts记忆目录扫描、frontmatter 解析、清单格式化src/memdir/memoryAge.ts记忆年龄计算与过期警告生成src/memdir/findRelevantMemories.tsSonnet 智能检索最多返回 5 条相关记忆src/services/extractMemories/extractMemories.ts后台自动提取、互斥与合并机制、工具权限src/services/autoDream/autoDream.tsAutoDream 主逻辑五道门检查、分叉代理、进度监控src/services/autoDream/consolidationLock.ts锁文件机制并发防止、时间戳、回滚与崩溃恢复src/services/autoDream/consolidationPrompt.ts四阶段整合提示词小结这套内存系统的设计哲学可以浓缩为两点只保存不可从代码推导的信息以及索引与内容分离MEMORY.md 始终载入、主题文件按需检索。结合自动提取、Sonnet 智能回忆、新鲜度警告与 AutoDream 后台整合Claude Code 得以在每次对话中低成本地持续构建关于你与项目的长期知识同时把记忆漂移的风险降到最低——这正是它区别于普通上下文窗口的关键所在。【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考