Memory-Tool

Das Memory-Tool ermöglicht Claude, Informationen über Gespräche hinweg durch ein Memory-Dateiverzeichnis zu speichern und abzurufen. Claude kann Dateien erstellen, lesen, aktualisieren und löschen, die zwischen Sitzungen bestehen bleiben, sodass es Wissen im Laufe der Zeit aufbauen kann, ohne alles im Kontextfenster zu behalten.

Dies ist das Schlüsselelement für Just-in-Time-Kontextabruf: Anstatt alle relevanten Informationen im Voraus zu laden, speichern Agenten, was sie lernen, im Memory und rufen es bei Bedarf ab. Dies hält den aktiven Kontext auf das konzentriert, was derzeit relevant ist – entscheidend für langfristige Workflows, bei denen das gleichzeitige Laden aller Informationen das Kontextfenster überlasten würde. Siehe Effective context engineering für das umfassendere Muster.

Das Memory-Tool wird auf der Client-Seite ausgeführt: Sie kontrollieren, wo und wie die Daten durch Ihre eigene Infrastruktur gespeichert werden.

Anwendungsfälle

• Projektkontext über mehrere Agent-Ausführungen hinweg beibehalten
• Aus vergangenen Interaktionen, Entscheidungen und Feedback lernen
• Wissensdatenbanken im Laufe der Zeit aufbauen
• Konversationsübergreifendes Lernen ermöglichen, bei dem Claude bei wiederkehrenden Workflows besser wird

Funktionsweise

Wenn aktiviert, prüft Claude automatisch sein Memory-Verzeichnis, bevor Aufgaben gestartet werden. Claude kann Dateien im /memories-Verzeichnis erstellen, lesen, aktualisieren und löschen, um zu speichern, was es während der Arbeit lernt, und dann diese Erinnerungen in zukünftigen Gesprächen referenzieren, um ähnliche Aufgaben effektiver zu bewältigen oder dort weiterzumachen, wo es aufgehört hat.

Da dies ein Client-seitiges Tool ist, führt Claude Tool-Aufrufe durch, um Memory-Operationen auszuführen, und Ihre Anwendung führt diese Operationen lokal aus. Dies gibt Ihnen vollständige Kontrolle darüber, wo und wie das Memory gespeichert wird. Aus Sicherheitsgründen sollten Sie alle Memory-Operationen auf das /memories-Verzeichnis beschränken.

Beispiel: Wie Memory-Tool-Aufrufe funktionieren

Wenn Sie Claude bitten, bei einer Aufgabe zu helfen, prüft Claude automatisch zuerst sein Memory-Verzeichnis. Hier ist, wie eine typische Interaktion aussieht:

1. Benutzeranfrage:

"Hilf mir, auf dieses Kundenservice-Ticket zu antworten."

2. Claude prüft das Memory-Verzeichnis:

"Ich helfe dir, auf das Kundenservice-Ticket zu antworten. Lass mich mein Memory auf vorherigen Kontext überprüfen."

Claude ruft das Memory-Tool auf:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Ihre 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. Ihre 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:

"Basierend auf Ihren Kundenservice-Richtlinien kann ich Ihnen helfen, eine Antwort zu verfassen. Bitte teilen Sie die Ticket-Details mit..."

Für Modellunterstützung siehe die Tool-Referenz.

Erste Schritte

Um das Memory-Tool zu verwenden:

1. Fügen Sie das Memory-Tool zu Ihrer Anfrage hinzu
2. Implementieren Sie Client-seitige Handler für Memory-Operationen

Grundlegende Verwendung

Tool-Befehle

Ihre Client-seitige Implementierung muss diese Memory-Tool-Befehle verarbeiten. Während diese Spezifikationen die empfohlenen Verhaltensweisen beschreiben, mit denen Claude am besten vertraut ist, können Sie Ihre Implementierung ändern und Zeichenketten nach Bedarf für Ihren Anwendungsfall zurückgeben.

