Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Das Memory-Tool ermöglicht es Claude, Informationen über Konversationen hinweg in einem Verzeichnis von Memory-Dateien zu speichern und abzurufen. Claude kann Dateien erstellen, lesen, aktualisieren und löschen, die zwischen Sitzungen bestehen bleiben, und so im Laufe der Zeit Wissen aufbauen, ohne alles im Kontextfenster zu behalten.
Memory unterstützt den Just-in-time-Kontextabruf. Anstatt alle relevanten Informationen im Voraus zu laden, zeichnet ein Agent das Gelernte in Memory-Dateien auf 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 andernfalls das Kontextfenster überlasten würden. Siehe Effective context 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.
Wenn das Memory-Tool aktiviert ist, überprüft Claude automatisch sein Memory-Verzeichnis, bevor es eine Aufgabe beginnt. Während der Arbeit speichert Claude das Gelernte in Dateien unter /memories und liest sie in späteren Konversationen wieder ein, um frühere Arbeit fortzusetzen.
Da das Memory-Tool clientseitig ist, fordert Claude Memory-Operationen nur 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 lebt vollständig in deiner Anwendung. Eine spätere Konversation setzt mit demselben Memory fort, wenn sie denselben tools-Eintrag sendet und dein Handler denselben Speicher bedient. Beschränke aus Sicherheitsgründen alle Memory-Operationen auf das Verzeichnis /memories (siehe Schutz vor Path Traversal).
Eine typische Interaktion sieht so aus:
1. Benutzeranfrage:
"Help me respond to this customer service ticket."2. Claude überprü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 auf allen Claude-4- und späteren Modellen verfügbar. Die vollständige Liste der von Anthropic bereitgestellten Tools findest du in der Tool-Referenz.
Das Memory-Tool ist in der Messages API allgemein verfügbar: Es ist kein Beta-Header erforderlich. Die Nutzung erfolgt in zwei Schritten:
tools-Eintrag {"type": "memory_20250818", "name": "memory"} ist die gesamte Konfiguration: Der name muss memory sein, und du definierst kein Eingabeschema für ein von Anthropic bereitgestelltes Tool./memories ablehnen, lies also Schutz vor Path Traversal, bevor du ihn schreibst.client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-5",
max_tokens=2048,
messages=[
{
"role": "user",
"content": "Help me respond to this customer service ticket.",
}
],
tools=[{"type": "memory_20250818", "name": "memory"}],
)
print(message)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 und gibt das Ergebnis in einem tool_result-Block zurück, dann sendet sie die Konversation zurück, damit Claude fortfahren kann: die standardmäßige Tool-Use-Schleife.
Vier SDKs bieten Memory-Tool-Helfer, 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, BetaLocalFilesystemMemoryTool. Die Helfer- und Tool-Runner-Oberflächen befinden sich im Beta-Namespace jedes SDKs, obwohl das Memory-Tool selbst allgemein verfügbar ist. Die Go- und Ruby-SDKs haben keinen Memory-Helfer, daher führen diese Beispiele die Tool-Use-Schleife selbst aus, und PHP umschließt 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",
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 sie in sich geschlossen: Jeder verzweigt anhand des command-Felds im input des tool_use-Blocks und gibt die unter Tool-Befehle beschriebenen Strings zurück. Ein Produktions-Handler benötigt außerdem die Pfadvalidierung, die diese Demonstrationsspeicher auslassen. Die vollständigen eigenen Beispiele der SDKs findest du hier:
Deine clientseitige Implementierung muss die folgenden Befehle verarbeiten. Diese Spezifikationen beschreiben die empfohlenen Verhaltensweisen und Rückgabe-Strings: Claude liest den Text, den dein Tool-Ergebnis enthält, du kannst also andere Strings zurückgeben, wenn deine Anwendung das benötigt.
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 Textdatei-Ansichten: [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.
Für Verzeichnisse: Gib eine Auflistung 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}5.5K, 1.2M). beginnen) und node_modules ausDas erste view von /memories auf einem leeren Speicher ist kein Fehler. Die Memory-Tools der SDKs für das lokale Dateisystem (BetaLocalFilesystemMemoryTool) erstellen das Memory-Stammverzeichnis vor Claudes erstem Aufruf und geben den Auflistungs-Header gefolgt von einer einzelnen Größe-und-Pfad-Zeile für das leere Verzeichnis selbst zurück.
Für Dateien: Gib Dateiinhalte mit einem Header und Zeilennummern zurück:
Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}Formatierung der Zeilennummern:
"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 nachfolgenden bereichsbasierten Ansichten langer Dateien.
"The path {path} does not exist. Please provide a valid path."Erstellt eine neue Datei:
{
"command": "create",
"path": "/memories/notes.txt",
"file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}"File created successfully at: {path}""Error: File {path} already exists"Claudes Tool-Beschreibung besagt, dass create eine Datei „erstellt oder überschreibt", rechne also mit create-Aufrufen auf Pfaden, die bereits existieren. Die Rückgabe des Fehlers ist das Referenzverhalten, und stattdessen zu überschreiben ist eine gültige Implementierungsentscheidung.
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.
"The memory file has been edited." gefolgt von einem Ausschnitt der bearbeiteten Datei mit Zeilennummern"Error: The path {path} does not exist. Please provide a valid path.""No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."old_str mehrfach vorkommt, gib zurück: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"Wenn der Pfad ein Verzeichnis ist, gib einen „Datei existiert nicht"-Fehler zurück.
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.
"The file {path} has been edited.""Error: The path {path} does not exist""Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"Wenn der Pfad ein Verzeichnis ist, gib einen „Datei existiert nicht"-Fehler zurück.
Löscht eine Datei oder ein Verzeichnis:
{
"command": "delete",
"path": "/memories/old_file.txt"
}"Successfully deleted {path}""Error: The path {path} does not exist"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, lehne also ein delete ab, dessen Pfad das Memory-Stammverzeichnis ist.
Benennt eine Datei oder ein Verzeichnis um oder verschiebt sie/es:
{
"command": "rename",
"old_path": "/memories/draft.txt",
"new_path": "/memories/final.txt"
}"Successfully renamed {old_path} to {new_path}""Error: The path {old_path} does not exist""Error: The destination {new_path} already exists"Benennt das Verzeichnis um. Die Tool-Beschreibung teilt Claude mit, dass es das Verzeichnis /memories selbst nicht umbenennen kann, lehne also ein rename ab, dessen old_path das Memory-Stammverzeichnis ist.
Wenn das Memory-Tool in den tools deiner Anfrage vorhanden ist, fügt die API diese Anweisung automatisch zum 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 organisiert zu halten, du musst diese Anweisung also nicht wiederholen. Wenn Claude dennoch unübersichtliche Memory-Dateien erstellt, kannst du dies 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 Memory schreibt. Zum Beispiel: „Schreibe nur Informationen, die für <topic> relevant sind, in dein Memory-System."
Deine Anwendung führt jede Dateioperation aus, die Claude anfordert, daher liegen diese Schutzmaßnahmen in deiner Verantwortung:
Claude weigert sich normalerweise, 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.
Verfolge die Größen der Memory-Dateien und begrenze, wie groß eine Datei werden kann. Erwäge, die Anzahl der Zeichen zu begrenzen, die der view-Befehl zurückgibt, und lass Claude den Rest mit view_range seitenweise durchblättern.
Lösche regelmäßig Memory-Dateien, auf die lange nicht zugegriffen wurde.
Erwäge diese Schutzmaßnahmen:
/memories beginnen../, ..\\ oder andere Traversal-Muster enthalten%2e%2e%2f)pathlib.Path.resolve() und relative_to())Das Memory-Tool verwendet ähnliche Fehlerbehandlungsmuster wie das Texteditor-Tool. Die Fehlermeldungen jedes Befehls sind unter Tool-Befehle aufgeführt. Um einen Fehler an Claude zurückzugeben, setze is_error im Tool-Ergebnis auf true und schreibe die Meldung in content:
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Error: The path /memories/notes.txt does not exist",
"is_error": true
}Das Memory-Tool lässt sich mit Context Editing kombinieren, um lang laufende Konversationen zu verwalten. Details findest du unter Context Editing.
Das Memory-Tool kann auch mit Compaction kombiniert werden, das älteren Konversationskontext serverseitig zusammenfasst. Context Editing löscht bestimmte Tool-Ergebnisse auf dem Client. Compaction fasst die gesamte Konversation automatisch auf dem Server zusammen, wenn sich die Konversation dem Limit des Kontextfensters nähert.
Für lang laufende Agenten 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 überleben müssen.
Für Softwareprojekte, die sich über mehrere Agent-Sitzungen erstrecken, richte Memory-Dateien gezielt ein, anstatt sie ad hoc während der Arbeit zu schreiben. Das folgende Muster macht Memory zu einem Wiederherstellungsmechanismus: Jede neue Sitzung setzt bei dem Zustand fort, den die letzte aufgezeichnet hat.
Initialisierungssitzung: Die erste Sitzung richtet die Memory-Dateien ein, bevor substanzielle Arbeit beginnt. Dazu gehören ein Fortschrittsprotokoll (das verfolgt, was erledigt wurde und was als Nächstes kommt), eine Feature-Checkliste (die den Arbeitsumfang definiert) und ein Verweis auf jedes Start- oder Initialisierungsskript, das das Projekt benötigt.
Nachfolgende Sitzungen: Jede neue Sitzung beginnt mit dem Lesen dieser Memory-Dateien. Dies stellt den Projektzustand wieder her, 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. Dies stellt sicher, dass die nächste Sitzung einen genauen Ausgangspunkt hat.
Arbeite an einem Feature nach dem anderen. Markiere ein Feature erst dann als abgeschlossen, wenn eine End-to-End-Verifizierung bestätigt, dass es funktioniert, nicht wenn der Code geschrieben ist. Dadurch bleibt das Fortschrittsprotokoll von Sitzung zu Sitzung korrekt.
Führe Shell-Befehle in einer persistenten Bash-Sitzung aus.
Verwalte den Konversationskontext automatisch mit Context Editing, während er wächst.
Serverseitige Kontext-Compaction zur Verwaltung langer Konversationen, die sich den Limits des Kontextfensters nähern.
Verzeichnis der von Anthropic bereitgestellten Tools und Referenz für optionale Eigenschaften der Tool-Definition.
Was this page helpful?