Memory Bank: How to Make Cline an AI Agent That Never Forgets - Cline Blog
Key Points
- 1Memory Bank is an AI agent solution for Cline that combats context loss by enabling the AI to store and retrieve project information from structured markdown files, much like a human rebuilding understanding from notes.
- 2This system uses a dedicated `memory-bank/` folder with core files (e.g., `projectbrief.md`, `activeContext.md`) and follows a continuous lifecycle of reading, verifying, executing, and updating information.
- 3A key innovation is the use of Mermaid diagrams within custom instructions to teach the AI how to manage this documentation structure, leveraging a formal, unambiguous visual language that is easier for AI to process than natural language.
The paper introduces Memory Bank, a novel system designed to address the inherent forgetfulness of AI coding assistants like Cline, which stems from the finite nature of their context windows. Inspired by the concept of externalized memory from *Memento*, Memory Bank enables Cline to maintain a persistent understanding of a project across sessions and beyond the limitations of its active context window.
The core problem tackled is that AI assistants reset or overflow their context windows, forcing users to repeatedly re-explain project specifics, tech stacks, and architectural details. Traditional solutions, such as starting new chats, manual context management, or summarization, are deemed inefficient or prone to data loss. Memory Bank offers a dynamic, self-maintaining solution by instructing the AI to utilize a dedicated local documentation system.
Memory Bank functions as a community-created custom instruction set for Cline. When integrated, these instructions direct Cline to interact with a memory-bank/ folder within the project directory. The initial instruction tells Cline: "Before you do any work, check the memory-bank/ folder in the project. If those files don't exist, create them. If they do exist, read them to understand the project context." This mechanism allows Cline to rebuild its understanding by consulting these externalized "memories" whenever its internal context window resets or a new session begins.
The methodology of Memory Bank operates on two primary levels of interaction between the AI and its persistent memory:
- Documentation Structure via Visual Prompting: The system uses Mermaid diagrams directly embedded within Cline's custom instructions to teach the AI how to structure and maintain its documentation. An example architecture diagram provided is:
flowchart TD
PB[projectbrief.md] --> PC[productContext.md]
PB --> SP[systemPatterns.md]
PB --> TC[techContext.md]
PC --> AC[activeContext.md]
SP --> AC
TC --> AC
AC --> P[progress.md]This Mermaid code is not merely a visual aid for humans; it is a formal, structured instruction for the AI, acting as a schema or rulebook that dictates the relationships and dependencies among the documentation files. This approach leverages the AI's proficiency in interpreting structured formats, providing unambiguous guidelines for information organization.
- Content Storage in Markdown Files: The actual project knowledge is stored in simple markdown files, adhering to the structure defined by the Mermaid diagrams. The core files include:
projectbrief.md: The foundational document.productContext.md: Business and user perspectives.systemPatterns.md: Technical architecture and decisions.techContext.md: Development environment and stack.activeContext.md: Current state of development.progress.md: Project status and tracking.
The Memory Bank lifecycle is a continuous cycle of "read, verify, execute, and update":
- Initial Setup: Upon starting a new project, Cline creates the
memory-bank/directory, initializes all required files, requests necessary information from the user, and establishes baseline documentation. - During Development: Before commencing work, Cline reads all Memory Bank files and verifies the completeness of the context. During work, it follows established patterns, tracks changes and decisions, and monitors its context window usage.
- After Significant Changes: Cline updates relevant documentation files, ensures consistency across the memory bank, and prepares for potential context resets.
A significant technical insight highlighted by Memory Bank is the efficacy of visual prompting using Mermaid diagrams for guiding AI. While traditional system prompts often use markdown, JSON, or XML, the paper argues that Mermaid diagrams, as formal languages for describing workflows, are particularly effective. An example of a workflow diagram used as a prompt is:
flowchart TD
Start[Start] --> ReadFiles[Read Memory Bank]
ReadFiles --> CheckFiles{Files Complete?}
CheckFiles -->|No| Plan[Create Plan]
Plan --> Document[Document in Chat]
CheckFiles -->|Yes| Verify[Verify Context]
Verify --> Strategy[Develop Strategy]
Strategy --> Present[Present Approach]This structured format, with its explicitly defined nodes, connections, and decision points, reduces ambiguity inherent in natural language instructions. For an AI, such a precise map of a process is hypothesized to be easier to understand and execute than verbose textual descriptions, leading to more predictable and accurate behavior. The larger implication is a shift in how developers might communicate with AI, moving towards structured languages for workflows rather than relying solely on natural language.