Memory Bank System v0.7-beta

A token-optimized, hierarchical task management system that integrates with Cursor custom modes for efficient development workflows.

graph TD
    Main["Memory Bank System"] --> Modes["Custom Modes"]
    Main --> Rules["Hierarchical Rule Loading"]
    Main --> Visual["Visual Process Maps"]
    Main --> Token["Token Optimization"]
    
    Modes --> VAN["VAN: Initialization"]
    Modes --> PLAN["PLAN: Task Planning"]
    Modes --> CREATIVE["CREATIVE: Design"]
    Modes --> IMPLEMENT["IMPLEMENT: Building"]
    Modes --> REFLECT["REFLECT: Review"]
    Modes --> ARCHIVE["ARCHIVE: Documentation"]
    
    style Main fill:#4da6ff,stroke:#0066cc,color:white
    style Modes fill:#f8d486,stroke:#e8b84d,color:black
    style Rules fill:#80ffaa,stroke:#4dbb5f,color:black
    style Visual fill:#d9b3ff,stroke:#b366ff,color:black
    style Token fill:#ff9980,stroke:#ff5533,color:black

Loading

Personal Note: Memory Bank is my personal hobby project that I develop for my own use in coding projects. As this is a personal project, I don't maintain an issues tracker or actively collect feedback. However, if you're using these rules and encounter issues, one of the great advantages is that you can ask the Cursor AI directly to modify or update the rules to better suit your specific workflow. The system is designed to be adaptable by the AI, allowing you to customize it for your own needs without requiring external support.

About Memory Bank

Memory Bank is a personal project that provides a structured approach to development using specialized modes for different phases of the development process. It uses a hierarchical rule loading architecture that loads only the rules needed for each phase, optimizing token usage and providing tailored guidance.

Token-Optimized Architecture

Version 0.7-beta introduces significant token optimization improvements:

• Hierarchical Rule Loading: Only loads essential rules initially with specialized lazy-loading
• Progressive Documentation: Implements concise templates that scale with task complexity
• Optimized Mode Transitions: Preserves critical context efficiently between modes
• Level-Specific Workflows: Adapts documentation requirements to task complexity

See the Memory Bank Optimizations document for detailed information about all optimization approaches.

Beyond Basic Custom Modes

While Cursor's documentation describes custom modes as primarily standalone configurations with basic prompts and tool selections, Memory Bank significantly extends this concept:

• Graph-Based Mode Integration: Modes are interconnected nodes in a development workflow rather than isolated tools
• Workflow Progression: Modes are designed to transition from one to another in a logical sequence (VAN → PLAN → CREATIVE → IMPLEMENT → REFLECT → ARCHIVE)
• Shared Memory: Persistent state maintained across mode transitions via Memory Bank files
• Adaptive Behavior: Each mode adjusts its recommendations based on project complexity
• Built-in QA Functions: QA capabilities can be called from any mode for technical validation

This approach transforms custom modes from simple AI personalities into components of a coordinated development system with specialized phases working together.

CREATIVE Mode and Claude's "Think" Tool

The CREATIVE mode in Memory Bank is conceptually based on Anthropic's Claude "Think" tool methodology, as described in their engineering blog. The v0.7-beta implements an optimized version with:

• Progressive documentation with tabular option comparison
• "Detail-on-demand" approach that preserves token efficiency
• Structured templates that scale with complexity level
• Efficient context preservation for implementation phases

For a detailed explanation of how Memory Bank implements these principles, see the CREATIVE Mode and Claude's "Think" Tool document.

Key Features

• Hierarchical Rule Loading: Load only the essential rules with specialized lazy-loading
• Progressive Documentation: Concise templates that scale with task complexity
• Unified Context Transfer: Efficient context preservation between modes
• Mode-Specific Visual Maps: Clear visual representations for each development phase
• Level-Specific Workflows: Adapted processes based on complexity (Levels 1-4)
• Platform-Aware Commands: Automatically adapts commands to your operating system

Installation Instructions

Prerequisites

• Cursor Editor: Version 0.48 or higher is required.
• Custom Modes: Feature must be enabled in Cursor (Settings → Features → Chat → Custom modes).
• AI Model: Claude 3.7 Sonnet is recommended for best results, especially for CREATIVE mode's "Think" tool methodology.

Step 1: Get the Files

Simply clone this repository into your project directory:

git clone https://github.com/vanzan01/cursor-memory-bank.git

Alternatively, you can download the ZIP file from GitHub and extract it to your project folder.

This provides you with all the necessary files, including:

• Rule files in .cursor/rules/isolation_rules/
• Mode instruction files in custom_modes/ directory
• Template Memory Bank files in memory-bank/

Step 2: Setting Up Custom Modes in Cursor

This is the most critical and challenging part of the setup. You'll need to manually create six custom modes in Cursor and copy the instruction content from the provided files:

How to Add a Custom Mode in Cursor

1. Open Cursor and click on the mode selector in the chat panel
2. Select "Add custom mode"
3. In the configuration screen:
   • Enter the mode name (you can include emoji icons like 🔍, 📋, 🎨, ⚒️ by copy-pasting them at the beginning of the name)
   • Select an icon from Cursor's limited predefined options
   • Add a shortcut (optional)
   • Check the required tools
   • Click on Advanced options
   • In the empty text box that appears at the bottom, paste the custom instruction content from the corresponding file

Example configuration screen:	Result in mode selection menu:

Mode Configuration

For each mode, configure as follows:

