AI 助理
文档备案控制台
官方文档
首页

记忆

更新时间：
复制 MD 格式
产品详情
我的收藏

Qoder CN CLI 每次会话都会重新构造上下文。需要跨会话保留的知识主要来自两类记忆：AGENTS.md 文件（由你或团队维护的持久指令，适合放开发规范、项目结构、常用命令和协作约定）和自动记忆（启用后由 Qoder CN CLI 在本机保存的 Markdown 记忆，适合记录后续会话仍有用的偏好、反馈、项目背景和外部参考）。

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

记忆类型

机制

谁来写

适合内容

作用域

查看入口

AGENTS.md

用户或团队

明确、稳定、希望每次会话都遵守的说明

用户级、项目级、本地项目级、插件提供

/memory

自动记忆

Qoder CN CLI

从对话中学到的可复用信息，例如偏好、反馈、项目背景、外部资料位置

项目级；可选用户级

/memory 打开 auto-memory folder；/memory manage 管理主题文件

AGENTS.md

AGENTS.md 是 Qoder CN CLI 默认的上下文文件名。启动或刷新记忆时，Qoder CN CLI 会读取可用的 AGENTS.md 文件，并把内容作为上下文注入会话。

常用位置

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

位置

用途

是否适合提交

~/.qoder-cn/AGENTS.md

当前用户跨项目通用偏好和工作习惯

否

<project>/AGENTS.md

团队共享的项目规则、架构说明、常用命令

是

<project>/AGENTS.local.md

当前机器上的项目私有说明，例如本地服务地址或个人测试数据

否

<project>/.qoder/rules/*.md

按主题或文件范围拆分的项目规则

是

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

加载逻辑

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

  • 用户级记忆：加载用户配置目录中的 AGENTS.md。

  • 项目和本地项目记忆：在可信工作区内，从当前工作区目录向父目录查找 AGENTS.md、AGENTS.local.md 和 .qoder/rules/**/*.md，默认到 .git 所在目录为止。

  • 没有 paths frontmatter 的规则会随项目记忆一起加载；带 paths frontmatter 的规则只会在 Qoder CN CLI 访问匹配文件后按需加载。

  • 子目录记忆：启动时不预加载。只有 Qoder CN 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 文件；可选的 paths frontmatter 决定它何时生效。

存放位置

规则有两种作用域：

作用域

位置

作用范围

是否提交

项目级

<project>/.qoder/rules/**/*.md

文件所在的项目，与团队共享

是

用户级

~/.qoder-cn/rules/**/*.md

你打开的每个项目，仅限本机个人使用

否

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

始终生效 vs 按路径生效

规则可选的 paths frontmatter 决定它何时加载：

  • 没有 paths frontmatter：规则始终生效。启动时即 eager 加载——项目级规则随项目层加载，用户级规则随用户层加载。

  • 带 paths frontmatter：规则按路径生效。只有在 Qoder CN CLI 访问到路径匹配某个 glob 的文件后，才会按需加载。

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

# API 规则

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

关于 paths：

  • 它是一组 glob 模式。项目级规则的 glob 相对于包含 .qoder/ 目录的项目目录匹配；用户级规则的 glob 相对于当前项目根目录匹配。

  • 只使用 **（匹配全部）的规则会被视为始终生效。

  • paths 是内部路由元数据：它只决定规则何时生效，不会注入到模型上下文中——注入的只有规则正文。

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

模式

匹配

**/*.ts

任意目录下的所有 TypeScript 文件

src/**/*

src/ 下任意深度的所有文件

*.md

任意目录下的 Markdown 文件

/*.md

仅项目根目录的 Markdown 文件

src/components/*.tsx

直接位于 src/components/ 下的文件（不含嵌套）

会话中更新规则

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

编写建议

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

  • 构建、测试、格式化和发布命令

  • 项目目录结构和关键模块边界

  • 代码风格、命名规则和评审要求

  • 团队约定的工作流，例如提交、分支、测试数据准备

  • 对当前仓库长期有效的安全或合规注意事项

不适合写：

  • 只对当前这次任务有用的临时状态

  • 会很快过期的排期和进度

  • 已经能从代码或 README 直接看出的长篇重复内容

  • 必须强制执行的安全策略。此类要求应放进 权限配置或 钩子

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

# 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 CN CLI 会在对话过程中把值得跨会话复用的信息保存为本机 Markdown 文件。它不会把每段对话都保存下来，而是根据内容判断是否值得记住。

适合保存的内容

自动记忆支持四类内容：

类型

用途

user

用户角色、长期偏好、跨项目工作习惯

feedback

用户对工作方式的纠正或确认，例如"以后不要这样做"

project

当前项目中无法直接从代码推导出的背景、约束或决策原因

reference

外部系统、看板、仪表盘、文档等资料位置

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

启用自动记忆

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

QODER_MEMORY=1 qoderclicn

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

QODER_MEMORY=1 QODER_MEMORY_USER=1 qoderclicn

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

自动记忆存储位置

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

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

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

~/.qoder-cn/memory/

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

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

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

查看和管理

在 TUI 中输入：

/memory

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

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

/memory manage

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

让 Qoder CN CLI 记住或忘记

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

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

或者：

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

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

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

排查问题

Qoder CN CLI 没有遵守 AGENTS.md

  • 运行 /memory，确认目标文件出现在列表中。

  • 确认当前目录位于可信工作区内；未信任目录不会加载项目设置、Hooks、MCP 和 AGENTS.md。

  • 检查是否存在冲突指令，尤其是用户级、项目级、本地项目级文件之间的冲突。

  • 检查 agentsMdExcludes 是否排除了目标文件。

  • 把笼统要求改成具体、可验证的规则。

@ 导入没有生效

  • 确认路径真实存在，并且不是写在 Markdown 代码块或行内代码中。

  • 项目外导入默认会被阻止，需要批准外部导入或调整安全设置。

  • 对 npm 包名、普通提及和没有文件特征的 @word，Qoder CN CLI 不会按文件导入处理。

自动记忆没有出现

  • 确认当前是 TUI 交互式会话。

  • 确认启动时已设置 QODER_MEMORY=1。

  • 运行 /memory 查看是否出现 auto-memory folder 入口；或运行 /memory manage 查看自动记忆管理器是否可用。

  • 不是每一轮都会保存记忆；没有值得跨会话复用的信息时，创建 0 条记忆是正常结果。

记忆内容过期

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

上一篇：工具下一篇：插件