The Claude Agent SDK is a library: the agent loop runs in your process, on your infrastructure, and — crucially for this article — its session state lives as JSONL files on your filesystem. JSONL ("JSON Lines") is simply a text file with one JSON object per line, which makes an agent transcript something you can read, grep, back up, and retain under your own policies. This is a deliberate contrast with Anthropic's hosted Managed Agents product, where sessions and their histories are stored server-side on Anthropic's infrastructure. With the SDK, continuity is a feature of your disk.
Where the session_id comes from
Every SDK session has an identity from its first moments. When you call query(), the first thing the stream yields is an init system message, and that message carries a session_id. If you want continuity, capturing this ID is the one thing your application must do — it is the handle for everything that follows.
from claude_agent_sdk import query
session_id = None
async for message in query(prompt="Start the quarterly data cleanup"):
if getattr(message, "subtype", None) == "init":
session_id = message.data.get("session_id") # save this
print(message)
# persist session_id somewhere durable (db row, job record, env of a CI step)Resume: pick up exactly where you left off
Passing resume=session_id on a later query() call continues the session with its full context — the conversation history, what the agent already read, what it decided, what it tried. For enterprise workflows this changes the shape of what an agent can be. A migration agent can process part of a backlog, stop, and be re-invoked by a scheduler tonight without re-explaining anything. A ticket-handling agent can wait for a human reply and resume with the entire investigation intact.
Because the state is a local file rather than an opaque server-side object, resume also survives your process. Restart the machine, redeploy the service, come back next week: as long as the JSONL files are there, the session is there.
Fork: two futures from one past
Forking takes the same mechanism in a different direction: instead of continuing a session, you branch it, exploring two approaches from the same starting point. The docs describe this as forking a session to explore different approaches — the shared history up to the fork is identical, and each branch proceeds independently from there.
This is more useful in practice than it sounds. Suppose an agent has spent significant effort understanding a legacy codebase, and there are two plausible refactoring strategies. Without forking you either commit to one or pay the full context-building cost twice. With forking, the expensive understanding phase is shared and only the divergence is new. The same pattern works for evaluations — run strategy A and strategy B from an identical state and compare outcomes fairly.
What local storage means for governance
Filesystem-backed sessions cut both ways, and your security team should hear both halves. The upside: transcripts never need to leave your environment, retention and deletion are enforced by you, and audit is a file read. The downside: those JSONL files contain everything the agent saw and did — file contents it read, command output, possibly sensitive data — so they deserve the same handling as application logs with secrets in them. Encrypt the volume, scope access, and fold them into your retention schedule deliberately rather than by accident.
On third-party platforms, nothing changes. Whether the model calls go to Amazon Bedrock (CLAUDE_CODE_USE_BEDROCK=1), Google Cloud (CLAUDE_CODE_USE_VERTEX=1), Microsoft Foundry (CLAUDE_CODE_USE_FOUNDRY=1), or Claude Platform on AWS (CLAUDE_CODE_USE_ANTHROPIC_AWS=1), session persistence is a client-side concern and works identically — one of the reasons the Agent SDK is the documented agent path on all four 3P surfaces.
Where to go next
Layer safety onto long-lived sessions with lifecycle hooks and the permission model, and compare this self-hosted model with server-side sessions in Managed Agents sessions and Agent SDK vs Managed Agents.