~/.claude/projects/ pada sistem file lokal. Adaptor SessionStore memungkinkan Anda mencerminkan transkrip tersebut ke backend Anda sendiri, seperti S3, Redis, atau database, sehingga sesi yang dibuat di satu host dapat dilanjutkan di host lain.
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 apa pun melanjutkan sesi apa pun.
- Daya tahan. Kontainer lokal bersifat sementara. Penyimpanan yang didukung oleh S3 atau database 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 tiga 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. 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.
| Metode | Diperlukan | Dipanggil ketika |
|---|---|---|
append | Ya | Setelah setiap batch entri transkrip ditulis secara lokal. Entri adalah objek yang aman JSON, satu per baris dalam JSONL lokal. |
load | Ya | Sekali sebelum subprocess spawn, ketika resume diatur. Kembalikan null jika sesi tidak dikenal. |
listSessions | Tidak | Oleh listSessions({ sessionStore }) dan oleh query()/startup() dengan continue: true. Jika tidak ditentukan, panggilan tersebut melempar. |
delete | Tidak | Oleh deleteSession({ sessionStore }). Menghapus kunci utama (tanpa subpath) harus cascade ke semua subkey untuk sesi itu. Jika tidak ditentukan, penghapusan adalah no-op, yang cocok untuk backend append-only. |
listSubkeys | Tidak | Selama resume, untuk menemukan transkrip subagent. Jika tidak ditentukan, hanya transkrip utama yang dipulihkan. |
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, delete, dan listSubkeys jika Anda ingin listSessions(), 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 seperti Postgres jsonb yang mengurutkan ulang kunci objek tidak masalah.
Implementasi referensi
Repositori TypeScript SDK mencakup adaptor referensi yang dapat dijalankan untuk S3, Redis, dan Postgres di bawahexamples/session-stores/. Mereka tidak dipublikasikan ke npm; salin file src/ yang Anda butuhkan ke proyek Anda dan instal klien backend yang sesuai.
| Adaptor | Klien backend | Model penyimpanan |
|---|---|---|
S3SessionStore | @aws-sdk/client-s3 | Satu file bagian JSONL per append(); load() mencantumkan, mengurutkan, dan menggabungkan. |
RedisSessionStore | ioredis | RPUSH/LRANGE list per transkrip, ditambah indeks sorted-set sesi. |
PostgresSessionStore | pg | Satu baris per entri dalam tabel jsonb, diurutkan oleh BIGSERIAL. |
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:
Python
Catatan perilaku
Arsitektur dual-write
Penyimpanan adalah cerminan, bukan pengganti. Subprocess Claude Code selalu menulis ke disk lokal terlebih dahulu; SDK kemudian meneruskan setiap batch keappend(). Jika Anda ingin salinan lokal bersifat sementara, arahkan CLAUDE_CONFIG_DIR ke direktori temp di options.env. Karena cerminan bergantung pada penulisan lokal, sessionStore tidak dapat digabungkan dengan persistSession: false; SDK melempar jika Anda menetapkan keduanya. Ini juga melempar jika digabungkan dengan enableFileCheckpointing, karena blob cadangan riwayat file ditulis langsung ke disk lokal dan tidak dicerminkan ke penyimpanan.
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, kesalahan dicatat, pesan { type: "system", subtype: "mirror_error" } dipancarkan ke iterator, batch dijatuhkan, dan kueri berlanjut. Transkrip lokal sudah tahan lama di disk, jadi pemadaman penyimpanan tidak mengganggu agen atau kehilangan data secara lokal. Pantau mirror_error jika Anda perlu mendeteksi kehilangan data penyimpanan. Karena batch yang dicoba ulang dapat mengirimkan ulang entri yang sudah mendarat, deduplikasi berdasarkan entry.uuid dalam implementasi append() Anda.
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: implementasikan TTL, kebijakan lifecycle S3, atau pembersihan terjadwal sesuai dengan persyaratan kepatuhan Anda. Transkrip lokal di bawahCLAUDE_CONFIG_DIR disapu secara independen oleh pengaturan cleanupPeriodDays.
Didukung pada
Fungsi SDK berikut menerima opsisessionStore dan beroperasi terhadap penyimpanan daripada sistem file lokal ketika disediakan:
query()startup()listSessions()getSessionInfo()getSessionMessages()renameSession()tagSession()deleteSession()forkSession()listSubagents()getSubagentMessages()
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 examples/session-stores/: Adaptor referensi S3, Redis, dan Postgres yang dapat dijalankan