Memory Bank

Memory Bank

Complete guide to Pantheon memory bank — structure, rules, optimization, and maintenance.

Two-System Model

Memory Bank Structure

.pantheon/memory-bank/
├── 00-project.md           ← What is this project? (fill once)
├── 00-architecture.md      ← System design and agent hierarchy
├── 00-components.md        ← Component breakdown and ownership
├── 00-tech-stack.md        ← Tech stack, setup, environment
├── 01-active-context.md    ← Current sprint focus, decisions, blockers (MOST IMPORTANT)
├── 02-progress-log.md      ← What works, what's left, milestones (append-only)
├── _tasks/
│   ├── _index.md           ← Task master list
│   └── TASK0001-name.md    ← Individual task records
└── _notes/
    ├── _index.md           ← Notes index
    └── NOTE0001-topic.md   ← Architectural decisions, findings

File Update Frequency

Golden Rules

1. Never create .md files outside .pantheon/memory-bank/ (except README.md, CONTRIBUTING.md)
2. Never create ANALYSIS_*.md, SUMMARY_*.md, STATUS_*.md anywhere
3. 01-active-context.md is the priority file — keep it current
4. 02-progress-log.md is append-only — never edit history
5. _notes/ decisions are immutable — supersede, never edit

Session → Active Context Graduation

During sprint:
  Athena writes plan → /memories/session/sprint-plan.md   (ephemeral)
  Agents track wip   → /memories/session/wip.md            (ephemeral)

At sprint close:
  @mnemosyne consolidates → .pantheon/memory-bank/01-active-context.md
                          → .pantheon/memory-bank/02-progress-log.md (appended)

Who Writes What

Optimization: Compression Rules

Problem: Memory bank files grow too large, wasting tokens on every load.

Strategy: Lazy-load only what's needed

Compression Targets

• 01-active-context.md: Keep under 100 lines. Archive old sprints to _notes/.
• 02-progress-log.md: Keep last 20 entries. Archive older to _notes/archive/.
• _tasks/: Mark completed tasks [x], move to _tasks/archive/.

Commands

@mnemosyne Compress memory bank          # Audit and compress all files
@mnemosyne Archive completed tasks       # Move done tasks to archive
@mnemosyne Trim active context           # Keep only current sprint

Anti-Patterns

❌ Session output as files

# Wrong
Create IMPLEMENTATION_SUMMARY.md
Create STATUS.md

# Right
@mnemosyne Append to 02-progress-log.md: [summary]

❌ Mandatory handoff after every phase

# Wrong: After every phase → handoff to @mnemosyne

# Right: Agent appends to 01-active-context.md directly
At sprint close → explicit @mnemosyne invocation

❌ Duplicating information

# Wrong: Stack in 00-project.md AND /memories/repo/stack.json

# Right: Atomic facts → /memories/repo/ (auto-loaded)
         Narrative context → 00-project.md (explicit read)

Adopting in a Product

mkdir -p .pantheon/memory-bank/_tasks .pantheon/memory-bank/_notes
touch .pantheon/memory-bank/_tasks/.gitkeep .pantheon/memory-bank/_notes/.gitkeep
# @mnemosyne Initialize memory bank for this repository

Add to .github/copilot-instructions.md:

Always read .pantheon/memory-bank/01-active-context.md before answering.