Managing CodeBuddy's Memory

Learn how to manage CodeBuddy Code's memory across sessions using different memory locations and best practices.

CodeBuddy Code can remember your preferences across sessions, such as code style guides and common commands in your workflow.

Determining Memory Types

CodeBuddy Code provides four hierarchically structured memory locations, each serving a different purpose:

Memory Type	Location	Purpose	Example Use Cases	Shared With
User Memory	`~/.codebuddy/CODEBUDDY.md`	Personal preferences across all projects	Code style preferences, personal tool shortcuts	Only you (across all projects)
User Rules	`~/.codebuddy/rules/*.md`	Modular personal rules	Personal coding habits, common workflows	Only you (across all projects)
Project Memory	`./CODEBUDDY.md` or `./.codebuddy/CODEBUDDY.md`	Team-shared instructions for a project	Project architecture, coding standards, common workflows	Team members via source control
Project Rules	`./.codebuddy/rules/*.md`	Modular, topic-specific project instructions	Language-specific guidelines, testing specifications, API standards	Team members via source control
Project Memory (Local)	`./CODEBUDDY.local.md`	Personal project-specific preferences	Your sandbox URL, preferred test data	Only you (current project)

All memory files are automatically loaded into CodeBuddy Code's context at startup. The loading order is as follows:

User-level: Load main files like ~/.codebuddy/CODEBUDDY.md and all rules under ~/.codebuddy/rules/
Project-level main files: Recursively load all CODEBUDDY.md and CODEBUDDY.local.md from current working directory upward
Project-level rules: Only load rules under .codebuddy/rules/ in the current working directory (not parent directories)
Subdirectory memory: When CodeBuddy operates on files in subdirectories, dynamically load that subdirectory's CODEBUDDY.md
Local memory: Load ./CODEBUDDY.local.md

Tip: CODEBUDDY.local.md files are automatically added to .gitignore, making them ideal for storing private project-specific preferences that should not be committed to version control.

CODEBUDDY.md Imports

CODEBUDDY.md files can import additional files using the @path/to/import syntax. The following example imports 3 files:

markdown

See @README for project overview, and @package.json for available npm commands.

# Additional Instructions
- Git workflow @docs/git-instructions.md

Both relative and absolute paths are supported. In particular, importing files from the user's home directory is a convenient way for team members to provide personal instructions that are not committed to the repository. Imports are an alternative to CODEBUDDY.local.md and work better with multiple git worktrees.

markdown

# Personal Preferences
- @~/.codebuddy/my-project-instructions.md

To avoid potential conflicts, imports within code blocks and code spans are not parsed.

markdown

This code span won't be treated as an import: `@tencent-ai/codebuddy-code`

Imported files can recursively import additional files, up to a maximum depth of 5 levels. You can view which memory files are loaded by running the /memory command.

How CodeBuddy Finds Memory

CodeBuddy Code reads memory recursively: Starting from the current working directory, CodeBuddy Code recurses up to (but not including) the root directory /, and reads any CODEBUDDY.md or CODEBUDDY.local.md files it finds. This works particularly well in large repositories where you run CodeBuddy Code in foo/bar/, with memories in both foo/CODEBUDDY.md and foo/bar/CODEBUDDY.md.

CodeBuddy also discovers CODEBUDDY.md files nested in subtrees below the current working directory. These files are not loaded at startup, but are only included when CodeBuddy reads files in those subtrees.

Direct Memory Editing with `/memory`

Use the /memory slash command during a session to open any memory file in your system editor for more extensive additions or organization.

Setting Up Project Memory

Suppose you want to set up a CODEBUDDY.md file to store important project information, conventions, and commonly used commands. Project memory can be stored in ./CODEBUDDY.md or ./.codebuddy/CODEBUDDY.md.

Bootstrap a CODEBUDDY.md for your codebase using the following command:

> /init

Tips:
Include common commands (build, test, lint) to avoid repetitive searches
Document code style preferences and naming conventions
Add project-specific important architectural patterns
CODEBUDDY.md memory can be used for both team-shared instructions and personal preferences

Modular Rules with `.codebuddy/rules/`

For larger projects, you can use the .codebuddy/rules/ directory to organize instructions into multiple files. This allows teams to maintain focused, well-organized rule files instead of a single large CODEBUDDY.md.

Basic Structure

Place markdown files in your project's .codebuddy/rules/ directory:

your-project/
├── .codebuddy/
│   ├── CODEBUDDY.md           # Main project instructions
│   └── rules/
│       ├── code-style.md      # Code style guidelines
│       ├── testing.md         # Testing specifications
│       └── security.md        # Security requirements

