1. 为什么你的 Claude Code 第二天就“失忆”了如果你正在用 Claude Code 做项目大概率遇到过这个场景第一天你花了半小时跟它讲清楚项目的构建命令、测试脚本、目录约定它配合得像个老搭档。第二天开个新会话你问它“上次那个 auth 模块改到哪了”它一脸茫然地反问你“请问您指的是哪个文件”。这不是模型变笨了而是它的记忆没有跨会话留存。Claude Code 的记忆系统其实不是“一个记忆文件”那么简单它由三层后台工作流组成分别对应三个时间尺度当前会话内的工作笔记Session Memory、跨轮次写入磁盘的持久记忆Auto Memory Extraction、以及跨多次会话的整合修剪Auto Dream。这三层都尽量不阻塞主对话用的是逻辑上的 forked agent能复用父级 prompt cache把额外开销压到接近一次旁路 LLM 调用。这篇面向想给 AI 编程搭档加持久记忆的开发者给出settings.json与config.toml的可复制骨架并演示一次记忆写入与跨会话召回验证。目标很明确把“一次性对话”变成可复现的有记性搭档。下面所有配置都基于 TaoToken 提供的 API 接入方式你可以直接照着改。2. 前置准备用 TaoToken 把 Claude Code 接起来在动记忆配置之前得先让 Claude Code 能稳定跑起来。我习惯用 TaoToken 做统一入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先去控制台建一个 Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成密钥 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后环境变量这样设Linux/macOS 写进~/.zshrc或~/.bashrcWindows 用系统环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥如果你用的是 Claude Code 的配置文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 } }注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要带/v1Claude Code 会自己拼路径。写错了会报 404这是最常见的接入坑。验证接入是否成功跑一条最小请求curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role:user,content:回复 OK 两个字母}] }返回里能看到content字段带OK说明链路通了。这一步过了再往下配记忆否则后面所有报错你都会怀疑是记忆配置的问题。3. 三层记忆的可复制配置骨架三层记忆的配置分散在两个文件里~/.claude/settings.json管功能开关和阈值~/.claude/config.toml管记忆目录和模板路径。先给一份能直接用的骨架。3.1 settings.json 骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, memory: { sessionMemory: { enabled: true, minimumMessageTokensToInit: 10000, minimumTokensBetweenUpdate: 5000, toolCallsBetweenUpdates: 3, templatePath: ~/.claude/session-memory/config/template.md, promptPath: ~/.claude/session-memory/config/prompt.md }, autoExtraction: { enabled: true, maxTurns: 5, skipTranscript: true, memoryDir: ~/.claude/projects/slug/memory }, autoDream: { enabled: true, minHours: 24, minSessions: 5, scanIntervalMs: 600000, lockFile: memory/.consolidate-lock, holderStaleMs: 3600000 } } }三个阈值解释一下minimumMessageTokensToInit是首次提取门槛低于 10K token 不初始化避免刚开对话就写一堆没用的笔记minimumTokensBetweenUpdate是后续更新门槛上次提取后至少再涨 5K token 才更新toolCallsBetweenUpdates是工具调用次数门槛至少 3 次。注意 token 增长是必须条件即使工具调用达标但 token 没涨够也不会触发这是防止频繁提取的关键设计。3.2 config.toml 骨架[memory.session] template ~/.claude/session-memory/config/template.md summary_dir {projectDir}/{sessionId}/session-memory summary_file summary.md max_section_tokens 2000 max_total_tokens 12000 [memory.extraction] memory_root ~/.claude/projects/{slug}/memory index_file MEMORY.md max_entrypoint_lines 200 max_entrypoint_bytes 25000 manifest_max_files 200 [memory.dream] log_dir logs/{yyyy}/{mm} consolidate_lock memory/.consolidate-lockmax_section_tokens和max_total_tokens是 Session Memory 的硬上限超标时 prompt 会加入 CRITICAL 级别的压缩指令。max_entrypoint_lines和max_entrypoint_bytes是 MEMORY.md 索引的截断保护先按行截断再按字节兜底超标会在末尾附 warning 告诉模型只加载了部分索引。3.3 Session Memory 模板骨架~/.claude/session-memory/config/template.md默认有 10 个固定 section你可以按项目类型改。做后端服务的可以这样# Session Title # Current State # Task specification # Files and Functions # Workflow # Errors Corrections # Codebase and System Documentation # Learnings # Key results # Worklog每个 section 有约 2K token 上限总文件 12K token。更新时 forked agent 用 Edit 工具就地编辑prompt 里有严格约束不允许修改、删除、新增 section 标题只能更新标题下方的内容。这个约束很重要否则模型会自作主张重构你的模板。4. 验证一次记忆写入与跨会话召回配置写完得验证它真的在工作。分两步先看当前会话有没有生成 summary.md再开新会话看持久记忆有没有被加载。4.1 触发 Session Memory 写入开一个新会话让 Claude Code 做点实际工作比如读几个文件、跑一次测试。当 token 增长到 10K 以上且工具调用超过 3 次Session Memory 会初始化。你可以用这条命令观察文件是否生成ls -la ~/.claude/projects/*/*/session-memory/summary.md如果看到文件且内容里有# Current State、# Worklog这些 section说明第一层在工作。文件路径形态是{projectDir}/{sessionId}/session-memory/summary.md注意不是放在~/.claude/session-memory/config/下那个目录只存模板和更新 prompt。4.2 触发 Auto Memory Extraction让对话自然收尾也就是模型给出最终回答、不再有 tool call。这时handleStopHooks()会 fire-and-forget 触发提取。检查持久记忆目录ls -la ~/.claude/projects/slug/memory/ cat ~/.claude/projects/slug/memory/MEMORY.md正常情况下你会看到几个 topic 文件加一个MEMORY.md索引。提取 agent 的 turn 数被限制为 5源码注释说“行为良好的提取 2-4 轮完成读→写”硬上限是防止它陷入验证代码的死循环。4.3 跨会话召回验证关掉当前会话开一个新的问一个只有上次会话才知道的问题比如“上次我们改的那个 auth 中间件放在哪个目录”。如果它答对了说明持久记忆被加载进上下文了。基础形态是把MEMORY.md作为索引加载实验分支会在每轮 query 前按需召回最多 5 个相关 memory 文件。想更直观地看召回可以在新会话里让它列出当前加载的记忆文件# 在 Claude Code 会话里输入 请列出你当前上下文里加载的 memory 文件路径如果它报出~/.claude/projects/slug/memory/下的文件名召回链路就通了。4.4 触发 Auto Dream 整合Dream 的触发条件是距上次整合 ≥24 小时且 ≥5 个新会话。想快速验证可以临时把minHours改成 0、minSessions改成 1跑几次会话后观察ls -la ~/.claude/projects/slug/memory/.consolidate-lock锁文件的 mtime 就是上次整合时间内容是持有者 PID。整合完成后主对话会显示 “Improved N memory files” 的系统消息。验证完记得把阈值改回去否则每次会话结束都触发整合token 消耗会很难看。5. 本篇常见错排查配置记忆系统时踩的坑基本集中在这几类。报 404 或 401先查ANTHROPIC_BASE_URL有没有多写/v1或末尾斜杠。TaoToken 的地址就是https://taotoken.net/apiClaude Code 自己拼/v1/messages。401 一般是 Key 没设对或者环境变量没生效用echo $ANTHROPIC_AUTH_TOKEN确认一下。summary.md 一直不生成检查 token 有没有涨到 10K。很多人开个会话问两句话就等文件那肯定不触发。另外确认settings.json里sessionMemory.enabled是 true且模板文件路径存在。模板文件不存在时不会报错只是静默不初始化。MEMORY.md 被截断丢信息这是设计上的硬限200 行 25KB。长期项目记忆量大时截断不可避免靠 Auto Dream 的修剪缓解。如果你发现关键记忆总被截掉可以手动精简 topic 文件或者把不常用的记忆归档到子目录。Dream 不触发按四步 gating 顺序查。先看时间门minHours默认 24 小时刚配好肯定不触发再看扫描节流10 分钟内不会重复扫目录然后看会话门需要 ≥5 个新会话且排除当前会话最后看锁门如果.consolidate-lock的 mtime 新鲜且 PID 存活会静默跳过。PID 已死或超过 1 小时会直接接管。提取写入重复文件提取前会扫描 memory 目录把现有文件列表最多 200 个作为 manifest 注入 prompt避免创建重复文件。如果你看到重复可能是 manifest 扫描被截断了检查manifest_max_files配置。主 Agent 和后台 Agent 写冲突如果主 Agent 在对话中已经手动写了记忆文件后台提取会跳过这一段只推进游标。这是hasMemoryWritesSince的互斥策略不是 bug。想强制后台提取就别在对话里手动写 memory 文件。6. 把记忆流水线跑成长期搭档三层记忆跑通之后你的 Claude Code 就从“一次性工具”变成了“有记性的搭档”。采集靠 Session Memory持久化靠 Auto Memory Extraction整合靠 Auto Dream每层成本和时间尺度不同但共用同一个架构模式后台 forked agent prompt cache 共享 权限沙箱。如果你还想继续调优可以从这几个方向入手。模型对话验证召回效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 对比不同模型在提取质量上的差异长期编码和 Agent 场景用 Coding Plan 把记忆流水线跑在稳定配额上 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 专用接入说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。最后留一个我实测下来最实用的技巧把~/.claude/projects/slug/memory/目录纳入 git 管理每次 Dream 整合后 commit 一次。这样你能清楚看到记忆是怎么演化的哪条记忆被合并、哪条被修剪出问题时也能回滚。记忆系统最怕的不是写错而是写错了你还不知道。
Claude Code 三层记忆系统拆解：Session Memory 到 Auto Dream 的配置骨架
1. 为什么你的 Claude Code 第二天就“失忆”了如果你正在用 Claude Code 做项目大概率遇到过这个场景第一天你花了半小时跟它讲清楚项目的构建命令、测试脚本、目录约定它配合得像个老搭档。第二天开个新会话你问它“上次那个 auth 模块改到哪了”它一脸茫然地反问你“请问您指的是哪个文件”。这不是模型变笨了而是它的记忆没有跨会话留存。Claude Code 的记忆系统其实不是“一个记忆文件”那么简单它由三层后台工作流组成分别对应三个时间尺度当前会话内的工作笔记Session Memory、跨轮次写入磁盘的持久记忆Auto Memory Extraction、以及跨多次会话的整合修剪Auto Dream。这三层都尽量不阻塞主对话用的是逻辑上的 forked agent能复用父级 prompt cache把额外开销压到接近一次旁路 LLM 调用。这篇面向想给 AI 编程搭档加持久记忆的开发者给出settings.json与config.toml的可复制骨架并演示一次记忆写入与跨会话召回验证。目标很明确把“一次性对话”变成可复现的有记性搭档。下面所有配置都基于 TaoToken 提供的 API 接入方式你可以直接照着改。2. 前置准备用 TaoToken 把 Claude Code 接起来在动记忆配置之前得先让 Claude Code 能稳定跑起来。我习惯用 TaoToken 做统一入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。先去控制台建一个 Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成密钥 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后环境变量这样设Linux/macOS 写进~/.zshrc或~/.bashrcWindows 用系统环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥如果你用的是 Claude Code 的配置文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 } }注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要带/v1Claude Code 会自己拼路径。写错了会报 404这是最常见的接入坑。验证接入是否成功跑一条最小请求curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role:user,content:回复 OK 两个字母}] }返回里能看到content字段带OK说明链路通了。这一步过了再往下配记忆否则后面所有报错你都会怀疑是记忆配置的问题。3. 三层记忆的可复制配置骨架三层记忆的配置分散在两个文件里~/.claude/settings.json管功能开关和阈值~/.claude/config.toml管记忆目录和模板路径。先给一份能直接用的骨架。3.1 settings.json 骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, memory: { sessionMemory: { enabled: true, minimumMessageTokensToInit: 10000, minimumTokensBetweenUpdate: 5000, toolCallsBetweenUpdates: 3, templatePath: ~/.claude/session-memory/config/template.md, promptPath: ~/.claude/session-memory/config/prompt.md }, autoExtraction: { enabled: true, maxTurns: 5, skipTranscript: true, memoryDir: ~/.claude/projects/slug/memory }, autoDream: { enabled: true, minHours: 24, minSessions: 5, scanIntervalMs: 600000, lockFile: memory/.consolidate-lock, holderStaleMs: 3600000 } } }三个阈值解释一下minimumMessageTokensToInit是首次提取门槛低于 10K token 不初始化避免刚开对话就写一堆没用的笔记minimumTokensBetweenUpdate是后续更新门槛上次提取后至少再涨 5K token 才更新toolCallsBetweenUpdates是工具调用次数门槛至少 3 次。注意 token 增长是必须条件即使工具调用达标但 token 没涨够也不会触发这是防止频繁提取的关键设计。3.2 config.toml 骨架[memory.session] template ~/.claude/session-memory/config/template.md summary_dir {projectDir}/{sessionId}/session-memory summary_file summary.md max_section_tokens 2000 max_total_tokens 12000 [memory.extraction] memory_root ~/.claude/projects/{slug}/memory index_file MEMORY.md max_entrypoint_lines 200 max_entrypoint_bytes 25000 manifest_max_files 200 [memory.dream] log_dir logs/{yyyy}/{mm} consolidate_lock memory/.consolidate-lockmax_section_tokens和max_total_tokens是 Session Memory 的硬上限超标时 prompt 会加入 CRITICAL 级别的压缩指令。max_entrypoint_lines和max_entrypoint_bytes是 MEMORY.md 索引的截断保护先按行截断再按字节兜底超标会在末尾附 warning 告诉模型只加载了部分索引。3.3 Session Memory 模板骨架~/.claude/session-memory/config/template.md默认有 10 个固定 section你可以按项目类型改。做后端服务的可以这样# Session Title # Current State # Task specification # Files and Functions # Workflow # Errors Corrections # Codebase and System Documentation # Learnings # Key results # Worklog每个 section 有约 2K token 上限总文件 12K token。更新时 forked agent 用 Edit 工具就地编辑prompt 里有严格约束不允许修改、删除、新增 section 标题只能更新标题下方的内容。这个约束很重要否则模型会自作主张重构你的模板。4. 验证一次记忆写入与跨会话召回配置写完得验证它真的在工作。分两步先看当前会话有没有生成 summary.md再开新会话看持久记忆有没有被加载。4.1 触发 Session Memory 写入开一个新会话让 Claude Code 做点实际工作比如读几个文件、跑一次测试。当 token 增长到 10K 以上且工具调用超过 3 次Session Memory 会初始化。你可以用这条命令观察文件是否生成ls -la ~/.claude/projects/*/*/session-memory/summary.md如果看到文件且内容里有# Current State、# Worklog这些 section说明第一层在工作。文件路径形态是{projectDir}/{sessionId}/session-memory/summary.md注意不是放在~/.claude/session-memory/config/下那个目录只存模板和更新 prompt。4.2 触发 Auto Memory Extraction让对话自然收尾也就是模型给出最终回答、不再有 tool call。这时handleStopHooks()会 fire-and-forget 触发提取。检查持久记忆目录ls -la ~/.claude/projects/slug/memory/ cat ~/.claude/projects/slug/memory/MEMORY.md正常情况下你会看到几个 topic 文件加一个MEMORY.md索引。提取 agent 的 turn 数被限制为 5源码注释说“行为良好的提取 2-4 轮完成读→写”硬上限是防止它陷入验证代码的死循环。4.3 跨会话召回验证关掉当前会话开一个新的问一个只有上次会话才知道的问题比如“上次我们改的那个 auth 中间件放在哪个目录”。如果它答对了说明持久记忆被加载进上下文了。基础形态是把MEMORY.md作为索引加载实验分支会在每轮 query 前按需召回最多 5 个相关 memory 文件。想更直观地看召回可以在新会话里让它列出当前加载的记忆文件# 在 Claude Code 会话里输入 请列出你当前上下文里加载的 memory 文件路径如果它报出~/.claude/projects/slug/memory/下的文件名召回链路就通了。4.4 触发 Auto Dream 整合Dream 的触发条件是距上次整合 ≥24 小时且 ≥5 个新会话。想快速验证可以临时把minHours改成 0、minSessions改成 1跑几次会话后观察ls -la ~/.claude/projects/slug/memory/.consolidate-lock锁文件的 mtime 就是上次整合时间内容是持有者 PID。整合完成后主对话会显示 “Improved N memory files” 的系统消息。验证完记得把阈值改回去否则每次会话结束都触发整合token 消耗会很难看。5. 本篇常见错排查配置记忆系统时踩的坑基本集中在这几类。报 404 或 401先查ANTHROPIC_BASE_URL有没有多写/v1或末尾斜杠。TaoToken 的地址就是https://taotoken.net/apiClaude Code 自己拼/v1/messages。401 一般是 Key 没设对或者环境变量没生效用echo $ANTHROPIC_AUTH_TOKEN确认一下。summary.md 一直不生成检查 token 有没有涨到 10K。很多人开个会话问两句话就等文件那肯定不触发。另外确认settings.json里sessionMemory.enabled是 true且模板文件路径存在。模板文件不存在时不会报错只是静默不初始化。MEMORY.md 被截断丢信息这是设计上的硬限200 行 25KB。长期项目记忆量大时截断不可避免靠 Auto Dream 的修剪缓解。如果你发现关键记忆总被截掉可以手动精简 topic 文件或者把不常用的记忆归档到子目录。Dream 不触发按四步 gating 顺序查。先看时间门minHours默认 24 小时刚配好肯定不触发再看扫描节流10 分钟内不会重复扫目录然后看会话门需要 ≥5 个新会话且排除当前会话最后看锁门如果.consolidate-lock的 mtime 新鲜且 PID 存活会静默跳过。PID 已死或超过 1 小时会直接接管。提取写入重复文件提取前会扫描 memory 目录把现有文件列表最多 200 个作为 manifest 注入 prompt避免创建重复文件。如果你看到重复可能是 manifest 扫描被截断了检查manifest_max_files配置。主 Agent 和后台 Agent 写冲突如果主 Agent 在对话中已经手动写了记忆文件后台提取会跳过这一段只推进游标。这是hasMemoryWritesSince的互斥策略不是 bug。想强制后台提取就别在对话里手动写 memory 文件。6. 把记忆流水线跑成长期搭档三层记忆跑通之后你的 Claude Code 就从“一次性工具”变成了“有记性的搭档”。采集靠 Session Memory持久化靠 Auto Memory Extraction整合靠 Auto Dream每层成本和时间尺度不同但共用同一个架构模式后台 forked agent prompt cache 共享 权限沙箱。如果你还想继续调优可以从这几个方向入手。模型对话验证召回效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 对比不同模型在提取质量上的差异长期编码和 Agent 场景用 Coding Plan 把记忆流水线跑在稳定配额上 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 专用接入说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。最后留一个我实测下来最实用的技巧把~/.claude/projects/slug/memory/目录纳入 git 管理每次 Dream 整合后 commit 一次。这样你能清楚看到记忆是怎么演化的哪条记忆被合并、哪条被修剪出问题时也能回滚。记忆系统最怕的不是写错而是写错了你还不知道。
