Skip to main content
操作指南

记忆

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当前用户跨项目通用偏好和工作习惯否
/AGENTS.md团队共享的项目规则、架构说明、常用命令是
/AGENTS.local.md当前机器上的项目私有说明，例如本地服务地址或个人测试数据否
/.qoder/rules/&#42;.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 决定它何时生效。

存放位置

规则有两种作用域：
作用域位置作用范围是否提交
项目级/.qoder/rules/&#42;&#42;/&#42;.md文件所在的项目，与团队共享是
用户级~/.qoder-cn/rules/&#42;&#42;/&#42;.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 风格匹配。常见示例：
模式匹配
&#42;&#42;/&#42;.ts任意目录下的所有 TypeScript 文件
src/&#42;&#42;/&#42;src/ 下任意深度的所有文件
&#42;.md任意目录下的 Markdown 文件
/&#42;.md仅项目根目录的 Markdown 文件
src/components/&#42;.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 条记忆是正常结果。

记忆内容过期

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