1. 为什么 CLAUDE.md 越写越长Claude Code 还是记不住项目先说一个我观察到的现象很多团队用 Claude Code 超过三个月之后仓库根目录的 CLAUDE.md 会从最初的 30 行长到 300 行然后开始失控。新来的同事不敢删老同事懒得改最后它变成一份没人读的“僵尸文档”。而 Claude Code 每次新会话照样问你这个项目用什么构建工具测试怎么跑问题不在于 CLAUDE.md 这个机制本身而在于它被塞进了两类性质完全不同的东西。一类是规则技术栈、构建命令、目录职责、提交规范、禁止事项。这类内容稳定、可共享、适合跟仓库一起做版本管理放进 CLAUDE.md 天经地义。另一类是经验某个测试本地失败多半是 Redis 没起、某个模块虽然丑但背着历史兼容不能删、某个接口改动前必须先看适配层。这类内容高频、易变、高度依赖本地环境硬塞进 CLAUDE.md 的结果就是文档膨胀加快速过期。Claude Code 的 Auto Memory 补的就是第二层。它把“值得跨会话保留的项目经验”自动写进本机目录而不是仓库。按官方给出的结构项目级记忆大致长这样~/.claude/projects/项目路径/memory/ ├── MEMORY.md ├── debugging.md ├── api-conventions.md └── ...这里的关键设计是主索引 主题文件MEMORY.md 作为入口会话启动时优先读取且只加载前 200 行超出的内容拆到 debugging.md、api-conventions.md 这类主题文件里按需再读。这跟工程系统里“热路径先加载、冷数据按需取”是同一个思路——它要的是有用的延续不是无差别灌一堆旧上下文。所以现在 Claude Code 的记忆是双层结构CLAUDE.md 是制度层memory/ 是经验层。一个偏静态、适合共享一个偏动态、适合本地持续积累。但这里有个现实问题多项目切换的开发者往往同时开着三四个仓库每个仓库的会话都要重新建立上下文。如果请求端点还分散在各自的配置里Key 管理、模型选择、记忆复用会一起变乱。我自己的做法是把 Claude Code 的请求端点统一收到 TaoToken 的 Key 通道上让记忆层和模型通道解耦——记忆归记忆通道归通道。下面就把 settings 配置、记忆文件样例和验证步骤完整走一遍。2. TaoToken 前置准备统一 Key 通道与 Claude Code 的对接位置在动 settings 之前先把通道这层理清楚。Claude Code 支持通过环境变量或 settings 文件指定 API 端点这意味着你可以把请求指向 TaoToken 的兼容入口用一把 Key 覆盖多个项目、多个模型。TaoToken 官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM 参数配置里直接写它。需要准备的东西只有三样第一一个可用的 API Key。到控制台创建路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建完在 API Keys 页面复制页面地址 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 只显示一次复制后先存到密码管理器。第二确认你要用的 Model ID。Claude Code 场景下通常用 Anthropic 兼容的模型标识具体可用的模型列表在文档里查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不要凭记忆写模型名写错了会直接报 model not found。第三确认 Claude Code 版本。Auto Memory 需要 v2.1.59 及以上先升级再配置claude update claude --version版本低于 2.1.59 的话/memory面板里不会出现 auto-memory 相关入口后面的验证步骤会卡住。这里解释一下为什么要统一通道。多项目切换时如果每个项目各自配一套 Key 和端点你会遇到三个麻烦Key 轮换要改 N 个地方某个项目额度用尽时排查成本高记忆文件里记录的“上次用哪个模型跑通的”和实际通道对不上。统一到 TaoToken 之后Base URL 和 Key 是全局一份项目差异只体现在 CLAUDE.md 和 memory/ 里职责边界清楚。如果你同时用 Claude Code 和别的编码 Agent比如 Cline、Codex 这类TaoToken 的 Coding Plan 可以覆盖长期编码场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。不过这篇的重点是 Claude Code 的记忆落地通道部分点到为止。3. 可复制配置settings.json 与项目记忆文件样例这一节给可直接粘贴的配置。分三块全局 settings、项目级 settings、记忆文件样例。3.1 全局 settings.json路径是~/.claude/settings.json。这个文件管跨项目的默认行为包括 API 端点、Key、默认模型以及 Auto Memory 的开关。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: 你的ModelID }, autoMemoryEnabled: true }三个字段说明一下。ANTHROPIC_BASE_URL写 TaoToken 的 API 基址注意结尾不要带斜杠带了有些客户端会拼出双斜杠导致 404。ANTHROPIC_API_KEY填你在控制台创建的那把 Key。ANTHROPIC_MODEL填文档里确认过的 Model ID。autoMemoryEnabled设为 true 表示全局开启自动记忆。如果你有 CI 环境共用这台机器建议全局关掉只在本地项目里开——CI 追求确定性不需要长期记忆。3.2 项目级 settings.json路径是项目根目录下的.claude/settings.json。这个文件可以覆盖全局设置适合做项目差异化。{ autoMemoryEnabled: true, env: { ANTHROPIC_MODEL: 项目专用ModelID } }如果某个项目你不想让它污染长期记忆比如临时探索性修改或者一次性实验就在这里把autoMemoryEnabled设为 false。环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY1优先级最高CI 里用这个最干净。3.3 记忆文件样例项目记忆目录在~/.claude/projects/项目路径/memory/。注意项目路径是 Claude Code 根据项目绝对路径生成的编码目录名不要手写让它自己创建。MEMORY.md 作为主索引只加载前 200 行所以这里要写得精炼把细节指向主题文件# 项目记忆索引 ## 工作流 - 构建用 Maven wrapper提交前跑 mvnw verify - 前端包管理必须 pnpm禁止 npm install - 详见 workflow.md ## 环境前置 - 调试 API 前先启动本地 Redis - 本地联调依赖 Docker Composeprofile 用 local - 详见 debugging.md ## 结构性经验 - adapter 层不要手改先看接口定义 - legacy 包背着历史兼容短期不要重构 - 详见 api-conventions.md主题文件按需拆分比如 debugging.md# 排障经验 ## 测试本地失败 - 多半是 Redis 没启动先 docker compose up redis - 若报连接超时检查 6379 是否被占用 ## 接口 500 - 先看全局异常处理器有没有吞掉原始堆栈 - 上周定位过一次是环境变量 MISSING_FLAG 没配api-conventions.md# 接口约定 - Controller 统一返回 RT - Service 用 interface impl 分离 - 新增接口必须挂全局异常处理器 - 老版本兼容接口不要改签名走新增重载这三份文件不需要你手写全部内容。Auto Memory 会在会话中自动沉淀你只需要在发现它记错或者记漏时手动修正。主动告诉它长期保留某件事直接在会话里说“记住这个项目用 pnpm不用 npm”即可。3.4 关于 CC Switch / Cline MCP / Codex auth.json如果你同时用 CC Switch 管理多套 Claude Code 配置或者用 Cline 的 MCP、Codex 的 auth.json记住三件套必须写全Base URL、Key、Model ID。缺任何一个都会在请求阶段失败。CC Switch 里切换配置时确认这三项跟着一起切不要只换 Key 不换端点。4. 验证请求确认记忆召回与通道生效配置写完怎么确认它真的在工作分两步先验证通道通再验证记忆召回。4.1 验证通道进入项目目录启动 Claude Codecd /path/to/your/project claude在会话里发一个最小请求比如“列出当前目录结构”。如果通道配置正确会正常返回。如果报 401说明 Key 有问题如果报连接失败说明 Base URL 写错了。也可以直接用 curl 验证端点排除 Claude Code 本身的干扰curl 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: 你的ModelID, max_tokens: 64, messages: [{role: user, content: ping}] }返回里带content字段就说明通道通了。这一步能快速区分是通道问题还是 Claude Code 配置问题。4.2 验证记忆召回通道通了之后验证记忆机制。在会话里执行/memory应该看到类似面板Memory Auto-memory: on 1. User memory Saved in ~/.claude/CLAUDE.md 2. Project memory Checked in at ./CLAUDE.md 3. Open auto-memory folder三个入口分别对应用户级记忆、项目规则、自动记忆目录。如果 Auto-memory 显示 off回去检查 settings 里的autoMemoryEnabled和环境变量。然后做一轮真实任务比如让它写一个接口或者补一组测试。观察终端提示如果出现Recalled X memories (ctrlo to expand)说明它加载了已有记忆。按 Ctrl O 展开看具体召回了哪些内容确认没有把无关信息拉进来。最后关掉会话重新打开问一个依赖历史背景的问题这个项目用什么构建工具 跑测试前要不要先启动依赖服务 上次这个模块为什么没继续重构如果它能直接接住而不是重新让你解释一遍记忆机制就真的生效了。我实测下来第一次配置完通常需要跑两三轮真实任务记忆文件才会积累到有意义的程度不要指望配完立刻见效。4.3 验证上下文复用多项目切换场景下重点验证的是“换项目后记忆不串”。开两个终端分别进两个不同项目各自问一个项目专属问题。如果 A 项目的记忆跑到 B 项目里说明项目路径编码出了问题检查~/.claude/projects/下的目录是否按项目正确隔离。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给排查路径。这些是我和身边开发者踩过的坑按出现频率排序。5.1 401 Unauthorized最常见。原因通常是 Key 写错、Key 过期、或者 Key 前面多了空格。排查顺序先确认ANTHROPIC_API_KEY的值没有多余空格和换行再到控制台确认这把 Key 还在有效期内然后用 4.1 的 curl 命令单独测端点。curl 通但 Claude Code 报 401说明是 Claude Code 读的配置文件和你想的不是同一个——检查是不是项目级 settings 覆盖了全局或者环境变量里有一份旧的 Key 在起作用。环境变量优先级高于 settings 文件。如果你之前 export 过ANTHROPIC_API_KEY它会盖掉 settings 里的值。用env | grep ANTHROPIC查一下。5.2 local proxy failed这个报错通常出现在你本地挂了某种转发工具或者 Base URL 指向了本地端口但服务没起。排查确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api不是http://localhost:xxxx。如果你确实需要本地转发确认那个本地服务在运行。另外检查系统代理设置有没有把请求劫持到不存在的端口。5.3 reading choices / reading choices这个报错一般出现在响应格式不符合预期时。Claude Code 走的是 Anthropic 兼容格式返回体里应该是content数组不是 OpenAI 风格的choices。如果你看到reading choices说明请求被路由到了一个返回 OpenAI 格式的端点或者 Model ID 填错了导致服务端返回了错误结构。排查确认 Base URL 是https://taotoken.net/apiModel ID 是文档里 Anthropic 兼容的那一档。不要混用 OpenAI 风格的模型名。5.4 OAuth 相关报错Claude Code 某些版本会尝试 OAuth 流程。如果你用的是 API Key 模式出现 OAuth 报错说明它没读到你的 Key走了默认的登录流程。排查确认ANTHROPIC_API_KEY已设置且非空。有些版本需要显式设置ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY具体看你的版本和文档说明。如果两个都设了确认它们值一致。5.5 记忆不生效/memory面板显示 Auto-memory: on但会话里从来不出现Recalled X memories。排查确认版本 ≥ 2.1.59确认项目记忆目录~/.claude/projects/项目路径/memory/下确实有 MEMORY.md确认 MEMORY.md 不是空的。如果目录不存在说明还没触发过记忆写入多跑几轮真实任务。另外MEMORY.md 只加载前 200 行如果你把关键信息写到了 200 行之后它不会被启动时读取要挪到前面或者拆到主题文件。5.6 记忆串项目A 项目的经验跑到 B 项目里。这通常是项目路径识别问题。检查~/.claude/projects/下的目录命名确认每个项目有独立目录。如果你在同一个目录下切换了 git 分支做不同的事记忆是共享的这是预期行为不是 bug。6. 把记忆层和通道层分开维护回到最开始的问题CLAUDE.md 为什么越写越长因为大家把规则和经验混在一起了。现在有了 Auto Memory正确的分工是——CLAUDE.md 只放制度性内容技术栈、构建命令、目录职责、提交规范、明确禁止事项。这些稳定、可共享、适合进 Git。经验性内容交给 memory/最近排障结论、本地环境注意事项、模块历史包袱、反复提到的协作偏好。这些动态、本地、高频复用。通道层单独维护Base URL、Key、Model ID 三件套统一在 settings 里多项目共用一份。这样 Key 轮换只改一个地方模型切换只改一个字段记忆文件里不需要记录任何通道信息。如果你还在用别的编码 Agent比如 Cline 的 MCP 或者 Codex同样把三件套写全不要只配一半。需要看模型实际对话效果可以用模型对话页面快速验证https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。长期编码和 Agent 场景走 Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一条边界Auto Memory 不是团队知识库的替代品。README、架构文档、ADR、运维手册该写还得写。它只是 Claude Code 的本地经验层。还有不要把密钥、隐私数据、生产凭据随手丢进记忆里——会记不代表什么都该记。
区域求和原理与工程实践)
