记忆 - Qoder

Qoder CLI 每次会话都会重新构造上下文。需要跨会话保留的知识主要来自两类记忆：

静态记忆：由你或团队维护的持久指令，包括 AGENTS.md 和 rules，适合放开发规范、项目结构、常用命令和协作约定。
自动记忆：启用后由 Qoder CLI 在本机保存的 Markdown 记忆，适合记录后续会话仍有用的偏好、反馈、项目背景和外部参考。

记忆会作为上下文提供给模型，但它不是强制策略。需要硬性阻止某类命令、工具或路径时，请使用权限配置或 Hooks。

记忆类型

机制	谁来写	适合内容	作用域	查看入口
静态记忆	用户或团队	明确、稳定、希望每次会话都遵守的说明；`AGENTS.md` 放整体说明，rules 按主题或文件范围拆分	用户级、项目级、本地项目级、插件提供	`/memory`
自动记忆	Qoder CLI	从对话中学到的可复用信息，例如偏好、反馈、项目背景、外部资料位置	项目级；可选用户级	`/memory` 打开 auto-memory folder；`/memory manage` 管理主题文件

静态记忆

静态记忆由你或团队显式编写和维护。AGENTS.md 适合承载整体项目说明和稳定约定，rules 适合把同类指令按主题或文件范围拆分成多个 Markdown 文件。

静态记忆文件

AGENTS.md 是 Qoder CLI 默认的上下文文件名，rules 是放在 rules/ 目录下的 Markdown 规则文件。启动或刷新记忆时，Qoder CLI 会读取可用的静态记忆文件，并把匹配内容作为上下文注入会话。

常用位置

~/.qoder/AGENTS.md
<project>/AGENTS.md
<project>/AGENTS.local.md
<project>/.qoder/rules/*.md

位置	用途	是否适合提交
`~/.qoder/AGENTS.md`	当前用户跨项目通用偏好和工作习惯	否
`<project>/AGENTS.md`	团队共享的项目规则、架构说明、常用命令	是
`<project>/AGENTS.local.md`	当前机器上的项目私有说明，例如本地服务地址或个人测试数据	否
`<project>/.qoder/rules/*.md`	按主题或文件范围拆分的项目规则	是

如果需要使用其他文件名，可以通过 context.fileName 设置单个文件名或文件名数组。默认值是 AGENTS.md。

加载逻辑

启动或刷新记忆时，Qoder CLI 的项目记忆会向上查找，并检查每一层的项目规则目录：

用户级记忆：加载用户配置目录中的 AGENTS.md。
项目和本地项目记忆：在可信工作区内，从当前工作区目录向父目录查找 AGENTS.md、AGENTS.local.md 和 .qoder/rules/**/*.md，默认到 .git 所在目录为止。
规则的 frontmatter 决定加载方式：始终生效的规则会随项目记忆一起加载；指定文件生效的规则只会在 Qoder CLI 访问匹配文件后按需加载；手动规则和模型决策规则不会在启动时注入正文。
子目录记忆：启动时不预加载。只有 Qoder CLI 成功读取子目录里的文件后，才会从该文件所在目录向上补充此前未加载的 AGENTS.md、AGENTS.local.md 或匹配的 .qoder/rules/**/*.md。这些按需加载的内容会进入后续上下文，并显示在 /memory 中。

例如在 /repo/packages/app 启动时，会检查：

