Persist sessions to external storage changedagent-sdk/session-storage
Upstream edited this page at 10 Oct 2026 17:34 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+20added
Lines−20removed
From line
82
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits11to this page, all time
The whole hunk
from line 82, old and new numbered
/
from line 82
8282
8383`SessionKey` addresses one transcript. `projectKey` is a stable, filesystem-safe encoding of the working directory, `sessionId` is the session UUID, and `subpath` is set when the entry belongs to a subagent transcript or sidecar file rather than the main conversation.
8484
85Because `projectKey` encodes the working directory, resume or continue from the store from a working directory matching the original run's. In TypeScript, if you set [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/en/sessions#name-the-project-directory-yourself) beside `CLAUDE_CONFIG_DIR` in a query's [`env` option](/docs/en/agent-sdk/typescript#options), the SDK keys that query's entries, and its `resume` and `continue` lookups, by that name instead. Because standalone helpers such as `listSessions` and `deleteSession` take no `env` and read the process environment, set `CLAUDE_CONFIG_DIR` and the same name in the host process environment too. Requires Agent SDK v0.3.234 or later.
85Because `projectKey` encodes the working directory, resume or continue from the store from a working directory matching the original run's. In TypeScript, if you set [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/en/sessions#name-the-project-directory-yourself) beside `CLAUDE_CONFIG_DIR` in a query's [`env` option](https://code.claude.com/docs/en/agent-sdk/typescript#options), the SDK keys that query's entries, and its `resume` and `continue` lookups, by that name instead. Because standalone helpers such as `listSessions` and `deleteSession` take no `env` and read the process environment, set `CLAUDE_CONFIG_DIR` and the same name in the host process environment too. Requires Agent SDK v0.3.234 or later.
8686
8787Treat `subpath` as an opaque key suffix; it follows the on-disk layout, for example `subagents/agent-<id>`. When `subpath` is undefined the key refers to the main transcript.
8888
from line 259
259259* **Fresh session, or a resume when the store has nothing for the session**: the local transcript under your config directory outlives the run, and the store receives a copy.
260260* **Run [resumed from the store](#resume-from-the-store)**: the local copy is deleted at run end, so the store holds the only durable copy.
261261
262If you don't want a fresh session to leave a transcript on local disk, set `CLAUDE_CONFIG_DIR` to a temp directory in `options.env`. A run resumed from the store already deletes its local copy, so it needs no such setting. In TypeScript, spread `process.env` into `env` as well, since the [`env` option](/docs/en/agent-sdk/typescript#options) replaces the subprocess environment.
262If you don't want a fresh session to leave a transcript on local disk, set `CLAUDE_CONFIG_DIR` to a temp directory in `options.env`. A run resumed from the store already deletes its local copy, so it needs no such setting. In TypeScript, spread `process.env` into `env` as well, since the [`env` option](https://code.claude.com/docs/en/agent-sdk/typescript#options) replaces the subprocess environment.
263263
264264If your app signs in through files in the config directory, such as OAuth credentials or an `apiKeyHelper` in your user `settings.json`, copy those files into the temp directory first, or set `ANTHROPIC_API_KEY` in `env` instead. Otherwise the run fails with `Not logged in`.
265265
from line 279
279279
280280The SDK also seeds the temporary directory with files from your real config directory. What it copies differs by language:
281281
282* **TypeScript**: credentials, `.claude.json`, and your user `settings.json`. From `settings.json` it strips the keys that misbehave under a temporary config directory: `enabledPlugins`, `extraKnownMarketplaces`, its [`additionalMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) alias, and any `CLAUDE_CONFIG_DIR` in the file's `env` block. Before Agent SDK v0.3.232, the SDK didn't strip the alias. Auth configured in settings, such as [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper), works when you resume from the store. Before Agent SDK v0.3.222, the TypeScript SDK copied only credentials and `.claude.json`.
282* **TypeScript**: credentials, `.claude.json`, and your user `settings.json`. From `settings.json` it strips the keys that misbehave under a temporary config directory: `enabledPlugins`, `extraKnownMarketplaces`, its [`additionalMarketplaces`](https://code.claude.com/docs/en/settings-reference#extraknownmarketplaces) alias, and any `CLAUDE_CONFIG_DIR` in the file's `env` block. Before Agent SDK v0.3.232, the SDK didn't strip the alias. Auth configured in settings, such as [`apiKeyHelper`](https://code.claude.com/docs/en/settings-reference#apikeyhelper), works when you resume from the store. Before Agent SDK v0.3.222, the TypeScript SDK copied only credentials and `.claude.json`.
283283* **Python**: credentials and `.claude.json` only, so an app that authenticates through `apiKeyHelper` in your user `settings.json` fails with `Not logged in` when resuming from a store. An `apiKeyHelper` in managed or project settings still works, because Claude Code reads those files from locations that `CLAUDE_CONFIG_DIR` doesn't affect.
284284
285285When the store has nothing for the session, the SDK runs under your real config directory instead, and the outcome depends on which option you passed:
from line 310
310310
311311The SDK never deletes from your store on its own. Retention is the adapter's responsibility: use your backend's expiry or lifecycle mechanism, or run scheduled cleanup, according to your compliance requirements.
312312
313Local transcripts under `CLAUDE_CONFIG_DIR` are swept independently by the `cleanupPeriodDays` setting, following the [retention sweep rules](/docs/en/claude-directory.md#cleaned-up-automatically). A run [resumed from the store](#resume-from-the-store) leaves no local transcript, so for those runs your store's retention is the only retention there is.
313Local transcripts under `CLAUDE_CONFIG_DIR` are swept independently by the `cleanupPeriodDays` setting, following the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically). A run [resumed from the store](#resume-from-the-store) leaves no local transcript, so for those runs your store's retention is the only retention there is.
314314
315315## Supported on
316316
317317The following TypeScript SDK functions accept a `sessionStore` option and operate against the store instead of the local filesystem when it is provided:
318318
319* [`query()`](/docs/en/agent-sdk/typescript#query)
320* [`startup()`](/docs/en/agent-sdk/typescript#startup)
321* [`listSessions()`](/docs/en/agent-sdk/typescript#listsessions)
322* [`getSessionInfo()`](/docs/en/agent-sdk/typescript#getsessioninfo)
323* [`getSessionMessages()`](/docs/en/agent-sdk/typescript#getsessionmessages)
324* [`renameSession()`](/docs/en/agent-sdk/typescript#renamesession)
325* [`tagSession()`](/docs/en/agent-sdk/typescript#tagsession)
326* [`deleteSession()`](/docs/en/agent-sdk/typescript)
327* [`forkSession()`](/docs/en/agent-sdk/typescript#forksession)
328* [`listSubagents()`](/docs/en/agent-sdk/typescript)
329* [`getSubagentMessages()`](/docs/en/agent-sdk/typescript)
319* [`query()`](https://code.claude.com/docs/en/agent-sdk/typescript#query)
320* [`startup()`](https://code.claude.com/docs/en/agent-sdk/typescript#startup)
321* [`listSessions()`](https://code.claude.com/docs/en/agent-sdk/typescript#listsessions)
322* [`getSessionInfo()`](https://code.claude.com/docs/en/agent-sdk/typescript#getsessioninfo)
323* [`getSessionMessages()`](https://code.claude.com/docs/en/agent-sdk/typescript#getsessionmessages)
324* [`renameSession()`](https://code.claude.com/docs/en/agent-sdk/typescript#renamesession)
325* [`tagSession()`](https://code.claude.com/docs/en/agent-sdk/typescript#tagsession)
326* [`deleteSession()`](https://code.claude.com/docs/en/agent-sdk/typescript)
327* [`forkSession()`](https://code.claude.com/docs/en/agent-sdk/typescript#forksession)
328* [`listSubagents()`](https://code.claude.com/docs/en/agent-sdk/typescript)
329* [`getSubagentMessages()`](https://code.claude.com/docs/en/agent-sdk/typescript)
330330
331In the Python SDK, set `session_store` in [`ClaudeAgentOptions`](/docs/en/agent-sdk/python#claudeagentoptions) to run `query()` against a store. The remaining operations each have a store-backed Python function that takes the store as an argument: `list_sessions_from_store()`, `get_session_info_from_store()`, `get_session_messages_from_store()`, `list_subagents_from_store()`, `get_subagent_messages_from_store()`, `rename_session_via_store()`, `tag_session_via_store()`, `delete_session_via_store()`, and `fork_session_via_store()`. `startup()` has no Python equivalent. The standalone functions documented in the [Python SDK reference](/docs/en/agent-sdk/python.md#functions), such as `list_sessions()`, read local session files.
331In the Python SDK, set `session_store` in [`ClaudeAgentOptions`](https://code.claude.com/docs/en/agent-sdk/python#claudeagentoptions) to run `query()` against a store. The remaining operations each have a store-backed Python function that takes the store as an argument: `list_sessions_from_store()`, `get_session_info_from_store()`, `get_session_messages_from_store()`, `list_subagents_from_store()`, `get_subagent_messages_from_store()`, `rename_session_via_store()`, `tag_session_via_store()`, `delete_session_via_store()`, and `fork_session_via_store()`. `startup()` has no Python equivalent. The standalone functions documented in the [Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md#functions), such as `list_sessions()`, read local session files.
332332
333333## Related resources
334334
335* [Work with sessions](/docs/en/agent-sdk/sessions.md): Continue, resume, and fork without a custom store
336* [Host the SDK](/docs/en/agent-sdk/hosting.md): Deployment patterns for multi-host environments
337* [TypeScript `Options`](/docs/en/agent-sdk/typescript#options): Full option reference
335* [Work with sessions](https://code.claude.com/docs/en/agent-sdk/sessions.md): Continue, resume, and fork without a custom store
336* [Host the SDK](https://code.claude.com/docs/en/agent-sdk/hosting.md): Deployment patterns for multi-host environments
337* [TypeScript `Options`](https://code.claude.com/docs/en/agent-sdk/typescript#options): Full option reference
338338* [Reference implementations](#reference-implementations): Runnable example adapters for an object store, a key-value store, and a database, in both SDK repositories
339339
No line in this hunk matches that.