persistence and checkpoints

5 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Agent Server persistence backs three types of data

Agent Server persists three types of data, all backed by PostgreSQL by default: (1) Core resource data (assistants, threads, runs, and cron jobs) always stored in PostgreSQL; (2) Checkpoints (short-term memory) which are snapshots of graph execution state written at each step to make runs durable—if a worker is interrupted, the run can resume from the last checkpoint rather than from the beginning—stored in PostgreSQL by default but can switch to MongoDB or custom implementation, with durability mode controlling checkpoint frequency (async writes after each step by default, exit stores only final state); (3) Store (long-term memory) that persists across threads enabling agents to retain information between separate conversations, stored in PostgreSQL by default but replaceable with custom implementation.

Durability modes control checkpoint frequency in Agent Server

Durability mode controls checkpoint frequency in Agent Server: async (default) writes checkpoints after each step, while exit stores only the final state. Checkpoints are snapshots of graph execution state that make runs durable—if a worker is interrupted, the run can resume from the last checkpoint rather than from the beginning.

Human-in-the-loop state persistence

Human-in-the-loop needs durable thread state to pause and resume. The managed runtime owns the checkpointer, so no extra setup is required.

Event stream resumption

Event streams are resumable. The Agent Server buffers events per run in a bounded buffer, assigns each a seq (per-session ordering) and a durable event_id (stable across replays and replicas), and replays from a cursor on reconnect. The SDK handles transient drops automatically: each open subscription tracks its highest observed seq, and on reconnect the SDK replays from that cursor and dedupes resent events by event_id.

Cross-boundary thread resumption

To resume across a process boundary—a page reload, a worker handoff, or a separate client—reopen the thread with the same thread_id. The server replays buffered events when a new subscription opens, and the SDK demultiplexes them into the same typed projections. Because the per-run buffer is bounded, the earliest events of a very long run may have been evicted.

Give your agent this brain