CodeBuddy 记忆（配置）

一、确定记忆类型

CodeBuddy Code 提供四种分层结构的记忆位置，每种都有不同的用途：

所有记忆文件在启动 CodeBuddy Code 时自动加载到上下文中。加载顺序如下：

1. 用户级：加载 ~/.codebuddy/CODEBUDDY.md 等主文件及 ~/.codebuddy/rules/ 下的所有规则

2. 项目级主文件：从当前工作目录向上递归加载所有 CODEBUDDY.md 和 CODEBUDDY.local.md

3. 项目级规则：仅加载当前工作目录的 .codebuddy/rules/ 下的规则（不加载父目录的规则）

4. 子目录记忆：当 CodeBuddy 操作子目录中的文件时，动态加载该子目录的 CODEBUDDY.md

5. 本地记忆：加载 ./CODEBUDDY.local.md

注意：说明：

注意：CODEBUDDY.local.md 文件会自动添加到 .gitignore，非常适合存储不应提交到版本控制的私有项目特定偏好。

二、CODEBUDDY.md 导入

CODEBUDDY.md 文件可以使用 @path/to/import 语法导入其他文件。以下示例导入了 3 个文件：

查看 @README 了解项目概述，@package.json 了解可用的 npm 命令。# 附加说明- Git 工作流程 @docs/git-instructions.md

支持相对路径和绝对路径。特别是，导入用户主目录中的文件是一种方便的方式，让团队成员可以提供不会提交到仓库的个人指令。导入是 CODEBUDDY.local.md 的替代方案，在多个 git worktree 之间工作得更好。

# 个人偏好- @~/.codebuddy/my-project-instructions.md

为避免潜在冲突，代码块和代码范围内的导入不会被解析。

此代码范围不会被视为导入：`@tencent-ai/codebuddy-code`

导入的文件可以递归导入其他文件，最大深度为 5 层。你可以通过运行 /memory 命令查看已加载的记忆文件。

三、CodeBuddy 如何查找记忆

CodeBuddy Code 递归读取记忆：从当前工作目录开始，CodeBuddy Code 向上递归到根目录（但不包括根目录 /），并读取找到的任何 CODEBUDDY.md 或 CODEBUDDY.local.md 文件。这在大型仓库中特别方便，当你在 foo/bar/ 目录中运行 CodeBuddy Code，并且在 foo/CODEBUDDY.md 和 foo/bar/CODEBUDDY.md 两处都有记忆时。

CodeBuddy 还会发现当前工作目录下子树中嵌套的 CODEBUDDY.md。这些文件不会在启动时加载，只有当 CodeBuddy 读取这些子树中的文件时才会包含。

四、使用 /memory 管理记忆

在会话中使用 /memory 斜杠命令，打开记忆管理面板。在该面板中你可以：

·打开 Auto Memory 目录

·打开 MEMORY.md 索引文件

·切换 Auto Memory 开关

五、设置项目记忆

假设你想设置一个 CODEBUDDY.md 文件来存储重要的项目信息、约定和常用命令。项目记忆可以存储在 ./CODEBUDDY.md 或 ./.codebuddy/CODEBUDDY.md 中。

使用以下命令为你的代码库引导一个 CODEBUDDY.md：

> /init

注意：提示：

六、使用 .codebuddy/rules/ 实现模块化规则

对于较大的项目，你可以使用 .codebuddy/rules/ 目录将指令组织到多个文件中。这允许团队维护专注的、组织良好的规则文件，而不是一个庞大的 CODEBUDDY.md。

七、基本结构

将 markdown 文件放在项目的 .codebuddy/rules/ 目录中：

your-project/├── .codebuddy/│ ├── CODEBUDDY.md # 主要项目指令│ └── rules/│ ├── code-style.md # 代码风格指南│ ├── testing.md # 测试规范│ └── security.md # 安全要求

.codebuddy/rules/ 中的所有 .md 文件都会自动作为项目记忆加载，优先级与 .codebuddy/CODEBUDDY.md 相同。

注意：项目级规则仅从当前工作目录（workDir）的 .codebuddy/rules/ 加载，不会加载父目录的规则文件夹。这确保规则的作用域清晰明确。

