Session State, Persistence and Resumption

The Messages API remembers nothing between requests. Every piece of continuity in a Claude system is something your application, or a harness such as Claude Code, has chosen to store and resend. Architects must therefore decide, for each kind of state, where it lives, how long it survives and how a run picks it up again. The exam tests the layers of state and the mechanisms for resumption at each layer.

Layer 1: the conversation

At the API level, state is the messages array. Your application owns it, appends to it and sends it in full on every call. Persist it if a conversation must survive a process restart; serialise the full content blocks, including tool_use, tool_result and thinking blocks, because the API validates their pairing on replay. Server-side compaction (beta) and context editing can shrink what is sent, but the responsibility for storage remains yours.

Layer 2: harness sessions

Claude Code records each session as a transcript on disk under the user's ~/.claude/projects/ directory, keyed by project path and session ID. Resumption options:

Mechanism	Behaviour
claude --continue (-c)	Reopens the most recent session in the current directory
claude --resume <id> (-r)	Reopens a specific session by ID or from a picker
/resume inside a session	Switch to another saved session
/rewind	Return to an earlier checkpoint in the conversation and, optionally, in the file state

Claude Code checkpoints file changes made through its edit tools during a session, which is what makes /rewind able to restore code as well as conversation. Changes made by shell commands are outside that mechanism; version control remains the safety net.

In the Agent SDK the init system message carries the session_id. Pass it back as resume to continue a run in a later process, or use continue for the latest session in the working directory. A fork option starts a new session that branches from an existing transcript, which is useful for exploring alternatives without disturbing the original.

Layer 3: cross-session memory

Conversation history is the wrong place for facts that must outlive a session. Three mechanisms serve that need:

Project memory files. CLAUDE.md (and .claude/rules/) are loaded at session start and are the canonical place for durable, human-curated instructions: build commands, conventions, architecture notes. Claude Code can also maintain an automatic memory directory per project in which it records its own observations across sessions; check the current documentation for how it is enabled and where it is stored.

The memory tool. At the API level, the Anthropic-defined memory_20250818 tool gives Claude a file-like store it can read and write across conversations. Your application implements the backend (a directory, a database) and the model decides what is worth remembering. Pair it with context editing or compaction so that long-running agents move stable knowledge out of the context and into memory.

Your own store. A database keyed by user or task, injected into the prompt at the start of each session. This is the most controllable option and the only one for state that must be queried or audited outside the model.

Layer 4: external task state

Agents that take hours or run across many sessions need a job record outside any conversation: which subtasks are complete, what artefacts exist, what decisions were made. Managed, server-side agent sessions store this for you; a custom orchestrator writes it to a table or a directory. The transcript is evidence of what happened; it is not a good source of truth for what to do next.

Resuming safely

Resumption raises a question the API cannot answer: were the side effects of the last tool call applied? If a process died between executing a payment and recording the result, replaying the transcript will see a tool_use with no tool_result and may run it again. Defend against this with idempotency keys in tool implementations, by recording tool outcomes before appending them to the transcript, and by checking external state on resume before continuing. Compaction adds a second concern: a summarised history loses detail, so anything a resumed agent must know precisely belongs in a file or memory, not in the summary.

Choosing a layer

State	Where it belongs
The current task's turns	Conversation (messages array or session transcript)
Project conventions and commands	CLAUDE.md, rules files
Facts learned about a user or codebase over time	Memory tool, auto memory or your own store
Progress of a long job	External job record
Secrets	Never in any of the above; environment or a secrets manager

Exam focus

• The API is stateless; the application sends the entire messages array every time and owns its persistence.
• Claude Code sessions resume with --continue (most recent) or --resume (by ID); /rewind restores conversation and tracked file checkpoints.
• The Agent SDK exposes session_id in the init message and accepts resume to continue it.
• CLAUDE.md is for curated, durable instructions; the memory tool and auto memory are for facts the model accumulates; neither replaces an external job record.
• Replaying a transcript can re-execute side effects; tool implementations need idempotency and resume logic must check external state.
• Compacted history is lossy; precise facts a resumed agent needs belong in files or memory.