Claude Agent SDK Session Persistence: External Store Design

An external transcript store needs a stable key, ordered append, load, retention, and concurrency behavior. The following is illustrative application code—not a claim that every SDK release exports this exact interface:

1type SessionKey = { projectKey: string; sessionId: string };2type TranscriptEntry = { id: string; createdAt: string; payload: unknown };3 4type TranscriptStore = {5  append(key: SessionKey, entries: TranscriptEntry[]): Promise<void>;6  load(key: SessionKey): Promise<TranscriptEntry[]>;7};

A project identifier should be stable across workers without exposing a raw filesystem path. A session identifier must be unguessable, and every append needs an idempotency key or sequence number so retries cannot duplicate transcript entries. Validate the real SDK contract separately before wiring this abstraction into query().

These are implementation patterns, not provider-supplied adapters. S3 works well for append-as-objects and long retention, but listing and ordering parts adds complexity. Redis supports fast list operations, but memory pressure, persistence configuration, and eviction policy become part of correctness. PostgreSQL makes ordering, uniqueness, and transactional writes explicit, but transcript growth requires indexing and retention jobs.

Choose based on the recovery requirement rather than a universal speed ranking. A transcript that must survive a worker restart needs durable writes and a replay test; a short-lived development session may only need an in-memory implementation.

A worker can write locally and mirror asynchronously, write to the external store before acknowledging progress, or use a queue between execution and persistence. Asynchronous mirroring preserves responsiveness but can lose the latest entries; synchronous persistence improves durability but makes storage outages visible in the agent path.

A resume flow should load the transcript, verify its schema and ordering, establish credentials separately, and record a new append checkpoint. Do not assume that an SDK automatically creates or cleans a temporary configuration directory unless the versioned documentation says so.

Build a local contract suite for ordering, retries, duplicate delivery, malformed entries, tenant isolation, and deletion. A successful happy-path resume proves very little if two workers can append the same turn or a deleted tenant can still load it.

Retention is part of the data contract. Define deletion, export, legal-hold, and encryption behavior for S3 lifecycle rules, Redis TTLs, or scheduled SQL cleanup. Record failures with enough metadata to replay safely without logging secrets or full prompts.

Implement the small TranscriptStore interface from the first section with an in-memory map. Append two entries, load them in order, then retry the second append with the same entry ID. Your store should keep one copy.

Add a schema-version field and reject an entry with an unsupported version. This practice proves ordered session resumption and idempotency under retry conditions.

Testing Durability Under Retries

The practice exercise validates two guarantees that matter in production: first, that entries are stored in append order and loaded in that same order (proving session replay is safe), and second, that retrying an append with the same idempotency key does not duplicate the entry. These constraints seem obvious in theory, but in distributed systems they require explicit testing. Start with the happy path (two appends, one load), then deliberately introduce failure scenarios: retry the same append twice, attempt to load with an invalid key, append an entry with an unsupported schema version. Each test should either pass cleanly (idempotent append, ordered load) or fail with a clear error (invalid schema), never silently succeeding or corrupting state.