Agent-Memory verwenden

Jede Managed-Agents-Session startet standardmäßig mit einem frischen Kontext. Wenn eine Session endet, ist jeder Zustand, den der Agent aufgebaut hat, verloren. „Memory stores“ (Gedächtnisspeicher) ermöglichen es dem Agenten, Informationen über Sessions hinweg mitzunehmen: Benutzerpräferenzen, Projektkonventionen, frühere Fehler und Domänenkontext.

Überblick

Ein Memory Store ist eine auf den Workspace beschränkte Sammlung von Textdokumenten, die für Claude optimiert ist. Wenn du einen Store an eine Session anhängst, wird er als Verzeichnis innerhalb der Sandbox der Session eingebunden. Der Agent liest und schreibt ihn mit denselben Datei-Tools, die er für den Rest des Dateisystems verwendet, und eine Notiz, die jeden Mount beschreibt, wird automatisch zum System-Prompt hinzugefügt und teilt dem Agenten mit, wo er nachsehen soll. Das Agent-Toolset ist für diese Interaktionen erforderlich; stelle sicher, dass du es bei der Agent-Erstellung aktivierst. Auf selbst gehosteten Sandboxes ist dieses Verzeichnis kein Live-Mount. Stattdessen lädt der Environment-Worker des SDK jeden angehängten Store in deine Sandbox herunter, bevor die Tools des Agenten ausgeführt werden, und hält diese Kopie mit dem Store synchron.

Jede Memory (Erinnerung) in einem Store wird über einen Pfad adressiert und kann direkt über die API oder die Claude Console gelesen und bearbeitet werden, was Feinabstimmung, Import und Export ermöglicht.

Jede Änderung an einer Memory erzeugt eine unveränderliche Memory-Version, die dir einen Audit-Trail und eine zeitpunktgenaue Wiederherstellung für alles bietet, was der Agent schreibt.

Einen Memory Store erstellen

Gib dem Store einen name und eine description. Die Beschreibung wird an den Agenten weitergegeben und teilt ihm mit, was der Store enthält.

ant apply memory_store.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.

Die id des Memory Stores (memstore_...) ist das, was du beim Anhängen des Stores an eine Session übergibst.

Mit Inhalten vorbefüllen (optional)

Befülle einen Store vorab mit Referenzmaterial, bevor ein Agent läuft:

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

Einen Memory Store an eine Session anhängen

Memory Stores werden im resources[]-Array der Session angehängt, wenn die Session erstellt wird. Anders als Datei-Ressourcen können Memory Stores nur zum Zeitpunkt der Session-Erstellung angehängt werden; das Hinzufügen oder Entfernen eines Stores bei einer laufenden Session wird nicht unterstützt. Du hängst Memory Stores für Sessions in Cloud- und selbst gehosteten Umgebungen auf dieselbe Weise an; selbst gehostete Umgebungen akzeptieren nur memory_store-Ressourcen.

Füge optional instructions hinzu, um sessionspezifische Anleitungen dafür bereitzustellen, wie der Agent diesen Store verwenden soll. Sie werden dem Agenten zusammen mit name und description des Stores angezeigt und sind auf 4.096 Zeichen begrenzt.

Du kannst auch access konfigurieren. Der Standardwert ist read_write (im folgenden Beispiel explizit gezeigt), aber read_only wird ebenfalls unterstützt.

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

Pro Session werden maximal 8 Memory Stores unterstützt. Hänge mehrere Stores an, wenn verschiedene Teile des Gedächtnisses unterschiedliche Eigentümer oder Zugriffsregeln haben. Häufige Gründe:

• Gemeinsam genutztes Referenzmaterial: ein schreibgeschützter Store, der an viele Sessions angehängt ist (Standards, Konventionen, Domänenwissen), getrennt vom eigenen Read-Write-Store jeder Session.
• Abbildung auf die Struktur deines Produkts: ein Store pro Endbenutzer, pro Team oder pro Projekt, während eine einzige Agent-Konfiguration gemeinsam genutzt wird.
• Unterschiedliche Lebenszyklen: ein Store, der jede einzelne Session überdauert, oder einer, den du nach eigenem Zeitplan archivieren möchtest.

Wie der Agent auf Memory zugreift

