记忆与规则

记忆

每个 Qwen Code 会话都以全新的上下文窗口开始。有两种机制跨会话保留知识，让你不必每次重新解释：QWEN.md（你写一次、Qwen 每个会话都读的指令）和自动记忆（Qwen 根据从你那里学到的内容自己写的笔记）。

QWEN.md：你给 Qwen 的指令

QWEN.md 是一个纯文本文件，写下 Qwen 应该始终了解的关于你的项目或偏好的事情，它就像一份在每次对话开始时加载的永久简报。该放什么：你否则每个会话都得重复的东西：构建和测试命令（npm run test、make build）；你团队遵循的编码约定（「所有新文件必须有 JSDoc 注释」）；架构决策（「我们用仓库模式，绝不在控制器里直接调用数据库」）；个人偏好（「总是用 pnpm，不要用 npm」）；高风险工作的验证策略（如「得出结论之前先对照数据库验证」）。不要包含 Qwen 读代码就能弄清楚的东西；QWEN.md 在简短而具体时效果最好，越长，Qwen 越不可靠地遵循它。

三者可以任意组合，Qwen 在你启动会话时全部加载。如果你的仓库已经有给其他 AI 工具用的 AGENTS.md 文件，Qwen 也读它，不必重复指令。.qwen/QWEN.local.md 用于项目特定但属于个人的指令：你自己的集群 ID、容器仓库命名空间或云账号；硬编码了你本地环境的个人调试命令；你想让 Qwen 知道、但不想提交的进行中工作的笔记。它在共享的项目 QWEN.md 之后加载，所以你的本地指令可以补充或覆盖团队的。你必须自己把它加进 gitignore（qwen-code 不会替你生成 .gitignore，有些项目还提交 .qwen/settings.json）：在 .gitignore 里加一行 .qwen/QWEN.local.md。

用 /init 自动生成：运行 /init，Qwen 会分析你的代码库来创建带有构建命令、测试说明和它发现的约定的起始 QWEN.md；如果已有一个，它建议补充而不是覆盖。引用其他文件：在 QWEN.md 的任何位置用 @path/to/file（相对路径从 QWEN.md 文件本身解析），如「See @README.md for project overview.」「Git workflow: @docs/git-workflow.md」。

自动记忆：Qwen 了解到的关于你的事

自动记忆在后台运行：每次你的对话之后，Qwen 悄悄保存它学到的有用的东西（你的偏好、你给的反馈、项目上下文），以便在以后的会话里使用而不让你重复。这与 QWEN.md 不同：不是你写的，是 Qwen 写的。Qwen 寻找四类值得记住的东西：关于你（你的角色、背景、你喜欢的工作方式）、你的反馈（你做的纠正、你确认的做法）、项目上下文（进行中的工作、决定、从代码看不出来的目标）、外部引用（你提到的仪表板、工单跟踪器、文档链接）。Qwen 不保存一切，只保存下次真正有用的东西。

存储位置：自动记忆文件在 ~/.qwen/projects/<project>/memory/。同一个检出的所有分支共享同一个记忆文件夹，所以 Qwen 在一个分支学到的东西在其他分支也可用；每个关联的 git worktree 有自己的记忆文件夹，与聊天和其他会话状态的按 worktree 隔离一致（要在每个 worktree 都有的仓库范围约定，属于团队记忆）。保存的一切都是纯 markdown，你可以随时打开、编辑或删除任何文件。固定记忆：把你手工整理、希望自动记忆维护保留的文档放在受管记忆目录的 pinned/ 下（如 ~/.qwen/projects/<project>/memory/pinned/architecture.md 或 ~/.qwen/memories/pinned/preferences.md），使用与其他记忆文档相同的 frontmatter；有效的固定文件 Qwen 可读，并在下次重建 MEMORY.md 时被包含，受与其他记忆文档相同的大小和文件数限制。只有直接位于受管记忆根目录里的顶层 pinned/ 目录受保护；自动提取被指示不动固定记录，Dream 整合会跳过 pinned/；你仍然可以直接控制这些文件，并用显式的 /forget 请求删除它们。

