Roo Code Memory Bank Documentation

The Memory Bank is organized within a memory-bank/ directory at your project root. It consists of core files for session management and optional files for deeper documentation.

Core Files

Optional Files

Directory Layout

project-root/
├── memory-bank/
│   ├── activeContext.md
│   ├── productContext.md
│   ├── progress.md
│   └── decisionLog.md  
└── projectBrief.md

The system supports intelligent mode switching based on intent-based triggers and operational needs. When a user provides a prompt containing specific keywords, the system can transition between modes to ensure the appropriate capabilities (like read-only vs. full write access) are available.

Intent-Based Triggers:

• code: triggered by implement, create, build, code, develop, fix.
• debug: triggered by debug, troubleshoot, diagnose, investigate, analyze, trace, root cause.
• architect: triggered by design, architect, structure, plan.
• ask: triggered by explain, help, what, how, why.

Operational Triggers:

• File-based: Switches based on the type of file operations being performed.
• Capability-based: Switches to a mode that possesses the required permissions for the task.

The system operates using four distinct modes, each with specific capabilities and file access permissions:

• Architect Mode: Used for system design and planning. It has access to Markdown files only. Best for initializing the Memory Bank and making architecture decisions.
• Code Mode: Used for implementation and coding. It has full file access and no file restrictions for code generation and modification.
• Ask Mode: Used for information retrieval and guidance. It has read-only file access. Best for documentation help and best practices.
• Debug Mode: Used for troubleshooting and root cause identification. It has read-only file access. Best for system behavior analysis and diagnostic tooling.

The Memory Bank system uses a memory-bank/ directory containing four core Markdown files to maintain persistent project context. These files serve different purposes throughout the development lifecycle:

• activeContext.md: Tracks the current session state, including current tasks, recent changes, open questions, and blockers. Updated every session.
• productContext.md: Defines the project scope, architecture, technical standards, and key dependencies. Updated when project scope changes.
• progress.md: Tracks work status, completed items, current tasks, and next steps. Updated as tasks progress.
• decisionLog.md: Records technical decisions, architecture choices, and implementation details. Updated whenever decisions are made.

To enable the Memory Bank features, you must configure the custom instructions for your specific Roo Code modes.

1. Open the Roo Code Prompts settings in VS Code.
2. Select the mode you wish to modify (e.g., Architect, Code, Ask, or Debug).
3. Locate the corresponding memory_bank_strategy_<mode>.yml file in the repository modules folder.
4. Copy the contents of that YAML file and paste it into the Roo Code mode settings.
5. Save the changes.

The Memory Bank integrates with different Roo Code modes to provide specialized context management:

Architect Mode

Use when: Designing system architecture, defining coding patterns, or structuring new projects. Focus: High-level system design and maintaining project-wide consistency.

Code Mode

Use when: Implementing new features, modifying existing code, or refactoring. Focus: Writing and maintaining code while following established patterns.

Ask Mode

Use when: Seeking project insights, explaining code implementations, or creating documentation. Focus: Acting as a knowledge base and documentation assistant.

Debug Mode

Use when: Investigating bugs, analyzing error patterns, or verifying fixes. Focus: Systematic problem-solving and root cause analysis.

To set up and use the Memory Bank effectively, follow this workflow:

1. Initialization

Start in Architect mode. The system will check for a memory-bank/ directory. If it is missing, the system will automatically:

• Create the memory-bank/ directory.
• Generate the core files (activeContext.md, productContext.md, progress.md, decisionLog.md).
• Set up the initial project context.

2. Session Workflow

• Session Start: The system reads all Memory Bank files to build comprehensive context and loads mode-specific rules.
• During Session: The system performs automatic mode switching as needed. It updates activeContext.md for context and progress.md for task tracking.
• Session End: Ensure you update progress.md with current status, record any new decisions in decisionLog.md, and plan the next steps for the following session.

The Memory Bank initialization is largely automatic when starting a new project. Follow these steps to set it up:

1. Start in Architect or Code Mode: Open your project in VS Code and switch to Architect or Code mode. Roo Code will automatically check for a memory-bank/ directory.
2. Follow the Initialization Plan: If the memory-bank/ directory is missing, Roo Code (in Architect mode) will provide a plan to set it up.
3. Switch to Code Mode: Follow the prompt to switch to Code mode.
4. Create Files: In Code mode, follow Roo's plan to create the memory-bank/ directory and the necessary core files.
5. Ready: Once the files are created, the Memory Bank is initialized.

The Memory Bank is designed for Real-time Updates, where Roo automatically synchronizes files with your work.

However, you should use Manual Updates as a fallback in the following scenarios:

• Ending a session unexpectedly.
• Halting mid-task.
• Recovering from connection issues.
• Forcing a full synchronization.

To trigger a manual update, use the commands UMB or update memory bank in the chat.

The update memory bank command (or the shorthand UMB) is a standalone prompt used to explicitly trigger a comprehensive update of all Memory Bank files.

When to use it:

• At the end of a session or before a break.
• Before closing VS Code or switching workspaces.
• To create project history checkpoints.

Why it is important: Using UMB as a standalone prompt ensures Roo Code saves the current state of all Memory Bank files (productContext.md, activeContext.md, progress.md, etc.), guaranteeing accurate and persistent project knowledge for the next session.

The system uses specialized .clinerules files to define behavior and permissions for each mode. These files should be located in the project root:

• .clinerules-architect: Defines mode switching for non-markdown files, Memory Bank initialization rules, and architecture documentation standards.
• .clinerules-code: Configures full file access, code generation settings, and tool access permissions.
• .clinerules-ask: Sets read-only access settings, rules for switching to edit mode, and documentation preferences.
• .clinerules-debug: Sets read-only access settings, diagnostic tool permissions, and logging/tracing configurations.