记忆

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

确定记忆类型

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

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

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

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

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

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

本地记忆：加载 ./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

提示：

包含常用命令（构建、测试、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 相同。

注意：

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

规则控制字段

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

规则类型判定

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

示例

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

---
# alwaysApply 默认为 true，可省略
---

# 通用代码规范

- 使用 2 空格缩进
- 文件末尾保留空行

条件触发规则：

---
alwaysApply: false
paths: 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

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

## CodeBuddy Added Memories

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

Auto Memory 系统

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

存储位置

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

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

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

启用与禁用

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

通过 /memory 命令面板切换

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

通过环境变量：CODEBUDDY_DISABLE_AUTO_MEMORY=1

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。

缓存与重载

常见问题

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、Glob、Grep、Edit、Write 等文件操作工具时

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

如何调试规则加载问题？

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

检查 frontmatter 格式是否正确（--- 分隔符）

确认 glob 模式是否匹配

重启 CodeBuddy 清除缓存

规则文件大小有限制吗？

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

与 CodeBuddy IDE 的兼容性

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

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

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