~/.claude/projects/ im lokalen Dateisystem. Ein SessionStore-Adapter ermöglicht es Ihnen, diese Transkripte in Ihrem eigenen Backend zu spiegeln, z. B. in S3, Redis oder einer Datenbank, sodass eine auf einem Host erstellte Sitzung auf einem anderen Host fortgesetzt werden kann.
Häufige Gründe für die Verwendung eines Session Store:
- Multi-Host-Bereitstellungen. Serverlose Funktionen, automatisch skalierte Worker und CI-Runner teilen sich kein Dateisystem. Ein gemeinsamer Store ermöglicht es jedem Replikat, jede Sitzung fortzusetzen.
- Dauerhaftigkeit. Lokale Container sind kurzlebig. Ein Store, der von S3 oder einer Datenbank unterstützt wird, übersteht Neustarts und Neubereitstellungen.
- Compliance und Audit. Bewahren Sie Transkripte in Speicher auf, den Sie bereits kontrollieren, mit Ihren eigenen Aufbewahrungsrichtlinien, Verschlüsselung und Zugriffskontrolle.
Die SessionStore-Schnittstelle
Ein SessionStore ist ein Objekt mit zwei erforderlichen Methoden, append und load, und drei optionalen Methoden. Das SDK ruft append auf, um Transkripteinträge während einer Abfrage zu schreiben, und load, um sie zum Fortsetzen zurückzulesen.
SessionKey adressiert ein Transkript. projectKey ist eine stabile, dateisystemsichere Kodierung des Arbeitsverzeichnisses, sessionId ist die Sitzungs-UUID, und subpath wird gesetzt, wenn der Eintrag zu einem Subagent-Transkript oder einer Sidecar-Datei statt zur Hauptkonversation gehört. Behandeln Sie subpath als einen undurchsichtigen Schlüsselsuffix; er folgt dem On-Disk-Layout, z. B. subagents/agent-<id>. Wenn subpath nicht definiert ist, bezieht sich der Schlüssel auf das Haupttranskript.
Schnellstart
Das SDK wird mit einemInMemorySessionStore für Entwicklung und Tests ausgeliefert. Das folgende Beispiel führt eine Abfrage mit dem angehängten Store aus, erfasst die Sitzungs-ID aus der Ergebnismeldung und setzt dann aus dem Store in einem zweiten query()-Aufruf fort. Der zweite Aufruf übergibt die gleiche Store-Instanz plus resume, sodass das SDK das Transkript aus dem Store statt aus dem lokalen Dateisystem lädt:
Schreiben Sie Ihren eigenen Adapter
Implementieren Sieappend und load gegen Ihr Backend. Fügen Sie listSessions, delete und listSubkeys hinzu, wenn Sie möchten, dass listSessions(), deleteSession() und Subagent-Wiederaufnahme gegen den Store funktionieren.
Einträge, die an append übergeben werden, sind als SessionStoreEntry typisiert (ein { type: string; ... }-Objekt). Behandeln Sie sie als undurchsichtige JSON-sichere Werte: persistieren Sie sie in Reihenfolge und geben Sie sie von load in der gleichen Reihenfolge zurück. load muss Einträge zurückgeben, die tiefengleich mit dem sind, was angehängt wurde; Byte-gleiche Serialisierung ist nicht erforderlich, daher sind Backends wie Postgres jsonb, die Objektschlüssel neu ordnen, in Ordnung.
Referenzimplementierungen
Das TypeScript SDK-Repository enthält ausführbare Referenz-Adapter für S3, Redis und Postgres unterexamples/session-stores/. Sie werden nicht auf npm veröffentlicht; kopieren Sie die src/-Datei, die Sie benötigen, in Ihr Projekt und installieren Sie den entsprechenden Backend-Client.
Jeder Adapter nimmt eine vorkonfigurierte Client-Instanz an, sodass Sie Anmeldedaten, TLS, Region und Pooling kontrollieren. Zum Beispiel mit S3:
TypeScript
Validieren Sie Ihren Adapter
Beide SDKs werden mit einer Konformitätssuite ausgeliefert, die den Verhaltensvertrag durchsetzt, denappend, load und die optionalen Methoden erfüllen müssen. Tests für optionale Methoden werden automatisch übersprungen, wenn diese Methoden nicht implementiert sind.
In TypeScript kopieren Sie shared/conformance.ts aus dem Beispielverzeichnis in Ihre Test-Suite. In Python wird die Suite im Paket ausgeliefert:
Python
Verhaltenshinweise
Dual-Write-Architektur
Der Store ist ein Spiegel, kein Ersatz. Der Claude Code-Subprozess schreibt immer zuerst auf die lokale Festplatte; das SDK leitet dann jeden Batch anappend() weiter. Wenn Sie möchten, dass die lokale Kopie kurzlebig ist, zeigen Sie CLAUDE_CONFIG_DIR auf ein temporäres Verzeichnis in options.env. Da der Spiegel von lokalen Schreibvorgängen abhängt, kann sessionStore nicht mit persistSession: false kombiniert werden; das SDK wirft einen Fehler, wenn Sie beide setzen. Es wirft auch einen Fehler, wenn es mit enableFileCheckpointing kombiniert wird, da Dateihistorie-Backup-Blobs direkt auf die lokale Festplatte geschrieben werden und nicht zum Store gespiegelt werden.
Spiegelschreibvorgänge sind Best-Effort
Wennappend() ablehnt, versucht das SDK den Batch bis zu zwei weitere Male mit kurzer Backoff-Zeit erneut, insgesamt höchstens drei Versuche. Ein Aufruf, der eine Zeitüberschreitung aufweist, wird nicht erneut versucht, da der ursprüngliche Aufruf möglicherweise noch ankommt. Wenn der Batch immer noch fehlschlägt, wird der Fehler protokolliert, eine { type: "system", subtype: "mirror_error" }-Meldung wird in den Iterator ausgegeben, der Batch wird verworfen, und die Abfrage wird fortgesetzt. Das lokale Transkript ist bereits auf der Festplatte dauerhaft, daher unterbricht ein Store-Ausfall den Agenten nicht und verliert keine Daten lokal. Überwachen Sie auf mirror_error, wenn Sie Datenverluste im Store erkennen müssen. Da ein erneut versuchter Batch Einträge, die bereits angekommen sind, erneut bereitstellen kann, deduplizieren Sie nach entry.uuid in Ihrer append()-Implementierung.
getSessionMessages gibt die Post-Komprimierungs-Kette zurück
getSessionMessages({ sessionStore }) gibt die verknüpfte Nachrichtenkette zurück, die der Agent beim Wiederaufnehmen sehen würde. Nach der automatischen Komprimierung werden frühere Umdrehungen durch eine Zusammenfassung ersetzt, daher kann eine Sitzung, deren Store 503 rohe Einträge enthält, 18 Nachrichten von getSessionMessages zurückgeben. Für die vollständige Rohhistorie, einschließlich Pre-Komprimierungs-Umdrehungen und Metadateneinträge, rufen Sie store.load(key) direkt auf.
forkSession ist keine Byte-Kopie
forkSession({ sessionStore }) liest die Quelleinträge, schreibt jedes sessionId-Feld um und ordnet Nachrichten-UUIDs neu zu, dann hängt die transformierten Einträge unter einem neuen Schlüssel an. Eine Adapter-Ebenen-Kopie oder CopyObject-Verknüpfung würde ein Transkript erzeugen, das immer noch auf die alte Sitzungs-ID verweist, daher verwendet das SDK keine.
Subagent-Transkripte
Subagent-Transkripte werden untersubpath: "subagents/agent-<id>" gespiegelt. listSubagents({ sessionStore }) erfordert, dass der Adapter listSubkeys implementiert; getSubagentMessages({ sessionStore }) verwendet es, wenn verfügbar, fällt aber auf den direkten Subpath zurück, wenn er nicht definiert ist. Das Wiederaufnehmen ruft auch listSubkeys auf, um Subagent-Dateien wiederherzustellen; ohne es wird nur das Haupttranskript materialisiert.
Aufbewahrung
Das SDK löscht niemals von selbst aus Ihrem Store. Die Aufbewahrung ist die Verantwortung des Adapters: implementieren Sie TTLs, S3-Lebenszyklusrichtlinien oder geplante Bereinigung gemäß Ihren Compliance-Anforderungen. Lokale Transkripte unterCLAUDE_CONFIG_DIR werden unabhängig durch die cleanupPeriodDays-Einstellung bereinigt.
Unterstützt auf
Die folgenden SDK-Funktionen akzeptieren einesessionStore-Option und arbeiten gegen den Store statt gegen das lokale Dateisystem, wenn es bereitgestellt wird:
query()startup()listSessions()getSessionInfo()getSessionMessages()renameSession()tagSession()deleteSession()forkSession()listSubagents()getSubagentMessages()
Verwandte Ressourcen
- Mit Sitzungen arbeiten: Fortsetzen, Wiederaufnehmen und Forken ohne einen benutzerdefinierten Store
- Das SDK hosten: Bereitstellungsmuster für Multi-Host-Umgebungen
- TypeScript
Options: Vollständige Optionsreferenz examples/session-stores/: Ausführbare S3-, Redis- und Postgres-Referenz-Adapter