1. VAN MODE (Initialization)

   • Name: 🔍 VAN
   • Tools: Enable "Codebase Search", "Read File", "Terminal", "List Directory"
   • Advanced options: Paste from custom_modes/van_instructions.md

2. PLAN MODE (Task Planning)

   • Name: 📋 PLAN
   • Tools: Enable "Codebase Search", "Read File", "Terminal", "List Directory"
   • Advanced options: Paste from custom_modes/plan_instructions.md

3. CREATIVE MODE (Design Decisions)

   • Name: 🎨 CREATIVE
   • Tools: Enable "Codebase Search", "Read File", "Terminal", "List Directory", "Edit File"
   • Advanced options: Paste from custom_modes/creative_instructions.md

4. IMPLEMENT MODE (Code Implementation)

   • Name: ⚒️ IMPLEMENT
   • Tools: Enable all tools
   • Advanced options: Paste from custom_modes/implement_instructions.md

5. REFLECT MODE (Review)

   • Name: 🔍 REFLECT
   • Tools: Enable "Codebase Search", "Read File", "Terminal", "List Directory"
   • Advanced options: Paste from custom_modes/reflect_archive_instructions.md (REFLECT section)

6. ARCHIVE MODE (Documentation)

   • Name: 📚 ARCHIVE
   • Tools: Enable "Codebase Search", "Read File", "Terminal", "List Directory", "Edit File"
   • Advanced options: Paste from custom_modes/reflect_archive_instructions.md (ARCHIVE section)

Note: REFLECT and ARCHIVE instructions are combined in a single file to optimize for Cursor's character limits while maintaining functionality. Thanks to GitHub user @joshmac007 for implementing this optimization.

For additional help on setting up custom modes in Cursor, refer to the official Cursor documentation on custom modes.

QA Functionality

QA is not a separate custom mode but rather a set of validation functions that can be called from any mode. You can invoke QA capabilities by typing "QA" in any mode when you need to perform technical validation. This approach provides flexibility to conduct verification at any point in the development process.

Basic Usage

1. Start with VAN Mode:

   • Switch to VAN mode in Cursor
   • Type "VAN" to initiate the initialization process
   • VAN will analyze your project structure and determine complexity

2. Follow the Workflow Based on Complexity:

   • Level 1 tasks: May proceed directly to IMPLEMENT after VAN
   • Level 2 tasks: Simplified workflow (VAN → PLAN → IMPLEMENT → REFLECT)
   • Level 3-4 tasks: Full workflow (VAN → PLAN → CREATIVE → IMPLEMENT → REFLECT → ARCHIVE)
   • At any point: Type "QA" to perform technical validation

3. Mode-Specific Commands:

   VAN - Initialize project and determine complexity
   PLAN - Create detailed implementation plan
   CREATIVE - Explore design options for complex components
   IMPLEMENT - Systematically build planned components
   REFLECT - Review and document lessons learned
   ARCHIVE - Create comprehensive documentation
   QA - Validate technical implementation (can be called from any mode)
   

Core Files and Their Purposes

graph LR
    subgraph "Memory Bank Files"
        Tasks["tasks.md<br>Source of Truth"]
        Active["activeContext.md<br>Current Focus"]
        Progress["progress.md<br>Implementation Status"]
        Creative["creative-*.md<br>Design Decisions"]
        Reflect["reflect-*.md<br>Review Documents"]
    end
    
    style Tasks fill:#f9d77e,stroke:#d9b95c,stroke-width:3px
    style Active fill:#a8d5ff,stroke:#88b5e0
    style Progress fill:#c5e8b7,stroke:#a5c897
    style Creative fill:#f4b8c4,stroke:#d498a4
    style Reflect fill:#b3e6cc,stroke:#66c999

Loading

• tasks.md: Central source of truth for task tracking
• activeContext.md: Maintains focus of current development phase
• progress.md: Tracks implementation status
• creative-*.md: Design decision documents generated during CREATIVE mode
• reflect-*.md: Review documents created during REFLECT mode

Troubleshooting

Common Issues

1. Mode not responding correctly:

   • Verify custom instructions were copied completely (this is the most common issue)
   • Ensure the correct tools are enabled for each mode
   • Check that you've switched to the correct mode before issuing commands
   • Make sure you pasted the instructions in the "Advanced options" text box

2. Rules not loading:

   • Make sure the .cursor/rules/isolation_rules/ directory is in the correct location
   • Verify file permissions allow reading the rule files

3. Command execution issues:

   • Ensure you're running commands from the correct directory
   • Verify platform-specific commands are being used correctly

Version Information

This is version v0.7-beta of the Memory Bank system. It introduces significant token optimization improvements over v0.6-beta while maintaining all functionality. See the Release Notes for detailed information about the changes.

Ongoing Development

The Memory Bank system is actively being developed and improved. Key points to understand:

• Work in Progress: This is a beta version with ongoing development. Expect regular updates, optimizations, and new features.
• Feature Optimization: The modular architecture enables continuous refinement without breaking existing functionality.
• Previous Version Available: If you prefer the stability of the previous version (v0.1-legacy), you can continue using it while this version matures.
• Architectural Benefits: Before deciding which version to use, please read the Memory Bank Upgrade Guide to understand the significant benefits of the new architecture.

Resources

• Memory Bank Optimizations - Detailed overview of token efficiency improvements
• Release Notes - Information about the latest changes
• Cursor Custom Modes Documentation
• Memory Bank Upgrade Guide
• CREATIVE Mode and Claude's "Think" Tool
• Mode-specific instruction files in the custom_modes/ directory

---

Note: This README is for v0.7-beta and subject to change as the system evolves.