Speicher verwenden

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

Übersicht

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

Jeder Speicher in einem Store kann direkt über die API oder Console zugegriffen und bearbeitet werden, was Abstimmung, Import und Export von Speichern ermöglicht.

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

Erstellen Sie einen Speicherstore

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=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

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

Füllen Sie es mit Inhalten (optional)

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

Speicher an eine Sitzung anhängen

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

Fügen Sie optional einen prompt ein, wenn Sie Claude sitzungsspezifische Anweisungen zur Verwendung dieses Speicherstores geben möchten. Er wird Claude zusätzlich zum name und zur description des Speicherstores 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 folgenden Beispiel explizit gezeigt).

Ein Maximum von 8 Speicherstores wird pro Sitzung unterstützt. Hängen Sie mehrere Stores an, wenn verschiedene Teile des Speichers 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.

Speicherwerkzeuge

Wenn Speicherstores an eine Sitzung angehängt sind, erhält der Agent automatisch Zugriff auf Speicherwerkzeuge. Die Interaktionen des Agenten mit Speicherstores werden als agent.tool_use-Ereignisse im Ereignisstrom registriert.

Speicher überprüfen und korrigieren

Speicherstores können direkt über die API verwaltet werden. Verwenden Sie dies zum Erstellen von Überprüfungs-Workflows, zum Korrigieren schlechter Speicher oder zum Seeding von Stores, bevor eine Sitzung läuft.

Speicher auflisten

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

Einen Speicher lesen

Das Abrufen eines einzelnen Speichers gibt den vollständigen Dokumentinhalt zurück.

Ein Dokument schreiben

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

Nur erstellen, wenn der Pfad frei ist

Übergeben Sie precondition={"type": "not_exists"} an memories.write, um es zu einem Schutz nur für die Erstellung zu machen. Wenn bereits ein Dokument 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, vorhandene Inhalte zu überschreiben.

Um ein vorhandenes Dokument 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 unten.

Update

memories.update() ändert ein vorhandenes Dokument 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 Dokument in einen Archivpfad um:

Sichere Inhaltsbearbeitungen (optimistische Parallelität)

Um den Inhalt eines Dokuments zu bearbeiten, ohne eine gleichzeitige Schreibvorgänge 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 Dokument erneut und versuchen es erneut gegen den aktuellen Status.

Ein Dokument löschen

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

Speicherversionen

Jede Mutation zu einem Speicher erstellt eine unveränderliche Speicherversion (memver_...). Versionen sammeln sich über die Lebensdauer des übergeordneten Speichers 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

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

Eine Version abrufen

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

Eine Version schwärzen

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