---
name: memory-bank
description: Persistent project documentation system that maintains context across sessions. Creates structured Memory Bank files to preserve project knowledge, decisions, and progress.
alwaysApply: true
---

# Memory Bank

I am Claude Code, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.

## Memory Bank Structure

The Memory Bank consists of required core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:

```
memory-bank/
├── projectbrief.md      # Foundation - core requirements and goals
├── productContext.md    # Why this exists, problems it solves
├── activeContext.md     # Current focus, recent changes, next steps
├── systemPatterns.md    # Architecture, patterns, decisions
├── techContext.md       # Tech stack, setup, constraints
└── progress.md          # Status, what works, what's left
```

### File Hierarchy

```
projectbrief.md
    ├── productContext.md
    ├── systemPatterns.md
    └── techContext.md
            └── activeContext.md
                    └── progress.md
```

### Core Files (Required)

1. **projectbrief.md**
   - Foundation document that shapes all other files
   - Created at project start if it doesn't exist
   - Defines core requirements and goals
   - Source of truth for project scope

2. **productContext.md**
   - Why this project exists
   - Problems it solves
   - How it should work
   - User experience goals

3. **activeContext.md**
   - Current work focus
   - Recent changes
   - Next steps
   - Active decisions and considerations

4. **systemPatterns.md**
   - System architecture
   - Key technical decisions
   - Design patterns in use
   - Component relationships

5. **techContext.md**
   - Technologies used
   - Development setup
   - Technical constraints
   - Dependencies

6. **progress.md**
   - What works
   - What's left to build
   - Current status
   - Known issues

### Additional Context

Create additional files/folders within memory-bank/ when they help organize:
- Complex feature documentation
- Integration specifications
- API documentation
- Testing strategies
- Deployment procedures

## Core Workflows

### Starting a Session

1. Read ALL memory bank files in order:
   - projectbrief.md (foundation)
   - productContext.md (why)
   - techContext.md (how)
   - systemPatterns.md (architecture)
   - activeContext.md (current state)
   - progress.md (status)

2. Verify context is complete
3. Identify current work focus from activeContext.md
4. Continue from where we left off

### During Work

1. Keep activeContext.md updated with current focus
2. Document significant decisions in systemPatterns.md
3. Update progress.md after completing features
4. Add new patterns or constraints to relevant files

### Ending a Session

1. Update activeContext.md with:
   - What was accomplished
   - Current state of work
   - Immediate next steps
   - Any blockers or considerations

2. Update progress.md with:
   - New completed items
   - Changed status of in-progress items
   - New known issues

## Documentation Updates

Memory Bank updates occur when:
1. Discovering new project patterns
2. After implementing significant changes
3. When user requests with **update memory bank** (MUST review ALL files)
4. When context needs clarification

When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state.

## Initializing Memory Bank

When starting a new project or if memory-bank/ doesn't exist:

```bash
mkdir -p memory-bank
```

Create projectbrief.md first by asking the user:
- What is this project?
- What are the core requirements?
- What are the main goals?

Then create remaining files based on discovered context.

## File Templates

### projectbrief.md
```markdown
# Project Brief

## Overview
[One paragraph describing what this project is]

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

## Goals
- [Goal 1]
- [Goal 2]

## Scope
### In Scope
- [Item]

### Out of Scope
- [Item]
```

### productContext.md
```markdown
# Product Context

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

## Solution
[How does this project solve it?]

## User Experience
[How should users interact with this?]

## Success Criteria
- [Criteria 1]
- [Criteria 2]
```

### activeContext.md
```markdown
# Active Context

## Current Focus
[What we're working on right now]

## Recent Changes
- [Change 1]
- [Change 2]

## Next Steps
1. [Step 1]
2. [Step 2]

## Active Decisions
- [Decision being considered]

## Blockers
- [Any blockers]
```

### systemPatterns.md
```markdown
# System Patterns

## Architecture
[High-level architecture description]

## Key Patterns
### [Pattern Name]
- Purpose: [Why this pattern]
- Implementation: [How it's implemented]

## Component Relationships
[How components interact]

## Design Decisions
| Decision | Rationale | Date |
|----------|-----------|------|
| [Decision] | [Why] | [When] |
```

### techContext.md
```markdown
# Tech Context

## Stack
- [Technology]: [Purpose]

## Development Setup
```bash
# Setup commands
```

## Dependencies
- [Dependency]: [Version] - [Purpose]

## Constraints
- [Constraint 1]

## Environment
- [Environment variable]: [Purpose]
```

### progress.md
```markdown
# Progress

## Completed
- [x] [Feature/Task]

## In Progress
- [ ] [Feature/Task] - [Status]

## Planned
- [ ] [Feature/Task]

## Known Issues
- [Issue 1]

## Metrics
- [Metric]: [Value]
```

## Best Practices

1. **Be Concise** - Memory bank files should be scannable
2. **Be Current** - Update after significant changes
3. **Be Accurate** - Don't let documentation drift from reality
4. **Be Complete** - Include enough context to resume work
5. **Be Structured** - Use consistent formatting

## REMEMBER

After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.