メインコンテンツへスキップ
デフォルトでは、SDK はセッションのトランスクリプトを ~/.claude/projects/ 下のローカルファイルシステムの JSONL ファイルに書き込みます。SessionStore アダプターを使用すると、これらのトランスクリプトを S3、Redis、データベースなど独自のバックエンドにミラーリングできるため、あるホストで作成されたセッションを別のホストで再開できます。 セッションストアを使用する一般的な理由:
  • マルチホスト展開。 サーバーレス関数、オートスケーリングワーカー、CI ランナーはファイルシステムを共有しません。共有ストアを使用すると、任意のレプリカが任意のセッションを再開できます。
  • 耐久性。 ローカルコンテナは一時的です。S3 またはデータベースで支援されるストアは、再起動と再デプロイを乗り越えます。
  • コンプライアンスと監査。 既に管理しているストレージにトランスクリプトを保持し、独自の保持ルール、暗号化、アクセス制御を適用できます。

SessionStore インターフェース

SessionStore は、2 つの必須メソッド appendload、および 3 つのオプションメソッドを持つオブジェクトです。SDK は append を呼び出してクエリ中にトランスクリプトエントリを書き込み、load を呼び出して再開用にそれらを読み戻します。
SessionKey は 1 つのトランスクリプトをアドレス指定します。projectKey は作業ディレクトリの安定したファイルシステム安全なエンコーディング、sessionId はセッション UUID、subpath はエントリがサブエージェントトランスクリプトまたはサイドカーファイルではなくメイン会話に属する場合に設定されます。subpath を不透明なキーサフィックスとして扱います。これはオンディスクレイアウトに従います。例えば subagents/agent-<id> です。subpath が未定義の場合、キーはメイントランスクリプトを参照します。

クイックスタート

SDK は開発とテスト用に InMemorySessionStore を提供しています。以下の例は、ストアを接続してクエリを実行し、結果メッセージからセッション ID をキャプチャしてから、2 番目の query() 呼び出しでストアから再開します。2 番目の呼び出しは同じストアインスタンスと resume を渡すため、SDK はローカルファイルシステムではなくストアからトランスクリプトを読み込みます:
2 番目のクエリは最初のクエリのファイルの概要を出力し、エージェントがストアから完全なコンテキストで再開されたことを示しています。

独自のアダプターを作成する

バックエンドに対して appendload を実装します。ストアに対して listSessions()deleteSession()、およびサブエージェント再開を機能させたい場合は、listSessionsdelete、および listSubkeys を追加します。 append に渡されるエントリは SessionStoreEntry として型付けされます({ type: string; ... } オブジェクト)。これらを不透明な JSON セーフ値として扱います。順序を保持して永続化し、load から同じ順序で返します。load は追加されたものと深く等しいエントリを返す必要があります。バイト等しいシリアル化は必須ではないため、Postgres jsonb のようなオブジェクトキーを並べ替えるバックエンドは問題ありません。

リファレンス実装

TypeScript SDK リポジトリには、examples/session-stores/ の下に S3、Redis、Postgres 用の実行可能なリファレンスアダプターが含まれています。これらは npm に公開されていません。必要な src/ ファイルをプロジェクトにコピーし、対応するバックエンドクライアントをインストールしてください。 各アダプターは事前に設定されたクライアントインスタンスを取得するため、認証情報、TLS、リージョン、プーリングを制御できます。例えば、S3 の場合:
TypeScript

アダプターを検証する

両方の SDK は、appendload、およびオプションメソッドが満たす必要がある動作契約をアサートする適合スイートを提供しています。オプションメソッドのテストは、これらのメソッドが実装されていない場合、自動的にスキップされます。 TypeScript では、例ディレクトリから shared/conformance.ts をテストスイートにコピーしてください。Python では、スイートはパッケージに含まれています:
Python

動作に関する注記

デュアルライトアーキテクチャ

ストアはミラーであり、置き換えではありません。Claude Code サブプロセスは常にローカルディスクに最初に書き込みます。SDK はその後、各バッチを append() に転送します。ローカルコピーを一時的にしたい場合は、options.env の一時ディレクトリに CLAUDE_CONFIG_DIR をポイントします。ミラーはローカル書き込みに依存するため、sessionStorepersistSession: false と組み合わせることはできません。両方を設定するとスローされます。また、enableFileCheckpointing と組み合わせることもできません。ファイル履歴バックアップブロブはローカルディスクに直接書き込まれ、ストアにはミラーリングされないためです。

ミラー書き込みはベストエフォート

append() が拒否した場合、SDK は短いバックオフで最大 2 回まで再試行し、合計で最大 3 回の試行を行います。タイムアウトした呼び出しは再試行されません。元の呼び出しがまだ到達する可能性があるためです。バッチがまだ失敗した場合、エラーはログに記録され、{ type: "system", subtype: "mirror_error" } メッセージがイテレータに発行され、バッチは削除され、クエリは続行されます。ローカルトランスクリプトは既にディスク上で耐久性があるため、ストア障害はエージェントを中断したり、ローカルでデータを失ったりしません。ストアデータ損失を検出する必要がある場合は mirror_error を監視してください。再試行されたバッチは既に到達したエントリを再配信できるため、append() 実装で entry.uuid によって重複排除してください。

getSessionMessages は圧縮後のチェーンを返す

getSessionMessages({ sessionStore }) は、エージェントが再開時に見るリンクされたメッセージチェーンを返します。自動圧縮後、以前のターンは概要に置き換えられるため、ストアが 503 個の生エントリを保持するセッションは getSessionMessages から 18 個のメッセージを返す場合があります。圧縮前のターンとメタデータエントリを含む完全な生履歴については、store.load(key) を直接呼び出します。

forkSession はバイトコピーではない

forkSession({ sessionStore }) はソースエントリを読み込み、すべての sessionId フィールドを書き直し、メッセージ UUID を再マップしてから、変換されたエントリを新しいキーの下に追加します。アダプターレベルのコピーまたは CopyObject ショートカットは、古いセッション ID を参照するトランスクリプトを生成するため、SDK はそれを使用しません。

サブエージェントトランスクリプト

サブエージェントトランスクリプトは subpath: "subagents/agent-<id>" の下にミラーリングされます。listSubagents({ sessionStore }) はアダプターが listSubkeys を実装する必要があります。getSubagentMessages({ sessionStore }) は利用可能な場合はそれを使用しますが、未定義の場合は直接サブパスにフォールバックします。再開も listSubkeys を呼び出してサブエージェントファイルを復元します。これがない場合、メイントランスクリプトのみが具体化されます。

保持

SDK は独自の判断でストアから削除することはありません。保持はアダプターの責任です。コンプライアンス要件に従って TTL、S3 ライフサイクルポリシー、またはスケジュール済みクリーンアップを実装します。CLAUDE_CONFIG_DIR の下のローカルトランスクリプトは cleanupPeriodDays 設定によって独立して掃除されます。

サポート対象

以下の SDK 関数は sessionStore オプションを受け入れ、提供されている場合、ローカルファイルシステムではなくストアに対して動作します: