AI agent context checkpoint, the two-layer pointer most guides skip

The mental model most articles import from the wrong domain

The phrase “context checkpoint” gets its connotation from two places. One is ML training, where you periodically write model weights and optimizer state to disk so the run survives a crash. The other is workflow orchestration, where a runtime like LangGraph or Microsoft Agent Framework serializes its state graph at each pause point so it can resume after a failure. Both are about the runtime owning the thing it serializes.

A frontier-model agent built on a vendor SDK is a different shape. The SDK owns the model session, the agent loop, the tool dispatch, the on-disk transcript, and the resume protocol. Your host code does not control those internals. If your host writes a checkpoint blob of “the agent’s state” you are duplicating something the SDK already maintains, and you will diverge from it within one rate limit. The right move is to use the SDK’s own on-disk transcript as the durable representation, and have your host write down only what the SDK does not: a stable identity that survives upstream rollover.

That is the two-layer pointer this page is about. Layer one is the SDK’s transcript file on disk. Layer two is a chain of upstream session IDs your host maintains so it can always tell the SDK which transcript to load.

The two-layer pointer

The diagram below is what a single checkpoint actually points at, in a live ACP-based agent. The center is the host’s stable conversation identity. On the left are the things that can roll the upstream session ID forward at any time. On the right are the durable artifacts a resume or fork eventually addresses.

Anything that arrives on the left re-emerges from the hub as a fresh upstream session ID, which gets appended to the chain. The transcript on the right is immutable per session ID, so each chain entry addresses its own JSONL file. To resume, the host hands the SDK the current head of the chain; to walk further back in history, the host can hand the SDK any older entry. The chain is the only piece of state that has to be yours.

One-layer versus two-layer, side by side

Toggle to see how the same conversation plays out the first time the upstream session ID rolls. The one-layer pattern is what almost every tutorial on AI agent context checkpointing actually implements, even when the prose talks about robustness.

What happens when you click fork

This is the lifecycle of one fork operation through the Fazm stack, from the button press in SwiftUI to the new branch landing in the chat. Every step here is a function you can open in the public repo.

Notice what does not happen. The host never serializes the conversation. The host never copies the prompt history into a new session. The host never reaches into the JSONL file. The branch is created by handing the upstream side a sessionId and letting the SDK manage the new on-disk transcript. The source’s JSONL is still there afterwards, recoverable via Conversation History because that view simply scans ~/.claude/projects for sessions on the current cwd.

The chain, written out

The chain itself is small. Five helpers in one file. The interesting one is appendToSessionChain at line 634 of Desktop/Sources/Providers/ChatProvider.swift. It de-duplicates older entries, no-ops if the new ID is already at the head, and bounds the chain at sixteen via sessionChainMaxSize at line 622. Every write to the primary acpSessionId_* UserDefaults key goes through persistSessionId (line 663), which sets the head AND appends to the chain in one call, so there is no path where the host writes a new head and forgets to extend the chain.

// Desktop/Sources/Providers/ChatProvider.swift
private static let sessionChainMaxSize = 16

private static func appendToSessionChain(_ id: String, storageKey: String) {
    let trimmed = id.trimmingCharacters(in: .whitespaces)
    guard !trimmed.isEmpty else { return }
    let chainK = chainKey(forStorageKey: storageKey)
    var chain = UserDefaults.standard.stringArray(forKey: chainK) ?? []
    if chain.last == trimmed { return }
    chain.removeAll { $0 == trimmed }
    chain.append(trimmed)
    if chain.count > sessionChainMaxSize {
        chain = Array(chain.suffix(sessionChainMaxSize))
    }
    UserDefaults.standard.set(chain, forKey: chainK)
}

private static func persistSessionId(_ id: String, storageKey: String) {
    guard !id.isEmpty else { return }
    UserDefaults.standard.set(id, forKey: storageKey)
    appendToSessionChain(id, storageKey: storageKey)
}