All .md files in .codebuddy/rules/ are automatically loaded as project memory with the same priority as .codebuddy/CODEBUDDY.md.

Note: Project-level rules are only loaded from .codebuddy/rules/ in the current working directory (workDir), not from parent directories. This ensures clear rule scoping.

Rule Control Fields

Rule files support the following YAML frontmatter fields to control loading and application behavior:

Field	Type	Default	Description
`enabled`	boolean	`true`	Whether to load this rule. When set to `false`, the rule is not loaded at all
`alwaysApply`	boolean	`true`	Whether to always apply this rule
`paths`	string/string[]	-	File path glob patterns that trigger the rule

Rule Type Determination

Rule type is determined by both alwaysApply and paths:

alwaysApply	paths	Rule Type	Behavior
`true` (default)	any	ALWAYS	Always injected into context
`false`	has value	MANUAL (conditional trigger)	Only triggered when operating on matching files
`false`	none	Not supported	Rule will not be loaded

Examples

Always-applied rule (default behavior):

markdown

---
# alwaysApply defaults to true, can be omitted
---

# General Code Standards

- Use 2-space indentation
- Keep blank line at end of file

Conditionally triggered rule:

markdown

---
alwaysApply: false
paths: src/api/**/*.ts
---

# API Development Rules

- All API endpoints must include input validation
- Use standard error response format
- Include OpenAPI documentation comments

Disabled rule (temporarily turned off):

markdown

---
enabled: false
---

# Rules not currently in use

Note: The paths field is not limited to .codebuddy/rules/ directory; it can be used in all memory files (including CODEBUDDY.md, CODEBUDDY.local.md).

Glob Patterns

The paths field supports standard glob patterns with the matchBase option enabled:

Pattern	Matches
`*/.ts`	All TypeScript files in any directory
`*.ts`	All TypeScript files in any directory (matchBase mode)
`src/*/`	All files under the `src/` directory
`*.md`	Markdown files in any directory
`src/components/*.tsx`	React components in a specific directory

matchBase explanation: With matchBase enabled, patterns without path separators (like *.ts) match files in any directory. For example, *.ts can match src/utils/helper.ts.

You can use braces to efficiently match multiple patterns:

markdown

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

# TypeScript/React Rules

This expands to match src/**/*.ts and src/**/*.tsx. You can also combine multiple patterns with commas:

markdown

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

Subdirectories

Rules can be organized into subdirectories for better structure:

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

All .md files are discovered recursively.

Symlinks

The .codebuddy/rules/ directory supports symlinks, allowing you to share common rules across multiple projects:

bash

# Symlink a shared rules directory
ln -s ~/shared-codebuddy-rules .codebuddy/rules/shared

# Symlink individual rule files
ln -s ~/company-standards/security.md .codebuddy/rules/security.md

Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.

User-Level Rules

You can create personal rules that apply to all projects in ~/.codebuddy/rules/:

~/.codebuddy/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

User-level rules are loaded before project rules, giving project rules higher priority.

Best Practices:
Keep rules focused: Each file should cover one topic (e.g., testing.md, api-design.md)
Use descriptive filenames: Filenames should indicate what the rules cover
Use conditional rules sparingly: Only add paths frontmatter when rules truly apply to specific file types
Organize with subdirectories: Group related rules (e.g., frontend/, backend/)

Memory Best Practices

Be specific: "Use 2-space indentation" is better than "Format code properly".
Use structured organization: Format each memory as a bullet point and group related memories under descriptive markdown headings.
Regular reviews: Update memory as the project evolves to ensure CodeBuddy always uses the latest information and context.

Setting Language Preferences

It is recommended to use the /config command to configure your preferred response language (see Settings Configuration), which is the simplest and most direct way:

> /config
# Select Language, enter your preferred language, e.g., "Simplified Chinese"

If you need more granular control (such as code comment language, commit message language), you can add to your memory file:

markdown

## CodeBuddy Added Memories

### Language Preferences
- Code comments in Chinese
- Commit messages in Chinese

Project-level language settings override user-level settings.

Hierarchical Memory Strategy Example

User-Level Memory (`~/.codebuddy/CODEBUDDY.md`)

markdown

## CodeBuddy Added Memories

### Tool Preferences
- Use pnpm instead of npm

### Code Preferences
- Prefer functional programming style
- Prioritize code readability

Tip: Response language is recommended to be set via /config rather than configured in memory files.

Project-Level Memory (`./CODEBUDDY.md`)

markdown

## CodeBuddy Added Memories

