# vanzan01/cursor-memory-bank architecture

> Architecture diagram of the GitHub repository vanzan01/cursor-memory-bank, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vanzan01/cursor-memory-bank
- Repository: https://github.com/vanzan01/cursor-memory-bank

## Overview

##### Project Type and Purpose
- This is a document-centric, AI-powered “Memory Bank” personal task management system tailored as a set of Cursor custom modes and hierarchical rule files.
- It is not a traditional code service or microservice setup but a structured repository of Markdown-based rules, mode instructions, and templates that work inside the Cursor editor to guide you through development phases.

##### Main Architectural Components
a. Memory Bank Core
- Orchestrator of the entire system. Loads rules, manages state, and drives mode transitions.
b. Custom Modes (Phases)
- 🔍 VAN (Initialization)
- 📋 PLAN (Task Planning)
- 🎨 CREATIVE (Design Decisions)
- ⚒️ IMPLEMENT (Code Implementation)
- 🔍 REFLECT (Review)
- 📚 ARCHIVE (Documentation)
c. Hierarchical Rule Loader
- `.cursor/rules/isolation_rules/` directory:
- Core rules
- Level1–Level4 workflows for complexity tiers
- Phase-specific rules and visual map modules
d. Memory Bank State Store
- Markdown files in root (e.g., `tasks.md`, `activeContext.md`, `progress.md`, `creative-*.md`, `reflect-*.md`) that persist the current context, decisions, and progress.
e. Visual Process Maps
f. Token Optimization Module
- Lazy-loading logic embedded in rule files to minimize AI prompt tokens.

##### Component Interactions and Data Flows
- The user invokes a mode in Cursor → Memory Bank Core loads the minimal rule set for that mode from the Hierarchical Rule Loader → Mode logic reads/writes Memory Bank State Store files → If requested, Visual Process Maps are rendered to guide the user → QA functions can be called at any point to validate code/design → Transitions to next mode follow the defined VAN→PLAN→…→ARCHIVE sequence based on task complexity.

##### Architectural Patterns and Principles
- Hierarchical Rule Loading: Layered directories of rules loaded on demand (Core → Level → Phase → Visual Map).
- Modular Custom Modes: Each mode is a self-contained module with clear inputs (state files, rules) and outputs (updates to state, new docs).
- Lazy Loading & Token Efficiency: Only load what’s necessary for each mode or complexity level.
- State Persistence: All runtime context is persisted in Markdown files, enabling deterministic transitions and easy backtracking.

