Memory-Tool
Ermögliche Claude, Informationen über Gespräche hinweg zu speichern und abzurufen, indem du die Dateioperationen des Memory-Tools in deiner Anwendung implementierst.
Das Memory-Tool ermöglicht es Claude, Informationen über Gespräche hinweg in einem Verzeichnis von Memory-Dateien zu speichern und abzurufen. Claude kann Dateien erstellen, lesen, aktualisieren und löschen, die zwischen Sitzungen erhalten bleiben, und so im Laufe der Zeit Wissen aufbauen, ohne alles im „context window“ (Kontextfenster) zu behalten.
Memory unterstützt „just-in-time context retrieval“ (bedarfsgesteuertes Abrufen von Kontext). Anstatt alle relevanten Informationen im Voraus zu laden, hält ein Agent das, was er lernt, in Memory-Dateien fest und liest sie bei Bedarf wieder ein. Dadurch bleibt der aktive Kontext auf die aktuelle Aufgabe fokussiert, was für lang laufende Sitzungen wichtig ist, die das Kontextfenster sonst überlasten würden. Siehe Effektives Kontext-Engineering für das übergeordnete Muster.
Das Memory-Tool arbeitet clientseitig: Claude fordert Dateioperationen an, und deine Anwendung führt sie aus. Du kontrollierst über deine eigene Infrastruktur, wo und wie die Daten gespeichert werden.
Anwendungsfälle
- Projektkontext über mehrere Agent-Sitzungen hinweg beibehalten
- Erkenntnisse aus früheren Interaktionen, Entscheidungen und Feedback auf neue Aufgaben anwenden
- Im Laufe der Zeit eine Wissensbasis aufbauen
Funktionsweise
Wenn das Memory-Tool aktiviert ist, prüft Claude automatisch sein Memory-Verzeichnis, bevor es mit einer Aufgabe beginnt. Während der Arbeit speichert Claude das Gelernte in Dateien unter /memories und liest sie in späteren Gesprächen wieder ein, um frühere Arbeit fortzusetzen.
Da das Memory-Tool clientseitig ist, fordert Claude nur Memory-Operationen an. Deine Anwendung führt jede Anfrage gegen einen von dir kontrollierten Speicher aus und gibt das Ergebnis in einem tool_result-Block zurück (siehe Tool-Aufrufe verarbeiten). Der Pfad /memories ist ein Präfix, das dein Handler auf echten Speicher abbildet, etwa ein Verzeichnis pro Benutzer oder Schlüssel in einer Datenbank. Memory existiert vollständig in deiner Anwendung. Ein späteres Gespräch setzt mit demselben Memory fort, wenn es denselben tools-Eintrag sendet und dein Handler denselben Speicher bereitstellt. Beschränke aus Sicherheitsgründen alle Memory-Operationen auf das Verzeichnis /memories (siehe Schutz vor Path Traversal).
Beispiel: Wie Memory-Tool-Aufrufe funktionieren
Eine typische Interaktion sieht so aus:
1. Benutzeranfrage:
"Help me respond to this customer service ticket."2. Claude prüft das Memory-Verzeichnis:
"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."Claude ruft das Memory-Tool auf:
{
"type": "tool_use",
"id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"name": "memory",
"input": {
"command": "view",
"path": "/memories"
}
}3. Deine Anwendung gibt den Verzeichnisinhalt zurück:
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}4. Claude liest relevante Dateien:
{
"type": "tool_use",
"id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"name": "memory",
"input": {
"command": "view",
"path": "/memories/customer_service_guidelines.xml"
}
}5. Deine Anwendung gibt den Dateiinhalt zurück:
{
"type": "tool_result",
"tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n 1\t<guidelines>\n 2\t<addressing_customers>\n 3\t- Always address customers by their first name\n 4\t- Use empathetic language\n..."
}6. Claude nutzt das Memory, um zu helfen:
"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."Das Memory-Tool ist für alle Modelle ab Claude 4 verfügbar. Die vollständige Liste der von Anthropic bereitgestellten Tools findest du in der Tool-Referenz.
Erste Schritte
Die Verwendung des Memory-Tools erfordert zwei Schritte:
- Füge das Memory-Tool zu deiner Anfrage hinzu. Der
tools-Eintrag{"type": "memory_20250818", "name": "memory"}ist die gesamte Konfiguration: Dernamemussmemorysein, und für ein von Anthropic bereitgestelltes Tool definierst du kein Eingabeschema. - Implementiere einen clientseitigen Handler für jeden Memory-Befehl. Dein Handler muss Pfade außerhalb von
/memoriesablehnen, also lies Schutz vor Path Traversal, bevor du ihn schreibst.
Grundlegende Verwendung
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)Den Memory-Handler implementieren
Claudes Antwort auf eine Anfrage wie die vorherige endet mit einem tool_use-Block, der eine Memory-Operation anfordert, etwa view /memories. Deine Anwendung führt die Operation aus, gibt das Ergebnis in einem tool_result-Block zurück und sendet das Gespräch dann zurück, damit Claude fortfahren kann: die standardmäßige Tool-Nutzungs-Schleife.
Vier SDKs bieten Memory-Tool-Helper, die die Tool-Schnittstelle und die Schleife übernehmen. Leite von BetaAbstractMemoryTool ab (Python und C#), verwende betaMemoryTool (TypeScript) oder implementiere BetaMemoryToolHandler (Java), um Memory mit deinem eigenen Speicher zu hinterlegen, etwa Dateien auf der Festplatte, einer Datenbank, Cloud-Speicher oder verschlüsselten Dateien. Python und TypeScript liefern außerdem eine fertige Implementierung für das lokale Dateisystem mit: BetaLocalFilesystemMemoryTool. Die Helper- und Tool-Runner-Schnittstellen befinden sich im Beta-Namespace deines SDKs, obwohl das Memory-Tool selbst keinen Beta-Header benötigt. Die Go- und Ruby-SDKs haben keinen Memory-Helper, daher führen diese Beispiele die Tool-Nutzungs-Schleife selbst aus, und PHP kapselt deine Handler-Closure in seinem generischen BetaRunnableTool. Alle drei verwenden einen In-Memory-Speicher, den du durch deinen eigenen Speicher ersetzt.
import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool
client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Remember that customer Acme Corp prefers email follow-ups.",
}
],
tools=[memory],
)
final_message = runner.until_done()
print(final_message.content)Die In-Memory-Speicher in den Go-, PHP- und Ruby-Beispielen halten diese in sich abgeschlossen: Jeder verzweigt anhand des Felds command im input des tool_use-Blocks und gibt die unter Tool-Befehle beschriebenen Strings zurück. Ein Handler für den Produktiveinsatz benötigt außerdem die Pfadvalidierung, die diese Demonstrationsspeicher auslassen. Die vollständigen Beispiele der SDKs findest du hier:
- Python: examples/memory/basic.py
- TypeScript: examples/tools-helpers-memory.ts
- C#: MemoryToolExample
- Java: BetaMemoryToolExample.java
Tool-Befehle
Deine clientseitige Implementierung muss die folgenden Befehle verarbeiten. Diese Spezifikationen beschreiben das empfohlene Verhalten und die empfohlenen Rückgabe-Strings: Claude liest jeden Text, den dein Tool-Ergebnis enthält, daher kannst du andere Strings zurückgeben, wenn deine Anwendung das erfordert.
view
Zeigt Verzeichnisinhalte oder Dateiinhalte mit optionalen Zeilenbereichen an:
{
"command": "view",
"path": "/memories/notes.txt",
"view_range": [1, 10]
}view_range ist optional und gilt für Ansichten von Textdateien: [start_line, end_line] gibt diese Zeilen zurück, und [start_line, -1] gibt alles von start_line bis zum Ende der Datei zurück.
Rückgabewerte
Für Verzeichnisse: Gib eine Liste zurück, die Dateien und Verzeichnisse mit ihren Größen anzeigt:
Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}- Listet Dateien bis zu 2 Ebenen tief auf
- Zeigt menschenlesbare Größen an (zum Beispiel
5.5K,1.2M) - Schließt versteckte Elemente (Dateien, die mit
.beginnen) undnode_modulesaus - Verwendet ein Tabulatorzeichen zwischen Größe und Pfad
Das erste view von /memories in einem leeren Speicher ist kein Fehler. Wo dein SDK ein Memory-Tool für das lokale Dateisystem mitliefert, BetaLocalFilesystemMemoryTool, erstellt es das Memory-Stammverzeichnis vor Claudes erstem Aufruf und gibt den Listenkopf gefolgt von einer einzelnen Zeile mit Größe und Pfad für das leere Verzeichnis selbst zurück.
Für Dateien: Gib den Dateiinhalt mit einem Header und Zeilennummern zurück:
Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}Formatierung der Zeilennummern:
- Breite: 6 Zeichen, rechtsbündig mit Leerzeichen aufgefüllt
- Trennzeichen: Tabulatorzeichen zwischen Zeilennummer und Inhalt
- Indizierung: 1-basiert (die erste Zeile ist Zeile 1)
- Zeilenlimit: Dateien mit mehr als 999.999 Zeilen sollten einen Fehler zurückgeben:
"File {path} exceeds maximum line limit of 999,999 lines."
Beispielausgabe:
Here's the content of /memories/notes.txt with line numbers:
1 Hello World
2 This is line two
10 Line ten
100 Line one hundredClaudes Tool-Beschreibung besagt außerdem, dass view Bilddateien (.jpg, .jpeg und .png) anzeigt und die Textansicht von Dateien mit mehr als 16.000 Zeichen kürzt. Rechne mit view-Aufrufen auf Bildpfaden und mit nachfolgenden Ansichten mit Zeilenbereichen bei langen Dateien.
Fehlerbehandlung
- Datei oder Verzeichnis existiert nicht:
"The path {path} does not exist. Please provide a valid path."
create
Erstellt eine neue Datei:
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}Rückgabewerte
- Erfolg:
"File created successfully at: {path}"
Fehlerbehandlung
- Datei existiert bereits:
"Error: File {path} already exists"
Claudes Tool-Beschreibung besagt, dass create eine Datei „erstellt oder überschreibt“, rechne also mit create-Aufrufen auf bereits existierenden Pfaden. Die Rückgabe des Fehlers ist das Referenzverhalten, und stattdessen zu überschreiben ist eine gültige Implementierungsentscheidung.
str_replace
Ersetzt Text in einer Datei:
{
"command": "str_replace",
"path": "/memories/preferences.txt",
"old_str": "Favorite color: blue",
"new_str": "Favorite color: green"
}new_str ist für str_replace optional: Wenn es weggelassen wird, wird old_str ohne Ersatz gelöscht.
Rückgabewerte
- Erfolg:
"The memory file has been edited."gefolgt von einem Ausschnitt der bearbeiteten Datei mit Zeilennummern
Fehlerbehandlung
- Datei existiert nicht:
"Error: The path {path} does not exist. Please provide a valid path." - Text nicht gefunden:
"No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}." - Doppelter Text: Wenn
old_strmehrfach vorkommt, gib zurück:"No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"
Umgang mit Verzeichnissen
Wenn der Pfad ein Verzeichnis ist, gib einen „Datei existiert nicht“-Fehler zurück.
insert
Fügt Text an einer bestimmten Zeile ein:
{
"command": "insert",
"path": "/memories/todo.txt",
"insert_line": 2,
"insert_text": "- Review memory tool documentation\n"
}insert_text wird nach Zeile insert_line eingefügt, und 0 fügt am Anfang der Datei ein.
Rückgabewerte
- Erfolg:
"The file {path} has been edited."
Fehlerbehandlung
- Datei existiert nicht:
"Error: The path {path} does not exist" - Ungültige Zeilennummer:
"Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"
Umgang mit Verzeichnissen
Wenn der Pfad ein Verzeichnis ist, gib einen „Datei existiert nicht“-Fehler zurück.
delete
Löscht eine Datei oder ein Verzeichnis:
{
"command": "delete",
"path": "/memories/old_file.txt"
}Rückgabewerte
- Erfolg:
"Successfully deleted {path}"
Fehlerbehandlung
- Datei oder Verzeichnis existiert nicht:
"Error: The path {path} does not exist"
Umgang mit Verzeichnissen
Löscht das Verzeichnis und seinen gesamten Inhalt rekursiv. Die Tool-Beschreibung teilt Claude mit, dass es das Verzeichnis /memories selbst nicht löschen kann, also lehne ein delete ab, dessen Pfad das Memory-Stammverzeichnis ist.
rename
Benennt eine Datei oder ein Verzeichnis um oder verschiebt es:
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}Rückgabewerte
- Erfolg:
"Successfully renamed {old_path} to {new_path}"
Fehlerbehandlung
- Quelle existiert nicht:
"Error: The path {old_path} does not exist" - Ziel existiert bereits: Gib einen Fehler zurück (nicht überschreiben):
"Error: The destination {new_path} already exists"
Umgang mit Verzeichnissen
Benennt das Verzeichnis um. Die Tool-Beschreibung teilt Claude mit, dass es das Verzeichnis /memories selbst nicht umbenennen kann, also lehne ein rename ab, dessen old_path das Memory-Stammverzeichnis ist.
Hinweise zum Prompting
Wenn das Memory-Tool in den tools deiner Anfrage enthalten ist, fügt die API diese Anweisung automatisch zum „system prompt“ (System-Prompt) hinzu. Du musst sie nicht selbst senden:
IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
- As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.Claudes Tool-Beschreibung weist es bereits an, das Memory-Verzeichnis geordnet zu halten, daher musst du diese Anweisung nicht wiederholen. Wenn Claude dennoch unübersichtliche Memory-Dateien erstellt, kannst du sie in deinem Prompt verstärken:
Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.Du kannst auch steuern, was Claude in das Memory schreibt. Zum Beispiel: „Only write down information relevant to <topic> in your memory system.“
Sicherheitsaspekte
Deine Anwendung führt jede Dateioperation aus, die Claude anfordert, daher liegen diese Schutzmaßnahmen in deiner Verantwortung:
Sensible Informationen
Claude weigert sich in der Regel, sensible Informationen in Memory-Dateien zu schreiben. Für stärkere Garantien füge eine Validierung hinzu, die sensible Daten entfernt, bevor dein Handler die Datei schreibt.
Dateispeichergröße
Überwache die Größe der Memory-Dateien und begrenze, wie groß eine Datei werden kann. Erwäge, die Anzahl der Zeichen zu begrenzen, die der Befehl view zurückgibt, und lass Claude mit view_range durch den Rest blättern.
Ablauf von Memory
Lösche regelmäßig Memory-Dateien, auf die lange nicht zugegriffen wurde.
Schutz vor Path Traversal
Erwäge diese Schutzmaßnahmen:
- Prüfe, dass alle Pfade mit
/memoriesbeginnen - Löse Pfade in ihre kanonische Form auf und prüfe, dass sie innerhalb des Memory-Verzeichnisses bleiben
- Lehne Pfade ab, die Sequenzen wie
../,..\\oder andere Traversal-Muster enthalten - Achte auf URL-kodierte Traversal-Sequenzen (
%2e%2e%2f) - Verwende die eingebauten Pfadsicherheits-Hilfsmittel deiner Sprache (zum Beispiel Pythons
pathlib.Path.resolve()undrelative_to())
Fehlerbehandlung
Das Memory-Tool verwendet ähnliche Muster zur Fehlerbehandlung wie das Text-Editor-Tool. Die Fehlermeldungen der einzelnen Befehle sind unter Tool-Befehle aufgeführt. Um einen Fehler an Claude zurückzugeben, setze is_error im Tool-Ergebnis auf true und gib die Meldung in content an:
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Error: The path /memories/notes.txt does not exist",
"is_error": true
}Integration mit Kontextbearbeitung
Das Memory-Tool lässt sich mit „context editing“ (Kontextbearbeitung) kombinieren, um lang laufende Gespräche zu verwalten. Details findest du unter Kontextbearbeitung.
Verwendung mit Compaction
Das Memory-Tool lässt sich auch mit der Komprimierung kombinieren, die älteren Gesprächskontext serverseitig zusammenfasst. Die Kontextbearbeitung entfernt bestimmte Tool-Ergebnisse auf dem Client. Die Komprimierung fasst das gesamte Gespräch automatisch auf dem Server zusammen, wenn sich das Gespräch dem Limit des Kontextfensters nähert.
Für lang laufende Agents solltest du beides in Betracht ziehen: Compaction hält den aktiven Kontext klein, ohne clientseitige Buchführung, und Memory bewahrt die Informationen, die die Zusammenfassung überstehen müssen.
Muster für sitzungsübergreifende Softwareentwicklung
Bei Softwareprojekten, die sich über mehrere Agent-Sitzungen erstrecken, solltest du Memory-Dateien gezielt einrichten, anstatt sie im Laufe der Arbeit ad hoc zu schreiben. Das folgende Muster macht Memory zu einem Wiederherstellungsmechanismus: Jede neue Sitzung setzt an dem Zustand an, den die letzte festgehalten hat.
Wie das Muster funktioniert
-
Initialisierungssitzung: Die erste Sitzung richtet die Memory-Dateien ein, bevor die eigentliche Arbeit beginnt. Dazu gehören ein Fortschrittsprotokoll (das festhält, was erledigt wurde und was als Nächstes kommt), eine Feature-Checkliste (die den Arbeitsumfang definiert) und ein Verweis auf ein eventuell benötigtes Start- oder Initialisierungsskript des Projekts.
-
Folgesitzungen: Jede neue Sitzung beginnt damit, diese Memory-Dateien zu lesen. Dadurch wird der Projektzustand wiederhergestellt, ohne die Codebasis erneut zu erkunden oder frühere Entscheidungen nachzuvollziehen.
-
Aktualisierung am Sitzungsende: Bevor eine Sitzung endet, aktualisiert sie das Fortschrittsprotokoll mit dem, was abgeschlossen wurde und was noch aussteht. So hat die nächste Sitzung einen korrekten Ausgangspunkt.
Grundprinzip
Arbeite jeweils an einem Feature. Markiere ein Feature erst dann als abgeschlossen, wenn eine End-to-End-Verifizierung bestätigt, dass es funktioniert, und nicht schon, wenn der Code geschrieben ist. So bleibt das Fortschrittsprotokoll von Sitzung zu Sitzung korrekt.
Nächste Schritte
Führe Shell-Befehle in einer persistenten Bash-Sitzung aus.
Verwalte den Gesprächskontext automatisch, während er wächst, mit Kontextbearbeitung.
Serverseitige Kontext-Compaction zur Verwaltung langer Gespräche, die sich dem Limit des Kontextfensters nähern.
Verzeichnis der von Anthropic bereitgestellten Tools und Referenz für optionale Eigenschaften von Tool-Definitionen.
Verfügbarkeit
Claude API
- API
- Messages API
- Modelle
- Alle Modelle
Amazon Bedrock
- API
- Messages API
- Modelle
- Alle Modelle
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Modelle
- Alle Modelle
Claude Platform on AWS
- API
- Messages API
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Modelle
- Alle Modelle
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Modelle
- Alle Modelle
Microsoft Foundry
- API
- Messages API
- Modelle
- Alle Modelle
Datenverarbeitung
Übersicht über die DatenverarbeitungZutreffende Endpunkte
/v1/messagesmit Toolmemory
Ausgenommen: Abgedeckte Modelle
Clientseitige Memory-Speicherung, bei der du die Datenaufbewahrung steuerst.
War diese Seite hilfreich?