### Project Architecture
- Using microservices architecture
- Frontend: React + TypeScript
- Backend: Node.js + Express

### Team Conventions
- PRs require 2 reviewers
- Follow Conventional Commits

Local Project Memory (`./CODEBUDDY.local.md`)

markdown

## CodeBuddy Added Memories

### Local Development Configuration
- Database port: 5433
- Use debug mode
- Skip CI for quick testing

Cache and Reload

Operation	Reloads	Notes
Process restart	Yes	Cache cleared
Edit via /memory	Yes	Cache automatically cleared
/clear command	No	Only clears message history
Manual file modification	No	Requires manual restart
Add/delete rule files	No	Requires manual restart

Frequently Asked Questions

What is the difference between AGENTS.md and CODEBUDDY.md?

CodeBuddy Code supports both AGENTS.md and CODEBUDDY.md as project memory files:

AGENTS.md Support: If a CODEBUDDY.md file exists in the project, project-level memory will use CODEBUDDY.md, otherwise it will use AGENTS.md
Auto-detection: The system automatically detects whether an AGENTS.md file exists in the project

Recommended: Use CODEBUDDY.md

While we maintain support for AGENTS.md, it is recommended that new projects use CODEBUDDY.md as the memory filename to maintain consistency with the CodeBuddy Code brand.

How to migrate AGENTS.md to CODEBUDDY.md?

Simply rename AGENTS.md to CODEBUDDY.md. The system will auto-detect, and CODEBUDDY.md takes priority.

How are memory files synchronized?

Project Memory: Synced with team via Git
User Memory: Stored locally, not synced
Local Project Memory: Stored locally, automatically added to .gitignore

When do conditional rules trigger?

They trigger in these situations:

When referencing a file with @path/to/file
When using file operation tools like Read, Glob, Grep, Edit, Write

Once triggered, matching rules are injected into the current message context as system reminders. When all conditional rules have been injected, they won't be injected again.

How to debug rule loading issues?

Run /memory to view the list of loaded rules
Check if frontmatter format is correct (--- separators)
Confirm glob patterns are matching
Restart CodeBuddy to clear cache

Is there a size limit for rule files?

It's recommended to keep them concise. For particularly large specification documents, use @import syntax to reference them rather than including directly.

Compatibility with CodeBuddy IDE

CodeBuddy Code CLI and CodeBuddy IDE both support memory/rules functionality, but conditional rules trigger differently:

CLI: Conditional rules trigger automatically through glob pattern matching on file operations (including @ references and tool calls), without support for model-intelligent rule selection
IDE: Conditional rules support manual user references via @RuleName, and also support model-based intelligent decision activation based on context

Settings Configuration - Configure CodeBuddy Code behavior
Slash Commands - All available commands
Quick Start - Quick start guide

Through effective memory management, make CodeBuddy Code better understand your needs and preferences

Managing CodeBuddy's Memory ​

Determining Memory Types ​

CODEBUDDY.md Imports ​

How CodeBuddy Finds Memory ​

Direct Memory Editing with /memory ​

Setting Up Project Memory ​

Modular Rules with .codebuddy/rules/ ​

Basic Structure ​

Rule Control Fields ​

Rule Type Determination ​

Examples ​

Glob Patterns ​

Subdirectories ​

Symlinks ​

User-Level Rules ​

Memory Best Practices ​

Setting Language Preferences ​

Hierarchical Memory Strategy Example ​

User-Level Memory (~/.codebuddy/CODEBUDDY.md) ​

Project-Level Memory (./CODEBUDDY.md) ​

Local Project Memory (./CODEBUDDY.local.md) ​

Cache and Reload ​

Frequently Asked Questions ​

Recommended: Use CODEBUDDY.md ​

Compatibility with CodeBuddy IDE ​

Related Resources ​

Managing CodeBuddy's Memory

Determining Memory Types

CODEBUDDY.md Imports

How CodeBuddy Finds Memory

Direct Memory Editing with `/memory`

Setting Up Project Memory

Modular Rules with `.codebuddy/rules/`

Basic Structure

Rule Control Fields

Rule Type Determination

Examples

Glob Patterns

Subdirectories

Symlinks

User-Level Rules

Memory Best Practices

Setting Language Preferences

Hierarchical Memory Strategy Example

User-Level Memory (`~/.codebuddy/CODEBUDDY.md`)

Project-Level Memory (`./CODEBUDDY.md`)

Local Project Memory (`./CODEBUDDY.local.md`)

Cache and Reload

Frequently Asked Questions

Recommended: Use CODEBUDDY.md

Compatibility with CodeBuddy IDE

Related Resources