~/.claude/projects/ im lokalen Dateisystem. Ein SessionStore-Adapter ermöglicht es Ihnen, diese Transkripte in Ihrem eigenen Backend zu spiegeln, z. B. in einem Objektspeicher, einem Key-Value-Store oder einer Datenbank, sodass eine auf einem Host erstellte Sitzung auf einem anderen Host mit einem übereinstimmenden Arbeitsverzeichnis 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 Replikaten, die Sitzungen voneinander fortzusetzen.
- Dauerhaftigkeit. Lokale Container sind kurzlebig. Ein externer Store ü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 vier 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.
Da projectKey das Arbeitsverzeichnis kodiert, müssen Sie zum Fortsetzen oder Fortfahren aus dem Speicher aus einem Arbeitsverzeichnis arbeiten, das dem ursprünglichen Lauf entspricht. In TypeScript können Sie, wenn Sie CLAUDE_CODE_PROJECT_DIR_NAME neben CLAUDE_CONFIG_DIR in der env-Option einer Abfrage setzen, das SDK diese Abfrage und ihre resume- und continue-Lookups nach diesem Namen statt nach dem Arbeitsverzeichnis schlüsseln. Da eigenständige Hilfsfunktionen wie listSessions und deleteSession kein env annehmen und die Prozessumgebung lesen, setzen Sie CLAUDE_CONFIG_DIR und denselben Namen auch in der Host-Prozessumgebung. Erfordert Agent SDK v0.3.234 oder später.
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.
In einem
SessionSummaryEntry ist mtime die Speicherschreibzeit des Sidecars und muss eine Zeitquelle mit den mtime-Werten teilen, die listSessions zurückgibt. data ist ein undurchsichtiger, vom SDK verwalteter Zustand; speichern Sie ihn wörtlich, ohne ihn zu interpretieren.
Erstellen Sie die Einträge, indem Sie die exportierte foldSessionSummary-Hilfsfunktion, fold_session_summary in Python, auf jeden Batch in append aufrufen. Überspringen Sie Batches, deren Schlüssel einen subpath hat; Subagent-Transkripte dürfen nicht zur Zusammenfassung der Hauptsitzung beitragen. Die Fold setzt mtime nie: Stempeln Sie es zur Persistierungszeit durch das options.mtime-Argument in TypeScript oder durch Überschreiben des Feldes auf dem zurückgegebenen Eintrag in Python. Gleichzeitige append-Aufrufe für dieselbe Sitzung können beim Sidecar konkurrieren, daher serialisieren Sie das Lesen-Fold-Schreiben mit einer Transaktion, einem Compare-and-Swap oder einem Pro-Sitzungs-Lock; die Fold selbst ist rein.
Für das, was das SDK mit dem Transkript macht, das load zurückgibt, siehe Aus dem Speicher fortsetzen.
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, listSessionSummaries, delete und listSubkeys hinzu, wenn Sie möchten, dass listSessions(), Metadaten-Lesevorgänge mit einem Aufruf, 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, die Objektschlüssel neu ordnen, wie eine binäre JSON-Spaltentyp, in Ordnung.
Referenzimplementierungen
Beide SDK-Repositories enthalten ausführbare Referenz-Adapter unterexamples/session-stores/ in TypeScript und examples/session_stores/ in Python. Es gibt einen Adapter pro Speichertyp, und jeder zeigt, wie append und load auf diese Art von Backend abgebildet werden. Sie werden nicht als Pakete veröffentlicht; kopieren Sie den Adapter für den Typ, der Ihrem Backend am nächsten kommt, in Ihr Projekt, installieren Sie den Client Ihres Backends, und passen Sie ihn an.
Jeder Adapter nimmt eine vorkonfigurierte Client-Instanz an, sodass Sie Anmeldedaten, TLS, Region und Pooling kontrollieren. Das folgende Beispiel verbindet den Objektspeicher-Adapter mit
query() und setzt dann auf einem anderen Host fort:
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. Um sie mit pytest auszuführen, das keine SDK-Abhängigkeit ist, installieren Sie zuerst pytest:
run_session_store_conformance einmal pro Vertrag aufruft, um einen neuen Store zu erstellen:
Python
MyRedisStore-Klasse selbst, wie in diesem Beispiel, funktioniert, wenn der Konstruktor keine Argumente benötigt. Für einen Adapter, der einen vorkonfigurierten Client benötigt, übergeben Sie stattdessen ein Lambda, das den Store konstruiert. Da die Verträge dieselben Sitzungsschlüssel wiederverwenden, muss jeder Store, den die Fabrik zurückgibt, mit leerem Speicher beginnen. Lassen Sie das Lambda daher isolierten Speicher pro Aufruf bereitstellen, z. B. einen neuen speicherinternen Fake, ein eindeutiges Schlüsselpräfix oder eine neue Test-Datenbank.
Verhaltenshinweise
Dual-Write-Architektur
Der Claude Code-Subprozess schreibt immer zuerst jeden Batch von Transkripteinträgen auf die lokale Festplatte, und das SDK leitet dann denselben Batch an dieappend()-Funktion Ihres Stores weiter, sodass der Store ein Spiegel des lokalen Transkripts ist und nicht dessen Ersatz. Welche Kopie den Durchlauf überlebt, hängt davon ab, wie der Durchlauf gestartet wurde:
- Neue Sitzung oder Wiederaufnahme, wenn der Store nichts für die Sitzung hat: Das lokale Transkript in Ihrem Konfigurationsverzeichnis überlebt den Durchlauf, und der Store erhält eine Kopie.
- Durchlauf vom Store wiederaufgenommen: Die lokale Kopie wird am Ende des Durchlaufs gelöscht, sodass der Store die einzige dauerhafte Kopie enthält.
CLAUDE_CONFIG_DIR in options.env auf ein temporäres Verzeichnis. Ein Durchlauf, der vom Store wiederaufgenommen wird, löscht bereits seine lokale Kopie, benötigt also keine solche Einstellung. In TypeScript müssen Sie auch process.env in env verteilen, da die env-Option die Subprozessumgebung ersetzt.
Wenn sich Ihre App über Dateien im Konfigurationsverzeichnis anmeldet, z. B. OAuth-Anmeldedaten oder ein apiKeyHelper in Ihrer Benutzer-settings.json, kopieren Sie diese Dateien zuerst in das temporäre Verzeichnis, oder setzen Sie stattdessen ANTHROPIC_API_KEY in env. Andernfalls schlägt der Durchlauf mit Not logged in fehl.
Zwei Optionen stehen in Konflikt mit dem Spiegel, und das SDK wirft beim Start einen Fehler, wenn Sie eine davon mit einem Store kombinieren:
persistSession: falsein TypeScript: Deaktiviert die lokalen Schreibvorgänge, auf denen der Spiegel aufgebaut ist. Das Python SDK hat keine entsprechende Option.- Datei-Checkpointing,
enableFileCheckpointingin TypeScript oderenable_file_checkpointingin Python: Schreibt seine Datei-Backups direkt auf die lokale Festplatte, und das SDK spiegelt sie nicht zum Store.
Vom Store wiederaufnehmen
Wenn Sieresume oder continue: true in TypeScript oder continue_conversation=True in Python zusammen mit einem Store übergeben, fragt das SDK den Store nach einem Transkript, bevor es den Subprozess startet:
resume: Das SDK fragt nach der Sitzung, deren ID Sie übergeben haben.continue: trueodercontinue_conversation=True: Das SDK fragt nach der neuesten Sitzung des Stores.
CLAUDE_CONFIG_DIR aus, das dort zeigt, und löscht das Verzeichnis, wenn der Durchlauf endet. Das lokale Transkript, das dieser Durchlauf schreibt, wird mit ihm gelöscht, weshalb der Store auf diesem Pfad die einzige dauerhafte Kopie enthält.
Das SDK startet auch das temporäre Verzeichnis mit Dateien aus Ihrem echten Konfigurationsverzeichnis. Was kopiert wird, unterscheidet sich je nach Sprache:
- TypeScript: Anmeldedaten,
.claude.jsonund Ihre Benutzer-settings.json. Aussettings.jsonentfernt es die Schlüssel, die sich unter einem temporären Konfigurationsverzeichnis nicht richtig verhalten:enabledPlugins,extraKnownMarketplaces, seinadditionalMarketplaces-Alias und alleCLAUDE_CONFIG_DIRimenv-Block der Datei. Vor Agent SDK v0.3.232 entfernte das SDK den Alias nicht. Die in den Einstellungen konfigurierte Authentifizierung, z. B.apiKeyHelper, funktioniert, wenn Sie vom Store wiederaufnehmen. Vor Agent SDK v0.3.222 kopierte das TypeScript SDK nur Anmeldedaten und.claude.json. - Python: Nur Anmeldedaten und
.claude.json, daher schlägt eine App, die sich überapiKeyHelperin Ihrer Benutzer-settings.jsonauthentifiziert, mitNot logged infehl, wenn sie vom Store wiederaufgenommen wird. EinapiKeyHelperin verwalteten oder Projekteinstellungen funktioniert immer noch, da Claude Code diese Dateien von Speicherorten liest, dieCLAUDE_CONFIG_DIRnicht beeinflusst.
resume: Beide SDKs übergeben die ID an den Subprozess, der das lokale Transkript genau wieresumeohne Store wiederaufnimmt.continue: truein TypeScript: Das SDK startet eine neue Sitzung.continue_conversation=Truein Python: Das SDK setzt die neueste lokale Sitzung fort.
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, protokolliert das SDK den Fehler, gibt eine { type: "system", subtype: "mirror_error" }-Nachricht in den Iterator aus, verwirft den Batch und setzt die Abfrage fort. Da ein erneut versuchter Batch Einträge, die bereits angekommen sind, erneut bereitstellen kann, deduplizieren Sie nach entry.uuid in Ihrer append()-Implementierung.
Ein Store-Ausfall unterbricht den Agenten nicht, da der Subprozess zuerst lokal schreibt. Überwachen Sie auf mirror_error, wenn Sie Datenverluste im Store erkennen müssen. Bei einem Durchlauf, der vom Store wiederaufgenommen wird, hat ein verworfener Batch keine überlebende Kopie, sobald der Durchlauf endet.
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: verwenden Sie die Ablauf- oder Lebenszyklusmechanismen Ihres Backends oder führen Sie geplante Bereinigung gemäß Ihren Compliance-Anforderungen durch. Lokale Transkripte unterCLAUDE_CONFIG_DIR werden unabhängig durch die cleanupPeriodDays-Einstellung bereinigt, nach den Aufbewahrungssweep-Regeln. Ein Durchlauf, der vom Store wiederaufgenommen wird, hinterlässt kein lokales Transkript, daher ist für diese Durchläufe die Aufbewahrung Ihres Stores die einzige Aufbewahrung, die es gibt.
Unterstützt auf
Die folgenden TypeScript 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()
session_store in ClaudeAgentOptions, um query() gegen einen Store auszuführen. Die verbleibenden Operationen haben jeweils eine Store-gestützte Python-Funktion, die den Store als Argument akzeptiert: 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() und fork_session_via_store(). startup() hat kein Python-Äquivalent. Die eigenständigen Funktionen, die in der Python SDK-Referenz dokumentiert sind, wie list_sessions(), lesen lokale Sitzungsdateien.
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 - Referenzimplementierungen: Ausführbare Beispieladapter für einen Objektspeicher, einen Schlüssel-Wert-Speicher und eine Datenbank in beiden SDK-Repositories