~/.claude/projects/ nel filesystem locale. Un adattatore SessionStore consente di eseguire il mirroring di questi trascritti nel vostro backend, come S3, Redis o un database, in modo che una sessione creata su un host possa essere ripresa su un altro.
Motivi comuni per utilizzare un session store:
- Distribuzioni multi-host. Le funzioni serverless, i worker con scalabilità automatica e i runner CI non condividono un filesystem. Un store condiviso consente a qualsiasi replica di riprendere qualsiasi sessione.
- Durabilità. I container locali sono effimeri. Uno store supportato da S3 o da un database sopravvive ai riavvii e ai ridistribuzioni.
- Conformità e audit. Mantenete i trascritti nell’archiviazione che già controllate, con le vostre regole di conservazione, crittografia e controlli di accesso.
L’interfaccia SessionStore
Un SessionStore è un oggetto con due metodi obbligatori, append e load, e tre metodi facoltativi. L’SDK chiama append per scrivere le voci di trascritto durante una query e load per leggerle di nuovo per la ripresa.
SessionKey indirizza un trascritto. projectKey è una codifica stabile e sicura per il filesystem della directory di lavoro, sessionId è l’UUID della sessione, e subpath è impostato quando la voce appartiene a un trascritto di subagent o a un file sidecar piuttosto che alla conversazione principale. Trattate subpath come una chiave suffisso opaca; segue il layout su disco, ad esempio subagents/agent-<id>. Quando subpath non è definito, la chiave si riferisce al trascritto principale.
Avvio rapido
L’SDK fornisce unInMemorySessionStore per lo sviluppo e i test. L’esempio seguente esegue una query con lo store allegato, acquisisce l’ID della sessione dal messaggio di risultato, quindi riprende dallo store in una seconda chiamata query(). La seconda chiamata passa la stessa istanza dello store più resume, in modo che l’SDK carichi il trascritto dallo store invece dal filesystem locale:
Scrivere il vostro adattatore
Implementateappend e load rispetto al vostro backend. Aggiungete listSessions, delete e listSubkeys se desiderate che listSessions(), deleteSession() e la ripresa dei subagent funzionino rispetto allo store.
Le voci passate a append sono digitate come SessionStoreEntry (un oggetto { type: string; ... }). Trattate le come valori JSON-safe opachi: persistetele in ordine e restituitetele da load nello stesso ordine. load deve restituire voci che siano deep-equal a quelle aggiunte; la serializzazione byte-equal non è richiesta, quindi i backend come Postgres jsonb che riordinano le chiavi degli oggetti vanno bene.
Implementazioni di riferimento
Il repository TypeScript SDK include adattatori di riferimento eseguibili per S3, Redis e Postgres inexamples/session-stores/. Non sono pubblicati su npm; copiate il file src/ di cui avete bisogno nel vostro progetto e installate il client backend corrispondente.
Ogni adattatore accetta un’istanza client preconfigurata, in modo che controlliate le credenziali, TLS, la regione e il pooling. Ad esempio, con S3:
TypeScript
Convalidare il vostro adattatore
Entrambi gli SDK forniscono una suite di conformità che asserisce il contratto comportamentale cheappend, load e i metodi facoltativi devono soddisfare. I test per i metodi facoltativi vengono saltati automaticamente quando questi metodi non sono implementati.
In TypeScript, copiate shared/conformance.ts dalla directory di esempio nella vostra suite di test. In Python, la suite è fornita nel pacchetto:
Python
Note sul comportamento
Architettura a doppia scrittura
Lo store è un mirror, non una sostituzione. Il subprocess Claude Code scrive sempre su disco locale per primo; l’SDK quindi invia ogni batch aappend(). Se desiderate che la copia locale sia effimera, puntate CLAUDE_CONFIG_DIR a una directory temporanea in options.env. Poiché il mirror dipende dalle scritture locali, sessionStore non può essere combinato con persistSession: false; l’SDK genera un’eccezione se impostate entrambi. Genera anche un’eccezione se combinato con enableFileCheckpointing, poiché i blob di backup della cronologia dei file vengono scritti direttamente su disco locale e non vengono sottoposti a mirroring nello store.
Le scritture mirror sono best-effort
Seappend() rifiuta, l’SDK ritenta il batch fino a due volte in più con un breve backoff, per un massimo di tre tentativi in totale. Una chiamata che scade non viene ritentata, poiché la chiamata originale potrebbe comunque arrivare. Se il batch continua a fallire, l’errore viene registrato, un messaggio { type: "system", subtype: "mirror_error" } viene emesso nell’iteratore, il batch viene scartato e la query continua. Il trascritto locale è già durevole su disco, quindi un’interruzione dello store non interrompe l’agente o perde dati localmente. Monitorate mirror_error se dovete rilevare la perdita di dati dello store. Poiché un batch ritentato può ri-consegnare voci che hanno già raggiunto la destinazione, deduplicare per entry.uuid nella vostra implementazione di append().
getSessionMessages restituisce la catena post-compattazione
getSessionMessages({ sessionStore }) restituisce la catena di messaggi collegati che l’agente vedrebbe al momento della ripresa. Dopo la compattazione automatica, i turni precedenti vengono sostituiti da un riepilogo, quindi una sessione il cui store contiene 503 voci grezze può restituire 18 messaggi da getSessionMessages. Per la cronologia grezza completa, inclusi i turni pre-compattazione e le voci di metadati, chiamate store.load(key) direttamente.
forkSession non è una copia byte
forkSession({ sessionStore }) legge le voci di origine, riscrive ogni campo sessionId e rimappa gli UUID dei messaggi, quindi aggiunge le voci trasformate sotto una nuova chiave. Una copia a livello di adattatore o un collegamento CopyObject produrrebbe un trascritto che fa ancora riferimento all’ID della sessione precedente, quindi l’SDK non ne utilizza uno.
Trascritti dei subagent
I trascritti dei subagent vengono sottoposti a mirroring insubpath: "subagents/agent-<id>". listSubagents({ sessionStore }) richiede che l’adattatore implementi listSubkeys; getSubagentMessages({ sessionStore }) lo utilizza quando disponibile ma ricade al subpath diretto quando non è definito. La ripresa chiama anche listSubkeys per ripristinare i file dei subagent; senza di esso, viene materializzato solo il trascritto principale.
Conservazione
L’SDK non elimina mai dal vostro store di sua iniziativa. La conservazione è responsabilità dell’adattatore: implementate TTL, politiche del ciclo di vita S3 o pulizia pianificata secondo i vostri requisiti di conformità. I trascritti locali inCLAUDE_CONFIG_DIR vengono puliti indipendentemente dall’impostazione cleanupPeriodDays.
Supportato su
Le seguenti funzioni SDK accettano un’opzionesessionStore e operano rispetto allo store invece del filesystem locale quando viene fornita:
query()startup()listSessions()getSessionInfo()getSessionMessages()renameSession()tagSession()deleteSession()forkSession()listSubagents()getSubagentMessages()
Risorse correlate
- Lavorare con le sessioni: Continuare, riprendere e fare un fork senza uno store personalizzato
- Ospitare l’SDK: Modelli di distribuzione per ambienti multi-host
- TypeScript
Options: Riferimento completo delle opzioni examples/session-stores/: Adattatori di riferimento S3, Redis e Postgres eseguibili