~/.claude/projects/ sur le système de fichiers local. Un adaptateur SessionStore vous permet de mettre en miroir ces transcriptions vers votre propre backend, tel que S3, Redis ou une base de données, afin qu’une session créée sur un hôte puisse être reprise sur un autre.
Raisons courantes d’utiliser un magasin de sessions :
- Déploiements multi-hôtes. Les fonctions serverless, les workers autoscalés et les exécuteurs CI ne partagent pas de système de fichiers. Un magasin partagé permet à n’importe quel réplica de reprendre n’importe quelle session.
- Durabilité. Les conteneurs locaux sont éphémères. Un magasin sauvegardé par S3 ou une base de données survit aux redémarrages et aux redéploiements.
- Conformité et audit. Conservez les transcriptions dans un stockage que vous gouvernez déjà, avec vos propres règles de rétention, chiffrement et contrôles d’accès.
L’interface SessionStore
Un SessionStore est un objet avec deux méthodes requises, append et load, et trois méthodes optionnelles. Le SDK appelle append pour écrire les entrées de transcription lors d’une requête et load pour les relire pour la reprise.
SessionKey adresse une transcription. projectKey est un encodage stable et sûr pour le système de fichiers du répertoire de travail, sessionId est l’UUID de la session, et subpath est défini lorsque l’entrée appartient à une transcription de sous-agent ou à un fichier sidecar plutôt qu’à la conversation principale. Traitez subpath comme un suffixe de clé opaque ; il suit la disposition sur disque, par exemple subagents/agent-<id>. Lorsque subpath n’est pas défini, la clé fait référence à la transcription principale.
Démarrage rapide
Le SDK expédie unInMemorySessionStore pour le développement et les tests. L’exemple ci-dessous exécute une requête avec le magasin attaché, capture l’ID de session du message de résultat, puis reprend à partir du magasin dans un deuxième appel query(). Le deuxième appel transmet la même instance de magasin plus resume, afin que le SDK charge la transcription à partir du magasin au lieu du système de fichiers local :
Écrivez votre propre adaptateur
Implémentezappend et load par rapport à votre backend. Ajoutez listSessions, delete et listSubkeys si vous voulez que listSessions(), deleteSession() et la reprise de sous-agent fonctionnent par rapport au magasin.
Les entrées transmises à append sont typées comme SessionStoreEntry (un objet { type: string; ... }). Traitez-les comme des valeurs JSON-safe opaques : persistez-les dans l’ordre et retournez-les de load dans le même ordre. load doit retourner des entrées qui sont deep-equal à ce qui a été ajouté ; la sérialisation byte-equal n’est pas requise, donc les backends comme Postgres jsonb qui réorganisent les clés d’objet vont bien.
Implémentations de référence
Le référentiel TypeScript SDK inclut des adaptateurs de référence exécutables pour S3, Redis et Postgres sousexamples/session-stores/. Ils ne sont pas publiés sur npm ; copiez le fichier src/ dont vous avez besoin dans votre projet et installez le client backend correspondant.
Chaque adaptateur prend une instance de client préconfigurée, afin que vous contrôliez les identifiants, TLS, la région et le pooling. Par exemple, avec S3 :
TypeScript
Validez votre adaptateur
Les deux SDK expédient une suite de conformité qui affirme le contrat comportemental queappend, load et les méthodes optionnelles doivent satisfaire. Les tests pour les méthodes optionnelles ignorent automatiquement lorsque ces méthodes ne sont pas implémentées.
En TypeScript, copiez shared/conformance.ts du répertoire d’exemples dans votre suite de tests. En Python, la suite est expédiée dans le package :
Python
Notes de comportement
Architecture à double écriture
Le magasin est un miroir, pas un remplacement. Le sous-processus Claude Code écrit toujours d’abord sur le disque local ; le SDK transfère ensuite chaque lot àappend(). Si vous voulez que la copie locale soit éphémère, pointez CLAUDE_CONFIG_DIR vers un répertoire temporaire dans options.env. Parce que le miroir dépend des écritures locales, sessionStore ne peut pas être combiné avec persistSession: false ; le SDK lève une exception si vous définissez les deux. Il lève également une exception s’il est combiné avec enableFileCheckpointing, car les blobs de sauvegarde de l’historique des fichiers sont écrits directement sur le disque local et ne sont pas mis en miroir vers le magasin.
Les écritures en miroir sont au mieux
Siappend() rejette, le SDK réessaie le lot jusqu’à deux fois supplémentaires avec un délai court, pour un maximum de trois tentatives au total. Un appel qui expire n’est pas réessayé, car l’appel original peut toujours aboutir. Si le lot échoue toujours, l’erreur est enregistrée, un message { type: "system", subtype: "mirror_error" } est émis dans l’itérateur, le lot est supprimé, et la requête continue. La transcription locale est déjà durable sur disque, donc une panne du magasin n’interrompt pas l’agent ou ne perd pas de données localement. Surveillez mirror_error si vous devez détecter une perte de données du magasin. Parce qu’un lot réessayé peut redélivrer des entrées qui ont déjà abouti, dédupliquez par entry.uuid dans votre implémentation de append().
getSessionMessages retourne la chaîne post-compaction
getSessionMessages({ sessionStore }) retourne la chaîne de messages liée que l’agent verrait à la reprise. Après la compaction automatique, les tours antérieurs sont remplacés par un résumé, donc une session dont le magasin contient 503 entrées brutes peut retourner 18 messages de getSessionMessages. Pour l’historique brut complet, y compris les tours pré-compaction et les entrées de métadonnées, appelez store.load(key) directement.
forkSession n’est pas une copie byte
forkSession({ sessionStore }) lit les entrées source, réécrit chaque champ sessionId et remapte les UUID de message, puis ajoute les entrées transformées sous une nouvelle clé. Une copie au niveau de l’adaptateur ou un raccourci CopyObject produirait une transcription qui référence toujours l’ancien ID de session, donc le SDK n’en utilise pas.
Transcriptions de sous-agents
Les transcriptions de sous-agents sont mises en miroir soussubpath: "subagents/agent-<id>". listSubagents({ sessionStore }) nécessite que l’adaptateur implémente listSubkeys ; getSubagentMessages({ sessionStore }) l’utilise quand disponible mais revient au subpath direct quand il n’est pas défini. La reprise appelle également listSubkeys pour restaurer les fichiers de sous-agents ; sans cela, seule la transcription principale est matérialisée.
Rétention
Le SDK ne supprime jamais de votre magasin de son propre chef. La rétention est la responsabilité de l’adaptateur : implémentez des TTL, des politiques de cycle de vie S3 ou un nettoyage programmé selon vos exigences de conformité. Les transcriptions locales sousCLAUDE_CONFIG_DIR sont balayées indépendamment par le paramètre cleanupPeriodDays.
Supporté sur
Les fonctions SDK suivantes acceptent une optionsessionStore et opèrent par rapport au magasin au lieu du système de fichiers local quand elle est fournie :
query()startup()listSessions()getSessionInfo()getSessionMessages()renameSession()tagSession()deleteSession()forkSession()listSubagents()getSubagentMessages()
Ressources connexes
- Travailler avec les sessions : Continuer, reprendre et forker sans magasin personnalisé
- Héberger le SDK : Modèles de déploiement pour les environnements multi-hôtes
- TypeScript
Options: Référence complète des options examples/session-stores/: Adaptateurs de référence S3, Redis et Postgres exécutables