~/.claude/projects/ pada sistem file lokal. Adaptor SessionStore memungkinkan Anda mencerminkan transkrip tersebut ke backend Anda sendiri, seperti object store, key-value store, atau database, sehingga sesi yang dibuat di satu host dapat dilanjutkan di host lain yang menjalankan dari direktori kerja yang cocok.
Alasan umum untuk menggunakan session store:
- Penerapan multi-host. Fungsi serverless, pekerja yang diskalakan otomatis, dan runner CI tidak berbagi sistem file. Penyimpanan bersama memungkinkan replika melanjutkan sesi satu sama lain.
- Daya tahan. Kontainer lokal bersifat sementara. Penyimpanan eksternal bertahan melalui restart dan redeploy.
- Kepatuhan dan audit. Simpan transkrip dalam penyimpanan yang sudah Anda kelola, dengan aturan retensi, enkripsi, dan kontrol akses Anda sendiri.
Antarmuka SessionStore
SessionStore adalah objek dengan dua metode yang diperlukan, append dan load, serta empat metode opsional. SDK memanggil append untuk menulis entri transkrip selama kueri dan load untuk membacanya kembali untuk resume.
SessionKey mengatasi satu transkrip. projectKey adalah pengkodean stabil dan aman sistem file dari direktori kerja, sessionId adalah UUID sesi, dan subpath diatur ketika entri milik transkrip subagent atau file sidecar daripada percakapan utama.
Karena projectKey mengkodekan direktori kerja, resume atau lanjutkan dari toko dari direktori kerja yang cocok dengan run asli. Di TypeScript, jika Anda menetapkan CLAUDE_CODE_PROJECT_DIR_NAME di samping CLAUDE_CONFIG_DIR dalam opsi env kueri, SDK menentukan kunci entri kueri itu, dan pencarian resume dan continue miliknya, dengan nama itu sebagai gantinya. Karena pembantu mandiri seperti listSessions dan deleteSession tidak mengambil env dan membaca lingkungan proses, atur CLAUDE_CONFIG_DIR dan nama yang sama di lingkungan proses host juga. Memerlukan Agent SDK v0.3.234 atau lebih baru.
Perlakukan subpath sebagai sufiks kunci yang tidak transparan; ini mengikuti tata letak on-disk, misalnya subagents/agent-<id>. Ketika subpath tidak ditentukan, kunci merujuk ke transkrip utama.
Dalam
SessionSummaryEntry, mtime adalah waktu penulisan penyimpanan sidecar dan harus berbagi sumber jam dengan nilai mtime yang dikembalikan listSessions. data adalah status SDK-owned yang tidak transparan; pertahankan secara verbatim tanpa menginterpretasinya.
Bangun entri dengan memanggil pembantu foldSessionSummary yang diekspor, fold_session_summary di Python, pada setiap batch di dalam append. Lewati batch yang kuncinya memiliki subpath; transkrip subagent tidak boleh berkontribusi pada ringkasan sesi utama. Fold tidak pernah menetapkan mtime: cap pada waktu persist, melalui argumen options.mtime di TypeScript atau dengan menimpa field pada entri yang dikembalikan di Python. Panggilan append bersamaan untuk sesi yang sama dapat race pada sidecar, jadi serialisasi read-fold-write dengan transaksi, compare-and-swap, atau per-session lock; fold itu sendiri adalah pure.
Untuk apa yang dilakukan SDK dengan transkrip load yang dikembalikan, lihat Resume dari toko.
Mulai cepat
SDK mengirimkanInMemorySessionStore untuk pengembangan dan pengujian. Contoh di bawah menjalankan kueri dengan penyimpanan yang terpasang, menangkap ID sesi dari pesan hasil, kemudian melanjutkan dari penyimpanan dalam panggilan query() kedua. Panggilan kedua melewatkan instance penyimpanan yang sama ditambah resume, sehingga SDK memuat transkrip dari penyimpanan daripada sistem file lokal:
Tulis adaptor Anda sendiri
Implementasikanappend dan load terhadap backend Anda. Tambahkan listSessions, listSessionSummaries, delete, dan listSubkeys jika Anda ingin listSessions(), pembacaan metadata satu panggilan, deleteSession(), dan subagent resume bekerja terhadap penyimpanan.
Entri yang dilewatkan ke append diketik sebagai SessionStoreEntry (objek { type: string; ... }). Perlakukan mereka sebagai nilai yang aman JSON yang tidak transparan: simpan dalam urutan dan kembalikan dari load dalam urutan yang sama. load harus mengembalikan entri yang deep-equal dengan apa yang ditambahkan; serialisasi byte-equal tidak diperlukan, jadi backend yang mengurutkan ulang kunci objek, seperti tipe kolom JSON biner, tidak masalah.
Implementasi referensi
Kedua repositori SDK mencakup adaptor referensi yang dapat dijalankan di bawahexamples/session-stores/ dalam TypeScript dan examples/session_stores/ dalam Python. Ada satu adaptor per jenis penyimpanan, dan masing-masing menunjukkan bagaimana append dan load memetakan ke jenis backend tersebut. Mereka tidak dipublikasikan sebagai paket; salin adaptor untuk jenis yang paling dekat dengan backend Anda ke dalam proyek Anda, instal klien backend Anda, dan sesuaikan.
Setiap adaptor mengambil instance klien yang telah dikonfigurasi sebelumnya, sehingga Anda mengontrol kredensial, TLS, region, dan pooling. Contoh berikut menghubungkan adaptor object-store ke
query() dan kemudian melanjutkan darinya di host lain:
TypeScript
Validasi adaptor Anda
Kedua SDK mengirimkan suite conformance yang menegaskan kontrak perilakuappend, load, dan metode opsional harus memuaskan. Tes untuk metode opsional melewati secara otomatis ketika metode tersebut tidak diimplementasikan.
Di TypeScript, salin shared/conformance.ts dari direktori contoh ke dalam suite pengujian Anda. Di Python, suite dikirimkan dalam paket. Untuk menjalankannya dengan pytest, yang bukan merupakan dependensi SDK, instal pytest terlebih dahulu:
run_session_store_conformance panggil sekali per kontrak untuk membangun toko yang segar:
Python
MyRedisStore itu sendiri, seperti yang dilakukan contoh ini, berfungsi ketika konstruktor tidak mengambil argumen. Untuk adaptor yang mengambil klien yang telah dikonfigurasi sebelumnya, teruskan lambda yang membangun toko sebagai gantinya. Karena kontrak menggunakan kembali kunci sesi yang sama, setiap toko yang dikembalikan factory harus dimulai dengan penyimpanan kosong, jadi buat lambda menyediakan penyimpanan backing terisolasi per panggilan, seperti fake in-memory yang segar, prefix kunci unik, atau database pengujian baru.
Catatan perilaku
Arsitektur dual-write
Subprocess Claude Code selalu menulis setiap batch entri transkrip ke disk lokal terlebih dahulu, dan SDK kemudian meneruskan batch yang sama keappend() penyimpanan Anda, sehingga penyimpanan adalah cerminan dari transkrip lokal daripada pengganti untuknya. Salinan mana yang bertahan dari run tergantung pada bagaimana run dimulai:
- Sesi segar, atau resume ketika penyimpanan tidak memiliki apa pun untuk sesi: transkrip lokal di bawah direktori konfigurasi Anda bertahan dari run, dan penyimpanan menerima salinan.
- Run dilanjutkan dari penyimpanan: salinan lokal dihapus di akhir run, sehingga penyimpanan menyimpan satu-satunya salinan yang tahan lama.
CLAUDE_CONFIG_DIR ke direktori temp di options.env. Run yang dilanjutkan dari penyimpanan sudah menghapus salinan lokalnya, jadi tidak memerlukan pengaturan seperti itu. Di TypeScript, sebarkan process.env ke env juga, karena opsi env menggantikan lingkungan subprocess.
Jika aplikasi Anda masuk melalui file di direktori konfigurasi, seperti kredensial OAuth atau apiKeyHelper di settings.json pengguna Anda, salin file-file tersebut ke direktori temp terlebih dahulu, atau atur ANTHROPIC_API_KEY di env sebagai gantinya. Jika tidak, run gagal dengan Not logged in.
Dua opsi bertentangan dengan cerminan, dan SDK melempar pada startup jika Anda menggabungkan salah satu dengan penyimpanan:
persistSession: falsedi TypeScript: mematikan penulisan lokal yang dibangun cerminan. Python SDK tidak memiliki opsi yang setara.- File checkpointing,
enableFileCheckpointingdi TypeScript atauenable_file_checkpointingdi Python: menulis cadangan file langsung ke disk lokal, dan SDK tidak mencerminkannya ke penyimpanan.
Resume dari penyimpanan
Ketika Anda melewatkanresume, atau continue: true di TypeScript atau continue_conversation=True di Python, bersama dengan penyimpanan, SDK meminta transkrip dari penyimpanan sebelum ia menelurkan subprocess:
resume: SDK meminta sesi yang ID-nya Anda lewatkan.continue: trueataucontinue_conversation=True: SDK meminta sesi terbaru penyimpanan.
CLAUDE_CONFIG_DIR menunjuk ke sana, dan menghapus direktori ketika run berakhir. Transkrip lokal yang run itu tulis dihapus bersama dengannya, itulah mengapa penyimpanan menyimpan satu-satunya salinan yang tahan lama di jalur ini.
SDK juga menyemai direktori sementara dengan file dari direktori konfigurasi nyata Anda. Apa yang disalinnya berbeda menurut bahasa:
- TypeScript: kredensial,
.claude.json, dansettings.jsonpengguna Anda. Darisettings.jsonia menghilangkan kunci yang berperilaku buruk di bawah direktori konfigurasi sementara:enabledPlugins,extraKnownMarketplaces, aliasadditionalMarketplaces-nya, danCLAUDE_CONFIG_DIRapa pun di blokenvfile. Sebelum Agent SDK v0.3.232, SDK tidak menghilangkan alias. Auth yang dikonfigurasi dalam pengaturan, sepertiapiKeyHelper, bekerja ketika Anda resume dari penyimpanan. Sebelum Agent SDK v0.3.222, TypeScript SDK hanya menyalin kredensial dan.claude.json. - Python: kredensial dan
.claude.jsonsaja, jadi aplikasi yang mengautentikasi melaluiapiKeyHelperdisettings.jsonpengguna Anda gagal denganNot logged inketika resume dari penyimpanan.apiKeyHelperdalam pengaturan terkelola atau proyek masih bekerja, karena Claude Code membaca file-file tersebut dari lokasi yang tidak dipengaruhi olehCLAUDE_CONFIG_DIR.
resume: kedua SDK melewatkan ID melalui ke subprocess, yang melanjutkan transkrip lokal persis sepertiresumetanpa penyimpanan.continue: truedi TypeScript: SDK memulai sesi segar.continue_conversation=Truedi Python: SDK melanjutkan dari sesi lokal terbaru.
Penulisan cerminan adalah best-effort
Jikaappend() menolak, SDK mencoba ulang batch hingga dua kali lagi dengan backoff singkat, untuk maksimal tiga percobaan total. Panggilan yang timeout tidak dicoba ulang, karena panggilan asli mungkin masih mendarat. Jika batch masih gagal, SDK mencatat kesalahan, memancarkan pesan { type: "system", subtype: "mirror_error" } ke iterator, menjatuhkan batch, dan melanjutkan kueri. Karena batch yang dicoba ulang dapat mengirimkan ulang entri yang sudah mendarat, deduplikasi berdasarkan entry.uuid dalam implementasi append() Anda.
Pemadaman penyimpanan tidak mengganggu agen, karena subprocess menulis lokal terlebih dahulu. Pantau mirror_error jika Anda perlu mendeteksi kehilangan data penyimpanan. Pada run dilanjutkan dari penyimpanan, batch yang dijatuhkan tidak memiliki salinan yang bertahan setelah run berakhir.
getSessionMessages mengembalikan rantai post-compaction
getSessionMessages({ sessionStore }) mengembalikan rantai pesan tertaut yang akan dilihat agen pada resume. Setelah auto-compaction, giliran sebelumnya diganti dengan ringkasan, jadi sesi yang penyimpanannya menyimpan 503 entri mentah dapat mengembalikan 18 pesan dari getSessionMessages. Untuk riwayat mentah lengkap, termasuk giliran pre-compaction dan entri metadata, panggil store.load(key) secara langsung.
forkSession bukan salinan byte
forkSession({ sessionStore }) membaca entri sumber, menulis ulang setiap bidang sessionId dan memetakan ulang UUID pesan, kemudian menambahkan entri yang ditransformasi di bawah kunci baru. Salinan tingkat adaptor atau shortcut CopyObject akan menghasilkan transkrip yang masih mereferensikan ID sesi lama, jadi SDK tidak menggunakannya.
Transkrip subagent
Transkrip subagent dicerminkan di bawahsubpath: "subagents/agent-<id>". listSubagents({ sessionStore }) memerlukan adaptor untuk mengimplementasikan listSubkeys; getSubagentMessages({ sessionStore }) menggunakannya ketika tersedia tetapi kembali ke subpath langsung ketika tidak ditentukan. Resume juga memanggil listSubkeys untuk memulihkan file subagent; tanpanya, hanya transkrip utama yang dimaterialisasi.
Retensi
SDK tidak pernah menghapus dari penyimpanan Anda sendiri. Retensi adalah tanggung jawab adaptor: gunakan mekanisme kedaluwarsa atau lifecycle backend Anda, atau jalankan pembersihan terjadwal, sesuai dengan persyaratan kepatuhan Anda. Transkrip lokal di bawahCLAUDE_CONFIG_DIR disapu secara independen oleh pengaturan cleanupPeriodDays, mengikuti aturan penyapuan retensi. Run dilanjutkan dari penyimpanan tidak meninggalkan transkrip lokal, jadi untuk run tersebut retensi penyimpanan Anda adalah satu-satunya retensi yang ada.
Didukung pada
Fungsi SDK TypeScript berikut menerima opsisessionStore dan beroperasi terhadap penyimpanan daripada sistem file lokal ketika disediakan:
query()startup()listSessions()getSessionInfo()getSessionMessages()renameSession()tagSession()deleteSession()forkSession()listSubagents()getSubagentMessages()
session_store dalam ClaudeAgentOptions untuk menjalankan query() terhadap penyimpanan. Operasi yang tersisa masing-masing memiliki fungsi Python yang didukung penyimpanan yang mengambil penyimpanan sebagai argumen: 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(), dan fork_session_via_store(). startup() tidak memiliki padanan Python. Fungsi mandiri yang didokumentasikan dalam referensi SDK Python, seperti list_sessions(), membaca file sesi lokal.
Sumber daya terkait
- Bekerja dengan sesi: Lanjutkan, resume, dan fork tanpa penyimpanan kustom
- Host SDK: Pola penerapan untuk lingkungan multi-host
- TypeScript
Options: Referensi opsi lengkap - Implementasi referensi: Adaptor contoh yang dapat dijalankan untuk penyimpanan objek, penyimpanan kunci-nilai, dan basis data, di kedua repositori SDK