Memory Guardian#

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

Architecture#

text

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#

Total LinesRiskAction< 2,000🟢 GreenNormal operations2,000-3,000🟡 YellowPrune sessions, compress old entries3,000-5,000🟠 OrangeAggressive promotion to permanent, archive sessions5,000+🔴 RedSemantic search returns noise → migrate to FAISS

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#

TriggerActionpermanent/ > 5,000 linesMigrate to FAISS vector storeBatch value-stack > 100 itemsAdd embeddings for semantic retrievalChatGPT corpus loadedFAISS mandatoryCross-batch connections > 50Consider Neo4j knowledge graph

Emergency Recovery#

Everything is git-tracked. If memory corrupts:

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

Context Budget#

ComponentTokensNotesSystem prompt2,000FixedMEMORY.md1,500Keep leanActive session1,000Today onlymemory_search500On-demandTotal overhead****~5,000Of 200K+ available