1. 从一次 prompt-too-long 报错说起Claude Code 记忆管理与压缩到底怎么跑如果你在本地跑 Claude Code 跑得比较久大概率见过这个报错prompt is too long: 210xxx tokens 200000 maximum。很多人第一反应是「上下文满了清一下会话」但清完发现刚聊过的文件路径、刚定的方案全没了又得重新喂一遍。问题不在「清不清」而在于你没搞懂 Claude Code 的记忆到底分几层、压缩到底在什么时机触发、压缩后哪些信息被保留、哪些被丢掉。这篇不聊玄学直接从 settings 配置一路拆到 API 通道链路把记忆存储、压缩策略、触发阈值、feature gate 开关全部落到可复制的配置和可验证的步骤上。核心检索词就三个Claude Code 记忆管理、上下文压缩触发条件、settings 配置链路。适合谁看适合已经在用 Claude Code 做日常编码、被上下文窗口反复打断、想搞清楚「为什么我的 CLAUDE.md 有时候生效有时候不生效」的开发者。读完你能自己复现压缩前后差异也能判断网上那些「五层记忆管理」的说法哪些是编的。先说结论Claude Code 的记忆不是五层是三种存储形态加七种压缩策略但主循环真正调用的只有三种压缩。这个差异是后面所有配置和排障的基础。我试过把会话跑到 90% 以上再观察压缩行为跟源码里写的阈值完全对得上下面一步步来。2. TaoToken 前置把 API 通道和 settings 链路先接对在拆压缩之前得先把请求通道理顺否则你连usage.input_tokens都拿不到压缩阈值根本无从观察。Claude Code 的请求最终走的是 Anthropic 兼容的 messages 接口本地 settings 决定模型、Base URL、Key 从哪来。如果你用的是 TaoToken 这类兼容通道配置入口在 https://taotoken.net/api Key 在控制台生成模型 ID 直接填 Claude 系列即可。这里有个容易踩的坑很多人把 Base URL 写成带/v1或不带/v1混着来结果 401 和 404 交替出现。正确做法是 Base URL 只写到域名根路径由客户端自己拼。下面这段是~/.claude/settings.json里跟通道相关的部分路径和字段名保持和官方一致你可以直接对照改{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 }, permissions: { allow: [Read, Edit, Bash(git:*)] } }注意ANTHROPIC_MODEL这个字段它决定了context_window_for_model()返回多大的窗口。源码里压缩阈值是按「已用 token / 窗口大小」算的模型填错会导致阈值判断整体偏移。比如你实际用的是 200k 窗口的模型却填了个 100k 的 ID那 90% 阈值会在真实用量 45% 时就触发压缩来得莫名其妙。Key 的获取路径是控制台里的 API Keys 页面生成后只显示一次记得存好。如果你还没配好先去 https://taotoken.net/api-keys 拿 Key再回来继续。通道通了之后用一条最小请求验证curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: reply with ok}] }返回里带usage.input_tokens就说明通道没问题这个字段就是后面观察压缩的抓手。如果返回 401先查 Key 有没有多余空格如果返回local proxy failed多半是 Base URL 写错或本地网络层拦截跟压缩无关先把通道修好再谈记忆管理。3. 可复制配置settings 里的记忆与压缩相关字段这一节是全文最该抄的部分。Claude Code 的记忆存储分三种常驻的CLAUDE.md热记忆、按需加载的话题文件温记忆、会话转录 JSONL冷记忆。压缩策略有七种但主循环实际只用三种。你要控制的就是「哪些记忆进上下文」和「压缩在什么阈值触发」。先看记忆相关的目录结构这是温记忆的落盘位置# ~/.claude/projects/项目哈希/memory/ 目录结构示意 # Memory.md —— 索引文件保存所有话题文件的元信息 # user_profile.md —— 用户背景与构建偏好 # skill_development.md —— 项目下的 skill 信息热记忆CLAUDE.md分两级用户级~/.claude/CLAUDE.md和项目级./CLAUDE.md。它被注入上下文的方式是作为 System Prompt 之后的一条 user message不是塞进 system 里。这点很关键因为压缩时第一条消息system/bootstrap会被snip_compact保留而CLAUDE.md作为紧随其后的 user message在激进压缩下是有可能被卷进摘要的。想让某条约束绝对不被压掉写进 system 级别的配置别只写CLAUDE.md。压缩行为的开关在环境变量里源码注释写得很清楚enabled via CLAURST_FEATURE_REACTIVE_COMPACT1。也就是说 reactive 分支默认不开开了之后压缩时机从「只在 end_turn / tool_use 后」变成「每轮模型返回后都判断」。配置片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key, ANTHROPIC_MODEL: claude-sonnet-4-5, CLAURST_FEATURE_REACTIVE_COMPACT: 1, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 } }三件套对照表配通道时逐项核对配置项作用常见错误值正确示例Base URL请求入口带/v1后缀https://taotoken.net/apiAPI Key鉴权带引号或空格sk-xxxxModel ID决定窗口大小填错窗口的模型claude-sonnet-4-5阈值这块源码里MicroCompactConfig的默认值是trigger_threshold: 0.75、keep_recent_messages: 10、summary_target_tokens: 2048。而主循环里 auto compact 的触发是 90%context collapse 是 97%。这几个数字要记住后面验证时全靠它们对号入座。KEEP_RECENT_MESSAGES 10意味着无论哪种压缩最近 10 条消息原样保留压缩的是更早的 head 部分。4. 验证请求与成功结果观察压缩前后差异配置改完怎么确认压缩真的按预期跑了最直接的办法是让会话涨到阈值附近然后看日志和消息条数变化。源码里压缩成功会打info!日志比如MicroCompact complete、Auto-compact complete、Context-collapse complete带上original和compacted的消息数。先跑一个能快速堆 token 的会话。用 Bash 工具连续读几个大文件或者直接让模型总结长文本把usage.input_tokens顶上去。观察点有两个一是TokenWarning事件80% 触发 Warning95% 触发 Critical二是压缩日志。下面是一段模拟观察流程# 启动 Claude Code 时打开调试日志 CLAUDE_CODE_DEBUG1 claude # 在会话里连续执行把上下文顶到 90% 以上 # 读几个大文件 Read src/main.rs Read src/lib.rs Read Cargo.toml # 然后问一个需要长回答的问题让 input_tokens 涨起来当input_tokens超过窗口的 90%如果没开 reactive gate你会在end_turn或tool_use之后看到Auto-compact complete日志里original_count明显大于new_count。开了 reactive gate 的话每轮返回后都会判断超过 90% 走reactive_compact超过 97% 走context_collapse。压缩后的消息结构长这样第一条是 synthetic user message内容是This session is being continued from a previous conversation that ran out of context...加上摘要后面接最近 10 条原始消息。你可以通过打印消息数组长度来验证# 伪代码验证压缩后消息结构 # 压缩前 messages 长度 42 # 压缩后 messages 长度 1 (summary) 10 (recent) 11 # 且 messages[0].role user内容是 summary preamblereactive_compact比 auto 多两步先strip_images删掉图片 block再尝试把最近修改的文件重新注入最多 5 个文件、单个超过 50KB 跳过。所以如果你在会话里改过文件reactive 压缩后可能会看到额外的file path...内容块这是正常的补上下文行为不是 bug。context_collapse最激进它把整个会话压成最多 500 词的紧急摘要然后只保留摘要加最后一条 user message。触发条件是 97% 以上属于「再不压下一轮请求就发不出去」的兜底。如果你看到日志里出现EMERGENCY CONTEXT COLLAPSE说明会话已经到极限了这时候历史基本只剩骨架。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth压缩相关的报错和通道相关的报错经常混在一起得分开看。下面按真实报错逐条对。401 Unauthorized出现在压缩日志之前说明请求根本没发出去跟记忆管理无关。检查ANTHROPIC_API_KEY是否有多余空格、是否过期。如果 Key 是对的还 401看 Base URL 是不是写成了https://taotoken.net/api/v1多写的/v1会导致路径拼成/api/v1/v1/messages。local proxy failed通常是本地网络层或 Base URL 解析问题。先确认ANTHROPIC_BASE_URL只写到https://taotoken.net/api再用第 2 节的 curl 单独验证通道。通道通了这个错就消失。reading choices这类报错一般出现在流式响应解析阶段源码里StreamAccumulator处理MessageDelta时如果stop_reason字段缺失或格式不对会抛。如果你用的是兼容通道确认返回的stop_reason是end_turn/tool_use/max_tokens这几个标准值之一。非标准值会被当成end_turn处理但解析层可能先报错。OAuth相关报错多见于用订阅账号登录而非 API Key 的场景。如果你走的是 API Key 通道settings 里不要同时留 OAuth 的 token 字段两者会打架。清掉~/.claude/下的凭据缓存再重启。还有一个隐蔽的坑压缩后模型「失忆」。这不是报错但表现是模型忘了之前定的方案。原因是summarise_head在压缩 head 时对结构化 blocks 的 tool result 会用占位符[complex content]代替不展开。如果你的关键信息藏在结构化返回里压缩后就丢了。解决办法是把关键约束写进CLAUDE.md或 system 级别配置别依赖工具返回。排查顺序建议先 curl 验通道再看usage.input_tokens有没有正常返回最后才看压缩日志。通道不通压缩逻辑根本不会执行。6. 语义一致 CTA把配置链路跑通之后通道和压缩都验证过之后日常编码场景建议直接上 Coding Plan省得每次手动配 Key 和模型。入口在 https://taotoken.net/coding-plan 适合长期跑 Agent 和批量改代码的用法。如果你只是想先验证某个模型在压缩后的表现用模型对话页面快速试https://taotoken.net/chat 。接入文档在 https://taotoken.net/doc 里面有各客户端的 Base URL 和字段对照配 settings 时对着抄就行。最后留一个实用习惯每次改完 settings先用一条最小请求确认usage.input_tokens正常返回再开长会话。压缩阈值是按这个字段算的它不对后面全是白忙。