Speicherwerkzeug

Das Speicherwerkzeug ermöglicht Claude, Informationen über Gespräche hinweg durch ein Speicherdateiverzeichnis zu speichern und abzurufen. Claude kann Dateien erstellen, lesen, aktualisieren und löschen, die zwischen Sitzungen bestehen bleiben, sodass es im Laufe der Zeit Wissen 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 Speicher 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 Laden von allem auf einmal das Kontextfenster überlasten würde. Siehe Effective context engineering für das umfassendere Muster.

Das Speicherwerkzeug funktioniert auf der Client-Seite: 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
• Gesprächsübergreifendes Lernen ermöglichen, bei dem Claude bei wiederkehrenden Workflows besser wird

Funktionsweise

Wenn aktiviert, prüft Claude automatisch sein Speicherverzeichnis, bevor er Aufgaben startet. Claude kann Dateien im Verzeichnis /memories 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 Werkzeug ist, führt Claude Werkzeugaufrufe durch, um Speicheroperationen auszuführen, und Ihre Anwendung führt diese Operationen lokal aus. Dies gibt Ihnen vollständige Kontrolle darüber, wo und wie der Speicher gespeichert wird. Aus Sicherheitsgründen sollten Sie alle Speicheroperationen auf das Verzeichnis /memories beschränken.

Beispiel: Wie Speicherwerkzeugaufrufe funktionieren

Wenn Sie Claude bitten, bei einer Aufgabe zu helfen, prüft Claude automatisch zuerst sein Speicherverzeichnis. So sieht eine typische Interaktion aus:

1. Benutzeranfrage:

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

2. Claude prüft das Speicherverzeichnis:

"Ich helfe dir, auf das Kundenservice-Ticket zu antworten. Lass mich meinen Speicher auf vorherigen Kontext prüfen."

Claude ruft das Speicherwerkzeug 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 die Erinnerung, 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 Speicherwerkzeug zu verwenden:

1. Fügen Sie das Speicherwerkzeug zu Ihrer Anfrage hinzu
2. Implementieren Sie Client-seitige Handler für Speicheroperationen

Grundlegende Verwendung

Werkzeugbefehle

Ihre Client-seitige Implementierung muss diese Speicherwerkzeugbefehle handhaben. 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: view specific lines
}

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 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: Geben Sie einen Fehler zurück (nicht überschreiben): "Error: The destination {new_path} already exists"

Verzeichnisbehandlung

Benennt das Verzeichnis um.

Anleitung zum Prompting

Diese Anweisung wird automatisch in die Systemaufforderung aufgenommen, wenn das Speicherwerkzeug 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 Speicherdateien erstellt, können Sie diese Anweisung einbeziehen:

Hinweis: Versuchen Sie beim Bearbeiten Ihres Speicherordners, seinen Inhalt 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 notwendig.

Sie können auch lenken, was Claude im Speicher schreibt. Zum Beispiel: „Schreiben Sie nur Informationen relevant zu <topic> in Ihr Speichersystem."

Sicherheitsaspekte

Hier sind wichtige Sicherheitsbedenken bei der Implementierung Ihres Speicherspeichers:

Sensible Informationen

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

Speicherdateigröße

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

Speicherablauf

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

Schutz vor Pfadtraversal

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 Speicherverzeichnis bleiben
• Lehnen Sie Pfade ab, die Sequenzen wie ../, ..\\ oder andere Traversal-Muster enthalten
• Achten Sie auf URL-kodierte Traversal-Sequenzen (%2e%2e%2f)
• Verwenden Sie die integrierten Pfadsicherheitsdienstprogramme Ihrer Sprache (z. B. Pythons pathlib.Path.resolve() und relative_to())

Fehlerbehandlung

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

Kontextbearbeitungsintegration

Das Speicherwerkzeug wird mit der Kontextbearbeitung kombiniert, um lange Gespräche zu verwalten. Weitere Informationen finden Sie unter Kontextbearbeitung.

Verwendung mit Komprimierung

Das Speicherwerkzeug kann auch mit Komprimierung kombiniert werden, die eine serverseitige Zusammenfassung des älteren Gesprächskontexts bietet. Während die Kontextbearbeitung bestimmte Werkzeugergebnisse 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 der Speicher behält wichtige Informationen über Komprimierungsgrenzen hinweg bei, sodass nichts Kritisches in der Zusammenfassung verloren geht.

Softwareentwicklungsmuster für mehrere Sitzungen

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

Funktionsweise

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

2. Nachfolgende Sitzungen: Jede neue Sitzung beginnt mit dem Lesen dieser Speicherartefakte. 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. Aktualisierung am Ende der Sitzung: 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 einer Funktion gleichzeitig. Markieren Sie eine Funktion nur als abgeschlossen, nachdem die End-to-End-Verifizierung bestätigt hat, dass sie funktioniert, nicht nur, nachdem der Code geschrieben wurde. Dies hält das Fortschrittsprotokoll zuverlässig und verhindert, dass Scope Creep sich über Sitzungen hinweg verschärft.

Nächste Schritte