Checkpoints

Conceptual

Durable snapshots enabling resumption, rollback and forking.

A checkpoint captures enough state to continue a run on another worker: plan revision, completed steps, working memory and an optional filesystem snapshot.

When checkpoints are written#

After every completed step (metadata checkpoint, always).
Before any irreversible effect (full checkpoint, always).
Before a plan revision that invalidates completed work.
At a caller-defined interval for long background runs.
On suspension for budget exhaustion or pending approval.

Rollback semantics#

Effect	Rollback
Workspace file writes	Restored from the filesystem snapshot
Working memory	Restored exactly
Long-term memory writes	Marked reverted; consolidations recomputed
External writes via connectors	Not automatic — compensating actions must be defined by the tool
Merged or released code	Not reversible once consumed; this is why merge authority never sits with the agent

bash

curl -X POST https://api.pimsy.ai/v1/runs/run_7c1a9d/resume \
  -H "Authorization: Bearer $PIMSY_API_KEY" \
  -d '{ "from_checkpoint": "ckpt_step_11", "budget": { "steps": 30 } }'

Last updated 2026-09-06