Persistentes Gedächtnis für Claude Code: Wie sitzungsübergreifender Kontext tatsächlich funktioniert

Das Kernproblem: Sitzungen sind konstruktionsbedingt zustandslos

Eine Claude Code-Sitzung ist ein Gespräch. Wenn sie endet, wird das Transkript archiviert, und der Arbeitskontext — das über Dutzende Tool-Aufrufe aufgebaute Verständnis — verflüchtigt sich. Die nächste Sitzung rekonstruiert den Kontext aus drei Quellen:

• Ihre CLAUDE.md files (project and user scope)
• Alle Dateien, die Claude während der Sitzung liest
• Was Sie eingeben

Keine dieser Quellen erfasst abgeleitetes Wissen: die Sackgassen, die Sie bereits erkundet haben, den Grund für einen seltsamen Workaround oder die Tatsache, dass Sie Ansatz A ausprobiert haben und dadurch die CI fehlgeschlagen ist. Dieses Wissen erneut herzuleiten, kostet in jeder einzelnen Sitzung Tokens und Echtzeit.

Der naheliegende Impuls ist, eine Gedächtnisschicht aufzubauen — festhalten, was passiert ist, es verdichten und den relevanten Ausschnitt beim Start wieder einspeisen. Das Open-Source- claude-mem Projekt ist eine saubere Referenzimplementierung genau dieses Musters, und es lohnt sich, es zu studieren, unabhängig davon, ob Sie es einsetzen.

Das Architekturmuster hinter dem persistenten Gedächtnis von Claude Code

Jeder ernstzunehmende Ansatz für persistentes Gedächtnis in Claude Code folgt demselben dreistufigen Zyklus. Wenn Sie die Phasen einzeln verstehen, können Sie jede davon selbst entwickeln, einkaufen oder überspringen.

Phase 1: Erfassen

Sie müssen beobachten, was in einer Sitzung passiert ist. Claude Code bietet für den Lebenszyklus Hooks – Shell-Befehle, die bei Ereignissen ausgeführt werden. Die relevanten sind:

Ein minimaler Erfassungs-Hook in .claude/settings.json:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/mem/capture.sh"
          }
        ]
      }
    ]
  }
}

Der Hook empfängt über stdin JSON, das das Ereignis beschreibt. Bei SessionEnd erhalten Sie die Sitzungs-ID und den Pfad zum Transkript, sodass capture.sh das vollständige Gesprächsprotokoll lesen kann:

#!/usr/bin/env bash
INPUT=$(cat)
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')

# Hand the raw transcript to the compression stage
python3 "$CLAUDE_PROJECT_DIR/.claude/mem/compress.py" \
  --transcript "$TRANSCRIPT" \
  --session "$SESSION_ID"

Ein häufiger Fallstrick: Hooks werden mit einem Zeitlimit ausgeführt, und ein großes Transkript, das synchron an ein LLM übergeben wird, überschreitet dieses Limit. In der Praxis sollte die Erfassung ohne Warten auf das Ergebnis erfolgen: Schreiben Sie den Transkriptpfad in eine Warteschlange und verarbeiten Sie ihn in einem Hintergrund-Worker, statt direkt im Hook.

Phase 2: Verdichten

Rohe Transkripte sind als Gedächtnis unbrauchbar – sie sind riesig und voller irrelevanter Inhalte (Dateiausgaben, massenhafte Tool-Ausgaben, Ihre Tippfehler). In der Verdichtungsphase extrahiert ein LLM aus der Sitzung dauerhaft relevante Fakten. Dafür setzen Sie einen Aufruf von Haiku 4.5 ein, keinen von Opus – Zusammenfassungen sind genau die Art von Aufgabe mit hohem Volumen und geringem Risiko, auf die die Preise von Haiku ausgelegt sind.

import anthropic

client = anthropic.Anthropic()