八、规则控制字段

规则文件支持以下 YAML frontmatter 字段来控制加载和应用行为：

九、规则类型判定

规则类型由 alwaysApply 和 paths 共同决定：

十、示例

始终应用的规则（默认行为）：

—# alwaysApply 默认为 true，可省略—# 通用代码规范- 使用 2 空格缩进- 文件末尾保留空行

条件触发规则：

—alwaysApply: falsepaths: src/api/**/*.ts—# API 开发规则- 所有 API 端点必须包含输入验证- 使用标准错误响应格式- 包含 OpenAPI 文档注释

禁用规则（临时关闭）：

—enabled: false—# 暂时不使用的规则

注意：paths 字段不仅限于 .codebuddy/rules/ 目录，在所有记忆文件（包括 CODEBUDDY.md、CODEBUDDY.local.md）中都可以使用。

十一、Glob 模式

paths 字段支持标准 glob 模式，并启用了 matchBase 选项：

matchBase 说明：启用 matchBase 后，不包含路径分隔符的模式（如 *.ts）会匹配任意目录下的文件。例如 *.ts 可以匹配 src/utils/helper.ts。

你可以使用大括号高效匹配多个模式：

—paths: src/**/*.{ts,tsx}—# TypeScript/React 规则

这会展开匹配 src/**/*.ts 和 src/**/*.tsx。你也可以用逗号组合多个模式：

—paths: {src，lib}/**/*.ts, tests/**/*.test.ts—

十二、子目录

规则可以组织到子目录中以获得更好的结构：

.codebuddy/rules/├── frontend/│ ├── react.md│ └── styles.md├── backend/│ ├── api.md│ └── database.md└── general.md

所有 .md 文件都会被递归发现。

十三、符号链接

.codebuddy/rules/ 目录支持符号链接，允许你在多个项目之间共享通用规则：

# 符号链接共享规则目录ln -s ~/shared-codebuddy-rules .codebuddy/rules/shared# 符号链接单个规则文件ln -s ~/company-standards/security.md .codebuddy/rules/security.md

符号链接会被解析，其内容正常加载。循环符号链接会被检测并优雅处理。

十四、用户级规则

你可以在 ~/.codebuddy/rules/ 中创建适用于所有项目的个人规则：

~/.codebuddy/rules/├── preferences.md # 你的个人编码偏好└── workflows.md # 你首选的工作流程

用户级规则在项目规则之前加载，给予项目规则更高的优先级。

使用建议：

·保持规则专注：每个文件应涵盖一个主题（如 testing.md、api-design.md）

·使用描述性文件名：文件名应表明规则涵盖的内容

·谨慎使用条件规则：仅当规则真正适用于特定文件类型时才添加 paths frontmatter

·用子目录组织：分组相关规则（如 frontend/、backend/）

十五、记忆使用建议

·具体明确：“使用 2 空格缩进”比“正确格式化代码”更好。

·使用结构组织：将每条记忆格式化为要点，并在描述性 markdown 标题下分组相关记忆。

·定期审查：随着项目发展更新记忆，确保 CodeBuddy 始终使用最新的信息和上下文。

十六、设置语言偏好

推荐使用 /config 命令配置首选响应语言（详见 设置配置），这是最简单直接的方式：

> /config# 选择 Language，输入你的首选语言，如"简体中文"

如果需要更细粒度的控制（如代码注释语言、提交信息语言），可以在记忆文件中添加：

## CodeBuddy Added Memories### 语言偏好- 代码注释使用中文- 提交信息使用中文

项目级语言设置会覆盖用户级设置。

十八、用户级记忆 (~/.codebuddy/CODEBUDDY.md)

## CodeBuddy Added Memories### 工具偏好- 使用 pnpm 而非 npm### 代码偏好- 倾向函数式编程风格- 优先代码可读性

注意：提示：

注意：响应语言推荐通过 /config 设置，而非在记忆文件中配置。

十九、项目级记忆 (./CODEBUDDY.md)

## CodeBuddy Added Memories### 项目架构- 使用微服务架构- 前端：React + TypeScript- 后端：Node.js + Express### 团队约定- PR 需要 2 人审查- 遵循 Conventional Commits

