Agentenspeicher verwenden

Managed Agents API-Sitzungen sind standardmäßig kurzlebig. Wenn eine Sitzung endet, geht alles, was der Agent gelernt hat, verloren. Memory Stores ermöglichen es dem Agent, Erkenntnisse über Sitzungen hinweg zu bewahren: Benutzereinstellungen, Projektkonventionen, frühere Fehler und Domänenkontexte.

Übersicht

Ein Memory Store ist eine arbeitsbereichsbezogene Sammlung von Textdokumenten, die für Claude optimiert sind. Wenn ein oder mehrere Memory Stores an eine Sitzung angehängt werden, prüft der Agent die Stores automatisch, bevor er eine Aufgabe startet, und schreibt dauerhafte Erkenntnisse nach Abschluss – ohne zusätzliche Eingabeaufforderungen oder Konfiguration auf Ihrer Seite.

Jedes Memory in einem Store kann direkt über die API oder die Console aufgerufen und bearbeitet werden, was Abstimmung, Import und Export von Memories ermöglicht.

Jede Änderung an einem Memory erstellt eine unveränderliche Memory-Version, um Auditing und Rollback von Memory-Änderungen zu unterstützen.

Erstellen Sie einen Memory Store

Geben Sie dem Store einen name und eine description. Die Beschreibung wird an den Agent weitergeleitet und teilt ihm mit, was der Store enthält.

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

Die Memory Store id (memstore_...) ist das, was Sie beim Anhängen des Stores an eine Sitzung übergeben.

Füllen Sie ihn mit Inhalten (optional)

Laden Sie einen Store vor mit Referenzmaterial, bevor ein Agent läuft:

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

Hängen Sie einen Memory Store an eine Sitzung an

Memory Stores werden im Array resources[] der Sitzung angehängt.

Fügen Sie optional einen prompt ein, wenn Sie Claude sitzungsspezifische Anweisungen zur Verwendung dieses Memory Stores geben möchten. Er wird Claude zusätzlich zum name und description des Memory Stores bereitgestellt und ist auf 4.096 Zeichen begrenzt.

Sie können auch access konfigurieren. Der Standard ist read_write, aber read_only wird auch unterstützt (im Beispiel unten explizit gezeigt).

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

Pro Sitzung werden maximal 8 Memory Stores unterstützt. Hängen Sie mehrere Stores an, wenn verschiedene Teile des Memory unterschiedliche Besitzer oder Zugriffsregeln haben. Häufige Gründe:

• Gemeinsames Referenzmaterial – ein schreibgeschützter Store, der an viele Sitzungen angehängt ist (Standards, Konventionen, Domänenwissen), getrennt von den eigenen Lese-Schreib-Erkenntnissen jeder Sitzung.
• Zuordnung zur Struktur Ihres Produkts – ein Store pro Endbenutzer, pro Team oder pro Projekt, während eine einzelne Agent-Konfiguration gemeinsam genutzt wird.
• Unterschiedliche Lebenszyklen – ein Store, der länger als eine einzelne Sitzung besteht, oder einer, den Sie nach eigenem Zeitplan archivieren möchten.

Memory-Tools

Wenn Memory Stores an eine Sitzung angehängt werden, erhält der Agent automatisch Zugriff auf Memory-Tools. Die Interaktionen des Agenten mit Memory Stores werden als agent.tool_use-Ereignisse im Event-Stream registriert.

Anzeigen und Bearbeiten von Memories

Memory Stores können direkt über die API verwaltet werden. Verwenden Sie dies zum Erstellen von Review-Workflows, zum Korrigieren fehlerhafter Memories oder zum Seeding von Stores vor dem Ausführen einer Sitzung.

Memories auflisten

List gibt keinen Memory-Inhalt zurück, nur Objektmetadaten. Verwenden Sie path_prefix für verzeichnisbezogene Listen (fügen Sie einen nachgestellten Schrägstrich ein: /notes/ entspricht /notes/a.md, aber nicht /notes_backup/old.md).

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

Lesen Sie ein Memory

Das Abrufen eines einzelnen Memory gibt den vollständigen Inhalt zurück.

mem = client.beta.memory_stores.memories.retrieve(
    memory_id,
    memory_store_id=store.id,
)
print(mem.content)

Erstellen Sie ein Memory

Verwenden Sie memories.write, um ein Memory nach Pfad zu erstellen oder zu aktualisieren. Wenn unter dem Pfad nichts vorhanden ist, wird es erstellt; wenn bereits ein Memory vorhanden ist, wird sein Inhalt ersetzt. Um ein vorhandenes Memory nach mem_... ID zu ändern (z. B. um seinen Pfad umzubenennen oder eine Inhaltsbearbeitung sicher anzuwenden), verwenden Sie stattdessen memories.update (siehe Update a memory unten).

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

