Agent Skills: Memory Bank

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.