Agent-Memory verwenden

Jede Managed-Agents-Session startet standardmäßig mit einem frischen Kontext. Wenn eine Session endet, ist jeglicher Zustand, den der Agent aufgebaut hat, verloren. „Memory stores" (Speicher) ermöglichen es dem Agent, 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 innerhalb der Sandbox der Session gemountet. Der Agent liest und schreibt darin 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 Agent mit, wo er nachschauen soll. Das Agent-Toolset ist für diese Interaktionen erforderlich; stelle sicher, dass du es bei der Agent-Erstellung aktivierst.

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

Jede Änderung an einer Memory erstellt eine unveränderliche Memory-Version, die dir einen Audit-Trail und eine Point-in-Time-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 Agent übergeben und teilt ihm mit, was der Store enthält.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

Die Memory-Store-id (memstore_...) ist das, was du übergibst, wenn du den Store an eine Session anhängst.



Mit Inhalt befüllen (optional)

Lade einen Store vorab mit Referenzmaterial, bevor ein Agent läuft:

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



Einen Memory Store an eine Session anhängen

Memory Stores werden im resources[]-Array der Session angehängt, wenn die Session erstellt wird. Im Gegensatz zu Datei- und Repository-Ressourcen können Memory Stores nur zum Zeitpunkt der Session-Erstellung angehängt werden; das Hinzufügen oder Entfernen aus einer laufenden Session wird nicht unterstützt.

Füge optional instructions hinzu, um sessionspezifische Anleitungen bereitzustellen, wie der Agent diesen Store verwenden soll. Diese werden dem Agent 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.

ant beta:sessions create <<YAML
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.
YAML

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

• Gemeinsames 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/ gemountet. Der Verzeichnisname ist der Anzeigename des Stores, bereinigt zu einem dateisystemsicheren Slug (kleingeschrieben; nicht-alphanumerische Zeichenfolgen werden zu einem einzelnen Bindestrich), sodass ein Store mit dem Namen „Demo Memory" unter /mnt/memory/demo-memory/ gemountet 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 zurück in den Store persistiert und bleiben über Sessions hinweg synchron, die ihn gemeinsam nutzen; Schreibvorgänge an jeden anderen Pfad unter /mnt/memory/ landen im container-lokalen Scratch-Bereich und gehen verloren, wenn die Session endet. Eine kurze Beschreibung jedes Mounts (Anzeigename, Mount-Pfad, Zugriffsmodus, Store-description 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 Agents 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 zum Erstellen von Review-Workflows, zum Korrigieren fehlerhafter Memories oder zum Befüllen von Stores, bevor eine Session läuft.



Memories auflisten

Liste die Memories in einem Store auf, optional gefiltert nach path_prefix, um einen Pfad wie ein Verzeichnis zu durchsuchen:

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

Siehe die List-Memories-Referenz für vollständige Parameter und Response-Schema.



Eine Memory lesen

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

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Siehe die Retrieve-a-Memory-Referenz für vollständige Parameter und Response-Schema.



Eine Memory erstellen

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

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Siehe die Create-a-Memory-Referenz für vollständige Parameter und Response-Schema.



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:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Siehe die Update-a-Memory-Referenz für vollständige Parameter und Response-Schema.



Sichere Inhaltsbearbeitungen (optimistische Nebenläufigkeit)

Um zu vermeiden, dass ein gleichzeitiger Schreibvorgang überschrieben wird, übergib eine content_sha256-Vorbedingung. Das Update wird nur angewendet, wenn der gespeicherte Content-Hash noch mit dem übereinstimmt, den du gelesen hast; bei Nichtübereinstimmung lies die Memory erneut und versuche es mit dem aktuellen Zustand erneut.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



Eine Memory löschen

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Siehe die Delete-a-Memory-Referenz für vollständige Parameter und Response-Schema.



Memory-Änderungen auditieren

Jede Mutation an einer Memory erstellt 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 bleiben erhalten, auch nachdem die Memory selbst gelöscht wurde, sodass der Audit-Trail vollständig bleibt. Versionen werden 30 Tage lang aufbewahrt; die jüngsten Versionen werden jedoch unabhängig vom Alter immer aufbewahrt, sodass Memories, die sich selten ändern, möglicherweise eine Historie über 30 Tage hinaus behalten. Der Live-Aufruf memories.retrieve gibt immer die neueste Version zurück; die Versions-Endpunkte geben 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, da Versionen ihre übergeordnete Memory überdauern).

Vergangene Memory-Versionen werden möglicherweise nach 30 Tagen gelöscht. Um die Memory-Historie länger zu bewahren, exportiere Versionen über die API.



Versionen auflisten

Liste die Versionshistorie für einen Store auf, neueste zuerst. Das Beispiel filtert auf die Historie einer einzelnen Memory:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

Siehe die List-Memory-Versions-Referenz für vollständige Parameter und Response-Schema.



Eine Version abrufen

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

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Siehe die Retrieve-a-Memory-Version-Referenz für vollständige Parameter und Response-Schema.



Eine Version schwärzen

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 von geleakten Secrets, personenbezogenen Daten (PII) oder Benutzerlöschanfragen.

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

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Siehe die Redact-a-Memory-Version-Referenz für vollständige Parameter und Response-Schema.



Memory Stores verwalten

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



Stores auflisten

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

ant beta:memory-stores list --include-archived

Siehe die List-Memory-Stores-Referenz für vollständige Parameter und Response-Schema.



Einen Store archivieren

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

ant beta:memory-stores archive --memory-store-id "$store_id"

Siehe die Archive-a-Memory-Store-Referenz für vollständige Parameter und Response-Schema.

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



Best Practices für Memory-Management

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

• Verwende fokussierte Stores. Anstatt eines großen Allzweck-Stores verwende kleinere zweckgebundene Stores — einen pro Benutzer, einen für gemeinsames Domänenwissen und einen für projektspezifischen Kontext. Jeder Store hat sein eigenes Limit von 2.000 Memories, sodass das Eingrenzen von Stores die Wahrscheinlichkeit verringert, dass ein einzelner voll wird.

• Verdichte oder bereinige, bevor der Store voll ist. Lösche veraltete oder redundante Memories mit memories.delete. Du kannst auch eine Dreaming-Session ausführen, die fragmentierte Inhalte in einen separaten neuen Output-Store konsolidiert, anstatt das Original zu ändern. Stelle deine Sessions auf diesen Output-Store um, dann archiviere oder lösche 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 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 Schreibzugriff, wo angemessen. Sessions, die nur gemeinsames Referenzmaterial lesen, benötigen kein read_write. Den Schreibzugriff auf Sessions zu beschränken, die tatsächlich neue Memories hinzufügen, macht es einfacher nachzuvollziehen, woher das Wachstum kommt.