定期清理：Qwen 定期梳理它保存的记忆，去重并清理过时的条目。当积累了足够多会话后，每天在后台自动运行一次；想立刻运行就用 /dream。清理期间你的会话正常继续。开关：自动记忆默认开启。要切换，打开 /memory 并用顶部的开关：可以只关自动保存、只关定期清理，或两者都关。也可以在 ~/.qwen/settings.json（适用于所有项目）或 .qwen/settings.json（仅此项目）里设置：

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

结构化召回（可选加入）：默认 Qwen 把记忆当作扁平的 MEMORY.md 索引读取。结构化协议用层级式记忆树取代它，只注入与你当前请求相关的子树，并给 Qwen 一个 search_memory 工具按需拉取完整条目；记忆集合超过寥寥几个文件之后，它花的 token 更少。它默认关闭，在 settings.json 里设 "memory": { "enableStructuredRecall": true }（需要重启），或用 QWEN_CODE_MEMORY_STRUCTURED_RECALL=1 只用于一次运行。打开它会启动后台元数据迁移：每个记忆文件获得召回所需的 frontmatter（类别、关键词、使用场景），每轮最多处理 10 个文件、只重写 frontmatter 而从不动笔记正文；该设置关闭时迁移从不被调度，所以什么都不被重写，也没有后台模型调用。

团队记忆（与协作者共享）：默认自动记忆只属于你：存在你的主目录下，从不共享。团队记忆是一个可选加入的层级，整个团队通过 git 共享。启用后，Qwen 多出第三个记忆目录 .qwen/team-memory/，在仓库内部，使用与私有层级相同的每记忆一个文件的布局和 MEMORY.md 索引。因为它提交到仓库，所以以正常方式与每个协作者共享：git pull 接收队友的记忆，提交/推送来分享你的；Qwen 把持久的、项目范围的知识（约定等）放在这里。按项目（或全局）在 settings.json 里启用："memory": { "enableTeamMemory": true }，默认关闭。注意事项：它受源代码控制，对所有有仓库访问权的人可见，把团队记忆当作提交到仓库；密钥被阻止（写入 .qwen/team-memory/ 会被扫描凭据（API key、令牌、私钥），检测到密钥就被拒绝而从不写入，扫描是兜底而不是保证，不要往那里放敏感数据）；改动可评审（团队记忆的写入像其他文件一样出现在 git status / PR diff 里，所以可以在提交前评审；在默认审批模式下 Qwen 也会在每次团队写入前询问，在 AUTO_EDIT/YOLO 模式下无提示应用但仍出现在 diff 里）；目录必须被 git 跟踪（如果你项目的 .gitignore 排除 .qwen/*，要重新包含该路径：!.qwen/team-memory/ 和 !.qwen/team-memory/**；用文件 glob 忽略形式 .qwen/*，而不是带尾部斜杠的目录形式 .qwen/，否则 git 完全跳过该文件夹，下面的 ! 重新包含无效，团队层级在 git 里静默为空；当该层级已启用但目录被 git 忽略或在任何 git 仓库之外时，Qwen 在启动时警告一次）。QWEN_CODE_MEMORY_TEAM=1 / =0 为单次运行覆盖该设置。

自动 git 同步（可选）：默认你用正常的 git 工作流共享团队记忆（pull 接收，commit/push 分享）。想让 Qwen 替你做，启用同步："memory": { "enableTeamMemory": true, "enableTeamMemorySync": true }。开启后，会话启动时 Qwen 尽力同步 .qwen/team-memory/ 目录：重建共享的 MEMORY.md 索引，先快进拉取协作者的更新，然后把你的团队记忆改动提交在上面，并只推送那个同步提交（通过显式的单分支 refspec），所以你加载的索引反映最新状态；它只暂存团队目录（你其他的工作改动不被触及）。启用前要知道两点：快进拉取作用于你整个当前分支，而不只是 .qwen/team-memory/（git 没有路径范围的拉取），所以同步会把你的分支快进到远程顶端；相反，推送是有范围的，只发布这次同步刚创建的提交，从不推送你其他未推送的提交（你的分支已领先于上游时，同步只在本地提交并跳过推送）。分叉的分支保持不动（--ff-only 从不合并）：这种情况下同步在该会话什么都不做，解决分叉（git pull）后恢复；没有上游（没有跟踪配置）的分支仍在本地提交但跳过推送，因为没有地方可推。

命令：/memory 打开记忆面板（开关自动保存、开关定期清理（dream）、打开你个人的 QWEN.md、打开项目 QWEN.md、浏览自动记忆文件夹）；/memory migrate-team 把团队记忆层级迁移到结构化元数据格式（个人和项目记忆在启用结构化召回后在后台自动迁移，团队记忆通过 git 共享，所以重写只在显式请求时运行）；/init 生成项目的起始 QWEN.md；/remember <text> 立即保存到自动记忆而不等 Qwen 自己捡起（如 /remember always use snake_case for Python variable names）；/forget <text> 移除匹配你描述的自动记忆条目；/dream 现在就运行记忆清理。

排障：Qwen 没有遵循我的 QWEN.md——打开 /memory 看加载了哪些文件，如果你的文件没列出，Qwen 看不到它（确保它在项目根目录或 ~/.qwen/ 里）；指令越具体越好用（对：Use 2-space indentation for TypeScript files；错：Format code nicely）；如果有多个互相冲突的 QWEN.md，Qwen 可能行为不一致，评审并去掉矛盾。我想看看 Qwen 保存了什么——运行 /memory 并选 Open auto-memory folder，所有保存的记忆都是可读的 markdown 文件。Qwen 总是忘事——如果自动记忆开着但似乎跨会话记不住，运行 /dream 强制清理一遍，并检查 /memory 确认两个开关都启用；对你总想让 Qwen 记住的东西，加到 QWEN.md 里：自动记忆是尽力而为的，QWEN.md 是有保证的。

规则

规则是一个 Markdown 文件，在会话开始时、或工作触及它所适用的文件的那一刻到达模型。规则放在 .qwen/rules/ 里，paths: 字段使第二种成为可能：关于你 React 组件的指导，在你编辑 Makefile 时不必出现在提示里。它们是上下文文件（QWEN.md，每个会话的每个请求都携带）的廉价对应物。

这些目录下的每个 .md 文件都会被发现，包括子目录里的，顺序是确定的。基线规则与条件规则：

---
description: How we write React components
paths:
  - 'src/**/*.tsx'
  - 'src/**/*.jsx'