view

Zeigt Verzeichnisinhalte oder Dateiinhalte mit optionalen Zeilenbereichen an:

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10] // Optional: spezifische Zeilen anzeigen
}

Rückgabewerte

Für Verzeichnisse: Geben Sie 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}    {path}
{size}    {path}/{filename1}
{size}    {path}/{filename2}

• Listet Dateien bis zu 2 Ebenen tief auf
• Zeigt menschenlesbare Größen (z. B. 5.5K, 1.2M)
• Schließt versteckte Elemente (Dateien, die mit . beginnen) und node_modules aus
• Verwendet Tabulatorzeichen zwischen Größe und Pfad

Für Dateien: Geben Sie Dateiinhalte mit einer Kopfzeile und Zeilennummern zurück:

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Zeilennummernformatierung:

• Breite: 6 Zeichen, rechts ausgerichtet mit Leerzeichen-Auffüllung
• 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

Fehlerbehandlung

• Datei/Verzeichnis existiert nicht: "The path {path} does not exist. Please provide a valid path."

create

Erstellen Sie 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"

str_replace

Ersetzen Sie Text in einer Datei:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

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, geben Sie 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, geben Sie einen Fehler „Datei existiert nicht" zurück.

insert

Fügen Sie Text in einer bestimmten Zeile ein:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

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, geben Sie einen Fehler „Datei existiert nicht" zurück.

delete

Löschen Sie eine Datei oder ein Verzeichnis:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

Rückgabewerte

• Erfolg: "Successfully deleted {path}"

Fehlerbehandlung

• Datei/Verzeichnis existiert nicht: "Error: The path {path} does not exist"

Verzeichnisbehandlung

Löscht das Verzeichnis und seinen gesamten Inhalt rekursiv.

rename

Benennen Sie eine Datei/ein Verzeichnis um oder verschieben Sie 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: Geben Sie einen Fehler zurück (nicht überschreiben): "Error: The destination {new_path} already exists"

Verzeichnisbehandlung

Benennt das Verzeichnis um.

Prompting-Anleitung

Diese Anweisung wird automatisch in die Systemaufforderung aufgenommen, wenn das Memory-Tool aktiviert ist:

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.

Wenn Sie beobachten, dass Claude ungeordnete Memory-Dateien erstellt, können Sie diese Anweisung einbeziehen:

Hinweis: Versuchen Sie beim Bearbeiten Ihres Memory-Ordners, seinen Inhalt immer aktuell, kohärent und organisiert zu halten. Sie können Dateien umbenennen oder löschen, die nicht mehr relevant sind. Erstellen Sie keine neuen Dateien, wenn nicht nötig.

Sie können auch lenken, was Claude im Memory speichert. Zum Beispiel: „Schreiben Sie nur Informationen relevant zu <topic> in Ihr Memory-System."

Sicherheitsüberlegungen

Hier sind wichtige Sicherheitsbedenken bei der Implementierung Ihres Memory-Speichers:

Sensible Informationen

Claude wird normalerweise ablehnen, sensible Informationen in Memory-Dateien zu schreiben. Sie möchten jedoch möglicherweise eine strengere Validierung implementieren, die potenziell sensible Informationen entfernt.

Speichergröße von Dateien

Erwägen Sie, Memory-Dateigrößen zu verfolgen und zu verhindern, dass Dateien zu groß werden. Erwägen Sie, eine maximale Anzahl von Zeichen hinzuzufügen, die der Memory-Lesbefehl zurückgeben kann, und lassen Sie Claude durch Inhalte paginieren.

Memory-Ablauf

Erwägen Sie, Memory-Dateien regelmäßig zu löschen, auf die über einen längeren Zeitraum nicht zugegriffen wurde.

Schutz vor Pfad-Traversal

Erwägen Sie diese Schutzmaßnahmen:

