---
id: structure-agent-memory
type: sop
status: published
version: 1
updated: 2026-11-06
token_estimate: 2271
---

# 如何给 Agent 建一套分层记忆

> **用途**：判断该不该分层、分几层、每层放什么。核心不是「记住更多」，是「记住对的，且不越写越乱」。
>
> **覆盖**：有固定记忆文件的 Agent —— WorkBuddy / CodeBuddy、Claude Code、Cursor，或自建的系统提示拼接。
>
> **产出**：一套分好的文件结构，每个文件该放什么的判据，以及三条自检。
>
> 拿到就能跑：先问四个问题，**别急着建文件**。多数人不需要三层。

---

## 触发的变异问法

- 「我的 Agent 老是忘事，怎么办」
- 「记忆文件太长了，怎么整理」
- 「MEMORY.md 越写越大，要不要拆」
- 「怎么让 AI 一直记住我的偏好」
- 「几个项目的记忆混在一起了」
- 「换个对话它就不认识我了」
- 「到底该记什么、不该记什么」
- 「怎么给 Agent 加长期记忆」
- 「AGENTS.md 该怎么写」

---

## 什么时候不要用这份文件

- **Agent 每次开新对话不会自动读任何文件** —— 没有固定位，分层无从谈起。转方案 D，别硬套。
- **只是想让它记住几句话**（称呼、语气、禁用词）—— 直接写进系统提示或自定义指令，不需要分层。
- **记忆文件不到 200 行，且只服务一个项目** —— 拆了只会增加维护成本，不会变好。
- **没有人在维护** —— 分层的收益来自持续整理，没人维护时它会慢慢腐化成两份互相矛盾的副本，比一份简单的更糟。

---

## 判断：先问四个问题

**一次只问一个，问完再问下一个。** 不要一口气抛四个。

| # | 问什么 | 怎么问出口（原话） | 判据 | 答不上来时 |
|---|---|---|---|---|
| Q1 | 有没有固定文件位 | 「你的 Agent 每次开新对话，会不会自动读到某个文件——比如项目里的 MEMORY.md、CLAUDE.md，或者设置里的自定义指令？」 | 会 → Q2；不会 → **方案 D，到此为止** | 在候选文件里加一句无害的话，新开对话问 Agent「那个文件里写了什么」，看它知不知道 |
| Q2 | 现在多大 | 「那个文件现在多少行？」 | ≤200 且单项目 → **方案 B**；>200 → Q3 | 打开数行数；或搜一个高频词，一篇几百行里出现十次以上，说明已经混装 |
| Q3 | 服务几个项目 | 「这个文件只服务一个项目，还是几个项目共用？」 | 多项目 → **方案 A**；单项目但 >200 行 → 也走 **方案 A** | 看文件里有没有出现两个以上互不相关的路径或项目名 |
| Q4 | 谁往里写 | 「里面的内容是你写的，还是 Agent 自己也会往里加？」 | Agent 也写 → 方案 A **必须配写入判据**；只有人写 → 方案 A 可简化 | 看文件末尾有没有「本次更新」这类 Agent 留下的句子 |

### 分支

| 条件 | 方案 |
|---|---|
| Q1 = 不会 | **D** · 没有固定位 |
| Q1 = 会，Q2 ≤ 200，单项目 | **B** · 先别拆 |
| Q1 = 会，且（Q2 > 200 或多项目） | **A** · 三层结构 |
| Q1 = 会，且某个文件 > 500 行 | **C** · 三层 + 分卷 |

---

## 方案 A · 三层结构

分三个**位置**，不是三个文件内容：

```
工作区根/
  通用/MEMORY.md      ← 跨项目都成立的：身份、协作方式、硬规则
  项目A/
    AGENTS.md         ← 这个项目的入口：它在做什么、约定、路径
    memory.md         ← 这个项目的记忆：进度、决策、坑
  项目B/...
```

**导航层不是文件，是每个文件开头固定几行**：这是什么、详情去哪找。写完这几行，Agent 打开任何一个文件都知道自己在哪。

关键在**每个容器的准入判据**，见下一节。

## 方案 B · 先别拆

两百行以内、只服务一个项目，说明还没到混乱的程度。这时候拆，得到的是三个空壳加一堆维护动作。

但立一条线：**超过 200 行就来拆**。200 不是科学数字，是「一屏读不完、Agent 开始抓不住重点」的经验位置。

## 方案 C · 三层 + 分卷

某个文件已经超过 500 行，光分层不够——通用层本身就要分卷。按主题切成几个文件（如「规则」「方法」「环境」），用一个索引文件连起来。

⛔ 分卷的前提是先分层。没分层就分卷，等于把混装切成几份混装。

## 方案 D · 没有固定位怎么办

用系统自带的长效设置：Project 的自定义指令、GPT 的 instructions、每次开头的模板消息。

这类位置通常只有几千字，**放不下分层**，只能精选。挑三条：

1. 你是谁、它该怎么称呼你
2. 你不可接受的行为（最硬的那条）
3. 一句话说明你的工作方式

其余全部放弃。没有固定位的时候，**少记几条但每次都生效**，好过记一堆但每次都要手动贴。

---

## 写入判据：一条信息该进哪个文件

这是整套方法的核心。四问按顺序过，前一问否决就不再问：

1. **不写进去，下次会不会做错？** —— 不会 → 不写。「知道了更好」不算。
2. **换个目录还成立吗？** —— 成立 → 通用层；不成立 → 项目层。
3. **每次会话都必须看到吗？** —— 是 → 常驻；不是 → 按需，用指针连。
4. **三个月后还成立吗？** —— 不成立 → 要么带上日期，要么改写成不依赖具体值的表述。

第一问挡掉大部分内容。**这一关过了，剩下的就不用纠结**——归属是判断，不是取舍。

### 指针怎么接

常驻层只写「有什么、在哪」，不写内容本身：

```
部署方式有七个坑，完整清单 → `基础设施/部署与索引-公共流程.md`
```

读到指针的 Agent 会自己去取；取不到时它知道该停下来问，而不是猜。

---

## 自检：三条，判断这次落地有没有走偏

1. **新开一个对话，让 Agent 说说「这个项目在做什么」。** 说不出来 → 项目层不够；说得出来但夹着别的项目 → 层没分开。
2. **在通用层里搜路径和项目名。** 搜到了 → 混装没清干净。
3. **在项目层里搜「所有项目」「任何情况下」。** 搜到了 → 通用规则放错了地方。

三条全过，这套结构才算立住。

---

## 常见错误

- **一上来就建四层** —— 层数超过实际需要，维护成本压过收益，最后没人更新。
- **只拆不写判据** —— 拆完很整齐，三个月后又混回去，因为没人知道新内容该放哪。
- **拆完不删旧的** —— 两份并存，Agent 读到哪份看运气，比不拆更糟。
- **通用层里塞项目路径** —— 换一个项目就失效，通用层也就不通用了。
- **把对话记录当记忆** —— 每日日志属于记录层，不是记忆层；把它搬进常驻层会立刻撑爆。
- **指望它自动保持** —— 分层是结构，不是机制。没有写入判据和定期整理，结构会自己塌。

---

## 最后核对

2026-11-06。本文件不依赖具体工具与平台；各家产品的文件名不同，但「有没有固定位」这个判断条件通用。与所执行系统的既定标准冲突时，以那个系统的标准为准。