1. 为什么你的 Claude Code 总是“失忆”刚接触 Claude Code 的开发者大概率都撞过同一堵墙昨天刚跟它讲清楚项目用 pnpm、组件统一script setup、接口前缀/api今天开个新会话它又默认给你生成npm install和 Options API 的代码。你不得不把同一套背景信息再复述一遍像在跟一个每天失忆的同事交接工作。这不是模型变笨了而是对话上下文天生就是临时的。一次会话结束上下文窗口里的内容就随之清空模型不会“记得”你上周说过什么。Claude Code 给出的解法是一套基于文件的持久化记忆系统把长期有效的信息写进磁盘上的 Markdown 文件每次新会话启动时自动读取并注入上下文。这样跨会话的偏好、项目规则、历史决策就能被稳定复用。这套机制对三类人价值最大一是长期维护同一项目的独立开发者二是需要把团队规范固化下来的小团队三是准备往 Agent 定制方向走的进阶用户——因为记忆系统正是自定义 Agent 的起点Agent 的“人设”和“领域知识”很大程度就靠记忆文件承载。本篇是系列第一篇目标很明确让你理解记忆系统是什么、文件长什么样然后跑通基础环境——包括用 TaoToken 统一配置 Key 与 API 通道最后给出验证记忆文件是否真正被加载的可操作步骤。读完你应该能独立搭起一个能“记住事”的 Claude Code 环境。2. 记忆系统到底是什么文件、索引与加载时机先把概念落地。Claude Code 的记忆系统本质是一个放在用户目录下的文件知识库结构大致如下~/.claude/projects/project-id/memory/ ├── MEMORY.md # 索引文件每次会话都会加载 ├── coding-preferences.md # 编码偏好 ├── project-rules.md # 项目规则 ├── database-info.md # 数据库信息 └── team-conventions.md # 团队约定每次新会话开始时Claude Code 会做三件事读取MEMORY.md这个索引根据索引里的条目按需加载对应记忆文件再把内容注入到当前对话上下文。所以MEMORY.md是入口其他文件是正文索引写得好不好直接决定记忆能不能被正确命中。它和普通对话上下文的区别可以用一张表说清维度对话上下文记忆系统生命周期单次会话持久直到手动删除容量受上下文窗口限制接近文件系统上限加载方式自动携带按索引读取可控性用户难以干预可直接编辑、增删记忆文件按用途分四类user存个人偏好比如“用 const 不用 let”project存项目信息比如数据库地址reference存外部资源链接feedback存你对 Claude 的纠正反馈。分类不是强制的但分清楚能让索引更清晰后续检索更准。还有一个容易混淆的点记忆系统和项目根目录的CLAUDE.md是互补关系不是二选一。CLAUDE.md通常纳入 git写团队共享的规范、技术栈、目录结构记忆系统放在用户家目录不纳入版本管理写个人偏好、历史决策和反馈。团队规范走CLAUDE.md私人习惯走记忆系统这样既共享又互不干扰。3. 前置准备用 TaoToken 统一 Key 与 API 通道在写记忆文件之前得先保证 Claude Code 能正常发请求。这里我用 TaoToken 做统一接入好处是一个 Key 走通模型对话和编码场景不用在多个平台之间来回切换配置。先拿到 API Key。打开控制台页面创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建后复制那串以sk-开头的 Key妥善保存。接着确认接入文档里的 Base URL 和请求格式文档入口https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteAPI 基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置时直接填这一串即可。如果你更习惯用 Anthropic 协议接入 Claude Code对应的通道说明在https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite环境变量是最省事的配置方式在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key改完执行source ~/.zshrc让配置生效。这里有个坑Key 千万别写进记忆文件或CLAUDE.md那些文件可能被同步或提交密钥只放环境变量或本地私密配置里。4. 可复制的 settings.json 骨架与记忆文件模板环境变量管的是“能不能连上”settings.json管的是 Claude Code 的行为。它一般放在~/.claude/settings.json下面是一份可以直接抄的骨架{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api }, permissions: { allow: [ Read, Write, Bash(git status), Bash(pnpm *) ], deny: [ Bash(rm -rf *) ] }, memory: { enabled: true, indexFile: MEMORY.md } }几个字段说明一下model指定默认模型env里可以再兜底一次 Base URLpermissions.allow列出允许自动执行的操作deny拦住危险命令memory段开启记忆系统并指定索引文件名。不同版本字段名可能有细微差异以你本地实际版本为准改完用claude --version确认版本再对照文档。接着建记忆目录和索引文件mkdir -p ~/.claude/projects/project-id/memory cd ~/.claude/projects/project-id/memory touch MEMORY.mdproject-id用你的项目标识替换保持和实际项目对应即可。然后写第一条记忆比如编码偏好--- name: coding-preferences description: 个人编码风格偏好 metadata: type: user --- - 使用 TypeScript不用 JavaScript - 组件统一用 script setup 语法 - 包管理器用 pnpm - API 路径统一以 /api 开头再把它登记进索引MEMORY.md# 记忆索引 - [编码偏好](coding-preferences.md) — TypeScript、pnpm、script setup索引条目建议控制在 10 到 20 条以内太多会导致每次加载的内容过载反而稀释了关键信息的权重。过时的记忆及时删掉别让它一直占着索引位。5. 验证记忆是否真的被加载配置写完不代表生效必须验证。最直接的方式是开一个新会话直接问它你记住了哪些关于我编码偏好的信息如果记忆系统正常工作Claude 会读取MEMORY.md索引加载coding-preferences.md然后复述出 TypeScript、pnpm、script setup这些条目。如果它答不上来或者答得含糊说明加载链路有问题。第二种验证方式是让它执行一个依赖记忆的任务观察输出是否符合偏好。比如帮我写一个用户列表组件如果它默认用script setup加 TypeScript而不是 Options API 加 JavaScript说明偏好已经注入成功。这一步比单纯问答更能反映真实效果因为它是隐式调用记忆。第三种是直接检查文件系统确认文件确实存在且内容正确ls -la ~/.claude/projects/project-id/memory/ cat ~/.claude/projects/project-id/memory/MEMORY.md文件在、索引对但模型还是“失忆”那问题多半出在配置层往下看排查部分。6. 本篇常见错误排查记忆不生效模型完全不知道有记忆这回事。先确认settings.json里memory.enabled是true再确认indexFile指向的文件名和实际文件名一致。大小写敏感MEMORY.md和memory.md是两个文件。索引写了但对应文件读不到。检查索引里的相对路径是否和实际文件同名[编码偏好](coding-preferences.md)里的文件名必须和磁盘上的完全一致。路径写错时加载会静默失败不会报错所以特别隐蔽。请求直接报鉴权失败。多半是 Key 没生效或 Base URL 写错。确认环境变量已经source用echo $ANTHROPIC_API_KEY看是否输出正确Base URL 必须是https://taotoken.net/api不要多加斜杠或路径。需要重新生成 Key 的话走这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite记忆文件里写了密钥导致泄露风险。记住一条铁律记忆文件、CLAUDE.md、settings.json里都不放密码和 Token。密钥只走环境变量这是最容易被忽视的安全习惯。改了记忆但新会话还是旧内容。检查是不是改了文件却没更新索引或者索引指向了另一个同名旧文件。改完记忆后最好新开一个会话验证避免旧上下文干扰判断。7. 下一步从记忆到 Agent 定制跑通这一篇你已经有了一个能跨会话记住偏好和项目规则的基础环境。记忆系统是 Agent 定制的起点——后面要做的自定义 Agent本质上就是给一组记忆文件加上特定的工具权限和行为约束让它在特定领域里稳定工作。如果你接下来要长期做编码和 Agent 相关开发建议直接上 Coding Plan把模型调用和额度统一管理起来省得每次单独配https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite想先验证模型对话是否通畅可以到模型对话页面试一条请求https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite下一篇会讲记忆文件的编写规范一条好的记忆该写多细、元数据怎么填、如何让 Claude 在对话中准确检索到它。把这一篇的settings.json和记忆骨架先跑起来下一篇直接在上面加内容就行。