1. 为什么我要从 Claude Code 的记忆系统倒推 settings.jsonClaude Code 是 Anthropic 推出的终端 Agent 工具它能读写文件、执行命令、跨会话保留项目上下文。很多人第一次用它时会好奇为什么它记得我上周改过哪个模块为什么它知道这个仓库不能用某个测试命令答案藏在它的 Agent 记忆系统里。而记忆系统的落地最终会收敛到一个配置文件——settings.json。我试过把 Claude Code 的记忆逻辑拆开看发现它本质上是一套「文件级记忆 按需召回 分层压缩」的组合拳。记忆不是存在某个黑盒向量库里而是以 Markdown 文件的形式落在本地目录由 Agent 通过工具调用显式写入和更新索引。这个设计的好处是你可以用cat看到 Agent 到底记住了什么也可以用git diff追踪记忆的变化。但问题来了如果你只是把 Claude Code 装好用默认配置跑记忆系统能工作却不一定高效。真正决定记忆质量的是settings.json里的几个关键参数——它们控制着记忆的存储路径、召回数量、压缩阈值和工具权限。这篇文章就围绕这 4 个「胜负手」展开结合 TaoToken 的统一 Key/API 通道给出一份可以直接复制的配置骨架。适合谁读正在用 Claude Code 做长期项目的人、想理解 Agent 记忆落地方式的开发者、以及需要把多个模型通道统一管理的人。读完之后你能拿到一份可运行的settings.json并知道每个字段为什么这么设。2. TaoToken 前置统一 Key 与 API 通道的接入准备在配置settings.json之前需要先解决一个前置问题Claude Code 默认走 Anthropic 官方通道但如果你同时用多个模型或需要统一管理 Key直接写死官方地址会很不灵活。TaoToken 提供的是一个统一 API 通道把模型对话、Coding Plan、API Keys 管理收敛到一个入口。你需要先拿到一个可用的 API Key。操作路径是访问 TaoToken 官网注册后在控制台创建 API Key。官网地址是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台入口在https://taotoken.net/consoleAPI Keys 管理页在https://taotoken.net/api-keys。拿到 Key 之后API 的基础地址是https://taotoken.net/api注意这个地址不加 UTM 参数直接用于程序调用。Claude Code 的接入文档在https://taotoken.net/doc里面有针对不同客户端的配置说明。如果你用的是 Claude Code 的 Anthropic 兼容模式可以参考https://taotoken.net/ClaudeCodeAnthropic这个 deep link。这里有一个容易踩的坑很多人把 API 地址和官网地址搞混在settings.json里填了带 UTM 的官网链接结果请求全部 404。记住程序调用只认https://taotoken.net/apiUTM 参数是给网页统计用的不要写进配置文件。另外如果你打算长期跑编码任务或 Agent 工作流可以了解一下 Coding Plan入口在https://taotoken.net/coding-plan。它和按量计费的 API Key 是两种模式前者更适合高频调用场景。模型对话的验证入口在https://taotoken.net你可以在网页上先测一下 Key 是否可用再写进配置。3. 可复制配置settings.json 的 4 个关键胜负手Claude Code 的settings.json通常位于项目根目录的.claude/文件夹下或者用户级的~/.claude/settings.json。下面这份配置骨架我按记忆系统的 4 个关键点拆开讲。3.1 胜负手一记忆存储路径与文件格式第一个胜负手是记忆存哪里、存成什么格式。Claude Code 的记忆系统默认使用 Markdown 文件作为持久化格式索引文件叫MEMORY.md其他记忆按类别存成独立文件。你需要在settings.json里显式指定记忆目录避免它散落在临时路径里。{ memory: { enabled: true, storagePath: .claude/memory, indexFile: MEMORY.md, format: markdown, categories: [user, feedback, project, reference] } }storagePath设为项目内的.claude/memory这样记忆可以跟着仓库走团队成员 clone 之后也能看到同一份记忆索引。categories对应源码里的记忆类型学用户偏好、反馈、项目决策、参考资料。分门别类的好处是召回时可以按类型过滤而不是一股脑全塞进上下文。这里的关键决策是不要用私有二进制格式。Markdown 的好处是可读、可 diff、可手动编辑。当 Agent 记错东西时你可以直接打开文件改掉而不是对着数据库发呆。3.2 胜负手二召回数量与信噪比控制第二个胜负手是每次召回多少条记忆。Claude Code 源码里的策略是「最多 5 条不确定就不选」。这个数字不是随便定的——太多会污染上下文太少会漏掉关键信息。你可以在settings.json里控制这个上限。{ memory: { recall: { maxItems: 5, requireReason: true, dedupeBySession: true, minConfidence: medium } } }maxItems设为 5和源码保持一致。requireReason要求模型在召回时给出理由这能逼它做判断而不是随机选。dedupeBySession对应源码里的readFileState机制——同一条记忆在同一会话里只注入一次防止重复污染。minConfidence设为medium意思是模型不确定的记忆就不召回。这个配置的核心思想是「饥饿营销」把记忆当成稀缺资源只选那些不提供就会导致任务失败的条目。很多 RAG 方案喜欢把相似度前 10 条全塞进去结果模型被无关信息干扰反而做不好决策。3.3 胜负手三压缩阈值与遗忘策略第三个胜负手是上下文压缩。Claude Code 的压缩分三层微压缩、会话记忆压缩、传统 LLM 摘要压缩。你需要在settings.json里设定触发阈值和熔断条件。{ memory: { compaction: { microCompactThreshold: 0.7, sessionMemoryEnabled: true, llmSummaryThreshold: 0.9, maxRetries: 3, restoreRecentFiles: 5 } } }microCompactThreshold设为 0.7意思是上下文窗口用到 70% 时先做轻量级压缩——截断过时的工具输出、删除重复内容。sessionMemoryEnabled开启会话记忆压缩用结构化的会话记忆文件替代旧消息。llmSummaryThreshold设为 0.9只有到 90% 才动用昂贵的 LLM 摘要。maxRetries设为 3连续失败 3 次就放弃避免死循环烧钱。restoreRecentFiles设为 5压缩后自动恢复最近读过的 5 个文件防止模型「失忆」。这套配置的本质是「遗忘经济学」先尝试最便宜的遗忘手段实在不行才调用模型摘要。你要保护的不只是上下文窗口还有 API 账单。3.4 胜负手四工具权限与记忆写入控制第四个胜负手是记忆写入的权限控制。Claude Code 把记忆操作工具化Agent 通过调用工具来写记忆。你需要在settings.json里限制哪些工具可以写记忆、哪些只能读。{ memory: { write: { allowedTools: [write_memory, update_memory_index], requireConfirmation: false, maxWritesPerSession: 10 }, read: { allowedTools: [read_memory, search_memory], readOnly: true } } }allowedTools限定只有write_memory和update_memory_index能写记忆其他工具只能读。maxWritesPerSession设为 10防止 Agent 在一次会话里疯狂写记忆导致索引膨胀。readOnly确保读取工具不会意外修改文件。这里的设计思路是「不信任但验证」Agent 可以写记忆但写入行为要可审计、可回滚。你可以在系统提示里加一句「信任回忆但若与当前事实冲突以当前对话为准」防止错误记忆污染任务。4. 验证请求确认配置生效与记忆系统工作配置写完之后需要验证它是否真的生效。最直接的方式是发一个请求看 Claude Code 是否按预期读写记忆。4.1 用 curl 验证 API 通道先用 curl 测一下 TaoToken 的 API 通道是否通。把YOUR_API_KEY替换成你在控制台创建的 Key。curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: YOUR_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 256, messages: [ {role: user, content: 回复 OK 两个字母即可} ] }如果返回的 JSON 里有content字段且包含OK说明 API 通道正常。如果返回 401检查 Key 是否复制完整如果返回 404检查地址是不是写成了带 UTM 的官网链接。4.2 在 Claude Code 里触发记忆写入启动 Claude Code让它做一个需要记忆的操作。比如claude 请记住这个项目用 pnpm 而不是 npm测试命令是 pnpm test执行后检查.claude/memory/MEMORY.md是否被更新。你应该能看到类似这样的内容# Memory Index ## Project - [package-manager.md](project/package-manager.md): 项目使用 pnpm测试命令为 pnpm test再打开project/package-manager.md确认内容被正确写入。如果文件没生成检查settings.json里的storagePath是否指向了正确目录以及allowedTools是否包含了write_memory。4.3 验证召回与去重新开一个会话问 Claude Code「这个项目用什么包管理器」它应该能召回刚才写入的记忆并给出pnpm。同时观察上下文里是否只注入了一次这条记忆——如果同一会话里反复问dedupeBySession应该阻止重复注入。你可以用cat .claude/memory/MEMORY.md随时查看索引用git diff .claude/memory/追踪记忆变化。这就是文件级记忆的好处一切可见、可审计。5. 本篇常见错排查配置过程中有几个高频错误我整理成对照表方便你快速定位。报错现象可能原因排查动作401 UnauthorizedAPI Key 无效或未传检查x-api-key头确认 Key 从控制台复制完整404 Not FoundAPI 地址写错确认地址是https://taotoken.net/api不带 UTM记忆文件不生成storagePath目录不存在手动创建.claude/memory目录或检查路径拼写记忆重复注入dedupeBySession未开启在settings.json里设为true压缩后模型失忆restoreRecentFiles为 0设为 5让压缩后恢复最近文件写入次数超限maxWritesPerSession太小根据任务复杂度调整默认 10 够用召回无关记忆minConfidence太低设为medium或high提高筛选门槛还有一个隐蔽的坑如果你在settings.json里同时配了用户级和项目级配置Claude Code 的合并策略是项目级覆盖用户级。所以如果你在用户级开了记忆项目级忘了开记忆功能在项目里可能不生效。建议统一在项目级配置跟着仓库走。另外MEMORY.md索引文件不要手动删。如果索引丢了Agent 就找不到其他记忆文件了。你可以手动编辑索引内容但不要删除文件本身。如果索引损坏可以从git历史里恢复。6. 下一步把记忆系统接进你的工作流配置跑通之后你可以做几件事让它更贴合自己的习惯。第一把.claude/memory/加入版本控制这样团队共享记忆新人 clone 后能快速了解项目约定。第二定期 reviewMEMORY.md删掉过时或错误的记忆保持索引干净。第三如果你同时用多个模型通道可以在 TaoToken 控制台统一管理 Key避免在多个配置文件里散落不同厂商的凭证。模型对话的验证入口在https://taotoken.net接入文档在https://taotoken.net/docAPI Keys 管理在https://taotoken.net/api-keys。如果你打算长期跑编码任务Coding Plan 的入口在https://taotoken.net/coding-plan适合高频调用场景。最后留一个实用技巧在系统提示里加一句「每次写入记忆前先检查 MEMORY.md 是否已有同类条目有则更新而非新建」。这能有效防止索引膨胀也是 Claude Code 源码里write-after-filter逻辑的简化版。记忆系统的核心不是记多少而是记准、记少、能忘。
