Serialising agent state is a compatibility contract, not a persistence detail

I treat serialising agent state as a compatibility contract, not a persistence detail. The bytes are the least interesting part. What matters is whether another process, release, or subsystem can recover the same meaning from them. The source taxonomy makes that boundary visible: its surviving pointer says agent state serialisation was merged into agent state management; that target says its 220 concepts then had to be split into six distinct layers. If the domain itself cannot be represented as one coherent category, a single opaque state blob is not a coherent interface.

That split names the consumers a state format must serve: frontend state patterns; session persistence, context compaction, and memory; durable execution, event sourcing, and checkpointing; Claude Code bootstrap and AppState architecture; LangGraph state management; and multi-agent distributed state and consistency. Each layer asks a different question of the representation. A session needs continuity, a durable workflow needs recoverable execution state, and distributed agents need a consistent interpretation. This is why session state and memory need different schemas—proximity in a broad state-management category does not make their lifecycles interchangeable.

I therefore read a serialised record as a message sent across time and system boundaries. Its writer and reader may be separated by a restart, a release, a framework boundary, or a transfer between cooperating agents. The representation carries assumptions about which focused layer owns it and how that layer interprets it. Choosing an encoding only defines the envelope—it does not settle whether a later reader belongs to the same compatibility domain or understands the stored meaning.

The practical consequence is that format decisions must be explicit at the boundary. I want a record to identify the schema it obeys, the subsystem that owns it, and the compatibility path available to a reader. Unknown or ambiguous state should fail as a compatibility problem rather than drift into control flow as plausible data. That is the deeper point behind giving agent state migration semantics—migration is not cleanup after persistence; it is how a changing system continues to honour previously written meaning.

Durability makes the contract unavoidable. A checkpoint exists so work can cross a process boundary, but surviving that boundary is only half the promise. The restored representation must still belong to the execution model that consumes it. The source split places durable execution, event sourcing, and checkpointing in their own focused cluster because recovery has concerns distinct from session context, frontend state, or distributed coordination. Durable agent execution preserves work; a compatible serialisation boundary preserves what that work means.

The six-way split also argues against one global state version. Framework mechanics, session context, AppState, durable history, frontend state, and distributed coordination do not evolve as one unit. I would version at the boundary where a reader makes commitments, then make translation or rejection deliberate there. The source hubs themselves offer a useful model: retired and merged notes remain stable link targets after their concepts move elsewhere. State formats need the same discipline—identities can remain resolvable while ownership and internal organisation change beneath them.

There is one precise concession: a disposable, single-process task that never resumes, shares state, or crosses a release boundary does not need a long-lived compatibility scheme. Its serialised value can remain an implementation detail because no independent reader depends on it. The concession ends as soon as the value becomes a checkpoint, a hand-off, or persisted input to later code—at that point there is a writer-reader boundary, whether or not the team has named it.

I want releases to expose that boundary rather than bury it in serialiser configuration. If behaviour, tools, and persisted state move together, the release must say which earlier representations it can read and which it refuses. That is why an agent release has to version the whole system. Serialisation is where past decisions meet present code—treating it as a contract turns that meeting into an engineered compatibility decision instead of an accidental recovery test.