Checkpoint

## Quick Recovery

**Last Checkpoint**: YYYY-MM-DD HH:MM **Branch**: `branch-name-here` **Working
On**: [brief task description] **Files Modified**: [list or "none"] **Next
Step**: [what to do next] **Uncommitted Work**: yes/no

2. Write State Files

Update .claude/state/handoff.json:

{
  "timestamp": "ISO datetime",
  "git": {
    "branch": "current branch",
    "lastCommit": "hash + message",
    "uncommittedFiles": ["list"]
  },
  "currentTask": "what you are working on",
  "completedSteps": ["step 1", "step 2"],
  "pendingSteps": ["step 3", "step 4"],
  "notes": "anything important for resumption"
}

For multi-step tasks, also write .claude/state/task-{name}.state.json:

{
  "task": "task-name",
  "started": "ISO datetime",
  "lastUpdated": "ISO datetime",
  "steps": [
    { "name": "Step 1", "status": "completed" },
    { "name": "Step 2", "status": "in_progress" }
  ],
  "context": { "branch": "branch-name", "notes": "key info" }
}

3. Consider Committing

If uncommitted work exists and the task is at a safe point:

git add -A && git commit -m "WIP: checkpoint before potential failure"

MCP Save (--mcp flag)

When --mcp is specified, also save structured entities to MCP memory.

Create Entities

Use mcp__memory__create_entities():

entities = [
  {
    name: "Session_2026-01-28_TaskName",
    entityType: "session_context",
    observations: [
      "Working on: [task description]",
      "Completed: [what was done]",
      "Decision: [key choice made]",
      "Files: [files modified]",
      "Next: [pending work]",
    ],
  },
];

Entity Types

Naming Conventions

• Sessions: Session_YYYY-MM-DD_BriefTaskName
• Decisions: Decision_FeatureName_Choice
• Bugs: Bug_ComponentName_Issue

Create Relations

Link related entities with mcp__memory__create_relations().

Confirm Save

After saving, report what was preserved:

Saved to MCP memory:
- Session context: [summary]
- Decisions: [count]
To retrieve later: mcp__memory__read_graph()

When to Use

• Before large file operations
• Before complex multi-step tasks
• When session is getting long (50+ tool calls)
• Periodically during long sessions (every 30-60 minutes)
• Before risky operations

Compaction Recovery

On resume after compaction:

1. Read .claude/state/handoff.json
2. Read any .claude/state/task-*.state.json
3. If MCP was used: mcp__memory__search_nodes("Session_")
4. Cross-reference with git log and git status

Version History