20、本地项目记忆 (./CODEBUDDY.local.md)

## CodeBuddy Added Memories### 本地开发配置- 数据库端口：5433- 使用 debug 模式- 跳过 CI 快速测试

21、Auto Memory 系统

Auto Memory 是 CodeBuddy Code 的自动记忆系统，允许 CodeBuddy 在会话之间自动保存和检索持久化记忆。与 CODEBUDDY.md 的静态记忆不同，Auto Memory 由 CodeBuddy 在工作过程中自主决定保存什么内容。

22、存储位置

·项目记忆：~/.codebuddy/memories/{project-id}/

·全局记忆：~/.codebuddy/memories/global/

每个项目都有一个 MEMORY.md 索引文件，其前 200 行会自动加载到会话上下文。详细的记忆内容应存储在独立的主题文件中（如 preferences.md、decisions.md），并从 MEMORY.md 链接引用。

23、启用与禁用

·通过 /config 面板切换 Auto Memory 开关

·通过 /memory 命令面板切换

·通过 settings.json 配置："memory": { "autoMemoryEnabled": false }

·通过环境变量：CODEBUDDY_DISABLE_AUTO_MEMORY=1

24、Typed Memory 模式

Typed Memory 是 Auto Memory 的增强版本，提供结构化的记忆类型系统（默认启用）。记忆文件使用 YAML frontmatter 和 4 种类型进行管理。

4 种记忆类型：

记忆文件格式：

—name: 用户角色description: 用户的职业背景和技术专长type: user—用户是资深后端工程师，拥有 10 年 Go 语言经验，但首次接触项目的 React 前端部分。

禁用方式（如需回退到通用格式）：

·通过 settings.json 配置："memory": { "typedMemory": false }

·通过环境变量：CODEBUDDY_TYPED_MEMORY_ENABLED=false

注意：提示：

注意：Typed Memory 默认启用。如果禁用，Auto Memory 会使用简化的通用格式，无类型系统和 YAML frontmatter。

25、缓存与重载

26、常见问题

AGENTS.md 和 CODEBUDDY.md 有什么区别？

CodeBuddy Code 同时支持 AGENTS.md 和 CODEBUDDY.md 作为项目记忆文件：

·AGENTS.md 支持：如果项目中存在 CODEBUDDY.md 文件，项目级记忆将使用 CODEBUDDY.md，否则使用 AGENTS.md

·自动检测：系统会自动检测项目中是否存在 AGENTS.md 文件

27、推荐使用 CODEBUDDY.md

虽然我们保持对 AGENTS.md 的支持，但建议新项目使用 CODEBUDDY.md 作为记忆文件名，以保持与 CodeBuddy Code 品牌的一致性。

如何迁移 AGENTS.md 到 CODEBUDDY.md？

重命名 AGENTS.md 为 CODEBUDDY.md 即可。系统自动检测，CODEBUDDY.md 优先加载。

记忆文件如何同步？

·项目记忆：通过 Git 与团队同步

·用户记忆：本地存储，不同步

·本地项目记忆：本地存储，自动添加到 .gitignore

条件规则什么时候触发？

在以下情况触发：

·使用 @path/to/file 引用文件时

·使用 Read、Glob、Grep、Edit、Write 等文件操作工具时

触发后，匹配规则会作为系统提醒注入到当前消息上下文。当所有条件规则都已注入后，不会重复注入。

如何调试规则加载问题？

1. 运行 /memory 查看已加载的规则列表

2. 检查 frontmatter 格式是否正确（— 分隔符）

3. 确认 glob 模式是否匹配

4. 重启 CodeBuddy 清除缓存

规则文件大小有限制吗？

建议保持简洁。特别大的规范文档使用 @import 语法引用而非直接包含。

28、与 CodeBuddy IDE 的兼容性

CodeBuddy Code CLI 和 CodeBuddy IDE 都支持记忆/规则功能，但条件规则的触发方式不同：

·CLI：条件规则通过 glob 模式自动匹配文件操作触发（包括 @ 引用和工具调用），不支持模型智能选择规则

·IDE：条件规则支持用户通过 @RuleName 手动引用，也支持模型基于上下文智能决策激活规则