Memory-Tool

Das Memory-Tool ermöglicht es 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, wodurch es im Laufe der Zeit Wissen aufbauen kann, ohne alles im Kontextfenster zu behalten.

Das Memory-Tool arbeitet clientseitig – 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 sich bei wiederkehrenden Arbeitsabläufen verbessert

Wie es funktioniert

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

Da dies ein clientseitiges Tool ist, führt Claude Tool-Aufrufe durch, um Memory-Operationen durchzufü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, überprüft Claude automatisch zuerst sein Memory-Verzeichnis. So sieht eine typische Interaktion aus:

1. Benutzeranfrage:

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

2. Claude überprüft das Memory-Verzeichnis:

"Ich helfe Ihnen, auf das Kundenservice-Ticket zu antworten. Lassen Sie mich mein Memory nach vorherigem Kontext durchsuchen."

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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude verwendet das Memory zur Hilfe:

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

Unterstützte Modelle

Das Memory-Tool ist verfügbar auf:

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

Erste Schritte

Um das Memory-Tool zu verwenden:

1. Fügen Sie den Beta-Header context-management-2025-06-27 in Ihre API-Anfragen ein
2. Fügen Sie das Memory-Tool zu Ihrer Anfrage hinzu
3. Implementieren Sie clientseitige Handler für Memory-Operationen

Grundlegende Verwendung

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Ich arbeite an einem Python-Web-Scraper, der ständig mit einem Timeout-Fehler abstürzt. Hier ist die problematische Funktion:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nBitte hilf mir, das zu debuggen."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

Tool-Befehle

Ihre clientseitige Implementierung muss diese Memory-Tool-Befehle handhaben:

view

Zeigt Verzeichnisinhalte oder Dateiinhalte mit optionalen Zeilenbereichen an:

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

create

Eine Datei erstellen oder überschreiben:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Besprechungsnotizen:\n- Projektzeitplan besprochen\n- Nächste Schritte definiert\n"
}

str_replace

Text in einer Datei ersetzen:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Lieblingsfarbe: blau",
  "new_str": "Lieblingsfarbe: grün"
}

insert

Text an einer bestimmten Zeile einfügen:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Memory-Tool-Dokumentation überprüfen\n"
}

delete

Eine Datei oder ein Verzeichnis löschen:

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

rename

Eine Datei/ein Verzeichnis umbenennen oder verschieben:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

Prompting-Anleitung

Wir fügen automatisch diese Anweisung zum System-Prompt hinzu, wenn das Memory-Tool enthalten ist:

WICHTIG: SCHAUEN SIE IMMER ZUERST IN IHR MEMORY-VERZEICHNIS, BEVOR SIE ETWAS ANDERES TUN.
MEMORY-PROTOKOLL:
1. Verwenden Sie den `view`-Befehl Ihres `memory`-Tools, um nach früherem Fortschritt zu suchen.
2. ... (an der Aufgabe arbeiten) ...
     - Während Sie Fortschritte machen, zeichnen Sie Status / Fortschritt / Gedanken etc. in Ihrem Memory auf.
UNTERBRECHUNG ANNEHMEN: Ihr Kontextfenster könnte jederzeit zurückgesetzt werden, daher riskieren Sie, jeden Fortschritt zu verlieren, der nicht in Ihrem Memory-Verzeichnis aufgezeichnet ist.

Wenn Sie beobachten, dass Claude unübersichtliche Memory-Dateien erstellt, können Sie diese Anweisung einschließen:

Hinweis: Beim Bearbeiten Ihres Memory-Ordners versuchen Sie immer, dessen 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, es sei denn, es ist notwendig.

Sie können auch leiten, was Claude in das Memory schreibt, z.B. "Schreiben Sie nur Informationen auf, die für <Thema> relevant sind, 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. Jedoch möchten Sie möglicherweise eine strengere Validierung implementieren, die potenziell sensible Informationen herausfiltert.

Dateispeichergröße

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

Pfad-Traversal-Schutz

Erwägen Sie diese Schutzmaßnahmen:

• Validieren Sie, dass alle Pfade mit /memories beginnen
• Lösen Sie Pfade zu ihrer kanonischen Form auf und überprüfen Sie, dass sie innerhalb des Memory-Verzeichnisses 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 eingebauten Pfad-Sicherheitsdienstprogramme Ihrer Sprache (z.B. Pythons pathlib.Path.resolve() und relative_to())

Fehlerbehandlung

Das Memory-Tool verwendet die gleichen Fehlerbehandlungsmuster wie das Text-Editor-Tool. Häufige Fehler umfassen Datei nicht gefunden, Berechtigungsfehler und ungültige Pfade.

Verwendung mit Context Editing

Das Memory-Tool kann mit Context Editing kombiniert werden, das automatisch alte Tool-Ergebnisse löscht, wenn der Gesprächskontext über einen konfigurierten Schwellenwert hinauswächst. Diese Kombination ermöglicht langanhaltende agentische Arbeitsabläufe, die andernfalls die Kontextgrenzen überschreiten würden.

Wie sie zusammenarbeiten

Wenn Context Editing aktiviert ist und Ihr Gespräch sich dem Löschschwellenwert nähert, erhält Claude automatisch eine Warnbenachrichtigung. Dies veranlasst Claude, wichtige Informationen aus Tool-Ergebnissen in Memory-Dateien zu bewahren, bevor diese Ergebnisse aus dem Kontextfenster gelöscht werden.

Nachdem Tool-Ergebnisse gelöscht wurden, kann Claude die gespeicherten Informationen aus Memory-Dateien abrufen, wann immer sie benötigt werden, und behandelt Memory effektiv als Erweiterung seines Arbeitskontexts. Dies ermöglicht es Claude:

• Komplexe, mehrstufige Arbeitsabläufe fortzusetzen, ohne kritische Informationen zu verlieren
• Auf vergangene Arbeit und Entscheidungen zu verweisen, auch nachdem Tool-Ergebnisse entfernt wurden
• Kohärenten Kontext über Gespräche hinweg zu bewahren, die typische Kontextgrenzen überschreiten würden
• Im Laufe der Zeit eine Wissensdatenbank aufzubauen, während das aktive Kontextfenster handhabbar bleibt

Beispiel-Arbeitsablauf

Betrachten Sie ein Code-Refactoring-Projekt mit vielen Dateioperationen:

1. Claude nimmt zahlreiche Änderungen an Dateien vor und generiert viele Tool-Ergebnisse
2. Während der Kontext wächst und sich Ihrem Schwellenwert nähert, erhält Claude eine Warnung
3. Claude fasst die bisher vorgenommenen Änderungen in einer Memory-Datei zusammen (z.B. /memories/refactoring_progress.xml)
4. Context Editing löscht die älteren Tool-Ergebnisse automatisch
5. Claude arbeitet weiter und verweist auf die Memory-Datei, wenn es sich daran erinnern muss, welche Änderungen bereits abgeschlossen wurden
6. Der Arbeitsablauf kann unbegrenzt fortgesetzt werden, wobei Claude sowohl aktiven Kontext als auch persistentes Memory verwaltet

Konfiguration

Um beide Funktionen zusammen zu verwenden:

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Ihre anderen Tools
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

Sie können auch Memory-Tool-Aufrufe vom Löschen ausschließen, um sicherzustellen, dass Claude immer Zugang zu aktuellen Memory-Operationen hat:

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}