session-checkpoint

name	session-checkpoint
description	Save session state to ledger file for continuity across crashes, context switches, or /clear + reload cycles.
allowed-tools	Read Write

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