Memory-Tool

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 „just-in-time context retrieval" (bedarfsgesteuerten 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 bei lang laufenden 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.



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, ü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 den 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 benutzerspezifisches Verzeichnis 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. Aus Sicherheitsgründen solltest du alle Memory-Operationen auf das Verzeichnis /memories beschränken (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 ü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-Modellen und neueren Modellen verfügbar. Die vollständige Liste der von Anthropic bereitgestellten Tools findest du in der Tool-Referenz.



Erste Schritte

Das Memory-Tool ist allgemein über die Messages API verfügbar: Es ist kein Beta-Header erforderlich. Die Verwendung erfordert zwei Schritte:

1. Füge das Memory-Tool zu deiner Anfrage hinzu. Der tools-Eintrag {"type": "memory_20250818", "name": "memory"} ist die gesamte Konfiguration: Der name muss memory sein, und du definierst kein Input-Schema für ein von Anthropic bereitgestelltes Tool.
2. Implementiere einen clientseitigen Handler für jeden Memory-Befehl. Dein Handler muss Pfade außerhalb von /memories ablehnen, lies also Schutz vor Path Traversal, bevor du ihn schreibst.



Grundlegende Verwendung

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    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 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. Erstelle eine Unterklasse von BetaAbstractMemoryTool (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 Helfer- und Tool-Runner-Schnittstellen 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 mit dem 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-4-8",
    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 geschlossen: Jeder verzweigt anhand des command-Felds im input des tool_use-Blocks und gibt die unter Tool-Befehle beschriebenen Strings zurück. Ein produktiver Handler 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 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 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 Textdatei-Ansichten: [start_line, end_line] gibt diese Zeilen zurück, und [start_line, -1] gibt alles ab start_line bis zum Ende der Datei zurück.



Rückgabewerte

Für Verzeichnisse: Gib eine Auflistung zurück, die Dateien und Verzeichnisse mit ihren Größen zeigt:

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 (zum Beispiel 5.5K, 1.2M)
• Schließt versteckte Elemente (Dateien, die mit . beginnen) und node_modules aus
• Verwendet ein Tabulatorzeichen zwischen Größe und Pfad

Das erste view von /memories auf einem leeren Speicher ist kein Fehler. Die lokalen Dateisystem-Memory-Tools der SDKs (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 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-indiziert (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 hundred

Claudes 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.



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 Pfaden, die bereits existieren. Den Fehler zurückzugeben 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_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"



Verzeichnisbehandlung

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}]"



Verzeichnisbehandlung

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"



Verzeichnisbehandlung

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.



rename

Benennt eine Datei oder ein Verzeichnis um oder verschiebt sie:

{
  "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"



Verzeichnisbehandlung

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.



Prompting-Hinweise

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 ins Memory schreibt. Zum Beispiel: „Schreibe nur Informationen, die für <topic> relevant sind, in dein Memory-System."



Sicherheitsüberlegungen

Deine Anwendung führt jede Dateioperation aus, die Claude anfordert, daher liegen diese Schutzmaßnahmen in deiner Verantwortung:



Sensible Informationen

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.



Dateispeichergröße

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 durchblättern.



Memory-Ablauf

Lösche regelmäßig Memory-Dateien, auf die lange nicht zugegriffen wurde.



Schutz vor Path Traversal

Berücksichtige diese Schutzmaßnahmen:

• Validiere, dass alle Pfade mit /memories beginnen
• Löse Pfade in ihre kanonische Form auf und überprüfe, dass sie innerhalb des Memory-Verzeichnisses bleiben
• Lehne Pfade ab, die Sequenzen wie ../, ..\\ oder andere Traversal-Muster enthalten
• Achte auf URL-codierte Traversal-Sequenzen (%2e%2e%2f)
• Verwende die integrierten Pfadsicherheits-Utilities deiner Sprache (zum Beispiel Pythons pathlib.Path.resolve() und relative_to())



Fehlerbehandlung

Das Memory-Tool verwendet ähnliche Fehlerbehandlungsmuster wie das Text-Editor-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
}



Integration mit Context Editing

Das Memory-Tool lässt sich mit „context editing" (Kontextbearbeitung) kombinieren, um lang laufende Konversationen zu verwalten. Details findest du unter Context Editing.



Verwendung mit Compaction

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 automatisch die gesamte Konversation auf dem Server zusammen, wenn sich die Konversation 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 überdauern müssen.



Muster für sitzungsübergreifende Softwareentwicklung

Für Softwareprojekte, die sich über mehrere Agent-Sitzungen erstrecken, richte Memory-Dateien bewusst ein, anstatt sie ad hoc zu schreiben, während die Arbeit voranschreitet. Das folgende Muster macht Memory zu einem Wiederherstellungsmechanismus: Jede neue Sitzung setzt bei dem Zustand fort, den die letzte aufgezeichnet hat.



Wie das Muster funktioniert

1. Initialisierungssitzung: Die erste Sitzung richtet die Memory-Dateien ein, bevor substanzielle 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.

2. Nachfolgende Sitzungen: Jede neue Sitzung beginnt mit dem Lesen dieser Memory-Dateien. Dadurch wird der Projektzustand wiederhergestellt, ohne die Codebasis erneut zu erkunden oder frühere Entscheidungen nachzuvollziehen.

3. 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 genauen Ausgangspunkt.



Grundprinzip

Arbeite an jeweils einem Feature. Markiere ein Feature erst als abgeschlossen, nachdem eine End-to-End-Verifizierung bestätigt hat, dass es funktioniert, nicht wenn der Code geschrieben ist. So bleibt das Fortschrittsprotokoll von Sitzung zu Sitzung korrekt.



Nächste Schritte