- name
- memory-guardian
- version
- 1.0.0
- description
- Memory health monitoring, integrity checks, and 3-layer memory architecture for AI agents. Use when agents need to prevent memory loss, detect context overflow before it happens, manage session-to-permanent memory promotion, and maintain a clean memory state across long-running workflows. Includes automated health checks (file size, staleness, duplicates, orphans), migration triggers for vector stores, and emergency recovery via git history.
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
| Total Lines | Risk | Action |
|---|---|---|
| < 2,000 | 🟢 Green | Normal operations |
| 2,000-3,000 | 🟡 Yellow | Prune sessions, compress old entries |
| 3,000-5,000 | 🟠 Orange | Aggressive promotion to permanent, archive sessions |
| 5,000+ | 🔴 Red | Semantic search returns noise → migrate to FAISS |
Promotion Protocol
Before deleting ANY session file, extract:
- Credentials/keys → permanent (NEVER lose these)
- Architecture decisions → permanent/business-strategy.md
- Infrastructure changes → permanent/outreach-infrastructure.md
- New project summaries → permanent/projects/[name].md
- User preferences → permanent/user-system.md
Everything else (debug logs, intermediate results) → delete.
Migration Triggers
| Trigger | Action |
|---|---|
| permanent/ > 5,000 lines | Migrate to FAISS vector store |
| Batch value-stack > 100 items | Add embeddings for semantic retrieval |
| ChatGPT corpus loaded | FAISS mandatory |
| Cross-batch connections > 50 | Consider Neo4j knowledge graph |
Emergency Recovery
Everything is git-tracked. If memory corrupts:
git log memory/→ find last good stategit checkout <hash> -- memory/→ restore- Rebuild MEMORY.md index from
ls memory/permanent/
Context Budget
| Component | Tokens | Notes |
|---|---|---|
| System prompt | ~2,000 | Fixed |
| MEMORY.md | ~1,500 | Keep lean |
| Active session | ~1,000 | Today only |
| memory_search | ~500 | On-demand |
| Total overhead | ~5,000 | Of 200K+ available |