##### Technologies & Artifacts
- Cursor Editor Custom Modes (no external services)
- Markdown for rules and state storage
- Git for versioning (README, RELEASE_NOTES, optimization docs)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core and Rule Loader
    Core["Memory Bank Core"]:::core
    CoreEntry["Core Entry Rules (main.mdc)"]:::rule
    RL1["Level1 Rules"]:::rule
    RL2["Level2 Rules"]:::rule
    RL3["Level3 Rules"]:::rule
    RL4["Level4 Rules"]:::rule

    CoreEntry --> RL1 --> RL2 --> RL3 --> RL4 --> Core

    %% Phases Sequence
    Core --> PhaseVAN
    subgraph Phases
        direction TB
        PhaseVAN["🔍 VAN (Initialization)"]:::phase
        PhasePLAN["📋 PLAN (Task Planning)"]:::phase
        PhaseCREATIVE["🎨 CREATIVE (Design Decisions)"]:::phase
        PhaseIMPLEMENT["⚒️ IMPLEMENT (Code Implementation)"]:::phase
        PhaseREFLECT["🔍 REFLECT (Review)"]:::phase
        PhaseARCHIVE["📚 ARCHIVE (Documentation)"]:::phase

        PhaseVAN -->|Proceed| PhasePLAN
        PhasePLAN -->|Proceed| PhaseCREATIVE
        PhaseCREATIVE -->|Proceed| PhaseIMPLEMENT
        PhaseIMPLEMENT -->|Proceed| PhaseREFLECT
        PhaseREFLECT -->|Proceed| PhaseARCHIVE
    end

    %% State Store
    StateStore["State Store (Markdown files)"]:::store

    %% QA Service and Visual Maps
    QA["QA Service"]:::qa
    subgraph VisualMaps
        direction TB
        VMVAN["VAN Mode Map"]:::visual
        VMVANsplit["VAN Split Maps"]:::visual
        VMPLAN["PLAN Mode Map"]:::visual
        VMCREATIVE["CREATIVE Mode Map"]:::visual
        VMIMPLEMENT["IMPLEMENT Mode Map"]:::visual
        VMREFLECT["REFLECT Mode Map"]:::visual
        VMARCHIVE["ARCHIVE Mode Map"]:::visual
    end

    %% Token Optimization Module
    TokenOpt["Token Optimization Module"]:::module
    OptJourney["Optimization Journey"]:::module

    %% Interactions
    PhaseVAN <--> StateStore
    PhasePLAN <--> StateStore
    PhaseCREATIVE <--> StateStore
    PhaseIMPLEMENT <--> StateStore
    PhaseREFLECT <--> StateStore
    PhaseARCHIVE <--> StateStore

    RL4 -->|Load Rules| PhaseVAN
    RL4 -->|Load Rules| PhasePLAN
    RL4 -->|Load Rules| PhaseCREATIVE
    RL4 -->|Load Rules| PhaseIMPLEMENT
    RL4 -->|Load Rules| PhaseREFLECT
    RL4 -->|Load Rules| PhaseARCHIVE

    PhaseVAN -.->|render| VMVAN
    PhaseVAN -.->|render| VMVANsplit
    PhasePLAN -.->|render| VMPLAN
    PhaseCREATIVE -.->|render| VMCREATIVE
    PhaseIMPLEMENT -.->|render| VMIMPLEMENT
    PhaseREFLECT -.->|render| VMREFLECT
    PhaseARCHIVE -.->|render| VMARCHIVE

    QA -.-> PhaseVAN
    QA -.-> PhasePLAN
    QA -.-> PhaseCREATIVE
    QA -.-> PhaseIMPLEMENT
    QA -.-> PhaseREFLECT
    QA -.-> PhaseARCHIVE

    TokenOpt --> Core
    TokenOpt --> RL1
    TokenOpt --> RL2
    TokenOpt --> RL3
    TokenOpt --> RL4
    OptJourney --> TokenOpt

    %% Click Events
    click Core "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Core"
    click CoreEntry "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/main.mdc"
    click RL1 "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Level1"
    click RL2 "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Level2"
    click RL3 "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Level3"
    click RL4 "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Level4"
    click PhaseVAN "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/van_instructions.md"
    click VMVAN "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/van-mode-map.mdc"
    click VMVANsplit "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/visual-maps/van_mode_split"
    click PhasePLAN "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/plan_instructions.md"
    click VMPLAN "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/plan-mode-map.mdc"
    click PhaseCREATIVE "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/creative_instructions.md"
    click VMCREATIVE "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/creative-mode-map.mdc"
    click PhaseRulesCreative "https://github.com/vanzan01/cursor-memory-bank/tree/main/.cursor/rules/isolation_rules/Phases/CreativePhase"
    click PhaseIMPLEMENT "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/implement_instructions.md"
    click VMIMPLEMENT "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/implement-mode-map.mdc"
    click PhaseREFLECT "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/reflect_archive_instructions.md"
    click VMREFLECT "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/reflect-mode-map.mdc"
    click PhaseARCHIVE "https://github.com/vanzan01/cursor-memory-bank/blob/main/custom_modes/reflect_archive_instructions.md"
    click VMARCHIVE "https://github.com/vanzan01/cursor-memory-bank/blob/main/.cursor/rules/isolation_rules/visual-maps/archive-mode-map.mdc"
    click TokenOpt "https://github.com/vanzan01/cursor-memory-bank/blob/main/MEMORY_BANK_OPTIMIZATIONS.md"
    click OptJourney "https://github.com/vanzan01/cursor-memory-bank/tree/main/optimization-journey/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef rule fill:#90EE90,stroke:#333,stroke-width:1px
    classDef phase fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef store fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef visual fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef qa fill:#FFA500,stroke:#333,stroke-width:1px
    classDef module fill:#FFE4B5,stroke:#333,stroke-width:1px
```
