如何构建不会“遗忘”的 AI Agents（使用 Memory Files）

大多数 AI Agent 失败的原因不在于模型本身。

它们失败是因为每次会话开始都像得了失忆症一样。

你告诉 Claude：“我们用 pnpm，不用 npm。”

下一次会话：它又尝试用 npm。

你告诉它：“这里不用默认导出。”

下一次会话：它又写了一个默认导出。

你每一次的纠正，在会话结束时都会消失。

有一个文件就能解决这个问题。

我花了三个月不断重复同样的指令才找到它。

以下是我学到的全部内容。

为什么大多数 AI Agent 会失败

不是模型的问题。

是模型缺少了底层的那一层。

→ 你写一个提示词

→ Agent 执行任务

→ 会话结束

→ 记忆消失

→ 下一次会话：同样的错误

→ 你重复同样的指令

→ 永远循环下去

这个循环是 AI 编码中浪费时间最多的原因。

不是糟糕的代码。不是幻觉。

是重复。

缺失的层面：记忆

每个人都痴迷于哪个模型最聪明。

关注错了层面。

真正的提升不是更聪明的模型。

而是给模型一个地方来存储它学到的东西。

→ 提示词 → 告诉 Agent 现在要做什么

→ Agents → 执行任务

→ 记忆 → 在会话之间保留上下文

→ 持久上下文 → 不再需要重复纠正

→ 学习系统 → Agent 实际上会随着时间改进

这就是工具和队友之间的区别。

工具每次都从零开始按你说的做。

队友会记得昨天的事。

每个 AI Agent 需要的 5 个记忆文件

一旦你接受记忆是缺失的层面，下一个问题就是：它存在哪里？

五个文件。每个有不同职责。

→ CLAUDE.md — Claude 的个人简报文件

→ AGENTS.md — 通用标准，每个主流工具都会读取

→ CLAUDE.local.md — 你的个人偏好，永远不提交到 git

→ MEMORY.md — AI 自动记录关于它自己的笔记

→ README.md — 给人类看的，不是给 Agent 看的

我们来逐一介绍。

CLAUDE.md — 一切开始的文件

把这个放在项目根目录。

Claude 在每次会话开始时都会读取它。

把它想象成给一个有失忆症的新团队成员准备的简报文件。

一个好的 CLAUDE.md 有四个部分：

→ 项目背景 — 一行。“使用 Stripe 和 Postgres 的 Next.js 电商应用。”

→ 代码风格 — 不是“正确格式化代码”，而是“使用 ES 模块、命名导出、2 空格缩进。”

→ 命令 — 确切的字符串。pnpm test:integration，而不是“运行测试。”

→ 架构 — “API 路由放在 /src/api/[resource]/route.ts。数据库访问使用仓库模式。”

1# CLAUDE.md
2
3## 项目背景
4Next.js 14 电商应用。Postgres + Stripe 集成。
5
6## 代码风格
7- 仅使用 ES 模块
8- 命名导出，不要默认导出
9- 2 空格缩进
10- TypeScript 严格模式
11
12## 命令
13- 安装：pnpm install
14- 开发：pnpm dev
15- 测试：pnpm test:integration
16- 代码检查：pnpm lint:fix
17
18## 架构
19- API 路由：/src/api/[resource]/route.ts
20- 数据库访问：仅使用仓库模式
21- 组件：/src/components，每个组件一个文件

目标：少于 300 行。

每一行都在与实际工作竞争注意力。

运行 /init，Claude 会自动生成一个入门文件。

然后删掉大部分内容。

默认文件包含 Claude 从你的 package.json 中已经知道的那些东西。只保留那些如果没有这个文件 Claude 就会出错的内容。

