Memory management for AI agents: Ebbinghaus forgetting curve, YAML frontmatter, tiered recall (core/active/warm/cold/archive), decay maintenance, creative random recall. Triggers: "memory management", "organize vault", "memory decay", "forgetting curve", "context budget", "memory bloat", "tier search", "creative recall", "memory health". Does NOT use for: general note-taking, project documentation, or CLAUDE.md configuration.
Memory system with automatic decay, tiered search, and creative recall. Works with any directory of markdown files.
init)decay)stats, scan)creative)search)promote, demote)touch)compress)generate-l1)python3 <skill_dir>/scripts/memory-engine.py <command> <args>decay daily via cron", "consider promoting X to core"python3 scripts/memory-engine.py scan <directory>
Reports: file count, YAML coverage, size, recommendations.
python3 scripts/memory-engine.py init <directory> [--dry-run]
Adds relevance, last_accessed, tier to files missing frontmatter.
Infers type from directory path. Infers dates from YAML fields, git log, or file mtime.
python3 scripts/memory-engine.py decay <directory> [--dry-run]
Updates all cards: recalculates relevance scores and reassigns tiers. Schedule daily via cron for automatic forgetting.
python3 scripts/memory-engine.py touch <filepath>
Resets card to active (relevance=1.0). Call this when reading a card to answer a question.
python3 scripts/memory-engine.py creative <N> <directory>
Random sample from cold/archive tiers. Read these cards and look for unexpected connections.
python3 scripts/memory-engine.py stats <directory>
Shows tier distribution, context budget, stale card count.
python3 scripts/memory-engine.py compress <directory> [--dry-run]
Generates cached l1_summary and content_tokens in YAML frontmatter for all cards.
python3 scripts/memory-engine.py generate-l1 <directory> [--dry-run]
Regenerates l1_summary field from card content (uses ## Summary section or first paragraph).
| Layer | What | Size Target | Loaded |
|---|---|---|---|
| Hot context | State file (volatile focus, blockers) | <4KB | Every turn |
| Searchable vault | Cards with YAML, one per entity | Unlimited | On demand |
| Archive | Old logs, completed work | Unlimited | Deep/creative only |
Rule: Each fact lives in ONE place. If it's in a card, don't also put it in the state file. See references/architecture.md for full design rationale.
Cards support three loading levels, inspired by OpenViking's progressive disclosure:
| Level | What's loaded | Use case |
|---|---|---|
| L0 | description field only | Index listings, bulk scans |
| L1 | l1_summary (cached) or ## Summary section | Search results, triage |
| L2 | Full card body | Deep read, answering questions |
Use --level 0|1|2 with search to control how much content is returned.
Use --all to include all tiers regardless of search mode.
Cards have relevance: 0.0-1.0 that decays linearly over time:
core tier is manual-only — for identity, security, pricing. Never auto-demoted.
| Mode | Tiers searched | When |
|---|---|---|
| heartbeat | core + active | Quick checks, monitoring |
| normal | active + warm | Most questions |
| deep | all tiers | Strategy, OSINT, complex analysis |
| creative | random cold+archive | Brainstorming, ideation |
See references/search-protocols.md for detailed protocols.
Minimum required fields (managed by engine):
---