PROMPT = """You are a memory compressor. From this coding session
transcript, extract ONLY durable facts worth remembering next session:
- Architectural decisions and their rationale
- Conventions discovered (naming, error handling, imports)
- Dead ends already explored (so we don't repeat them)
- Unresolved TODOs

Output JSON: a list of {fact, category, files[], confidence}.
Omit anything transient. If nothing durable happened, output []."""

resp = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=1500,
    system=PROMPT,
    messages=[{"role": "user", "content": transcript_text}],
)
memories = resp.content[0].text

Beachten Sie das confidence Feld und die ausdrückliche Anweisung zur Ausgabe von []. Beides dient dazu, die Folgen des Fehlers zu begrenzen, auf den wir noch eingehen. Speichern Sie die Ausgabe an einem Ort, der Abfragen ermöglicht – in SQLite mit einer Embedding-Spalte oder in einem Vektorspeicher mit Projekt- und Dateipfaden als Schlüssel.

Phase 3: Einfügen

Zu Beginn einer Sitzung rufen Sie die relevanten Gedächtnisinhalte ab und fügen sie ein. Der SessionStart Hook kann auf stdout schreiben, und diese Ausgabe wird dem Kontext von Claude hinzugefügt:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/mem/inject.sh" }
        ]
      }
    ]
  }
}

Die entscheidende technische Frage ist die Relevanzfilterung. Alle Gedächtnisinhalte einzufügen ist der naive Ansatz, und er ist falsch – er bläht Ihren Kontext auf und lässt die nützlichen Fakten untergehen. Besser: Rufen Sie Inhalte danach ab, worum es in der Sitzung voraussichtlich geht. Wenn Sie das noch nicht erkennen können, fügen Sie nur projektweite Fakten mit hoher Konfidenz ein und stellen Sie den Rest über einen MCP-Server bereit, damit Claude Gedächtnisinhalte bei Bedarf abfragen kann:

# A tiny MCP tool the agent calls when it wants history
@mcp.tool()
def recall(query: str, files: list[str] = []) -> list[dict]:
    """Retrieve relevant memories about this codebase."""
    return memory_store.search(query, files=files, min_confidence=0.6)

Dieses Pull-Modell schlägt in der Praxis das Push-Modell. Statt beim Start zu erraten, was relevant ist, lassen Sie den Agenten genau dann fragen, wenn es darauf ankommt: „Haben wir diesen Abrechnungscode schon einmal bearbeitet?“ Der Hook stellt eine kleine, stets verfügbare Zusammenfassung bereit; der MCP-Server übernimmt den gezielten Abruf.

Wo das scheitert – und es scheitert tatsächlich

Ich habe Gedächtnisschichten lange genug betrieben, um ihnen skeptisch gegenüberzustehen. Die Fehler sind real und verstärken sich gegenseitig.

KI-verdichtete Gedächtnisinhalte halluzinieren. Das Modell, das die Verdichtung übernimmt, ist selbst ein Sprachmodell. Gelegentlich hält es eine „Entscheidung“ fest, die eigentlich eine verworfene Idee war, oder kehrt die Begründung für eine Wahl ins Gegenteil um. Dann werden beim Start autoritativ klingende, falsche Gedächtnisinhalte eingefügt, und der Agent vertraut ihnen mehr, als er sollte. Das ist schlimmer als gar kein Gedächtnis, weil es mit großer Sicherheit falsch liegt. Das confidence Feld und eine menschliche Prüfung des Gedächtnisspeichers sind die einzigen wirksamen Gegenmaßnahmen.

Veralteter Kontext ist eine stille Gefahr. Sie refaktorieren UserService am Dienstag. Ihr Gedächtnis vom Montag sagt immer noch: „Die Authentifizierung liegt in UserService.“ Nichts erklärt diese Information für ungültig. Gedächtnisinhalte verlieren an Genauigkeit, sobald sich der Code ändert, und es gibt kein eindeutiges Signal, um sie ablaufen zu lassen. Verknüpfen Sie Gedächtnisinhalte mit Datei-Hashes oder Commit-SHAs und betrachten Sie sie als fragwürdig, wenn die zugrunde liegende Datei verschoben wird.