[@imports](https://x.com/@imports) 系统 — 保持精简

CLAUDE.md 不需要包含所有东西。

它可以导入其他文件：

查看

@README .md 了解项目概览 查看

@docs/api-patterns .md 了解 API 约定 查看

@package .json 了解可用的 npm 脚本

导入可以是递归的——最多 5 层深度。

这解决了“一个巨大的文件”的问题。

对于团队：前端团队拥有 docs/frontend-rules.md。

安全团队拥有 docs/security.md。

CLAUDE.md 只需导入它们全部。

一个根文件。多个专门的来源。

AGENTS.md — 通用标准

CLAUDE.md 只对 Claude 有效。

如果你的团队还使用 Cursor、Copilot 或 Gemini CLI——它们从不读取它。

AGENTS.md 解决了这个问题。

一个文件。每个主流 Agent 都会读取。

受 Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp 等支持。

它是标准 markdown。没有特殊模式。不需要 YAML。

1# AGENTS.md
2
3## 项目概览
4基于 Next.js 14、Postgres 和 Stripe 的电商平台。
5
6## 构建与测试
7- 安装：pnpm install
8- 开发：pnpm dev
9- 测试：pnpm test
10- 代码检查：pnpm lint:fix
11
12## 代码标准
13- TypeScript 严格模式
14- 命名导出优先于默认导出
15- API 路由遵循 /src/api/ 中的 REST 约定
16
17## 测试要求
18- 所有 PR 必须包含测试
19- 单元测试使用 vitest，端到端测试使用 playwright

把它当作 AI Agent 的 README。

README.md 给人类看。AGENTS.md 给所有 Agent 看，不分厂商。CLAUDE.md 在此基础上添加 Claude 特有的额外内容。

它们是互补的，不是竞争的。

自动记忆——会自己做笔记的 AI

这是最新且最有趣的层面。

Claude Code 现在会在你的会话期间自己写入记忆文件。

memory/ ├── MEMORY.md ← 索引，每次会话加载 ├── debugging.md ← 关于调试模式的笔记 ├── api-conventions.md ← API 设计决策 └── ...

关键的转变：

你编写 CLAUDE.md。你提供指令。

Claude 编写 MEMORY.md。它记录下学到的内容。

→ 人类编写规则

→ Agent 在工作时发现模式

→ Agent 写下自己的记忆

→ 未来的会话从更聪明开始

你可以直接触发这个。在高效的会话结束时，只需说：

“把你今天关于我们代码库学到的内容更新到你的记忆文件中。”

学到的内容会持久化。再也不需要第五次重新解释你的自定义 ORM 封装了。

随时运行 /memory 来查看或编辑 Claude 保存的内容。

/init 然后删除的工作流

在新项目上快速启动记忆文件的最快方法：

1. 在你的项目目录中运行 /init
2. Claude 会根据你的代码库生成一个入门 CLAUDE.md
3. 删除不需要的部分

第 3 步是大多数人出错的地方。

生成的文件是草稿，不是最终产品。

它通常包含填充内容。“这个项目使用 JavaScript。”谢谢——从 package.json 就能看出来。

从一个合理的草稿开始编辑比从空白文件开始写要好。

设置完成后，有机地构建。

当 Claude 做出错误假设时——比如它不断导入一个已弃用的包——不要只纠正一次。

告诉它：“添加到我的 CLAUDE.md：总是从 @company/utils-v2 导入，而不是 @company/utils。”

这个指令会持续存在于每一次未来的会话中。

每隔几周，让 Claude 审查并清理 CLAUDE.md。

指令会积累。有些变得多余。另一些开始冲突。快速检查一遍能保持其精炼。

我的实际设置

在多个生产项目上测试了所有这些之后，以下是我坚持使用的方案：

→ AGENTS.md 放在项目根目录——任何 AI 工具都能读取的共享指令。构建命令、代码标准、测试要求。

→ CLAUDE.md 配合 @imports 来处理 Claude 特有的行为。保持在 100 行以内，主要指向 docs/ 文件。

→ CLAUDE.local.md 处理个人偏好——我的测试数据、沙箱 URL、快捷命令。从不提交到 git。

→ 自动记忆已启用。 Claude 自己记笔记。我每月审查一次。

→ 其他所有内容都用符号链接替换，指回 AGENTS.md。一个真相来源。

1# 多工具一致性的符号链接设置
2ln -sfn AGENTS.md .github/copilot-instructions.md
3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc

不算优雅。

但它消除了团队中每个工具之间的指令偏差。

更大的转变

大多数开发者认为：

更好的模型 = 更好的 Agent。

错了。

真正的公式是：

模型 + 记忆 + 检索 + 反馈 = 有用的 Agent

一个更聪明的模型没有记忆，明天仍然会忘记你的测试命令。

一个中等模型拥有良好的记忆，每周都会变得更敏锐。

记忆是复利变量。

模型智能不是。

我对我的 AI 工作流做出的最大改进不是换模型。

而是给模型一个记忆。

区别在于：

“Claude，我们用 pnpm”——每次会话

和：

“Claude 已经知道了”——每次会话

这就是工具和队友之间的区别。

如果这对你有用：

→ 转发分享给每个还在向 Claude 重复自己的开发者

→ 关注 @sairahul1 获取更多在你睡觉时也能产生复利的系统

→ 收藏这篇文章——今晚就设置好，明天就不用再纠正了

我写关于 AI、产品构建以及那些不需要你就能正常工作的系统。