Named Checkpoints

Save workstream state to its own file. MEMORY.md stays a thin index. Multiple sessions can checkpoint concurrently without conflict.

Triggers

• Save: “checkpoint {name}”, “checkpoint” (defaults to branch name)
• Resume: “continue {name}”, “continue checkpoint” (auto-select if one, list if many)
• Cleanup: “clear checkpoint {name}”

Save Procedure

1. Determine Name

If user gave a name, use it (lowercase, sanitize: replace / with -). If no name, derive from branch:

git branch --show-current

Sanitize: lowercase, replace / with -, strip leading -.

2. Locate Memory Directory

Find the auto memory directory path from the system prompt line: You have a persistent auto memory directory at <path>

3. Gather State

Run in parallel:

git branch --show-current
git status --short | head -10

From conversation context, determine:

• What was accomplished this session
• What failed or was abandoned (and why)
• What the next action should be
• Which files were modified

4. Find Active Plan

Check if a plan file was referenced in conversation context. If found, read it to get step N of M. If none referenced, skip — don’t guess.

5. Write Checkpoint File

Write <memory_dir>/checkpoint-{name}.md:

# Checkpoint: {name}

- **Branch:** `{branch}`
- **Saved:** {YYYY-MM-DD HH:MM}
- **Plan:** `~/.claude/plans/{file}` (step N of M)

## Next Action: {Title}
{1-3 lines with file paths}

## Done This Session
- {accomplishments}

## Failed Approaches
- {what + why — or "None"}

## Modified Files
- {list}

Omit the Plan: line if no plan file exists.

6. Update MEMORY.md Index

Read MEMORY.md. Find the ## Active Checkpoints section.

• If checkpoint name already in index: update its line.
• If not: add a new bullet.
• If no ## Active Checkpoints section exists: insert it after the first # heading. If MEMORY.md doesn’t exist, create it with # Project Memory as the heading.

Bullet format:

- **{name}** ({branch}, {Mon DD HH:MM}) — {one-line summary}

Keep the Resume any: \continue {name}“ line after the bullets.

Do NOT touch any other sections in MEMORY.md.

7. Smart Output

Always save the checkpoint file (it’s insurance if they /clear later). Then recommend the right next step.

Heuristic: Is there an active plan referenced in conversation context?

Yes → plan-driven. Context is disposable (plan tracks progress). Recommend /clear:

Checkpoint "{name}" saved -> checkpoint-{name}.md

/clear then: continue {name}
Next: {one-line next action}

No → exploratory. Context has unique value (debugging, discoveries, decisions). Recommend /compact to preserve it:

Checkpoint "{name}" saved -> checkpoint-{name}.md

/compact {focus guidance derived from session's key findings}

No “continue” line for the /compact case — they’re staying in the session. The checkpoint file is there if they /clear later.

Resume Procedure

1. Determine Name

If user gave a name, use it. If no name given:

• List checkpoint-*.md files in memory directory
• If exactly one: use it automatically
• If multiple: list them and ask user to pick
• If none: report “No checkpoints found.” and stop

2. Read Checkpoint

Read <memory_dir>/checkpoint-{name}.md. If file missing: list available checkpoints (from filenames), ask user to pick.

3. Check Branch

git branch --show-current

If current branch differs from checkpoint’s branch, warn:

Warning: You're on `{current}` but checkpoint was saved on `{saved}`. Switch with: git checkout {saved}

Continue regardless — user decides.

4. Load Plan

If checkpoint references a plan file, read it.

5. Present and Begin

Output the checkpoint summary and next action.

If Failed Approaches is non-empty, explicitly note them before starting work:

⚠ Previously failed: {approach} — {why}

Do not repeat failed approaches. Choose alternative strategies. Then begin working on the next action.

Cleanup Procedure

1. Delete File

Delete <memory_dir>/checkpoint-{name}.md.

2. Update MEMORY.md

Remove the bullet for {name} from ## Active Checkpoints. If no bullets remain, remove the entire section (header + resume line).

3. Output

Cleared checkpoint "{name}"

First-Time Migration

If MEMORY.md contains legacy volatile sections (## Current State, ## Next Action, ## Session Checkpoint, ## Session * Summary), migrate on first save:

1. Extract volatile content into the checkpoint file being saved
2. Remove volatile sections from MEMORY.md
3. Add ## Active Checkpoints section to MEMORY.md
4. Preserve all stable sections verbatim