The chain is reset only by clearSessionId (line 671), which is called from New Chat, sign-out, and explicit pop-out close paths. Never from a transient failure. A rate limit is not a new conversation, it is a glitch in an old one, and resetting the chain on it is the entire bug this pattern exists to prevent.

The fork call, written out

And here is the actual JSON-RPC call that branches the upstream session. From acp-bridge/src/index.ts line 4136, insidehandleForkSession:

// acp-bridge/src/index.ts
const result = (await acpRequest("session/fork", {
  sessionId: sourceEntry.sessionId,
  cwd,
  mcpServers: buildMcpServers(mode, cwd, msg.toSessionKey),
})) as { sessionId: string };

// In-place fork: re-bind the same UI key to the new sessionId.
// Side-by-side fork: leave the source under fromSessionKey, register the new one under toSessionKey.
if (inPlace) {
  unregisterSession(msg.fromSessionKey);
}
registerSession(msg.toSessionKey, { sessionId: result.sessionId, cwd, model });

Two valid modes, called out in the inline comments at lines 4109 to 4117. The in-place fork replaces the source under the same UI key (this is the “fork the current chat” button most users interact with). The side-by-side fork registers the branch under a different key while leaving the source live, which is the primitive a future “open fork in new pop-out” UX is built on.

In both cases the source’s sessionId is left alive on disk. The bridge does not delete the JSONL, the upstream does not delete the JSONL, and the Conversation History view that scans ~/.claude/projects/<encoded-cwd> will still surface it next time the user opens the picker. A fork creates a branch, it does not erase the trunk.

Branching from a non-head position

ACP exposes session/fork only at the head of a live session, which is enough for “branch from current point” but not for “branch from a turn three positions back.” That second pattern is what an edit-and-resubmit UX needs: the user clicks an old prompt, edits the text, sends it, and expects everything after that turn to be replaced with a fresh response.

The Fazm implementation lives at truncateForEdit in ChatProvider.swift around line 1800. It drops the edited message and every later message from the in-memory list, the persisted store, and the visible chat history, tears down the upstream ACP session for the affected key, and clears the streaming state. The caller then re-sends the edited text through the normal send path. The next prompt the model sees was issued against a fresh session, with the truncated conversation reconstructed via the priorContext preamble path.

There is a real fidelity caveat here, called out in the function’s comment at lines 1796 to 1799: the preamble is text-only (no tool calls, no thinking blocks) and capped to roughly 20 turns. A tool-heavy conversation that gets truncated and resumed will diverge somewhat from one that ran continuously, because the model sees a summary of past tool work rather than the raw turn-by-turn record. That cost is the price of having a non-head branching primitive at all: the SDK does not natively support resuming mid-transcript, so something has to be discarded.

What this means if you are building on Claude Code, Codex, or any agent SDK

One: do not write a state-blob checkpointer. The SDK already has one, on disk, and you cannot beat its fidelity because it is fed from the inside of the tool-dispatch loop. Use the JSONL transcript as your durable representation. Address it by upstream session ID.

Two: own a stable client-side identity for each conversation. Do not treat the upstream ID as identity. Maintain an append-only chain of every upstream ID the conversation has held. Bound the chain so it does not grow without limit on a long-lived conversation. Reset only on explicit user actions.

Three: branch via the SDK’s native primitive. For ACP that is session/fork, accessed through the Claude Agent SDK as unstable_forkSession. For Codex via ACP it is the same call against codex-acp. Do not copy prompt history into a new session, because you will pay the prompt-caching penalty on every fork and your branches will be perceptibly slower than the source.

Four: accept that mid-transcript branching is a separate problem. The SDK does not natively branch from arbitrary positions in the JSONL, only from the head of a live session. If you need edit-and-resubmit, you are buying truncation plus a capped preamble replay, and you should be honest with the user about the fidelity tradeoff (especially on tool-heavy conversations).