┌─────────────────────────────────────────────────────────┐
│                    AI Assistant Session                   │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │              System Prompt / Custom Rules           │  │
│  │  "MUST read ALL memory bank files at start of      │  │
│  │   EVERY task. This is NOT optional."               │  │
│  └───────────────┬────────────────────────────────────┘  │
│                  │                                        │
│  ┌───────────────▼────────────────────────────────────┐  │
│  │            Memory Bank Manager                      │  │
│  │                                                     │  │
│  │  Session Start:                                     │  │
│  │    1. Read ALL files in hierarchical order          │  │
│  │    2. Validate completeness                         │  │
│  │    3. Extract current state                         │  │
│  │                                                     │  │
│  │  During Work:                                       │  │
│  │    1. Reference patterns and decisions              │  │
│  │    2. Follow documented conventions                 │  │
│  │                                                     │  │
│  │  Session End / Update Trigger:                      │  │
│  │    1. Update activeContext.md                        │  │
│  │    2. Update progress.md                            │  │
│  │    3. Log new decisions                             │  │
│  │    4. Document new patterns                         │  │
│  └───────────────┬────────────────────────────────────┘  │
│                  │                                        │
└──────────────────┼────────────────────────────────────────┘
                   │
     ┌─────────────▼─────────────────────┐
     │       memory-bank/ Directory       │
     │                                    │
     │  Layer 1: projectBrief.md          │
     │  Layer 2: productContext.md        │
     │  Layer 3: systemPatterns.md        │
     │  Layer 4: techContext.md           │
     │  Layer 5: activeContext.md         │
     │  Layer 6: progress.md             │
     │  Layer 7: decisionLog.md          │
     │                                    │
     │  (All stored in project git repo)  │
     └────────────────────────────────────┘

project-root/
├── memory-bank/
│   ├── projectBrief.md      # Layer 1: Foundation
│   ├── productContext.md     # Layer 2: Purpose & Goals
│   ├── systemPatterns.md     # Layer 3: Architecture
│   ├── techContext.md        # Layer 4: Tech Stack
│   ├── activeContext.md      # Layer 5: Current State
│   ├── progress.md           # Layer 6: Tracking
│   └── decisionLog.md        # Layer 7: Decision History
└── .clinerules               # Optional: AI behavioral rules

# Project Brief

## Project Name
[Name of the project]

## Mission Statement
[One-paragraph description of what this project is and why it exists]

## Problem Statement
[What problem does this solve? Who has this problem?]

## Core Requirements
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

## Key Constraints
- [Constraint 1: e.g., must work offline]
- [Constraint 2: e.g., budget limit]
- [Constraint 3: e.g., timeline]

## Success Criteria
- [How do we know this project succeeded?]
- [Measurable outcomes]

## Scope Boundaries
### In Scope
- [What is included]

### Out of Scope
- [What is explicitly excluded]

# Product Context

## Why This Project Exists
[Business justification and user need]

## Target Users
[Who uses this and how]

## User Problems
- [Problem 1 that users face]
- [Problem 2 that users face]

## User Experience Goals
- [UX goal 1: e.g., "Should feel instant"]
- [UX goal 2: e.g., "Zero configuration needed"]

## How It Should Work
[High-level user flow description]

## What Makes It Different
[Differentiation from alternatives]

# System Patterns

## Architecture Overview
[High-level architecture description — e.g., "Monorepo with microservices"]

## Architecture Diagram