Die Token-Kosten steigen bei jeder Sitzung. Eingefügte Gedächtnisinhalte sind Kontext, für den Sie bei jedem Dialogschritt bezahlen, unabhängig davon, ob er verwendet wird. Eine Gedächtnisschicht, die beim Start 4K Tokens einfügt, erhöht Ihre Eingabekosten für die gesamte Sitzung um diese Menge. Das Pull-basierte MCP-Modell hilft, aber Erfassung und Verdichtung verursachen ebenfalls laufende Kosten.

Hier ist der ehrliche Vergleich:

Die unbequeme Wahrheit: Sie brauchen es wahrscheinlich nicht

Bevor Sie irgendetwas davon entwickeln, schreiben Sie eine gute CLAUDE.md. Eine von Hand gepflegte Datei, in der steht: „Wir verwenden Result<T>, niemals Exceptions werfen; UserService darf billing/nicht importieren; die Authentifizierung wurde nach auth/ im zweiten Quartal verschoben“, löst 80% des Gedächtnisproblems ohne Halluzinationsrisiko und mit deterministischen Kosten. Sie ist von Menschen verfasst und damit von Grund auf vertrauenswürdig.

Gedächtnisschichten rechtfertigen ihren Aufwand in einem engeren Einsatzbereich, als der Hype vermuten lässt: bei langwieriger, explorativer Arbeit, bei der sich das abgeleitetes Wissen (Sackgassen, halb abgeschlossene Untersuchungen) tatsächlich nicht im Voraus aufschreiben lässt, weil es noch nicht bekannt ist. Bei routinemäßiger Feature-Entwicklung deckt CLAUDE.md zusammen mit einigen MCP-Servern mit begrenztem Aufgabenbereich mehr ab als eine automatisierte Gedächtnispipeline und liefert Ihnen niemals falsche Angaben.

Wenn Sie die Pipeline tatsächlich entwickeln, kommt es in der Verdichtungsphase am stärksten auf die Kosten an: Häufige Zusammenfassungen mit Haiku sind günstig, aber nur, wenn die Preise pro Token von vornherein angemessen sind. Das ist einer der Gründe, warum Teams solche Hintergrundaufgaben mit hohem Volumen über Anbieter wie AI Prime Tech abwickeln.

Praktische Empfehlungen

• Sitzungen sind zustandslos. Abgeleitetes Wissen – Sackgassen, Begründungen, Konventionen – ist das, was tatsächlich verloren geht und dessen erneute Herleitung teuer ist.
• Das Muster lautet: erfassen → verdichten → einfügen. Verbinden Sie Erfassung und Einfügen über SessionEnd/SessionStart Hooks; führen Sie die Erfassung asynchron aus, um Hook-Zeitüberschreitungen zu vermeiden.
• Bevorzugen Sie Pull gegenüber Push. Stellen Sie beim Start eine sehr kurze Zusammenfassung bereit und bieten Sie dann ein recall MCP-Tool an, damit der Agent Gedächtnisinhalte nur dann abruft, wenn sie relevant sind.
• Verdichten Sie mit Haiku 4.5, versehen Sie jeden Gedächtniseintrag mit einer Konfidenzangabe und Hashes der Quelldateien und betrachten Sie Gedächtnisinhalte als fragwürdig, wenn sich Dateien ändern.
• Automatisiertes Gedächtnis kann lügen. Halluzinierter und veralteter Kontext ist schlimmer als gar keiner, weil er autoritativ wirkt. Beziehen Sie bei der Pflege des Gedächtnisspeichers einen Menschen ein.
• Probieren Sie CLAUDE.md zuerst aus. Für die meisten Projekte ist eine handgeschriebene Kontextdatei zusammen mit Tools mit begrenztem Aufgabenbereich einer vollständigen Gedächtnisschicht bei Kosten, Vertrauenswürdigkeit und Wartung überlegen – greifen Sie nur dann zu Persistenz, wenn Ihre Arbeit tatsächlich langwierig und explorativ ist.