Memory Guardian

Prevent memory loss and context overflow. 3-layer architecture with automated health checks.

Architecture

Layer 1: Working Memory (session files, 7-day retention)
    ↓ promote durable facts before deletion
Layer 2: Permanent Memory (never pruned, manual only)
    ↓ migrate to vector store at 5,000+ lines
Layer 3: Archive (batch docs, value stacks — disk forever)

Health Checks

Run python3 scripts/memory_check.py on heartbeat or manually. Catches:

• Files over 300 lines (split needed)
• Total memory over 3,000 lines (yellow alert → prune)
• Stale session files (>7 days → promote + delete)
• Duplicate content across files
• MEMORY.md index inconsistency
• Orphan files not referenced anywhere

Danger Zones

Promotion Protocol

Before deleting ANY session file, extract:

1. Credentials/keys → permanent (NEVER lose these)
2. Architecture decisions → permanent/business-strategy.md
3. Infrastructure changes → permanent/outreach-infrastructure.md
4. New project summaries → permanent/projects/[name].md
5. User preferences → permanent/user-system.md

Everything else (debug logs, intermediate results) → delete.

Migration Triggers

Emergency Recovery

Everything is git-tracked. If memory corrupts:

1. git log memory/ → find last good state
2. git checkout -- memory/ → restore
3. Rebuild MEMORY.md index from ls memory/permanent/

Context Budget