摘要：很多熟悉 Claude Code 的人都知道
CLAUDE.md很重要，它相当于项目里的 AI 指令手册。但真正能让 Claude Code 越跑越顺的，往往是另一个容易被忽略的文件：MEMORY.md。它保存的是项目相关的长期记忆，例如历史决策、调试经验、失败路径、架构约束和复用知识。本文系统讲清楚MEMORY.md的位置、加载机制、Auto Memory 开关、和CLAUDE.md/CLAUDE.local.md的区别、最佳实践与实战案例，并顺手说明如何在 Claude Code 工作流里搭配 4sAPI 大模型 API 中转站管理模型调用和成本。
关键词：Claude Code、MEMORY.md、CLAUDE.md、CLAUDE.local.md、大模型API中转站、4sAPI、Auto Memory、AI Agent、项目记忆、Claude Code教程
适合读者：Claude Code 用户、AI Agent 玩家、独立开发者、团队工程师、长期维护项目的人，以及希望让 Claude Code 在项目里越用越懂上下文的用户。
1. 开篇：只会写CLAUDE.md还不够
熟悉 Claude Code 的人，大多知道 CLAUDE.md 很重要。
它通常放在项目根目录，用来告诉 Claude Code：
这个项目用什么技术栈
代码风格是什么
哪些命令可以跑
哪些文件不要动
输出要遵守什么格式
遇到问题先怎么排查
简单说，CLAUDE.md 是给 AI 的项目说明书。
但如果一个项目维护时间很长，只靠 CLAUDE.md 还不够。
因为项目里真正值钱的上下文，往往不是“现在应该怎么干”，而是“以前为什么这么干”：
- 为什么不用 Turbopack；
- 为什么某个 webhook 不能跑在 Edge Function；
- 为什么
sharp某个版本在 Apple Silicon 上会构建失败； - 为什么 API 测试必须依赖本地 Redis；
- 为什么移动端通知不用 WebSocket；
- 为什么某个架构迁移暂时被搁置。
这些信息不会天天出现，但一旦忘掉，Claude Code 就会重复踩坑。
MEMORY.md 解决的正是这个问题。
它不是第二个 CLAUDE.md，而是 Claude Code 的项目笔记本。
2. MEMORY.md是什么
MEMORY.md 是 Claude Code Auto Memory 机制中的核心索引文件。
它是一个 Markdown 文件，保存的是和项目相关的长期记忆。比如：
- 已经做过的技术决策；
- 重要历史上下文；
- 稳定项目知识；
- 反复出现的经验教训；
- 失败尝试和死路记录；
- 假设、取舍和约束。
一句话理解：
CLAUDE.md = AI 应该怎么干活
CLAUDE.local.md = 你的私人额外指令
MEMORY.md = AI 应该记住什么
这三个文件的分工一定要分清。
如果你把行为规则写进 MEMORY.md，它会变得像第二份指令手册，越用越乱。如果你把历史经验全塞进 CLAUDE.md，Claude Code 每次启动都会加载过多上下文，浪费 token，也降低重点信息的清晰度。
3. MEMORY.md放在哪里
CLAUDE.md 通常放在项目根目录，方便 Claude Code 启动时发现和加载。
MEMORY.md 不一样。它通常放在 Claude Code 的项目记忆目录中：
~/.claude/projects/<project>/memory/
└── MEMORY.md
其中 <project> 通常由 Git 仓库根目录派生而来。非 Git 项目则可能使用工作目录。也就是说，同一个仓库下的 worktree 和子目录，通常会共享同一个 memory 目录。
当项目变大后，memory 目录可以拆成多份专题文件：
~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── design-conventions.md
├── architecture.md
├── api-conventions.md
└── build-issues.md
这里的关键设计是：
MEMORY.md 做轻量索引
专题文件保存详细内容
Claude 按需读取专题文件
这比把所有内容都堆在 MEMORY.md 里更合理。
如果你想自定义 memory 存储位置，可以在 settings.json 中设置：
{
"autoMemoryDirectory": "~/my-custom-memory-dir"
}
注意：Auto Memory 是本机本地存储，不会自动跨机器或云端同步。换一台电脑，就没有原来的 memory 文件，除非你自己做备份或同步。
4. 加载机制：为什么前200行很重要
每次 Claude Code 会话开始时，MEMORY.md 的前 200 行，或者前 25KB，会被自动加载到上下文里。
规则可以理解成：
前 200 行 或 前 25KB
哪个先到，就按哪个算
超过阈值的内容不会在启动时自动加载。
这个限制只适用于 MEMORY.md。其他专题文件，比如 debugging.md、architecture.md、api-conventions.md，不会在会话开始时全部加载，而是由 Claude Code 在需要时按需读取。
这就是 MEMORY.md 应该保持短小的原因。
它的最佳形态不是长篇日志，而是一个高信号索引：
# Build Issues
- sharp@0.33.x 在 Apple Silicon 上构建失败，降级到 0.32.6 解决。详见 build-issues.md。
- CI pnpm install 超时，使用 --frozen-lockfile --prefer-offline。详见 build-issues.md。
# Architecture Decisions
- 2026-04 评估过 Vite vs Turbopack，当前选择 Vite。详见 architecture.md。
- monorepo 暂不拆成 polyrepo，等待 PNPM Workspace Catalogs 稳定。详见 architecture.md。
# Product Learnings
- 新手引导改版后流失率下降约 18%，后续改动不要删除关键进度反馈。
前 200 行是黄金位置，要留给最稳定、最长期、最能减少重复踩坑的信息。
5. 如何开启或关闭Auto Memory
Claude Code 的 Auto Memory 由 autoMemoryEnabled 控制。材料中提到它默认开启，可以在 settings 文件中配置：
{
"autoMemoryEnabled": true
}
配置位置可以是：
~/.claude/settings.json
.claude/settings.json
也可以用环境变量强制控制：
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0
材料中提到，Auto Memory 需要 Claude Code v2.1.59 或更高版本。可以运行下面命令确认：
claude --version
还有一个需要注意的限制：根据社区反馈，autoMemoryEnabled 开关可能同时影响 CLAUDE.md 加载和 MEMORY.md 记忆功能。如果你只想禁用 Auto Memory，但保留 CLAUDE.md 自动加载，当前可能没有独立开关可以完全分开控制。材料中提到该行为被标记为设计决策，而不是 bug。
所以如果你要在团队里调整这个开关，建议先在非关键项目里测试，不要直接改生产项目的默认工作流。
6. 谁来写MEMORY.md
在 AI 优先的工作流里，MEMORY.md 主要由 Claude Code 自己写。
Claude 不会每个 session 都写入记忆。它会判断某条信息是否值得未来复用。
常见触发场景包括：
- 你纠正了 Claude 的行为，比如“别用 npm，用 pnpm”；
- 你告诉它一条项目知识，比如“API 测试需要本地 Redis”；
- Claude 在调试中发现了值得记录的模式；
- 你主动说“记住这个”；
- 某个方案失败了，而且未来很可能还会有人再试。
当 Claude 写入或读取 memory 时，界面可能会显示类似：
Writing memory
Recalled memory
如果你不确定它记住了什么，可以用 /memory 命令查看。
7. /memory命令怎么用
在 Claude Code 会话中输入：
/memory
通常可以做几件事：
- 查看当前加载的
CLAUDE.md、CLAUDE.local.md和 rules 文件； - 开关 Auto Memory；
- 打开 memory 文件夹；
- 查看所有 memory 文件；
- 直接编辑
MEMORY.md。
所有 memory 文件本质上都是普通 Markdown 文件，你可以随时手动编辑、删除、整理。
不过更推荐的方式是：让 Claude 负责写入，你负责定期审核。
你可以直接对 Claude 说：
记住这个：API 测试需要本地 Redis 实例。
或者：
这次 sharp 的版本问题值得记录到 memory，避免以后重复排查。
这样比你手动维护一大堆笔记更自然。
8. CLAUDE.md、CLAUDE.local.md、MEMORY.md怎么分工
这三个文件很容易混。
可以用一张表理解：
| 文件 | 谁写 | 存什么 | 位置 | 是否适合进 Git |
|---|---|---|---|---|
CLAUDE.md |
你或团队 | 指令、规则、技术栈、工作流 | 项目根目录或全局 Claude 目录 | 适合 |
CLAUDE.local.md |
你 | 私人偏好、本地环境、本地测试数据 | 项目根目录 | 不适合，建议加入 .gitignore |
MEMORY.md |
Claude 为主 | 知识、经验、历史决策、失败路径 | ~/.claude/projects/<project>/memory/ |
不适合，本机独有 |
8.1 CLAUDE.md：AI的指令手册
CLAUDE.md 用来告诉 Claude Code 怎么干活。
示例：
# Role
You are a senior product engineer working on a SaaS dashboard application.
# Tech Stack
- TypeScript
- Next.js App Router
- Tailwind
- shadcn/ui
# Rules
- Prefer server components unless interactivity is required
- Never introduce new dependencies without approval
- Keep components under 250 lines
- Use Zod for validation
- Use React Query for async state
# Workflow
- Think through architecture before coding
- Explain major tradeoffs before implementation
- Update tests when changing business logic
这类内容是行为规则，应该放在 CLAUDE.md，不是 MEMORY.md。
8.2 CLAUDE.local.md：你的私人偏好
CLAUDE.local.md 适合放不想提交到 Git 的个人设置，比如：
- 本地沙箱 URL；
- 常用测试账号；
- 个人输出偏好；
- 本机路径；
- 本地 mock 数据；
- 临时调试习惯。
它和 CLAUDE.md 一样属于“指令”，区别是它更私人，不适合团队共享。
8.3 MEMORY.md：Claude的项目笔记
MEMORY.md 存的是知识，不是命令。
示例：
# Product Decisions
- 可用性测试中，用户明显偏好卡片布局，不喜欢密集表格。
- 深色模式使用率超过 70%，新功能默认必须支持深色模式。
# Technical Learnings
- Vercel Edge Functions 在 Stripe webhook 场景中会超时。
- Safari 在处理流式 AI 响应时偶尔出现断流。
# Historical Context
- 2026-03 从 Firebase 迁移到 Supabase，主要是为了减少厂商锁定。
- 新手引导改版后，流失率下降约 18%。
如果某条信息是“Claude 应该遵守的指令”，放进 CLAUDE.md 或 CLAUDE.local.md。
如果某条信息是“Claude 以后应该记得的经验”，放进 MEMORY.md。
9. 最佳实践：让记忆小而高信号
9.1 只存长期知识
MEMORY.md 应该保存跨多个 session 仍然有价值的信息。
值得存：
- 核心架构决策；
- 反复出现的 UX 发现；
- 集成限制；
- 性能发现；
- 构建失败经验；
- 被验证失败的方案。
不建议存：
- 临时 TODO；
- Sprint 任务；
- 随机调试日志；
- 短期实验；
- 当天对话摘要。
每次想加入一条记忆前，可以问一句：
一个月后，这条信息还有用吗？
如果答案是否定的，就不适合进 MEMORY.md。
9.2 不要放操作指令
不要把 MEMORY.md 变成第二个 CLAUDE.md。
比如：
Always use TypeScript.
Never edit migrations.
Prefer pnpm over npm.
这些是行为规则，应该放在 CLAUDE.md 或 CLAUDE.local.md。
MEMORY.md 应该写成：
- 2026-05 项目迁移到 pnpm，是因为 npm 在 CI 中多次出现 lockfile 不一致问题。
前者是命令，后者是经验。
9.3 解释为什么，而不只记录做了什么
最有价值的记忆不是结论，而是推理。
比如只写：
- 切换到 Redis。
价值不大。
更好的写法是：
- 切换到 Redis，是因为 serverless 内存重置导致 session 不稳定。
未来 Claude Code 再遇到 session 问题时，就能理解当时的取舍。
9.4 定期清理
记忆不清理，会慢慢变成噪音。
建议每月 review 一次：
- 已解决的问题，删除或标记已解决；
- 废弃架构，删除；
- 重复发现，合并；
- 超过三个月没再用到的信息，优先复查；
- 过长内容，拆到专题文件。
小而高信号的 memory，比大而杂的 memory 更有价值。
9.5 记录失败和死路
MEMORY.md 里最有价值的一类信息，是失败路径。
示例：
- 尝试用 WebSocket 推送移动端通知，放弃。原因是移动端后台重连稳定性太差。
- 尝试把 Stripe webhook 放到 Edge Function，放弃。原因是执行时间和依赖限制不适合当前场景。
这类记录能避免 Claude Code 一个月后又把你带回同一个坑。
10. 实战案例：构建问题怎么靠MEMORY.md省时间
假设你遇到一个构建问题。
没有 MEMORY.md 时，你可能要重新解释：
上次构建失败是因为 sharp 的 native 模块在 ARM Mac 上有兼容问题，试一下降级版本。
Claude 可能还要从头排查，查依赖、看日志、试版本，最后才想起正确方案。
如果 MEMORY.md 里已经有记录：
# Build Issues
- sharp@0.33.x 在 Apple Silicon 上构建失败，降级到 0.32.6 解决。
- CI 中 pnpm install 超时，使用 --frozen-lockfile --prefer-offline。
- postinstall 脚本需要 Node 20+，低于 20 会直接跳过。
下一次你只要说：
构建又失败了。
Claude Code 读取 memory 后，就能先检查 sharp 版本、Node 版本和 CI install 参数，而不是从零开始。
这就是项目记忆的价值：减少重复排查，缩短 Agent 的试错时间。
11. 4sAPI配置：让Claude Code长期项目更好控成本
MEMORY.md 解决的是项目记忆问题。
但长期使用 Claude Code 还有另一个问题：模型调用成本和模型切换。
一个成熟项目里，Claude Code 可能会频繁做这些事：
- 读取大量文件；
- 解释历史上下文；
- 生成 patch；
- 跑测试后分析错误；
- 反复修改；
- 写入或读取 memory；
- 生成总结和文档。
这些都会消耗模型调用。
如果你在国内环境中使用 Claude Code、Codex、Hermes 等多个 Agent 工具，可以考虑把模型 API 接入层统一到 4sAPI 大模型 API 中转站。
推荐思路是：
Claude Code / Codex / Hermes
-> 项目指令与记忆：CLAUDE.md / MEMORY.md / Skills
-> 4sAPI 大模型 API 中转站
-> Claude / GPT / Gemini / DeepSeek 等模型
4sAPI 在这里的价值是：
- 一个入口管理多个模型；
- 给不同项目单独建 Key；
- 查看调用日志和消耗；
- 给长期项目设置额度；
- 按任务切换快模型和强模型；
- 避免多个 Agent 工具各自维护一堆 Key。
例如你可以在 4sAPI 后台创建：
claude-code-project-a
claude-code-project-b
codex-refactor-workflow
hermes-agent-memory
这样每个项目和工作流的成本都能分开看。
如果你的工具支持 OpenAI-compatible endpoint，可以使用类似配置：
OPENAI_BASE_URL=https://4sapi.com/v1
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-5.5-xhigh
实际模型 ID 以 4sAPI 模型广场为准。
需要强调的是，4sAPI 解决的是模型接入和成本管理，不会替代 Claude Code 的 MEMORY.md。两者是不同层：
MEMORY.md 管项目长期记忆
4sAPI 管模型 API 接入
把这两层配好，长期项目里的 Agent 才会既“记得住”，又“花得明白”。
12. 速查表
| 问题 | 答案 |
|---|---|
MEMORY.md 在哪里 |
~/.claude/projects/<project>/memory/MEMORY.md |
谁写 MEMORY.md |
Claude 为主，你可以审核和整理 |
| 启动时加载多少 | 前 200 行或 25KB，先到为准 |
| 专题文件会启动加载吗 | 不会，Claude 按需读取 |
| 怎么开关 | /memory 命令，或 settings.json 里的 autoMemoryEnabled |
| 版本要求 | 材料中提到 Claude Code v2.1.59+ |
| 是否跨机器同步 | 不会，本机独有 |
| 能否自定义路径 | 可以，用 autoMemoryDirectory |
和 CLAUDE.local.md 的区别 |
CLAUDE.local.md 是你写的私人指令，MEMORY.md 是 Claude 写的项目笔记 |
| 多久清理一次 | 建议每月 review 一次 |
13. 总结：让Agent记住项目，而不是每次重新认识项目
MEMORY.md 的价值，不是多一个 Markdown 文件，而是让 Claude Code 从“一次性助手”变成“长期项目伙伴”。
CLAUDE.md 告诉它怎么干活。
CLAUDE.local.md 告诉它你的私人偏好。
MEMORY.md 告诉它这个项目曾经发生过什么、为什么这么决策、哪些坑不要再踩。
如果你经常在同一个项目里使用 Claude Code，建议尽早建立一套 memory 习惯：
重要决策要记
失败路径要记
长期约束要记
短期任务不要记
每月清理一次
再配合 4sAPI 这样的模型 API 中转站，把不同项目的模型调用、日志和额度分开管理，Claude Code 的长期使用体验会稳定很多。
一句话总结：
CLAUDE.md 让 Claude Code 知道规矩。
MEMORY.md 让 Claude Code 记住经验。
4sAPI 让 Claude Code 的模型调用更好管理。