/repo/packages/app/AGENTS.md
/repo/packages/app/.qoder/rules/*.md
/repo/packages/AGENTS.md
/repo/packages/.qoder/rules/*.md
/repo/AGENTS.md
/repo/.qoder/rules/*.md

如果从 /repo 启动，则不会预加载 /repo/packages/app/AGENTS.md 或 /repo/packages/app/.qoder/rules/*.md；需要访问 packages/app 下的文件后才会按需加载。

规则（Rules）

规则是放在 rules/ 目录下、按主题拆分的指令文件，用来替代单个臃肿的 AGENTS.md。可以按主题（测试、API、安全）或按其管辖的代码区域来拆分。每条规则就是一个普通 Markdown 文件；可选的 frontmatter 决定它何时生效。 Qoder CLI 的 rules frontmatter 兼容 Qoder Desktop 中配置的 rules 设置；从 Qoder Desktop 同步或复制的规则文件可以继续使用原有触发配置。

存放位置

规则有两种作用域：

作用域	位置	作用范围	是否提交
项目级	`<project>/.qoder/rules/*/.md`	文件所在的项目，与团队共享	是
用户级	`~/.qoder/rules/*/.md`	你打开的每个项目，仅限本机个人使用	否

项目级规则可以位于工作区的任意层级（含嵌套子目录），通过从工作目录向上查找发现。用户级规则从用户配置目录读取，对所有项目生效。

支持的生效方式

Qoder CLI 支持四种 rules 生效方式。没有配置加载相关 frontmatter 时，规则默认始终生效；trigger 存在时优先于 alwaysApply。

生效方式	适合场景	配置方式	加载行为
始终生效	每次会话都要遵守的通用规则	不写加载 frontmatter，或设置 `trigger: always_on`，或设置 `alwaysApply: true`	启动或刷新记忆时加载规则正文。
手动引入	偶尔使用，需要明确引入的规则	`trigger: manual` 或 `alwaysApply: false`	不自动注入规则正文。
模型决策	可用一句描述判断是否与当前任务相关的规则	`trigger: model_decision` + 非空 `description`	只注入规则路径和说明，模型判断相关时再读取规则正文。
指定文件生效	只对某些文件或目录生效的规则	`trigger: glob` + `glob`，或直接配置 `paths`	Qoder CLI 访问匹配文件后，按需加载规则正文。

trigger: model_decision 必须同时设置非空 description；trigger: glob 必须同时设置有效 glob。缺少必需字段时，规则正文不会自动注入上下文。

配置示例

始终生效的规则可以不写 frontmatter，也可以显式设置：

---
trigger: always_on
---

# 通用项目约定

- 提交前运行测试。
- 修改公共 API 时同步更新文档。

手动引入的规则不会自动注入上下文：

---
trigger: manual
---

# 发布检查清单

- 确认版本号已更新。
- 确认 changelog 已补充。

模型决策规则需要提供 description，用于判断是否需要读取规则正文：

---
trigger: model_decision
description: 修改 API handler、schema 或接口错误结构时使用。
---

# API 规则

- 使用 `src/api/schema/` 下的共享 schema 校验请求体。
- 每个 handler 必须返回标准错误结构。

指定文件生效时，可以使用 trigger: glob + glob：

---
trigger: glob
glob:
  - src/api/**
  - "**/*.test.ts"
---

# API 规则

- 使用 `src/api/schema/` 下的共享 schema 校验请求体。
- 每个 handler 必须返回标准错误结构。

也可以直接使用 paths 配置按路径生效：

---
paths:
  - src/api/**
  - "**/*.test.ts"
---

Frontmatter 可配置项

配置项	可用值	说明
`trigger`	`always_on`、`manual`、`model_decision`、`glob`	生效方式。`always_on` 表示始终生效；`manual` 表示手动引入；`model_decision` 表示模型决策，必须同时设置非空 `description`；`glob` 表示指定文件生效，必须同时设置有效 `glob`。
`alwaysApply`	`true`、`false`	兼容配置。`true` 等价于 `trigger: always_on`；`false` 等价于 `trigger: manual`。
`description`	字符串	模型决策规则的说明，帮助模型判断是否需要读取规则正文。
`glob`	单个 glob 或 glob 列表	与 `trigger: glob` 搭配，指定规则生效的文件范围。
`paths`	单个 glob 或 glob 列表	指定规则生效的文件范围，行为等价于 `trigger: glob` + `glob`。

关于 glob 和 paths：

它是一组 glob 模式。项目级规则的 glob 相对于包含 .qoder/ 目录的项目目录匹配；用户级规则的 glob 相对于当前项目根目录匹配。
它们是内部路由元数据：只决定规则何时生效，不会随规则正文注入到模型上下文。

模式采用 gitignore 风格匹配。常见示例：

模式	匹配
`*/.ts`	任意目录下的所有 TypeScript 文件
`src/*/`	`src/` 下任意深度的所有文件
`*.md`	任意目录下的 Markdown 文件
`/*.md`	仅项目根目录的 Markdown 文件
`src/components/*.tsx`	直接位于 `src/components/` 下的文件（不含嵌套）

会话中更新规则

规则加载后，Qoder CLI 会在本次会话剩余时间里持续监视该文件。编辑规则（无论通过哪种方式加载、项目级还是用户级）会在下一轮被感知，因此你可以即时调整规则、让 Qoder CLI 无需重启就遵循新版本。按路径生效的规则在首次匹配到被访问文件时也会被纳入监视。

编写建议

把 AGENTS.md 当成“下次会话还要知道的事实和约定”。适合写：

构建、测试、格式化和发布命令
项目目录结构和关键模块边界
代码风格、命名规则和评审要求
团队约定的工作流，例如提交、分支、测试数据准备
对当前仓库长期有效的安全或合规注意事项

不适合写：

只对当前这次任务有用的临时状态
会很快过期的排期和进度
已经能从代码或 README 直接看出的长篇重复内容
必须强制执行的安全策略。此类要求应放进权限配置或 Hooks

指令越具体越稳定。例如：

# Development

- Use `pnpm test` before committing changes.
- API handlers live in `src/api/handlers/`.
- Do not modify generated files under `src/generated/`.

导入其他文件

AGENTS.md 可以用 @path/to/file 引入其他文件。相对路径基于当前 AGENTS.md 所在目录解析。

# Project Notes

See @README.md for the high-level architecture.
Use @docs/testing.md for test data setup.

导入规则：

