/memory-maintenance

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

**FIRST, before distillation or any reads:** if you have not already banked a heartbeat journal entry (topic `memory-maintenance`) claiming this run, do it NOW, then re-read recent `memory-maintenance` journal entries. If a sibling banked an earlier heartbeat for tonight, stand down: contribute deltas via journal only, never state files. Scheduled runs can double-fire; the journal write claims, the re-read arbitrates.

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: <term>")
• 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.