Agent-Memory verwenden
Gib deinen Agenten mithilfe von Memory Stores ein persistentes Gedächtnis, das über Sessions hinweg erhalten bleibt.
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 Workspace-bezogene Sammlung von Textdokumenten, die für Claude optimiert ist. Wenn du einen Store an eine Session anhängst, wird er als Verzeichnis in der Sandbox der Session eingebunden. Der Agent liest und schreibt ihn mit denselben Datei-Tools, die er auch für den Rest des Dateisystems verwendet, und ein Hinweis, der jeden Mount beschreibt, wird automatisch zum System-Prompt hinzugefügt und teilt dem Agenten mit, wo er suchen 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 dein Environment-Worker 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 übergeben 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 übergibst, wenn du den Store an eine Session anhängst.
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 bei der Erstellung der Session angehängt werden; das Hinzufügen oder Entfernen eines Stores in 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 dem name und der 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 angegeben), 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 Lese-Schreib-Store jeder Session
- Abbildung der Struktur deines Produkts: ein Store pro Endbenutzer, Team oder 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 in der Sandbox der Session als Verzeichnis unter /mnt/memory/ eingebunden. Der Verzeichnisname ist der Anzeigename des Stores, bereinigt zu einem dateisystemsicheren Slug (in Kleinbuchstaben, wobei jede Folge nicht-alphanumerischer Zeichen durch einen einzelnen Bindestrich ersetzt wird), 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 dort aus, anstatt ihn selbst zu konstruieren. Der Agent liest und schreibt den Store mit dem Standard-Agent-Toolset. Schreibvorgänge unter dem Einbindungspfad werden in den Store zurückgeschrieben und bleiben über Sessions, die ihn gemeinsam nutzen, synchron; Schreibvorgänge in einen anderen Pfad unter /mnt/memory/ schlagen fehl, da die Sandbox dieses übergeordnete Verzeichnis schreibgeschützt einbindet. Eine kurze Beschreibung jeder Einbindung (Anzeigename, Einbindungspfad, Zugriffsmodus, description des Stores und eventuelle instructions) wird automatisch zum System-Prompt hinzugefügt.
access wird auf Dateisystemebene durchgesetzt: Eine read_only-Einbindung lehnt Schreibvorgänge ab, während Schreibvorgänge in eine read_write-Einbindung Erinnerungsversionen 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_prefixbeschränkt die Liste auf ein Verzeichnis. Es muss mit/enden und gleicht ganze Pfadsegmente ab, sodasspath_prefix=/notes//notes/todo.mdzurückgibt, aber nicht/notes-archive/todo.md.depthsteuert, wie tief die Liste unterhalb vonpath_prefixreicht: Lass den Parameter weg (oder übergib0), um den gesamten Teilbaum aufzulisten, oder übergib1, um nur die unmittelbaren Kinder aufzulisten. Andere Werte geben einen400-Fehler zurück.
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)Vollständige Parameter und das Antwortschema findest du in der Referenz Erinnerungen auflistenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
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)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerung abrufenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Eine Memory erstellen
client.beta.memory_stores.memories.create() erstellt eine Erinnerung unter einem angegebenen path. Create überschreibt nicht; um eine bestehende Erinnerung zu aktualisieren, verwende client.beta.memory_stores.memories.update().
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerung erstellenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Eine Memory aktualisieren
client.beta.memory_stores.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",
)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerung aktualisierenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Sichere Inhaltsbearbeitungen (optimistische Nebenläufigkeit)
Um das Überschreiben eines gleichzeitigen Schreibvorgangs zu vermeiden, übergib eine content_sha256-Vorbedingung. Das Update wird nur angewendet, wenn der gespeicherte Inhalts-Hash noch mit dem übereinstimmt, den du gelesen hast; bei einer Abweichung liest du die Erinnerung erneut und versuchst es mit dem aktuellen Zustand noch einmal.
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,
)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerung löschenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
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 Erinnerung) und werden nicht gelöscht, wenn die Erinnerung selbst gelöscht wird, sodass der Audit-Trail auch gelöschte Erinnerungen abdeckt, vorbehaltlich der weiter unten beschriebenen Aufbewahrung. Versionen werden 30 Tage nach ihrem Schreiben aufbewahrt; die neuesten Versionen einer aktiven Erinnerung werden jedoch unabhängig von ihrem Alter immer beibehalten, sodass Erinnerungen, die sich selten ändern, ihren Verlauf möglicherweise über 30 Tage hinaus behalten. Der Live-Aufruf client.beta.memory_stores.memories.retrieve() gibt immer die neueste Version zurück; die Versions-Endpunkte liefern dir den aufbewahrten Verlauf.
Es gibt keinen eigenen Wiederherstellungs-Endpunkt; um ein Rollback durchzuführen, rufe die gewünschte Version ab und schreibe ihren content mit client.beta.memory_stores.memories.update() zurück (oder mit client.beta.memory_stores.memories.create(), falls die übergeordnete Memory gelöscht wurde, sofern die gewünschte Version noch aufbewahrt wird).
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].idVollständige Parameter und das Antwortschema findest du in der Referenz Erinnerungsversionen auflistenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Eine Version abrufen
Das Abrufen einer einzelnen Version gibt dieselben Felder wie die Listenantwort zurück, zuzüglich des vollständigen content-Inhalts.
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerungsversion abrufenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
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 dies für Compliance-Workflows, etwa zum Entfernen geleakter Secrets oder personenbezogener Daten (PII) oder zur Erfüllung von 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,
)Vollständige Parameter und das Antwortschema findest du in der Referenz Eine Erinnerungsversion schwärzenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Memory Stores verwalten
Zusätzlich zu createVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. unterstützen Memory Stores retrieveVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., updateVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., listVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., archiveVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. und deleteVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Stores auflisten
Liste die Stores im Workspace auf. Archivierte Stores sind standardmäßig ausgeschlossen; setze include_archived auf 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)Vollständige Parameter und das Antwortschema findest du in der Referenz Memory Stores auflistenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
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)Vollständige Parameter und das Antwortschema findest du in der Referenz Einen Memory Store archivierenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..
Um einen Store dauerhaft zu löschenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren., zusammen mit all seinen Erinnerungen und Versionen, rufe client.beta.memory_stores.delete() auf.
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 client.beta.memory_stores.memories.create()-Aufrufe als auch die Dateischreibvorgänge des Agenten in nicht zugeordnete Pfade. Vorhandene Memories bleiben lesbar und bearbeitbar. Die folgenden Praktiken helfen dir, deutlich unter dem Limit zu bleiben und dich problemlos zu erholen, falls du es erreichst.
-
Verwende fokussierte Stores. Statt eines großen Allzweck-Stores solltest du kleinere, zweckgebundene Stores verwenden: einen für jeden Benutzer, einen für gemeinsam genutztes Domänenwissen und einen für projektspezifischen Kontext. Jeder Store hat sein eigenes Limit von 10.000 Erinnerungen, sodass eng gefasste Stores die Wahrscheinlichkeit verringern, dass ein einzelner voll wird.
-
Verdichte oder bereinige, bevor der Store voll ist. Lösche veraltete oder redundante Memories mit
client.beta.memory_stores.memories.delete(). Du kannst auch eine Dreaming-Session ausführen, die fragmentierte Inhalte in einem separaten neuen Ausgabe-Store zusammenführt, anstatt das Original zu ä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.
Verfügbarkeit
Claude API
- Status
- Beta
- API
- Managed Agents
- Beta-Header
- Erfordert
- Modelle
- Alle Modelle
- Hinweis
Wenn du bei einem Memory-Store-Aufruf
managed-agents-2026-04-01zusammen mitagent-memory-2026-07-22sendest, wird ein 400-Fehler zurückgegeben.
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Beta-Header
- Erfordert
- Modelle
- Alle Modelle
- Hinweis
Auf Claude Platform on AWS können Sitzungen in selbst gehosteten Umgebungen keine Memory Stores anhängen. Wenn du bei einem Memory-Store-Aufruf
managed-agents-2026-04-01zusammen mitagent-memory-2026-07-22sendest, wird ein 400-Fehler zurückgegeben.
Claude Models on Google Cloud (Anthropic managed)
- Status
- Beta
- API
- Managed Agents
- Beta-Header
- Erfordert
- Modelle
- Alle Modelle
- Hinweis
Auf Claude Models on Google Cloud (Anthropic managed) werden Memory Stores für Sitzungen in selbst gehosteten Umgebungen nicht unterstützt. Wenn du bei einem Memory-Store-Aufruf
managed-agents-2026-04-01zusammen mitagent-memory-2026-07-22sendest, wird ein 400-Fehler zurückgegeben.
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/agents/v1/sessions/v1/environments
Nicht für ZDR berechtigt, außer bei selbst gehosteten Managed Agents. Sitzungen sind zustandsbehaftete Ressourcen; Transkripte bleiben erhalten, bis du sie löschst. Mehr erfahren
Nicht für HIPAA berechtigt. Gilt für alle Unterfunktionen von Managed Agents.
War diese Seite hilfreich?