> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 记忆

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 会读取可用的静态记忆文件，并把匹配内容作为上下文注入会话。

#### 常用位置

```text theme={null}
~/.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` 启动时，会检查：

```text theme={null}
/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，也可以显式设置：

```markdown theme={null}
---
trigger: always_on
---

# 通用项目约定

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

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

```markdown theme={null}
---
trigger: manual
---

# 发布检查清单

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

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

```markdown theme={null}
---
trigger: model_decision
description: 修改 API handler、schema 或接口错误结构时使用。
---

# API 规则

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

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

```markdown theme={null}
---
trigger: glob
glob:
  - src/api/**
  - "**/*.test.ts"
---

# API 规则

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

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

```markdown theme={null}
---
paths:
  - src/api/**
  - "**/*.test.ts"
---
```

#### Frontmatter 可配置项

| 配置项           | 可用值                                          | 说明                                                                                                                      |
| ------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `trigger`     | `always_on`、`manual`、`model_decision`、`glob` | 生效方式。`always_on` 表示始终生效；`manual` 表示手动引入；`model_decision` 表示模型决策，必须同时设置非空 `description`；`glob` 表示指定文件生效，必须同时设置有效 `glob`。 |
| `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

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

```markdown theme={null}
# 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` 所在目录解析。

```markdown theme={null}
# 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 应先核对当前事实再据此行动。

### 启用自动记忆

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

```bash theme={null}
QODER_MEMORY=1 qodercli
```

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

```bash theme={null}
QODER_MEMORY=1 QODER_MEMORY_USER=1 qodercli
```

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

### 自动记忆存储位置

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

```text theme={null}
~/.qoder/projects/<project>/memory/
```

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

```text theme={null}
~/.qoder/memory/
```

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

```text theme={null}
memory/
├── MEMORY.md
├── user-preferences.md
├── feedback-testing.md
└── project-release-context.md
```

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

## 查看和管理

在 TUI 中输入：

```text theme={null}
/memory
```

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

如果要在 TUI 内按主题文件管理自动记忆：

```text theme={null}
/memory manage
```

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

### 让 Qoder CLI 记住或忘记

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

```text theme={null}
记住这个项目的集成测试需要先启动本地 Redis。
```

或者：

```text theme={null}
忘记之前关于旧部署脚本的记忆。
```

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

```text theme={null}
把这条测试约定加到项目 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 条记忆是正常结果。

### 记忆内容过期

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