memory-compaction

Memory Compaction

Reorganizes the memory tree to keep it scannable without losing durable facts.

Run this when compact-memory.sh reports warnings, or proactively after dense work periods.

---

Invariants -- never violate

• Every durable fact must survive compaction (move or merge, never delete)
• Memory/MEMORY.md must stay short and scannable
• Every branch folder must contain a same-name entry note (<topic>/<topic>.md)
• Evidence files are never touched during compaction

---

Step 1 -- Audit

Run the report script first:

scripts/compact-memory.sh /path/to/project

Note which files are flagged as:

• CRITICAL (>200 lines) -- act immediately
• WARNING (>150 lines) -- split at next opportunity
• stub or empty -- populate or remove

---

Step 2 -- Prune stale entries

In each branch note, remove or update entries that are:

• Superseded: a newer entry contradicts the old one -> remove the old, update the new
• Dead reference: refers to a path, API, or dependency that no longer exists -> remove
• Speculation never confirmed: still marked with "might", "probably", "TODO: verify" -> remove or move to Open Questions
• Recent Changes too old: entries older than ~4 weeks -> move stable facts to Current State, drop transient ones

Do not prune:

• Gotchas and lessons (even old ones are valuable if the risk still exists)
• Decision rationale (even for reversed decisions -- mark as Status: reversed)

---

Step 3 -- Split large branch notes

If a branch note exceeds ~150 lines:

1. Identify the dominant sub-topic that makes it large
2. Promote the branch to a folder if it is still a flat note:
   • Create Memory/<topic>/ directory
   • Move Memory/<topic>.md to Memory/<topic>/<topic>.md
3. Create Memory/<topic>/<subtopic>.md for the extracted content
4. Replace the moved section in the entry note with a link:

   See [subtopic.md](subtopic.md) for details.
   

5. Update Memory/MEMORY.md branch link if the path changed