Sichere Schreibvorgänge (optimistische Parallelität)

Übergeben Sie precondition={"type": "not_exists"} an memories.write, um es zu einer Create-Only-Schutzmaßnahme zu machen. Wenn bereits ein Memory unter dem Pfad vorhanden ist, gibt der Schreibvorgang 409 memory_precondition_failed zurück, anstatt es zu ersetzen. Verwenden Sie dies beim Seeding eines Stores, wenn Sie vermeiden möchten, dass vorhandene Inhalte überschrieben werden.

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

Um ein vorhandenes Memory sicher zu bearbeiten (lesen, ändern, zurückschreiben, ohne eine gleichzeitige Änderung zu überschreiben), verwenden Sie stattdessen memories.update mit einer content_sha256-Vorbedingung. Siehe Update a memory unten.

Aktualisieren Sie ein Memory

memories.update() ändert ein vorhandenes Memory nach seiner mem_... ID. Sie können content, path (eine Umbenennung) oder beides in einem Aufruf ändern.

Das Umbenennen auf einen besetzten Pfad gibt 409 conflict zurück. Der Aufrufer muss den Blocker zuerst löschen oder umbenennen, oder precondition={"type": "not_exists"} übergeben, um die Umbenennung zu einem No-Op zu machen, wenn bereits etwas unter dem Ziel vorhanden ist.

Das folgende Beispiel benennt ein Memory in einen Archivpfad um:

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

Sichere Inhaltsbearbeitungen (optimistische Parallelität)

Um den Inhalt eines Memory zu bearbeiten, ohne eine gleichzeitige Schreiboperation zu überschreiben, übergeben Sie eine content_sha256-Vorbedingung. Das Update wird nur angewendet, wenn der gespeicherte Hash immer noch dem entspricht, den Sie gelesen haben; bei Nichtübereinstimmung gibt es 409 memory_precondition_failed zurück. Zu diesem Zeitpunkt lesen Sie das Memory erneut und versuchen es erneut mit dem aktuellen Status.

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

Löschen Sie ein Memory

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

Übergeben Sie optional expected_content_sha256 für einen bedingten Löschvorgang.

Audit von Memory-Änderungen

Jede Mutation zu einem Memory erstellt eine unveränderliche Memory-Version (memver_...). Versionen sammeln sich über die Lebensdauer des übergeordneten Memory an und bilden die Audit- und Rollback-Oberfläche darunter. Der Live-memories.retrieve-Aufruf gibt immer den aktuellen Head zurück; die Versions-Endpunkte geben Ihnen die vollständige Historie.

Eine neue Version wird bei jeder Mutation geschrieben:

• Der erste memories.write zu einem Pfad erstellt eine Version mit operation: "created".
• memories.update, das content, path oder beides ändert, erstellt eine Version mit operation: "modified".
• memories.delete erstellt eine Version mit operation: "deleted".

Verwenden Sie die Versions-Endpunkte, um zu überprüfen, welcher Benutzer oder Agent was und wann geändert hat, um einen vorherigen Snapshot zu überprüfen oder wiederherzustellen, und um mit Redact sensible Inhalte aus der Historie zu entfernen.

Versionen auflisten

Listet paginierte Versionmetadaten für einen Store auf, neueste zuerst. Filtern Sie nach memory_id, operation (created, modified oder deleted), session_id, api_key_id oder einem created_at_gte/created_at_lte Zeitbereich. Die Listenantwort enthält nicht den content Body; rufen Sie einzelne Versionen mit retrieve ab, wenn Sie den vollständigen Inhalt benötigen.

for v in client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
):
    print(f"{v.id}: {v.operation}")

Eine Version abrufen

Das Abrufen einer einzelnen Version gibt die gleichen Felder wie die Listenantwort plus den vollständigen content Body zurück.

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

Eine Version schwärzen

Schwärzen entfernt Inhalte aus einer historischen Version, während die Audit-Spur erhalten bleibt (wer hat was wann getan). Verwenden Sie es für Compliance-Workflows wie das Entfernen von durchgesickerten Geheimnissen, PII oder Anfragen zur Benutzerlöschung. Schwärzen löscht content, content_sha256, content_size_bytes und path vollständig; alle anderen Felder, einschließlich des Akteurs und der Zeitstempel, bleiben erhalten.

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)