memory-bank

Memory bank rules, structure, and optimization — complete guide to Pantheon memory management.

SKILL.md

GitHub

Memory Bank

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


Two-System Model

System Where Owner Lifetime Purpose
Memory Bank .pantheon/memory-bank/ Team Permanent, versioned Project context: architecture, patterns, progress
VS Code /memories/ .vscode/ or workspace Agent Session/repo scoped Atomic facts, conversation plans

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

File Fill when Update frequency
00-project.md Project start Rarely
00-architecture.md Project start On significant changes
00-components.md Project start When components added/removed
00-tech-stack.md Project start On stack changes
01-active-context.md Each sprint Each sprint / major decision
02-progress-log.md First completion Append-only per milestone
_tasks/ Sprint tracking Per task
_notes/ Significant findings Per finding

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

Content Written by Where
Project overview, architecture Mnemosyne (at init) 00-03.md
Sprint context, decisions Agent / Mnemosyne 01-active-context.md
Milestone completions Any agent 02-progress-log.md (append)
Task records Mnemosyne (on request) _tasks/TASK000X-*.md
Architecture decisions Mnemosyne (on request) _notes/NOTE000X-*.md
Atomic facts Any agent /memories/repo/
Conversation plans Athena / any agent /memories/session/

Optimization: Compression Rules

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

Strategy: Lazy-load only what's needed

Rule Before After
Active context 500+ lines of history 50 lines: current sprint only
Progress log Everything since day 1 Link to archived logs; keep last 50 lines
Task records All tasks in one file One file per task; archive completed
Notes Long narrative Bullet points with links to source

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.