Memory-Tool

Das Memory-Tool lässt Claude Informationen über Gespräche hinweg in einem Verzeichnis von Memory-Dateien speichern und abrufen. 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-Kontextabruf. Anstatt alle relevanten Informationen im Voraus zu laden, zeichnet ein Agent das, was er lernt, in Memory-Dateien auf und liest sie bei Bedarf zurück. Dadurch bleibt der aktive Kontext auf die aktuelle Aufgabe fokussiert, was für langlaufende Sitzungen wichtig ist, die andernfalls das Kontextfenster überlasten würden. Siehe Effektives Kontext-Engineering für das umfassendere 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
• Lektionen aus vergangenen 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 es arbeitet, speichert Claude das, was es lernt, in Dateien unter /memories und liest sie in späteren Gesprächen zurück, um frühere Arbeit fortzusetzen.

Da das Memory-Tool clientseitig ist, fordert Claude nur Memory-Operationen an. Deine Anwendung führt jede Anfrage gegen 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. Ein späteres Gespräch setzt vom selben Memory fort, wenn es denselben tools-Eintrag sendet und dein Handler denselben Speicher bedient. Aus Sicherheitsgründen beschränke 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 ü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.

Erste Schritte

Die Verwendung des Memory-Tools erfolgt in zwei Schritten:

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 Eingabeschema 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-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 und gibt das Ergebnis in einem tool_result-Block zurück, sendet dann das Gespräch zurück, damit Claude fortfahren kann: die standardmäßige Tool-Nutzungs-Schleife.

Vier SDKs bieten Memory-Tool-Helfer, die die Tool-Schnittstelle und die Schleife verarbeiten. 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 lokale Dateisystem-Implementierung, BetaLocalFilesystemMemoryTool. Die Helfer- und Tool-Runner-Oberflächen leben im Beta-Namespace jedes SDKs, obwohl das Memory-Tool selbst keinen Beta-Header erfordert. Die Go- und Ruby-SDKs haben keinen Memory-Helfer, daher führen diese Beispiele die Tool-Nutzungs-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-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 eigenständig: Jeder verteilt 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 überspringen. Die vollständigen eigenen 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, welchen Text auch immer dein Tool-Ergebnis enthält, sodass du andere Strings zurückgeben kannst, wenn deine Anwendung dies benötigt.

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 von 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 der Größe und dem Pfad

Die erste view von /memories bei einem leeren Speicher ist kein Fehler. Die lokalen Dateisystem-Memory-Tools der SDKs (BetaLocalFilesystemMemoryTool) erstellen das Memory-Root vor Claudes erstem Aufruf und geben den Auflistungs-Header gefolgt von einer einzelnen Größen-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:

• Breite: 6 Zeichen, rechtsbündig mit Leerzeichen-Auffüllung
• Trennzeichen: Tabulatorzeichen zwischen Zeilennummer und Inhalt
• Indizierung: 1-indiziert (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 hundred

Claudes Tool-Beschreibung besagt außerdem, dass view Bilddateien (.jpg, .jpeg und .png) anzeigt und die Textansicht von Dateien, die länger als 16.000 Zeichen sind, abschneidet. Erwarte view-Aufrufe auf Bildpfaden und nachfolgende bereichsbasierte 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“, erwarte also create-Aufrufe auf Pfaden, die bereits existieren. 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 Ersetzung 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 mehrmals 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-Root 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-Root ist.

Prompting-Anleitung

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, sodass du diese Anweisung nicht wiederholen musst. Wenn Claude dennoch unübersichtliche Memory-Dateien erstellt, kannst du es 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.“

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, zu begrenzen, wie viele Zeichen 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

Erwäge 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 Pfad-Sicherheitsdienstprogramme deiner Sprache (zum Beispiel Pythons pathlib.Path.resolve() und relative_to())

Fehlerbehandlung

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 platziere 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 der Kontextbearbeitung

Das Memory-Tool lässt sich mit der Kontextbearbeitung kombinieren, um langlaufende Gespräche zu verwalten. Details findest du unter Kontextbearbeitung.

Verwendung mit Kompaktierung

Das Memory-Tool kann auch mit Kompaktierung kombiniert werden, die älteren Gesprächskontext serverseitig zusammenfasst. Die Kontextbearbeitung löscht bestimmte Tool-Ergebnisse auf dem Client. Die Kompaktierung fasst das gesamte Gespräch automatisch auf dem Server zusammen, wenn sich das Gespräch dem Limit des Kontextfensters nähert.

Für langlaufende Agenten erwäge, beides zu verwenden: Die Kompaktierung hält den aktiven Kontext klein ohne clientseitige Buchführung, und Memory bewahrt die Informationen, die die Zusammenfassung überleben müssen.

Muster für Softwareentwicklung über mehrere Sitzungen

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 verwandelt Memory in einen Wiederherstellungsmechanismus: Jede neue Sitzung setzt von 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 verfolgt, was getan wurde und was als Nächstes kommt), eine Feature-Checkliste (die den Arbeitsumfang definiert) und ein Verweis auf jedes Startup- oder Initialisierungsskript, das das Projekt benötigt.

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

3. Aktualisierung am Sitzungsende: Bevor eine Sitzung endet, aktualisiert sie das Fortschrittsprotokoll mit dem, was abgeschlossen wurde und was verbleibt. Dies stellt sicher, dass die nächste Sitzung einen genauen Ausgangspunkt hat.

Schlüsselprinzip

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. Dies hält das Fortschrittsprotokoll von Sitzung zu Sitzung genau.

Nächste Schritte