Jeder angehängte Store wird innerhalb der Sandbox der Session als Verzeichnis unter /mnt/memory/ eingebunden. Der Verzeichnisname ist der Anzeigename des Stores, bereinigt zu einem dateisystemsicheren Slug (kleingeschrieben; Folgen nicht-alphanumerischer Zeichen werden zu einem einzelnen Bindestrich), sodass ein Store namens „Demo Memory“ unter /mnt/memory/demo-memory/ eingebunden wird. Der genaue Pfad wird im Feld mount_path der Memory-Store-Ressource der Session zurückgegeben; lies ihn von dort aus, anstatt ihn selbst zu konstruieren. Der Agent liest und schreibt den Store mit dem standardmäßigen Agent-Toolset. Schreibvorgänge unter dem Mount-Pfad werden in den Store zurückgeschrieben und bleiben über Sessions hinweg synchron, die ihn gemeinsam nutzen; Schreibvorgänge auf jeden anderen Pfad unter /mnt/memory/ schlagen fehl, da die Sandbox dieses übergeordnete Verzeichnis schreibgeschützt einbindet. Eine kurze Beschreibung jedes Mounts (Anzeigename, Mount-Pfad, Zugriffsmodus, description des Stores und etwaige instructions) wird automatisch zum System-Prompt hinzugefügt.

access wird auf Dateisystemebene durchgesetzt: Ein read_only-Mount lehnt Schreibvorgänge ab, während Schreibvorgänge auf einen read_write-Mount Memory-Versionen erzeugen, die der Session zugeordnet werden.

Die Lese- und Schreibvorgänge des Agenten erscheinen im Event-Stream als gewöhnliche agent.tool_use- und agent.tool_result-Events für das jeweilige Tool, das den Mount berührt hat.

Memories anzeigen und bearbeiten

Memory Stores können direkt über die API verwaltet werden. Nutze dies, um Review-Workflows zu erstellen, fehlerhafte Memories zu korrigieren oder Stores vorzubefüllen, bevor eine Session läuft.

Memories auflisten

Liste die Memories in einem Store auf. Ergebnisse werden in einer stabilen, serverseitig definierten Reihenfolge zurückgegeben.

• path_prefix beschränkt die Liste auf ein Verzeichnis. Es muss mit / enden und gleicht ganze Pfadsegmente ab, sodass path_prefix=/notes/ /notes/todo.md zurückgibt, aber nicht /notes-archive/todo.md.
• depth steuert, wie tief die Auflistung unterhalb von path_prefix geht: Lass es weg (oder übergib 0), um den gesamten Teilbaum aufzulisten, oder übergib 1, um nur die unmittelbaren Kinder aufzulisten. Andere Werte geben einen 400-Fehler zurück.

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for item in page.data:
    print(item.type, item.path)

Siehe die Referenz zum Auflisten von Memories für vollständige Parameter und das Antwortschema.

Eine Memory lesen

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

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

Siehe die Referenz zum Abrufen einer Memory für vollständige Parameter und das Antwortschema.

Eine Memory erstellen

memories.create erstellt eine Memory unter einem angegebenen path. Create überschreibt nicht; um eine bestehende Memory zu ändern, verwende memories.update.

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

Siehe die Referenz zum Erstellen einer Memory für vollständige Parameter und das Antwortschema.

Eine Memory aktualisieren

memories.update ändert eine bestehende Memory anhand ihrer ID. Du kannst content, path (eine Umbenennung) oder beides ändern. Das Beispiel benennt eine Memory in einen Archivpfad um:

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

Siehe die Referenz zum Aktualisieren einer Memory für vollständige Parameter und das Antwortschema.

Sichere Inhaltsbearbeitungen (optimistische Nebenläufigkeit)

Um zu vermeiden, dass ein gleichzeitiger Schreibvorgang überschrieben wird, übergib eine content_sha256-Vorbedingung. Die Aktualisierung wird nur angewendet, wenn der gespeicherte Inhalts-Hash noch mit dem übereinstimmt, den du gelesen hast; bei einer Abweichung lies die Memory erneut und versuche es gegen den aktuellen Zustand erneut.

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},
)

Eine Memory löschen

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

Siehe die Referenz zum Löschen einer Memory für vollständige Parameter und das Antwortschema.

Memory-Änderungen auditieren

Jede Mutation einer Memory erzeugt eine unveränderliche Memory-Version (memver_...). Verwende die Versions-Endpunkte, um zu auditieren, wer was wann geändert hat, um einen früheren Snapshot zu inspizieren oder wiederherzustellen und um sensible Inhalte mit Redact aus der Historie zu entfernen.

Versionen gehören zum Store (nicht zur einzelnen Memory) und werden nicht gelöscht, wenn die Memory selbst gelöscht wird, sodass der Audit-Trail auch gelöschte Memories abdeckt, vorbehaltlich der unten beschriebenen Aufbewahrung. Versionen werden 30 Tage nach ihrem Schreiben aufbewahrt; die jüngsten Versionen einer aktiven Memory werden jedoch unabhängig vom Alter immer behalten, sodass Memories, die sich selten ändern, ihre Historie möglicherweise über 30 Tage hinaus behalten. Der Live-Aufruf memories.retrieve gibt immer die neueste Version zurück; die Versions-Endpunkte liefern dir die aufbewahrte Historie.

