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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。先去控制台建一个 Key，路径是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成密钥： https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

拿到 Key 之后，环境变量这样设（Linux/macOS 写进~/.zshrc或~/.bashrc，Windows 用系统环境变量）：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的TaoToken密钥"

如果你用的是 Claude Code 的配置文件方式，可以在~/.claude/settings.json里写：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoToken密钥" } }

注意：ANTHROPIC_BASE_URL不要带末尾斜杠，也不要带/v1，Claude 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-lock"

max_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/api，Claude 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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 对比不同模型在提取质量上的差异；长期编码和 Agent 场景，用 Coding Plan 把记忆流水线跑在稳定配额上： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ；接入细节和参数说明看文档： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。Claude Code 专用接入说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=ClaudeCodeAnthropic&utm_campaign=rewrite 。

最后留一个我实测下来最实用的技巧：把~/.claude/projects/<slug>/memory/目录纳入 git 管理，每次 Dream 整合后 commit 一次。这样你能清楚看到记忆是怎么演化的，哪条记忆被合并、哪条被修剪，出问题时也能回滚。记忆系统最怕的不是写错，而是写错了你还不知道。