Session Checkpoint

Session Checkpoint

Audience: Agents and developers needing to preserve session state during long-running workflows.

Goal: Snapshot current session state to a ledger file for crash recovery, context refresh, and cross-session continuity.

Key insight: /clear + ledger reload provides fresh context with full signal preservation, avoiding the cumulative degradation of repeated /compact cycles.

Config Dependency

Requires session.ledger: true in .agents.yml:

session:
  ledger: true
  ledger_path: .agents/session_ledger.md  # optional, defaults to .agents/session_ledger.md

Note: The ledger is per-worktree (ephemeral session state). Handoffs go to main worktree (permanent, for Skill("learn")).

Process

Step 1: Check Config

SESSION = config_read("session", "{}")

If session.ledger is false or missing:

• Return: Checkpoint skipped - session.ledger not enabled in .agents.yml
• Exit without creating file

Step 2: Determine Ledger Path

Use session.ledger_path from config, or default to .agents/session_ledger.md.

Ensure the directory exists:

mkdir -p .agents

Step 3: Gather State

From the provided context, extract:

1. Goal - What is being worked on (success criteria if known)
2. Constraints/Assumptions - Known limitations or decisions
3. Key Decisions - Important choices made during this work
4. State:
   • Done: Completed items
   • Now: Current focus
   • Next: Planned next step
5. Open Questions - Unresolved items (mark as UNCONFIRMED if uncertain)
6. Working Set - Key files, IDs, or commands relevant to current work

Step 4: Write Ledger

Write to the ledger file using this format:

# Session Ledger

_Last updated: <timestamp>_

## Goal
<goal and success criteria>

## Constraints/Assumptions
- <constraint 1>
- <constraint 2>

## Key Decisions
- <decision 1>
- <decision 2>

## State

### Done
- <completed item 1>
- <completed item 2>

### Now
<current focus>

### Next
<planned next step>

## Open Questions
- <question 1>
- <question 2> `UNCONFIRMED`

## Working Set
- Files: <key files>
- IDs: <relevant IDs>
- Commands: <useful commands>

Step 5: Return Confirmation

Return a brief confirmation:

Checkpoint saved to .agents/session_ledger.md
- Goal: <brief goal>
- State: <done count> done, now: <current>, next: <next>

When to Checkpoint

Context Threshold Triggers

• 70% context usage - Checkpoint before context becomes constrained
• 85%+ context usage - Checkpoint immediately, then consider /clear + ledger reload
• Multi-day implementations - Checkpoint at end of each working session
• Complex refactors - Checkpoint before and after major changes

Skip Checkpointing For

• Quick tasks under 30 minutes
• Simple bug fixes or single-file changes
• Sessions already using /handoff

Integration Points

Other agents or skills can invoke checkpointing:

Before risky operations

Before starting major refactor, apply `session-checkpoint` skill to save current state.

After milestones

After completing each major step, apply `session-checkpoint` skill with current progress.

At context thresholds

If context usage exceeds 70%, apply `session-checkpoint` skill before continuing.

Post-Clear Recovery Protocol

When resuming after /clear with a ledger file:

1. Auto-load ledger - Read the ledger file to restore context
2. Validate UNCONFIRMED items - Any assumption marked UNCONFIRMED needs verification
3. Ask 1-3 validation questions before continuing work:
   • "The ledger shows X was in progress - is this still the current focus?"
   • "I see assumption Y marked UNCONFIRMED - can you confirm this?"
4. Resume from "Now" section after validation

UNCONFIRMED Marker Usage

Mark assumptions as UNCONFIRMED when:

• File state may have changed externally
• User preferences were inferred, not stated
• Technical decisions were made without explicit approval
• External dependencies (APIs, services) status is uncertain

Clear + Ledger vs Repeated Compaction

Prefer /clear + ledger reload over multiple /compact cycles:

Guideline: After 2-3 compactions in a session, checkpoint to ledger and /clear for fresh context with preserved state.

Ledger vs Handoff vs Tasks

Use session-checkpoint for:

• Automated state preservation during workflows
• Recovery from unexpected session termination
• Quick snapshots before risky operations
• Context refresh after multiple compactions

Use /handoff for:

• Intentional session handoffs
• Detailed context for new sessions
• Structured handoff with analysis