Es gibt keinen dedizierten Restore-Endpunkt; um zurückzurollen, rufe die gewünschte Version ab und schreibe ihren content mit memories.update zurück (oder mit memories.create, falls die übergeordnete Memory gelöscht wurde, vorausgesetzt, die gewünschte Version wird noch aufbewahrt).

Frühere Memory-Versionen können nach 30 Tagen gelöscht werden. Um die Memory-Historie länger zu bewahren, exportiere Versionen über die API.

Versionen auflisten

Liste die Versionshistorie eines Stores auf, neueste zuerst. Das Beispiel filtert auf die Historie einer einzelnen Memory:

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

version_id = versions.data[1].id

Siehe die Referenz zum Auflisten von Memory-Versionen für vollständige Parameter und das Antwortschema.

Eine Version abrufen

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

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

Siehe die Referenz zum Abrufen einer Memory-Version für vollständige Parameter und das Antwortschema.

Eine Version schwärzen (Redact)

Redact entfernt Inhalte aus einer historischen Version, während der Audit-Trail (wer hat was wann getan) erhalten bleibt. Verwende es für Compliance-Workflows wie das Entfernen geleakter Secrets, personenbezogener Daten (PII) oder für Löschanfragen von Benutzern.

Eine Version, die der aktuelle Head einer aktiven Memory ist, kann nicht geschwärzt werden. Schreibe zuerst eine neue Version (oder lösche die Memory) und schwärze dann die alte.

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

Siehe die Referenz zum Schwärzen einer Memory-Version für vollständige Parameter und das Antwortschema.

Memory Stores verwalten

Zusätzlich zu create unterstützen Memory Stores retrieve, update, list, archive und delete.

Stores auflisten

Liste die Stores im Workspace auf. Archivierte Stores sind standardmäßig ausgeschlossen; übergib include_archived: true, um sie einzuschließen.

for memory_store in client.beta.memory_stores.list(include_archived=True):
    print(memory_store.id, memory_store.name, memory_store.archived_at)

Siehe die Referenz zum Auflisten von Memory Stores für vollständige Parameter und das Antwortschema.

Einen Store archivieren

Das Archivieren macht einen Store schreibgeschützt und verhindert, dass er an neue Sessions angehängt wird. Archivieren ist eine Einbahnstraße; es gibt kein Entarchivieren.

client.beta.memory_stores.archive(store.id)

Siehe die Referenz zum Archivieren eines Memory Stores für vollständige Parameter und das Antwortschema.

Um einen Store zusammen mit allen seinen Memories und Versionen dauerhaft zu entfernen, verwende memory_stores.delete.

Best Practices für die Memory-Verwaltung

Wenn ein Store sein Limit von 10.000 Memories erreicht, schlagen Schreibvorgänge für neue Memories fehl: sowohl direkte memories.create-Aufrufe als auch Dateischreibvorgänge des Agenten auf nicht zugeordnete Pfade. Bestehende Memories bleiben lesbar und bearbeitbar. Die folgenden Praktiken helfen dir, deutlich unter dem Limit zu bleiben und dich geordnet zu erholen, falls du es erreichst.

• Verwende fokussierte Stores. Anstelle eines großen Allzweck-Stores verwende kleinere, zweckgebundene Stores: einen pro Benutzer, einen für gemeinsam genutztes Domänenwissen und einen für projektspezifischen Kontext. Jeder Store hat sein eigenes Limit von 10.000 Memories, sodass eng gefasste Stores die Wahrscheinlichkeit verringern, dass ein einzelner voll wird.

• Verdichte oder bereinige, bevor der Store voll wird. Lösche veraltete oder redundante Memories mit memories.delete. Du kannst auch eine Dreaming-Session ausführen, die fragmentierte Inhalte in einem separaten neuen Ausgabe-Store konsolidiert, anstatt das Original zu verändern. Stelle deine Sessions auf diesen Ausgabe-Store um und archiviere oder lösche dann das Original.

• Hänge einen neuen Store an, wenn es sinnvoll ist. Wenn ein Store über seinen nützlichen Umfang hinausgewachsen ist, hänge einen frischen Store für neue Inhalte an und hänge das Original mit read_only-Zugriff an. Der Agent kann aus beiden lesen, während er nur in den neuen schreibt.

• Beschränke den Schreibzugriff, wo es angemessen ist. Sessions, die nur gemeinsam genutztes Referenzmaterial lesen, benötigen kein read_write. Wenn der Schreibzugriff auf Sessions beschränkt bleibt, die tatsächlich neue Memories hinzufügen, lässt sich leichter nachverfolgen, woher das Wachstum kommt.