checkpoint

checkpoint: flush memory before a context wipe

The user is about to run /clear or /compact. Save durable facts before either command, then report whether it is safe to wipe.

MEMORY.md is generated from (~/.claude/subrosa/memory.db). Never hand-edit it. Write leaf files and register facts. The generator rebuilds the byte-budgeted index. Use the subrosa CLI (subrosa fact …, subrosa generate, subrosa search …). If it is not on PATH, bootstrap installs it at ~/.claude/subrosa/bin/subrosa.

Procedure

1. Scan the full conversation. Review every turn, not only the last. Classify each candidate as one of these four types:

   • user: role, preferences, knowledge, and working context
   • feedback: corrections and validated approaches. Include the reason for both.
   • project: ongoing work, deadlines, motivations, roles, and reasons
   • reference: pointers to external systems, dashboards, and ticket projects

2. Apply the exclusion list strictly. Never save:

   • Code patterns, conventions, file paths, or architecture
   • Git history, commit hashes, blame info, or PR numbers
   • Debugging recipes. The fix is in code, and the reason is in the commit message.
   • Anything already covered by CLAUDE.md
   • Ephemeral state, such as task details, investigation chains, or bare ticket numbers
   • Routine activity logs. Save only what was surprising or non-obvious.

   These exclusions apply even when the user says, "save this." Ask what was non-obvious or whether they meant CLAUDE.md.

3. Check existing memory before writing. Run subrosa fact list for curated facts. Run subrosa search "<keyword>" for the full transcript archive. Read related leaf files. For each candidate:

   • A correct similar fact exists: skip it.
   • A stale similar fact exists: update it in place.
   • No similar fact exists: write a new one.

4. Write the leaf, then register the fact. Do NOT hand-edit MEMORY.md.

   • Create or update the leaf with frontmatter: name, description, type.
   • Use Why: and How to apply: for feedback and project. The why helps future readers judge edge cases.
   • Register it: subrosa fact upsert --leaf <file.md> --hook "<one-line hook, under ~150 chars>" --origin-session <id>. <id> is the current session id from step 10. Pass it for new and updated facts, because checkpoint-mark refuses a session with no fact stamped with its id. Type and title come from frontmatter. Pass --pin for an always-loaded guardrail, but pinned facts still compete for the byte budget. On update, the stored title stays unless you pass --title. New facts append; updates keep their place.
   • Link related leaves with [[slug]], using the other leaf's name. A not-yet-written leaf is allowed. Run subrosa fact link <slug> after registration. [dangling] means a typo or missing leaf.