跳轉到主要內容
默認情況下,SDK 將會話記錄寫入本地文件系統上 ~/.claude/projects/ 下的 JSONL 文件。SessionStore 適配器允許您將這些記錄鏡像到您自己的後端,例如 S3、Redis 或數據庫,以便在一個主機上創建的會話可以在另一個主機上恢復。 使用會話存儲的常見原因:
  • 多主機部署。 無服務器函數、自動擴展的工作進程和 CI 運行器不共享文件系統。共享存儲允許任何副本恢復任何會話。
  • 耐久性。 本地容器是短暫的。由 S3 或數據庫支持的存儲可以在重新啟動和重新部署後存活。
  • 合規性和審計。 將記錄保存在您已經管理的存儲中,使用您自己的保留規則、加密和訪問控制。

SessionStore 介面

SessionStore 是一個物件,具有兩個必需的方法 appendload,以及三個可選方法。SDK 呼叫 append 在查詢期間寫入記錄項目,呼叫 load 讀取它們以進行恢復。
SessionKey 指向一個記錄。projectKey 是工作目錄的穩定、檔案系統安全的編碼,sessionId 是工作階段 UUID,subpath 在項目屬於子代理記錄或邊車檔案而不是主對話時設定。將 subpath 視為不透明的鍵後綴;它遵循磁碟上的配置,例如 subagents/agent-<id>。當 subpath 未定義時,鍵指向主記錄。

快速開始

SDK 附帶一個 InMemorySessionStore 用於開發和測試。下面的示例使用附加的存儲運行查詢,從結果消息中捕獲會話 ID,然後在第二個 query() 呼叫中從存儲恢復。第二個呼叫傳遞相同的存儲實例加上 resume,因此 SDK 從存儲而不是本地檔案系統載入記錄:
第二個查詢會列印來自第一個查詢的檔案摘要,這表明代理已從存儲恢復並具有完整的上下文。

編寫您自己的適配器

針對您的後端實現 appendload。如果您希望 listSessions()deleteSession() 和子代理恢復針對存儲工作,請添加 listSessionsdeletelistSubkeys 傳遞給 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 指向臨時目錄。因為鏡像依賴於本地寫入,sessionStore 不能與 persistSession: false 結合;如果您同時設置兩者,SDK 會拋出異常。如果與 enableFileCheckpointing 結合,它也會拋出異常,因為文件歷史備份 blob 直接寫入本地磁盤,不會鏡像到存儲。

鏡像寫入是盡力而為

如果 append() 拒絕,SDK 會以短暫的退避重試該批次最多兩次,總共最多三次嘗試。超時的呼叫不會重試,因為原始呼叫可能仍然會到達。如果批次仍然失敗,錯誤被記錄,一個 { 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 }) 要求適配器實現 listSubkeysgetSubagentMessages({ sessionStore }) 在可用時使用它,但在未定義時回退到直接子路徑。恢復也調用 listSubkeys 來恢復子代理文件;沒有它,只有主記錄被物化。

保留

SDK 永遠不會自行從您的存儲中刪除。保留是適配器的責任:根據您的合規要求實現 TTL、S3 生命週期策略或計劃清理。CLAUDE_CONFIG_DIR 下的本地記錄由 cleanupPeriodDays 設置獨立清掃。

支持於

以下 SDK 函數接受 sessionStore 選項,當提供時針對存儲而不是本地文件系統運行: