What does Koog's Persistency feature checkpoint, and what does a rollback not undo?

## What the feature is for Agent runs are long, non-deterministic and expensive. A run that dies at step nine of twelve has burned real money and real wall-clock time, and re-running it from scratch burns them again — and may not reproduce, because the model is sampling. Koog's Persistency feature exists to make a run's progress durable so it can be resumed, and rewindable so a bad branch can be abandoned without discarding everything before it. You turn it on by installing the feature on the agent and giving it a storage provider. From there, checkpoints can be taken at points you choose, or automatically as the run advances if you enable that. ## What a checkpoint holds Conceptually, a checkpoint captures the run's execution state: the messages the agent has accumulated so far, and where in the strategy execution stood, including the input that step was working on. That combination is what lets execution be re-entered rather than restarted — the agent resumes with the same context it had, at the same place. It does not capture the world. Nothing outside the agent process — your database, a third-party API, a queue, a mailbox — is part of the snapshot. ## Durability is the storage provider's decision The feature separates *taking* a checkpoint from *keeping* it. An in-memory provider is fine for tests and for rewind-within-a-run, and useless for crash recovery: when the JVM exits, the checkpoints exit with it. Surviving a restart or a redeploy means a provider that writes somewhere durable — a file, or your own implementation over a database. Two consequences follow. The state you checkpoint has to be serialisable, which constrains what you may park in it. And checkpoint writes are I/O on the hot path, so automatic per-step checkpointing on a chatty strategy is a real cost in latency and storage churn; checkpoint where the value is, typically before an expensive or irreversible step. ## The rollback illusion The most important thing to say in an interview is that rollback is not a database transaction. Restoring an earlier checkpoint rewinds the *agent's* state. It does not rewind anything a tool already did. If the agent called a tool that emailed a customer, refunded an order, posted to Slack or deleted a file, that happened. Rewinding to a point before the tool call means the agent may well decide to call it again — and now the customer has two emails. The same asymmetry applies to money and rate limits: tokens spent before the checkpoint you rewound to are spent, and provider rate-limit budget consumed is consumed. Persistency buys you recovery of context, not of consequences. ## Designing around it Three patterns handle this. Make side-effecting tools *idempotent*, keyed by something stable — an order id, a request id you generate before the call — so a replayed call is a no-op rather than a duplicate. Where idempotency is impossible, define a *compensating action* (refund for charge, retraction for publish) and make the recovery path invoke it rather than pretending the effect never happened. And *checkpoint immediately before* irreversible steps, so a resume re-enters at the effect rather than replaying a long tail of work that precedes it. Also think about ordering: a tool that both mutates the world and returns data the agent needs should, where possible, record its own outcome durably so that on resume the agent can read the outcome instead of repeating the mutation. ## Persistency versus memory A frequent confusion is between checkpointing and agent memory. Checkpointing is about one run's execution state — mechanical, short-lived, about resumption. Koog's memory feature is a different concern: durable facts extracted from runs, stored under concepts and scopes, and loaded back into later prompts so an agent recalls things across runs. Restoring a checkpoint replays a run; memory changes what a *new* run knows. In production you often install both, for different reasons. ## Operational questions to be ready for How long do checkpoints live, and who deletes them? They contain conversation content, which frequently contains personal data, so retention and encryption are governance questions, not implementation details. What happens if the strategy changes between checkpoint and resume — a checkpoint taken by yesterday's graph may reference a step that no longer exists, so treat resumability across deploys as a versioning problem. And can two workers resume the same checkpoint concurrently? If your storage does not prevent it, you have just double-executed the tail of a run.