管理 CodeBuddy 的记忆 ​

了解如何通过不同的记忆位置和最佳实践来管理 CodeBuddy Code 跨会话的记忆。

CodeBuddy Code 可以跨会话记住您的偏好，例如代码风格指南和工作流程中的常用命令。

确定记忆类型 ​

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

记忆类型位置用途使用场景示例共享范围
项目记忆./CODEBUDDY.md 或 ./.codebuddy/CODEBUDDY.md项目的团队共享指令项目架构、编码标准、常用工作流程通过源代码管理与团队成员共享
项目规则./.codebuddy/rules/*.md模块化的、按主题划分的项目指令语言特定指南、测试规范、API 标准通过源代码管理与团队成员共享
用户记忆~/.codebuddy/CODEBUDDY.md适用于所有项目的个人偏好代码风格偏好、个人工具快捷方式仅限本人（所有项目）
项目记忆（本地）./CODEBUDDY.local.md个人的项目特定偏好您的沙箱 URL、首选测试数据仅限本人（当前项目）

所有记忆文件在启动 CodeBuddy Code 时自动加载到上下文中。层级较高的文件优先级更高，先加载，为更具体的记忆提供基础。

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

CODEBUDDY.md 导入 ​

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

markdown
查看 @README 了解项目概述，@package.json 了解可用的 npm 命令。

# 附加说明
- Git 工作流程 @docs/git-instructions.md

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

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

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

markdown
此代码范围不会被视为导入：`@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 斜杠命令，可以在系统编辑器中打开任何记忆文件进行更广泛的添加或整理。

设置项目记忆 ​

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

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

> /init

提示：

  • 包含常用命令（构建、测试、lint）以避免重复搜索
  • 记录代码风格偏好和命名约定
  • 添加项目特定的重要架构模式
  • CODEBUDDY.md 记忆既可用于与团队共享的指令，也可用于个人偏好

使用 .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 相同。

路径特定规则 ​

规则可以使用 YAML frontmatter 的 paths 字段限定到特定文件。这些条件规则仅在 CodeBuddy 处理匹配指定模式的文件时才适用。

markdown
---
paths: src/api/**/*.ts
---

# API 开发规则

- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释

没有 paths 字段的规则会无条件加载，适用于所有文件。

Glob 模式 ​

paths 字段支持标准 glob 模式：

模式匹配
**/*.ts任意目录下的所有 TypeScript 文件
src/**/*src/ 目录下的所有文件
*.md项目根目录下的 Markdown 文件
src/components/*.tsx特定目录下的 React 组件

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

markdown
---
paths: src/**/*.{ts,tsx}
---

# TypeScript/React 规则

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

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

子目录 ​

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

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

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

符号链接 ​

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

bash
# 符号链接共享规则目录
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 始终使用最新的信息和上下文。

设置语言偏好 ​

在用户级记忆中添加语言偏好：

markdown
## CodeBuddy Added Memories

### 语言偏好
- 请始终使用中文回答我的问题
- 代码注释使用中文
- 提交信息使用中文

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

分层记忆策略示例 ​

用户级记忆 (~/.codebuddy/CODEBUDDY.md) ​

markdown
## CodeBuddy Added Memories

### 语言与工具
- 请始终使用中文回答
- 使用 pnpm 而非 npm

### 代码偏好
- 倾向函数式编程风格
- 优先代码可读性

项目级记忆 (./CODEBUDDY.md) ​

markdown
## CodeBuddy Added Memories

### 项目架构
- 使用微服务架构
- 前端：React + TypeScript
- 后端：Node.js + Express

### 团队约定
- PR 需要 2 人审查
- 遵循 Conventional Commits

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

markdown
## CodeBuddy Added Memories

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

缓存与重载 ​

操作重新加载说明
进程重启是缓存清空
通过 /memory 编辑是自动清除缓存
/clear 命令否仅清除消息历史
手动修改文件否需手动重启
新增/删除规则文件否需手动重启

常见问题 ​

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

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

  • AGENTS.md 支持：如果项目中存在 CODEBUDDY.md 文件，项目级记忆将使用 CODEBUDDY.md，否则使用 AGENTS.md
  • 自动检测：系统会自动检测项目中是否存在 AGENTS.md 文件

推荐使用 CODEBUDDY.md ​

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

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

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

记忆文件如何同步？

  • 项目记忆：通过 Git 与团队同步
  • 用户记忆：本地存储，不同步
  • 本地项目记忆：本地存储，自动添加到 .gitignore

条件规则什么时候触发？

在以下情况触发：

  • 使用 @path/to/file 引用文件时
  • 使用 Read 工具读取文件时

触发后，匹配规则会注入到当前消息上下文。

如何调试规则加载问题？

  1. 运行 /memory 查看已加载的规则列表
  2. 检查 frontmatter 格式是否正确（--- 分隔符）
  3. 确认 glob 模式是否匹配
  4. 重启 CodeBuddy 清除缓存

规则文件大小有限制吗？

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

与 CodeBuddy IDE 的兼容性 ​

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

  • CLI：条件规则仅通过 glob 模式自动匹配文件操作触发，不支持手动 @RuleName 引用，也不支持模型智能选择规则
  • IDE：条件规则支持用户通过 @RuleName 手动引用，也支持模型基于上下文智能决策激活规则

相关资源 ​

通过有效的记忆管理，让 CodeBuddy Code 更好地理解您的需求和偏好