## Design Patterns in Use
### [Pattern Name, e.g., "Repository Pattern"]
- **Where Used**: [Which modules/files]
- **Why**: [Rationale]
- **Implementation**: [Brief description of how it's implemented]

### [Pattern Name 2]
...

## Coding Conventions
- [Convention 1: e.g., "All API responses use envelope format { data, error, meta }"]
- [Convention 2: e.g., "Database queries live in /src/repositories/"]
- [Convention 3: e.g., "Error handling uses custom AppError class"]

## File Organization

## Key Technical Decisions
- [Decision 1: e.g., "Using SQLite for local storage — see decisionLog.md"]
- [Decision 2: e.g., "Event-driven architecture for notifications"]

# Tech Context

## Technology Stack
### Languages
- [Language 1: version]
- [Language 2: version]

### Frameworks
- [Framework 1: version — purpose]
- [Framework 2: version — purpose]

### Databases
- [Database 1: purpose]

### Key Libraries
- [Library 1: purpose]
- [Library 2: purpose]

## Development Environment Setup
1. [Step 1: e.g., "Clone repository"]
2. [Step 2: e.g., "Install dependencies: npm install"]
3. [Step 3: e.g., "Copy .env.example to .env"]
4. [Step 4: e.g., "Run migrations: npm run migrate"]

## Build Commands
- **Build**: `[command]`
- **Test**: `[command]`
- **Lint**: `[command]`
- **Dev Server**: `[command]`

## Deployment
- **Environment**: [e.g., "AWS Lambda via Serverless Framework"]
- **Deploy Command**: `[command]`
- **CI/CD**: [e.g., "GitHub Actions — .github/workflows/"]

## Environment Variables
| Variable | Purpose | Required |
|----------|---------|----------|
| DATABASE_URL | Database connection | Yes |
| API_KEY | External API access | Yes |

## Version Requirements
- Node.js: >= 18.0.0
- npm: >= 9.0.0

# Active Context

## Current Focus
[What is being worked on RIGHT NOW — 1-2 sentences]

## Recent Changes
- [Change 1: what was done and when]
- [Change 2: what was done and when]
- [Change 3: what was done and when]

## Current State
[Brief description of where things stand — what works, what doesn't]

## Active Decisions
- [Decision pending: e.g., "Need to decide between REST and GraphQL for new endpoints"]
- [Decision made this session: e.g., "Chose to use WebSockets for real-time updates"]

## Open Questions
- [Question 1]
- [Question 2]

## Blockers
- [Blocker 1: what's blocking progress]

## Next Steps
1. [Immediate next task]
2. [Following task]
3. [After that]

# Progress

## Completed
- [x] [Feature/task 1 — date completed]
- [x] [Feature/task 2 — date completed]
- [x] [Feature/task 3 — date completed]

## In Progress
- [ ] [Feature/task 4 — current status]
- [ ] [Feature/task 5 — current status]

## Known Issues
- [Issue 1: description and impact]
- [Issue 2: description and impact]

## Technical Debt
- [Debt 1: what needs cleanup]
- [Debt 2: what needs cleanup]

## Upcoming
- [ ] [Planned task 1]
- [ ] [Planned task 2]
- [ ] [Planned task 3]

## Milestones
### Phase 1: [Name] — [Status]
- [Summary of phase goals and completion]

### Phase 2: [Name] — [Status]
- [Summary]

# Decision Log

## Decision: [Decision Title]
- **Date**: [YYYY-MM-DD]
- **Status**: [Accepted / Superseded / Deprecated]
- **Context**: [What situation prompted this decision]
- **Options Considered**:
  1. [Option A — pros/cons]
  2. [Option B — pros/cons]
  3. [Option C — pros/cons]
- **Selected**: [Which option was chosen]
- **Rationale**: [Why this option was chosen]
- **Trade-offs**: [What we gave up]
- **Consequences**: [Expected impact]

---

## Decision: [Another Decision Title]
...

1. Read ALL Memory Bank files in hierarchical order (1→7)
2. Verify documentation completeness:
   - Are all core files present?
   - Is activeContext.md current?
   - Are there gaps in knowledge?
3. Analyze project context from filesystem:
   - Check directory structure
   - Read relevant source files
   - Understand current code state
4. Develop strategy:
   - Based on documented patterns (systemPatterns.md)
   - Consistent with tech stack (techContext.md)
   - Aligned with project goals (productContext.md)
5. Present approach to user before execution

1. Check Memory Bank (especially activeContext.md)
2. Follow .clinerules guidance for this project
3. Execute tasks using documented patterns
4. Document changes in real-time:
   - Update activeContext.md with current state
   - Add progress entries
5. On completion:
   - Update progress.md (move items to Completed)
   - Update activeContext.md (new current state)
   - Add decision log entries if needed

1. Review what has changed since last update
2. Determine which files need updating
3. Update files in REVERSE hierarchy order:
   a. progress.md — Update task statuses
   b. activeContext.md — Write current state summary
   c. decisionLog.md — Append new decisions (if any)
   d. techContext.md — Update if stack changed
   e. systemPatterns.md — Update if patterns changed
   f. productContext.md — Update if scope changed
   g. projectBrief.md — Update only if fundamental change
4. Validate consistency across files
5. Confirm updates to user

Session Start:
  1. Check if memory-bank/ directory exists
     - If not: Offer to initialize (create directory + template files)
  2. Read files in hierarchical order:
     a. projectBrief.md
     b. productContext.md
     c. systemPatterns.md
     d. techContext.md
     e. activeContext.md
     f. progress.md
     g. decisionLog.md
  3. Identify any missing or incomplete files
  4. Present summary to user:
     - Current project state (from activeContext.md)
     - Active blockers (from activeContext.md)
     - In-progress work (from progress.md)
     - Next planned steps
  5. Ask what the user wants to work on

Session End:
  1. Summarize what was accomplished this session
  2. Update activeContext.md with:
     - What was done
     - Current state of things
     - Any open questions or blockers
     - Immediate next steps
  3. Update progress.md:
     - Move completed items
     - Add new items discovered
     - Update status of in-progress items
  4. Add any decision log entries
  5. Commit memory changes alongside code changes

1. Create memory-bank/ directory in project root
2. Create all 7 template files with placeholder content
3. If projectBrief.md content is provided by user:
   a. Populate projectBrief.md
   b. Derive initial content for other files based on the brief
4. If no brief provided:
   a. Analyze the existing codebase:
      - Read package.json / requirements.txt / etc.
      - Scan directory structure
      - Identify frameworks and patterns
   b. Auto-populate techContext.md from discovered stack
   c. Auto-populate systemPatterns.md from directory structure
   d. Create skeleton files for remaining
5. Report what was created and ask user to verify/expand

Required files (must exist):
  - projectBrief.md
  - activeContext.md
  - progress.md

Recommended files (create if missing):
  - productContext.md
  - systemPatterns.md
  - techContext.md
  - decisionLog.md

Validation checks:
  - File is not empty
  - File has at least one markdown header (#)
  - File content is consistent with its purpose
  - No obvious contradictions between files

- **Input**: `{ projectPath: string, brief?: string }`

- **Input**: `{}` (no parameters)

- **Returns**: Array of `{ name: string, path: string }`

- **Input**: `{ projectPath: string, fileName: string }`

- **Returns**: `{ content: string, lastModified: string }`

- **Input**: `{ projectPath: string, fileName: string, content: string }`

- **Returns**: `{ success: boolean, path: string }`

- **Input**: `{ projectPath: string, fileName: string, content: string }`

- **Returns**: `{ success: boolean, path: string }`

- **Input**: `{ projectPath: string }`

- **Returns**: Array of `{ name: string, size: number, lastModified: string }`

- **Input**: `{ projectPath: string }`

- **Returns**: `{ valid: boolean, missingRequired: string[], missingRecommended: string[] }`

// Server setup
const server = new McpServer({
  name: "memory-bank",
  version: "1.0.0",
});

// Environment variable
const MEMORY_BANK_ROOT = process.env.MEMORY_BANK_ROOT || path.join(os.homedir(), "memory-banks");

# Project Rules

## Code Style
- Use TypeScript strict mode
- All functions must have JSDoc comments
- Use named exports, not default exports

## Testing
- Every new function needs a test
- Use vitest for unit tests
- Minimum 80% coverage for new code

## Git
- Conventional commits format
- Feature branches from main
- Squash merge PRs

## Memory Bank
- Update activeContext.md after every significant change
- Log all architecture decisions in decisionLog.md
- Keep progress.md in sync with GitHub issues

.roorules-architect  # Rules when in architect mode
.roorules-code       # Rules when in code mode
.roorules-ask        # Rules when in ask mode
.roorules-debug      # Rules when in debug mode

---
paths:
  - "src/api/**/*.ts"
  - "lib/server/**/*.ts"
---

# API Development Rules
- All endpoints require input validation using Zod
- Response format: { data, error, meta }
- Rate limiting applied to all public endpoints

# Memory Bank System

## Critical Principle
**I MUST read ALL memory bank files at the start of EVERY task.**
This is not optional. My memory resets completely between sessions.
The Memory Bank is the sole bridge between sessions.

## Read Order (Session Start)
1. projectBrief.md — Project foundation
2. productContext.md — Purpose and goals
3. systemPatterns.md — Architecture and patterns
4. techContext.md — Technology stack
5. activeContext.md — Current session state
6. progress.md — Task tracking
7. decisionLog.md — Decision history

## Operating Protocol

### Plan Mode
1. Read ALL Memory Bank files in order
2. Verify documentation completeness
3. Analyze project context from code
4. Develop strategy based on documented patterns
5. Present approach before execution

### Act Mode
1. Check Memory Bank (especially activeContext.md)
2. Follow .clinerules guidance
3. Execute using documented patterns
4. Update Memory Bank after significant changes

## Update Protocol
When to update (triggers):
- Discovering new patterns (≥25% impact)
- Completing significant implementation
- Making architecture decisions
- User requests "update memory bank" or "UMB"

What to update (in this order):
1. progress.md — Task status changes
2. activeContext.md — Current state, focus, blockers, next steps
3. decisionLog.md — New decisions (append only)
4. techContext.md — If stack changed
5. systemPatterns.md — If patterns changed
6. productContext.md — If scope changed
7. projectBrief.md — Only if fundamental change

## Writing Rules
- Write for someone with NO context about recent work
- Include specific file names, function names, error messages
- Remove outdated information
- Keep each file readable in under 2 minutes
- Use proper markdown formatting
- Include dates in progress and decision entries

1. Start session → Read all memory files
2. User requests work → Plan mode activates
3. Plan presented → User approves → Act mode
4. Work completed → Memory bank updated
5. Session end → Final state written to activeContext.md

MEMORY_BANK_ROOT/
├── project-a/
│   └── memory-bank/
│       ├── projectBrief.md
│       └── ...
├── project-b/
│   └── memory-bank/
│       ├── projectBrief.md
│       └── ...
└── project-c/
    └── memory-bank/
        ├── projectBrief.md
        └── ...