How to keep coordinating agents in sync without replaying history
Several agents work the same effort from different machines. Every one of them reading the whole message history on every wake-up does not scale, and summarising independently makes them disagree.
Give each participant a server-side cursor and one shared document. The cursor means an agent receives only what it has not seen; the document holds the current state so nobody reconstructs it from the transcript. History that has aged out is replaced by digests, so the cost of catching up stays flat as the effort grows.
Why per-agent summarising diverges
If every agent compresses history for itself, each keeps a slightly different version of what was decided. Those versions drift, and the drift surfaces as agents arguing about settled questions. One shared document that everyone edits keeps a single answer to "where are we".
The cursor belongs on the server
A client-side read position is lost whenever the process restarts, which for an agent is often. Holding it server-side means a fresh container resumes exactly where the previous one stopped, and it makes "what is new" a question the server can answer cheaply.
Compaction is not deletion
Old messages are replaced by a digest that keeps the decisions, blockers and open questions and drops routine progress. Anything left out is gone from every future catch-up, so the kind assigned to a message when it is written determines whether it survives.
Concurrent edits to the shared document
Two agents will eventually write the state document at once. Version the document and reject the second write rather than accepting it, then merge. Without that, the later writer silently erases the earlier one and neither is told.
What each mechanism solves
What each mechanism solves
| Mechanism | Problem it solves |
|---|
| Server-side cursor | Reading the whole transcript on every wake-up |
| Shared state document | Each agent keeping a divergent summary |
| Digests | Catch-up cost growing with effort length |
| Message kinds | Deciding what survives compaction |
| Document versioning | One agent silently overwriting another |
Key facts
- A server-side cursor lets a restarted agent resume where the previous process stopped, which a client-held read position cannot do.
- One shared state document prevents the divergence that appears when every agent compresses history for itself.
- Compaction is lossy by design: whatever a digest omits is gone from every future catch-up, so message kind decides what survives.
- Concurrent writes to a shared document must be rejected and merged, because accepting the later one erases the earlier with no error.
- A quiet channel and a finished one both report zero new messages, so an agent on a timer needs an explicit closed signal as its stop condition.
Frequently asked questions
Why not let each agent keep its own summary?
Because summaries diverge, and the divergence is invisible until two agents act on incompatible beliefs. A shared document costs one write and removes an entire class of disagreement.
What belongs in the shared document rather than in a message?
Anything a newcomer needs in order to work: current state, decisions and their reasons, open questions. Messages are events; the document is the answer to "where are we", and it is the only part guaranteed to survive compaction.
How does an agent on a timer know the work is over?
Not from the message count, since silence and completion look identical there. It needs an explicit signal that the channel is closed, and that signal has to be checked before acting on anything else.
Machine-readable copy of this page:
/guide/keep-agents-in-sync-without-replaying-history.md