支持相对路径、绝对路径和 ~/ 路径。
Markdown 行内代码和代码块中的 @... 不会被当作导入。
项目和本地项目记忆默认只允许导入项目边界内的文件；指向项目外的导入需要显式批准或通过安全设置允许。
导入会递归展开，并有深度限制，避免循环导入无限展开。

如果只是想在文本中提到 @README.md，请写成 `@README.md`。

自动记忆

自动记忆启用后，Qoder CLI 会在对话过程中把值得跨会话复用的信息保存为本机 Markdown 文件。它不会把每段对话都保存下来，而是根据内容判断是否值得记住。

适合保存的内容

自动记忆支持四类内容：

类型	用途
`user`	用户角色、长期偏好、跨项目工作习惯
`feedback`	用户对工作方式的纠正或确认，例如“以后不要这样做”
`project`	当前项目中无法直接从代码推导出的背景、约束或决策原因
`reference`	外部系统、看板、仪表盘、文档等资料位置

自动记忆是本机文件，不会因为提交代码自动同步到其他机器。它也可能过期；当记忆涉及文件、函数、配置或外部状态时，Qoder CLI 应先核对当前事实再据此行动。

启用自动记忆

自动记忆只在交互式会话中运行。当前实现使用环境变量作为有效开关：

QODER_MEMORY=1 qodercli

如果还想启用跨项目的用户级自动记忆根目录，同时设置：

QODER_MEMORY=1 QODER_MEMORY_USER=1 qodercli

QODER_MEMORY_USER 只有在 QODER_MEMORY 已启用时才生效。未启用自动记忆时，/memory 仍可管理 AGENTS.md 文件；/memory manage 会提示自动记忆不可用。

自动记忆存储位置

项目级自动记忆保存在当前项目对应的 Qoder 配置目录下：

~/.qoder/projects/<project>/memory/

启用用户级自动记忆后，还会使用：

~/.qoder/memory/

每个自动记忆目录包含一个 MEMORY.md 索引和若干主题文件：

memory/
├── MEMORY.md
├── user-preferences.md
├── feedback-testing.md
└── project-release-context.md

MEMORY.md 是索引，不应写入长篇正文。Qoder CLI 启动时会读取每个活跃自动记忆根的 MEMORY.md，最多读取前 200 行或约 25KB。更详细的内容应放在单独的主题文件中，由索引指向。

查看和管理

在 TUI 中输入：

/memory

/memory 会打开记忆概览，显示用户级、项目级、本地项目级记忆文件，并在自动记忆启用时显示 Open auto-memory folder 入口。选择该入口会用系统文件管理器打开对应的 auto-memory folder。如果要在 TUI 内按主题文件管理自动记忆：

/memory manage

/memory manage 会打开自动记忆管理器，可以查看、打开、编辑或删除自动记忆主题文件。删除主题文件时，Qoder CLI 会同步移除对应 MEMORY.md 索引行。

让 Qoder CLI 记住或忘记

可以直接用自然语言表达：

记住这个项目的集成测试需要先启动本地 Redis。

或者：

忘记之前关于旧部署脚本的记忆。

如果内容更像团队规则或项目说明，建议明确要求写入 AGENTS.md：

把这条测试约定加到项目 AGENTS.md。

排查问题

Qoder CLI 没有遵守 `AGENTS.md`

运行 /memory，确认目标文件出现在列表中。
确认当前目录位于可信工作区内；未信任目录不会加载项目设置、Hooks、MCP 和 AGENTS.md。
检查是否存在冲突指令，尤其是用户级、项目级、本地项目级文件之间的冲突。
检查 agentsMdExcludes 是否排除了目标文件。
把笼统要求改成具体、可验证的规则。

`@` 导入没有生效

确认路径真实存在，并且不是写在 Markdown 代码块或行内代码中。
项目外导入默认会被阻止，需要批准外部导入或调整安全设置。
对 npm 包名、普通提及和没有文件特征的 @word，Qoder CLI 不会按文件导入处理。

自动记忆没有出现

确认当前是 TUI 交互式会话。
确认启动时已设置 QODER_MEMORY=1。
运行 /memory 查看是否出现 auto-memory folder 入口；或运行 /memory manage 查看自动记忆管理器是否可用。
不是每一轮都会保存记忆；没有值得跨会话复用的信息时，创建 0 条记忆是正常结果。

记忆内容过期

记忆反映的是写入时的上下文。处理当前代码、配置、外部系统状态时，应以当前文件和当前系统为准；如果发现记忆已经过期，更新或删除对应记忆。

​记忆类型

​静态记忆

​静态记忆文件

​常用位置

​加载逻辑

​规则（Rules）

​存放位置

​支持的生效方式

​配置示例

​Frontmatter 可配置项

​会话中更新规则

​编写建议

​导入其他文件

​自动记忆

​适合保存的内容

​启用自动记忆

​自动记忆存储位置

​查看和管理

​让 Qoder CLI 记住或忘记

​排查问题

​Qoder CLI 没有遵守 AGENTS.md

​@ 导入没有生效

​自动记忆没有出现

​记忆内容过期