跳转到主要内容
Qoder CLI 每次会话都会重新构造上下文。需要跨会话保留的知识主要来自两类记忆：
  • AGENTS.md 文件：由你或团队维护的持久指令，适合放开发规范、项目结构、常用命令和协作约定。
  • 自动记忆：启用后由 Qoder CLI 在本机保存的 Markdown 记忆，适合记录后续会话仍有用的偏好、反馈、项目背景和外部参考。
记忆会作为上下文提供给模型，但它不是强制策略。需要硬性阻止某类命令、工具或路径时，请使用权限配置或 Hooks。

​
记忆类型

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

​
AGENTS.md

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

​
常用位置

~/.qoder/AGENTS.md
<project>/AGENTS.md
<project>/AGENTS.local.md
位置用途是否适合提交
~/.qoder/AGENTS.md当前用户跨项目通用偏好和工作习惯否
<project>/AGENTS.md团队共享的项目规则、架构说明、常用命令是
<project>/AGENTS.local.md当前机器上的项目私有说明，例如本地服务地址或个人测试数据否
如果需要使用其他文件名，可以通过 context.fileName 设置单个文件名或文件名数组。默认值是 AGENTS.md。

​
加载逻辑

启动或刷新记忆时，Qoder CLI 的项目记忆只做“向上查找”，不会扫描子目录：
  • 用户级记忆：加载用户配置目录中的 AGENTS.md。
  • 项目和本地项目记忆：在可信工作区内，从当前工作区目录向父目录查找 AGENTS.md 和 AGENTS.local.md，默认到 .git 所在目录为止。
  • 子目录记忆：启动时不预加载。只有 Qoder CLI 成功读取子目录里的文件后，才会从该文件所在目录向上补充此前未加载的 AGENTS.md 和 AGENTS.local.md。这些按需加载的内容会进入后续上下文，并显示在 /memory 中。
例如在 /repo/packages/app 启动时，会检查： 
/repo/packages/app/AGENTS.md
/repo/packages/AGENTS.md
/repo/AGENTS.md
如果从 /repo 启动，则不会预加载 /repo/packages/app/AGENTS.md；需要访问 packages/app 下的文件后才会按需加载。

​
编写建议

把 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 条记忆是正常结果。

​
记忆内容过期

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