# 记忆

> 每次 Qwen Code 会话都从一个全新的上下文窗口开始。有两种机制可以在会话之间传递知识，让你不必每次都重新解释：

- 网址：https://funcoding.ai/agents/qwen-code/users/features/memory/
- 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/features/memory

---
每次 Qwen Code 会话都从一个全新的上下文窗口开始。有两种机制可以在会话之间传递知识，让你不必每次都重新解释：

- **QWEN.md** — 由_你_编写一次，Qwen 在每次会话中都会读取的指令
- **自动记忆** — Qwen 根据从你这里学到的内容自己编写的笔记

---

## QWEN.md：你给 Qwen 的指令

QWEN.md 是一个纯文本文件，你可以在其中写下 Qwen 应该始终了解的关于你的项目或你的偏好的内容。可以把它看作是在每次对话开始时加载的永久性简报。

### 在 QWEN.md 中写些什么

添加那些否则你每次会话都不得不重复的内容：

- 构建和测试命令（`npm run test`、`make build`）
- 你的团队遵循的编码规范（“所有新文件必须有 JSDoc 注释”）
- 架构决策（“我们使用 Repository 模式，永远不要从控制器直接调用数据库”）
- 个人偏好（“始终使用 pnpm，而不是 npm”）
- 针对高风险工作的验证策略——例如“在得出结论前对照数据库进行验证”（参见[强制基于证据的结论](https://funcoding.ai/agents/qwen-code/users/common-workflow/#enforce-evidence-based-conclusions)获取现成模板）

不要包含 Qwen 可以通过阅读你的代码自己弄清楚的内容。QWEN.md 在简短且具体时效果最好——它越长，Qwen 遵循它的可靠性就越低。

### 在哪里创建 QWEN.md

| 文件 | 适用对象 |
| --- | --- |
| `~/.qwen/QWEN.md` | 你，跨所有项目 |
| 项目根目录下的 `QWEN.md` | 你的整个团队（将其提交到版本控制） |
| `.qwen/QWEN.local.md` | 仅限你，仅限此项目（不要提交到 git） |

你可以任意组合使用这些文件。Qwen 会在你启动会话时加载所有这些文件。

如果你的仓库已经有一个供其他 AI 工具使用的 `AGENTS.md` 文件，Qwen 也会读取它。无需重复编写指令。

#### 何时使用 `.qwen/QWEN.local.md`

用于**特定于项目但属于个人**的指令——属于此项目但不应与团队共享的内容：

- 你自己的集群 ID、容器注册表命名空间或云账户
- 硬编码了你本地环境的个人调试命令
- 你希望 Qwen 了解的关于你正在进行的工作的笔记，但不想提交

它在共享的项目 `QWEN.md` **之后**加载，因此你的本地指令可以补充或覆盖团队的指令。

**你必须自己将其添加到 `.gitignore`。** 尽管 `.qwen/` 通常被视为本地目录，但 qwen-code 不会为你生成 `.gitignore`，并且有些项目会提交 `.qwen/settings.json`。将此行添加到你的 `.gitignore`（或你的全局 git ignore）中：

```
.qwen/QWEN.local.md
```

### 使用 `/init` 自动生成

运行 `/init`，Qwen 将分析你的代码库，以创建一个包含它找到的构建命令、测试指令和规范的初始 QWEN.md。如果已经存在一个，它会建议添加内容而不是覆盖。

### 引用其他文件

你可以在 QWEN.md 中指向其他文件，以便 Qwen 也读取它们：

```markdown
See @README.md for project overview.

# Conventions

- Git workflow: @docs/git-workflow.md
```

在 QWEN.md 的任何地方使用 `@path/to/file`。相对路径从 QWEN.md 文件本身开始解析。

---

## 自动记忆：Qwen 从你这里学到了什么

自动记忆在后台运行。在每次对话之后，Qwen 会悄悄保存它学到的有用内容——你的偏好、你给出的反馈、项目上下文——以便它可以在未来的会话中使用它们，而无需你重复说明。

这与 QWEN.md 不同：你不是编写者，Qwen 才是。

### Qwen 保存什么

Qwen 会寻找四种值得记住的内容：

| 内容 | 示例 |
| --- | --- |
| **关于你** | 你的角色、背景、你喜欢的工作方式 |
| **你的反馈** | 你做出的纠正、你确认的方法 |
| **项目上下文** | 正在进行的工作、决策、从代码中不明显看出的目标 |
| **外部引用** | 你提到的仪表盘、工单跟踪器、文档链接 |

Qwen 不会保存所有内容——只保存下次真正有用的内容。

### 存储位置

自动记忆文件位于 `~/.qwen/projects/<project>/memory/`。同一 checkout 的所有分支共享同一个记忆文件夹，因此 Qwen 在一个分支中学到的内容在其他分支中也可用。每个链接的 git worktree 拥有独立的记忆文件夹，与聊天和其他会话状态的 per-worktree 隔离方式一致——你希望在每个 worktree 中都可用的全仓库规范应放在[团队记忆](#团队记忆与协作者共享)中。

所有保存的内容都是纯 Markdown 格式——你可以随时打开、编辑或删除任何文件。

#### 固定记忆

将需要自动记忆维护保留的手动整理文档放在托管记忆目录下的 `pinned/` 中，例如 `~/.qwen/projects/<project>/memory/pinned/architecture.md` 或 `~/.qwen/memories/pinned/preferences.md`。使用与其他记忆文档相同的 frontmatter。有效的固定文件可被 Qwen 读取，并在下次重建 `MEMORY.md` 时被包含在内，遵循与其他记忆文档相同的文件大小和文件数量限制。

仅直接位于托管记忆根目录内的顶层 `pinned/` 目录受保护；嵌套目录（如 `memory/project/pinned/`）是普通的可写记忆。自动提取和 Dream worker 以不区分大小写的方式匹配该保留目录名称。

自动提取被指示保持固定记录及其有效索引条目不变，而 Dream 被指示在合并期间跳过 `pinned/`。自动提取和 fork 的 Dream worker（包括后台清理）都会在其写入和编辑工具上执行固定文件边界检查，包括通过符号链接解析到 `pinned/` 的路径；其现有的只读 shell 策略会阻止命令行删除。你仍然可以直接控制这些文件，并可以通过显式的 `/forget` 请求移除它们。

> **注意：** 可见的 `/dream` 斜杠命令在主 Agent 上运行。它接收相同的跳过指令，但尚未接收 fork worker 的确定性逐轮工具门控。

### 定期清理

Qwen 会定期遍历其保存的记忆，以删除重复项并清理过时的条目。在积累了足够的会话后，这会在后台每天自动运行一次。如果你想让它立即运行，可以使用 `/dream` 手动触发。

在后台运行清理时，你的会话会正常继续。

### 开启或关闭

自动记忆默认开启。要切换它，请打开 `/memory` 并使用顶部的开关。你可以仅关闭自动保存、仅关闭定期清理，或同时关闭两者。

你也可以在 `~/.qwen/settings.json`（适用于所有项目）或 `.qwen/settings.json`（仅限此项目）中进行设置：

```json
{
  "memory": {
    "enableManagedAutoMemory": true,
    "enableManagedAutoDream": true
  }
}
```

### 团队记忆（与协作者共享）

默认情况下，自动记忆是**你私有的**——它位于你的主目录下，永远不会被共享。团队记忆是一个可选的层级，整个团队**通过 git** 共享。

启用后，Qwen 会在**仓库内部**的 `.qwen/team-memory/` 获得第三个记忆目录。它使用与私有层级相同的“每个记忆一个文件”的布局和 `MEMORY.md` 索引。因为它被提交到仓库中，所以它会以常规方式与每个协作者共享：你通过 `git pull` 接收队友的记忆，并通过 commit/push 分享你的记忆。Qwen 会将持久的、全项目范围的知识路由到这里——每个贡献者都必须遵循的规范、共享的引用指针（跟踪器、仪表盘）——而个人和快速过时的笔记则保持私有。

在 `settings.json` 中按项目（或全局）启用它：

```json
{
  "memory": {
    "enableTeamMemory": true
  }
}
```

它**默认关闭**。请记住以下注意事项：

- **它受版本控制，对具有仓库访问权限的每个人可见。** 将团队记忆视为提交到仓库。
- **阻止写入机密信息。** 对 `.qwen/team-memory/` 的写入会扫描凭据（API 密钥、令牌、私钥）；检测到的机密信息会被拒绝，永远不会被写入。扫描是最后一道防线，而不是保证——不要将敏感数据放在那里。
- **更改可被审查。** 团队记忆的写入会像其他任何文件一样出现在 `git status` / PR diff 中，因此可以在提交前进行审查。在默认的批准模式下，Qwen 在每次团队写入前也会询问；在 `AUTO_EDIT`/YOLO 模式（你已选择自动批准）下，它们会在没有提示的情况下应用，但仍然会出现在 diff 中。
- **该目录必须被 git 跟踪。** 如果你的项目的 `.gitignore` 排除了 `.qwen/*`，请重新包含该路径以便共享：

  ```gitignore
  !.qwen/team-memory/
  !.qwen/team-memory/**
  ```

  注意：使用文件通配符忽略形式（`.qwen/*`），而不是带尾随斜杠的目录形式（`.qwen/`）。目录形式的忽略会使 git 完全跳过该文件夹，因此其下方的 `!` 重新包含将不起作用，并且团队层级在 git 中会保持静默为空。当启用该层级但其目录被 git 忽略或位于任何 git 仓库之外时，Qwen 会在启动时发出一次警告，因此这种错误配置不会被忽略。

`QWEN_CODE_MEMORY_TEAM=1` / `=0` 会覆盖单次运行的设置。

### 自动 git 同步（可选）

默认情况下，你通过常规的 git 工作流共享团队记忆（通过 `pull` 接收，通过 `commit`/`push` 共享）。要让 Qwen 为你执行此操作，请启用同步：

```json
{
  "memory": {
    "enableTeamMemory": true,
    "enableTeamMemorySync": true
  }
}
```

开启后，在会话开始时，Qwen 会尽力同步 `.qwen/team-memory/` 目录：它重建共享的 `MEMORY.md` 索引，**首先**快进拉取协作者的更新，然后在之上提交你的团队记忆更改，并**仅推送该同步提交**（通过显式的单分支 refspec）——这样你加载的索引就能反映最新状态。它只**暂存**团队目录（你的其他工作更改永远不会被提交），并且永远不会因 git 失败而阻塞会话。默认关闭。`QWEN_CODE_MEMORY_TEAM_SYNC=1` / `=0` 会覆盖单次运行的设置。

启用前需要了解的两件事：

- **快进拉取作用于你的整个当前分支，而不仅仅是 `.qwen/team-memory/`**（git 没有路径范围的拉取）。因此，同步会将你的分支快进到远程顶端。相比之下，推送是限定范围的：它**仅发布此同步刚刚创建的提交**，因此它永远不会推送你拥有的其他未推送的提交——如果你的分支已经领先于上游，同步会在本地提交并跳过推送。在快进拉取没有问题的分支上启用它——或者在专用的 checkout 上运行它。
- **分叉的分支保持不变**（`--ff-only` 永远不会合并）。当发生这种情况时，同步在该会话中直接什么都不做；解决分叉（`git pull`）后它会恢复。没有上游（没有跟踪配置）的分支仍然会在本地提交，但会跳过推送——因为没有地方可以推送。

---

## 命令

### `/memory`

打开记忆面板。从这里你可以：

- 开启或关闭自动记忆保存
- 开启或关闭定期清理（dream）
- 打开你的个人 QWEN.md（`~/.qwen/QWEN.md`）
- 打开项目 QWEN.md
- 浏览自动记忆文件夹

### `/init`

为你的项目生成一个初始的 QWEN.md。Qwen 读取你的代码库并填入它发现的构建命令、测试指令和规范。

### `/remember <text>`

立即将某些内容保存到自动记忆中，而无需等待 Qwen 自动获取：

```
/remember always use snake_case for Python variable names
/remember the staging environment is at staging.example.com
```

### `/forget <text>`

删除与你的描述匹配的自动记忆条目：

```
/forget old workaround for the login bug
```

### `/dream`

立即运行记忆清理，而不是等待自动计划：

```
/dream
```

---

## 故障排除

### Qwen 没有遵循我的 QWEN.md

打开 `/memory` 查看加载了哪些文件。如果你的文件未列出，Qwen 无法看到它——请确保它位于项目根目录或 `~/.qwen/` 中。

指令越具体，效果越好：

- ✓ `Use 2-space indentation for TypeScript files`
- ✗ `Format code nicely`

如果你有多个包含冲突指令的 QWEN.md 文件，Qwen 的行为可能会不一致。请检查它们并删除任何矛盾之处。

### 我想看看 Qwen 保存了什么

运行 `/memory` 并选择**打开自动记忆文件夹**。所有保存的记忆都是可读的 Markdown 文件，你可以浏览、编辑或删除它们。

### Qwen 总是忘记事情

如果自动记忆已开启，但 Qwen 似乎无法在会话之间记住内容，请尝试运行 `/dream` 强制执行一次清理。同时检查 `/memory` 以确认两个开关都已启用。

对于你始终希望 Qwen 记住的内容，请将它们添加到 QWEN.md 中——自动记忆是尽力而为的，而 QWEN.md 是有保证的。