/checkpoint

name: checkpoint
description: Flush durable facts from the current conversation into subrosa's memory before /clear or /compact. Scans the session for user, feedback, project, and reference items; writes or updates leaf memory files and the facts database, then regenerates the byte-budgeted MEMORY.md; soft-archives stale entries; reports a short session recap and confirms it's safe to wipe.

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.

5. **Convert relative dates to absolute dates** before writing. Use today's date as the anchor. For example, replace "yesterday", "last Thursday", or "next sprint".

6. **Use the project-scoped memory directory** from the system prompt's auto memory section, rooted at `~/.claude/projects/<sanitized-cwd>/memory/`. Do not create another location. Facts use that project key.

7. **Review stale facts.** After saving, scan active facts with `subrosa fact list`. Use these signals:

• The hook has an absolute date before today, such as "Next check: 2026-04-27" after that date.
• The hook has "Complete", "Done", "Closed", or similar terminal language for possibly archivable work.
• The hook names a ticket, such as `PROJ-123`, that this conversation says is closed or superseded.

Split candidates into high-confidence and low-confidence tiers. Auto-archive the first tier. Flag the second.

**HIGH-confidence stale: auto-archive (soft-delete).** Both conditions must hold:

• The leaf confirms the terminal state. It may use `Status: Closed/Done/Resolved/Archived/Cancelled`, a heading like `## Outcome` ending in completion, or a closing paragraph that says the work is finished or superseded.
• The hook has a terminal marker (`Complete|Done|Closed|Resolved|Archived|Cancelled|Superseded`) or an absolute date more than 30 days past today.

For each match, run `subrosa fact archive --leaf <file.md>`. This sets `status='archived'`, so the fact leaves generated `MEMORY.md`. The DB row and leaf stay on disk. Nothing is deleted. Count it as `Archived <Z>` in the headline. Restore it with `subrosa fact upsert --leaf <file.md>`.

**LOW-confidence stale flags: flag only.** Use this tier when one signal exists, the leaf does not confirm it, or you are unsure. Count it as `Flagged <W>` in the headline. Cap the stale-flag list at ~5 entries. If more appear, suggest a separate batch review.

Keep the scan cheap. Read hook text first. Open a leaf only for a possible high-confidence archive. Do not open every memory file just to flag it.

8. **Regenerate `MEMORY.md`.** Always run `subrosa generate`, even when nothing was saved. The generator rebuilds active facts with a 23000-byte default budget. It prevents overflow and removes manual hook trimming.

It ranks by pinned > type weight > recency > hits and keeps curated display order. It logs facts below budget. They stay in the DB and remain `subrosa fact search`-able, but are not always loaded.

Pin a dropped fact with `subrosa fact pin --leaf <file.md>`, then regenerate. Raise the project budget with `echo 24500 > <memdir>/.budget`. Claude Code stops reading `MEMORY.md` at around 25,000 b