| name | memory-maintenance |
| description | End of day memory maintenance. Runs distillation, updates state files, prunes stale info. Runs in background with no user interaction. |
Memory Maintenance
Scheduled maintenance to keep memory current and useful. Runs automatically at end of day.
Important: This runs in the background with no user interaction. Do not ask questions - make decisions and note uncertainties in the journal.
Process
1. Run Distillation
First, run the /distill skill to extract facts from today's conversations.
This processes all conversation files, spawns sub-agents for extraction, and writes distilled actions to the journal.
Check if distill already ran today:
grep "distill-summary" ~/.config/macrodata/journal/$(date +%Y-%m-%d).jsonl 2>/dev/null
If not found, invoke /distill. If already ran, skip to step 2.
2. Review Distilled Content
Read the distilled entries from today's journal:
grep '"topic":"distilled"' ~/.config/macrodata/journal/$(date +%Y-%m-%d).jsonl 2>/dev/null | jq -r '.content'
Use these to inform state file updates.
3. State File Updates
State files are a bounded working set, not a log. Each has a budget (a screenful); content over budget is truncated at injection, so a bloated file helps no one. The detail belongs in the journal and entity files — state holds only what's live and load-bearing now, each item a one-line status with a pointer to where the detail lives. Updating state means as much cutting as adding.
today.md
- Clear completed items; move yesterday's detail to the journal
- Keep only carryover that's still live; leave it minimal for morning prep
workspace.md
- Each active project / open thread = one line: status + a pointer (
entities/projects/x.md or "search: ")
- If a bullet has grown into a paragraph, that detail goes to the project's entity file and the bullet becomes a pointer
- Drop resolved threads (the record is in the journal)
human.md
- Only genuinely new, durable facts about the user. Rare updates.
3b. Flags Review
Review state/flags.md — the channel that carries items to the user across sessions.
- For each open flag: is it still true? If addressed/merged/resolved/obsolete, remove it.
- Did today's work surface anything the user needs to see (a bug you can't fix, a decision only they can make, work awaiting their review)? Add it — one line + a pointer to the journal/entity with the full writeup. Do not paste the investigation into flags.md.
- Keep the list short and live. A stale flag list gets ignored.
4. Entity Updates
Review entities/people/ and entities/projects/:
- Integrate any facts extracted by distillation
- Project status changes?
- New projects to create files for?
5. Compact State to Budget
State files must stay within budget. Check them:
wc -c ~/.config/macrodata/state/*.md
Rough targets: today ≲ 3 KB, workspace ≲ 3 KB, human ≲ 3.5 KB, flags ≲ 3 KB, identity ≲ 3 KB. (Hard cap is 4 KB each — content over that is truncated at injection.)
For any file over budget, compact it — this is expected maintenance, not optional:
- Move the detail to the journal (
log_journal) or the relevant entity file first, so nothing is lost
- Then cut the state entry down to a one-line pointer, or remove it if it's resolved
- Also clear: completed todos still listed active, context no longer relevant, info duplicated across files
A file that only ever grows is the bug this step exists to catch. After compacting, re-run wc -c to confirm you're under budget.
6. Index Maintenance
Check if indexes need rebuilding:
manage_index(target="memory", action="stats")
manage_index(target="conversations", action="stats")
If counts seem low or stale, trigger rebuild:
manage_index(target="memory", action="rebuild")
manage_index(target="conversations", action="update")
7. Journal Summary
Write a brief maintenance journal entry:
log_journal(topic="maintenance", content="[what was updated, what was pruned, any observations]")
Note anything uncertain that should be confirmed with the user next session.
