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:

• Extract volatile content into the checkpoint file being saved

• Remove volatile sections from MEMORY.md

• Add ## Active Checkpoints section to MEMORY.md

• Preserve all stable sections verbatim