---

Components are function components. Co-locate the test beside the component.
Never reach for a global store for state one screen owns.

带 paths: 的是条件规则：它在工具调用读取或编辑匹配其 glob 的文件之前不出现在提示里，之后在会话剩余时间里注入一次；不带 paths: 的是基线规则：从第一个请求起就是系统提示的一部分，与上下文文件完全一样，每一轮成本相同。两个字段都是可选的，完全没有 frontmatter 的规则是基线规则。要点：glob 与相对项目根目录的路径匹配（所有平台都用正斜杠，并且匹配点文件）；符号链接会被解析，所以不论工具调用用的是链接还是真实路径，规则都匹配；条件规则每个会话只注入一次，第二个匹配的文件不会重复；规则正文里的 HTML 注释在发送前被剥离。

来自扩展的规则：扩展可以随附 rules/ 目录，它的规则必须是条件规则：没有 paths: 的规则被跳过，并带点名它的启动警告。这个限制正是关键所在：扩展的上下文文件（contextFileName）会被拼进该扩展活动期间每个会话的每个请求里，没有相关性门控。扩展规则在提示里按所有者标注（如 charts:rules/charting.md），所以转录显示是谁的规则触发了；它们不受工作区信任把关（与项目规则不同），因为安装扩展本身就是显式行为。如果你写扩展：永远为真的事实（扩展的身份、词汇、一条硬约束）放进上下文文件；「处理 X 时做 Y」放进有 paths: 门控的规则或技能；模型按要求运行的流程放进技能。

技能适合模型选择遵循的流程；条件规则适合适用于代码库某个区域的约束（不论模型是否想到去查）。技能也可以用 paths: 门控，让它们的列表条目在相关之前也不出现在提示里。