• Validieren Sie, dass alle Pfade mit /memories beginnen
• Lösen Sie Pfade in ihre kanonische Form auf und überprüfen Sie, dass sie im Memory-Verzeichnis bleiben
• Lehnen Sie Pfade ab, die Sequenzen wie ../, ..\\ oder andere Traversal-Muster enthalten
• Achten Sie auf URL-codierte Traversal-Sequenzen (%2e%2e%2f)
• Verwenden Sie die integrierten Pfadsicherheitsdienstprogramme Ihrer Sprache (z. B. Pythons pathlib.Path.resolve() und relative_to())

Fehlerbehandlung

Das Memory-Tool verwendet ähnliche Fehlerbehandlungsmuster wie das Text-Editor-Tool. Siehe die einzelnen Tool-Befehlsabschnitte oben für detaillierte Fehlermeldungen und Verhaltensweisen. Häufige Fehler sind Datei nicht gefunden, Berechtigungsfehler, ungültige Pfade und doppelte Text-Übereinstimmungen.

Kontextbearbeitungsintegration

Das Memory-Tool wird mit Kontextbearbeitung gepaart, um lange Gespräche zu verwalten. Weitere Informationen finden Sie unter Kontextbearbeitung.

Verwendung mit Komprimierung

Das Memory-Tool kann auch mit Komprimierung gepaart werden, die serverseitige Zusammenfassung älterer Gesprächskontexte bietet. Während die Kontextbearbeitung spezifische Tool-Ergebnisse auf der Client-Seite löscht, fasst die Komprimierung automatisch das gesamte Gespräch auf der Server-Seite zusammen, wenn es sich dem Kontextfensterlimit nähert.

Für langfristige agentengesteuerte Workflows sollten Sie beide verwenden: Die Komprimierung hält den aktiven Kontext verwaltbar, ohne Client-seitige Buchführung, und Memory behält wichtige Informationen über Komprimierungsgrenzen hinweg bei, sodass nichts Kritisches in der Zusammenfassung verloren geht.

Multi-Session-Softwareentwicklungsmuster

Für langfristige Softwareprojekte, die mehrere Agent-Sitzungen umfassen, müssen Memory-Dateien absichtlich initialisiert werden, nicht nur ad hoc geschrieben, während die Arbeit fortschreitet. Das folgende Muster verwandelt Memory in einen strukturierten Wiederherstellungsmechanismus, sodass jede neue Sitzung genau dort weitermachen kann, wo die letzte endete.

Funktionsweise

1. Initializer-Sitzung: Die erste Sitzung richtet die Memory-Artefakte ein, bevor substantielle Arbeit beginnt. Dies umfasst ein Fortschrittsprotokoll (Verfolgung, was getan wurde und was als nächstes kommt), eine Feature-Checkliste (Definition des Arbeitsumfangs) und einen Verweis auf jedes Startup- oder Initialisierungsskript, das das Projekt benötigt.

2. Nachfolgende Sitzungen: Jede neue Sitzung beginnt mit dem Lesen dieser Memory-Artefakte. Dies stellt den vollständigen Zustand des Projekts in Sekunden wieder her, ohne den Codebase neu erkunden oder frühere Entscheidungen zurückverfolgen zu müssen.

3. End-of-Session-Update: Bevor eine Sitzung endet, aktualisiert sie das Fortschrittsprotokoll mit dem, was abgeschlossen wurde und was bleibt. Dies stellt sicher, dass die nächste Sitzung einen genauen Ausgangspunkt hat.

Schlüsselprinzip

Arbeiten Sie an einem Feature gleichzeitig. Markieren Sie ein Feature nur als abgeschlossen, nachdem eine End-to-End-Überprüfung bestätigt hat, dass es funktioniert, nicht nur nachdem der Code geschrieben wurde. Dies hält das Fortschrittsprotokoll zuverlässig und verhindert, dass Scope Creep sich über Sitzungen hinweg verstärkt.

Nächste Schritte