Memory & Kontext-Persistenz

Jede Claude-Code-Session beginnt mit einem leeren Kontextfenster. Damit Wissen trotzdem von einer Sitzung in die nächste überlebt, gibt es zwei Mechanismen: CLAUDE.md -Dateien, die du selbst schreibst, und Auto-Memory, in dem Claude eigene Notizen ablegt. Dieses Modul zeigt, wo diese Dateien liegen, in welcher Reihenfolge sie geladen werden und wie du Anweisungen formulierst, denen Claude zuverlässig folgt.

Wo Memory liegt und wie es geladen wird

Beide Systeme landen zu Beginn jeder Unterhaltung im Kontext — und beide sind für Claude Kontext, keine erzwungene Konfiguration. Für CLAUDE.md nennt die Dokumentation vier Orte: Managed Policy (organisationsweit, von der IT ausgerollt), Benutzeranweisungen in ~/.claude/CLAUDE.md, Projektanweisungen in ./CLAUDE.md oder ./.claude/CLAUDE.md und lokale Anweisungen in ./CLAUDE.local.md, die du in die .gitignore aufnimmst. Aufgelistet sind sie in Ladereihenfolge, vom breitesten zum speziellsten Geltungsbereich.

Diese Orte überschreiben einander nicht. Claude Code läuft vom Arbeitsverzeichnis aus den Verzeichnisbaum nach oben, sammelt jede gefundene CLAUDE.md und CLAUDE.local.md ein und hängt sie aneinander. Geordnet wird von der Dateisystem-Wurzel abwärts, sodass die Anweisungen direkt an deinem Arbeitsverzeichnis zuletzt gelesen werden; innerhalb eines Verzeichnisses steht CLAUDE.local.md hinter CLAUDE.md. Welche Dateien wirklich angekommen sind, zeigt dir /context unter „Memory files“.

In der Praxis: Ins Projekt-Memory gehört, was ein neuer Teamkollege bräuchte — Build- und Testbefehle, Konventionen, Architekturentscheidungen. Ins Benutzer-Memory gehört, wie du persönlich arbeitest, nicht was das Projekt tut. Und was nur dich und nur dieses Projekt betrifft, etwa eine Sandbox-URL oder deine Testdaten, landet in CLAUDE.local.md und bleibt aus der Versionsverwaltung heraus. Als Faustregel: Schreib auf, was du sonst ein zweites Mal erklären müsstest.

Wird eine einzelne Datei zu groß, teilst du die Anweisungen in .claude/rules/ auf — eine Markdown-Datei je Thema, rekursiv auch in Unterordnern. Mit dem Frontmatter-Feld paths bindest du eine Regel an bestimmte Dateien, sodass sie nur dann in den Kontext kommt, wenn Claude dort arbeitet:

---
paths: src/api/**/*.ts
---
All API endpoints must validate input with Zod. Return 400 with field-level errors on validation failure.

Eine solche pfad-gebundene Regel greift, sobald Claude eine passende Datei liest — nicht bei jedem Tool-Aufruf, der diese Datei berührt. Regeln ohne paths -Feld werden beim Start geladen, mit derselben Priorität wie .claude/CLAUDE.md. Persönliche Regeln unter ~/.claude/rules/ gelten für jedes Projekt auf deinem Rechner und werden vor den Projektregeln geladen, sodass Projektregeln Vorrang haben. Symlinks löst Claude Code dabei auf; zirkuläre Verweise erkennt es und behandelt sie sauber.

Memory anlegen und pflegen

Am schnellsten kommst du mit /init zu einer ersten CLAUDE.md: Claude sieht sich die Codebase an und schreibt Build-Befehle, Testanweisungen und erkannte Konventionen hinein. Gibt es die Datei schon, schlägt /init Verbesserungen vor, statt sie zu überschreiben. Mit CLAUDE_CODE_NEW_INIT=1 läuft stattdessen ein mehrstufiger, interaktiver Ablauf, der die Codebase mit einem Subagenten erkundet, Lücken per Rückfrage schließt und dir einen Vorschlag zur Durchsicht vorlegt, bevor irgendetwas geschrieben wird.

Zum Bearbeiten öffnet /memory deine Memory-Dateien im Editor und listet auch Orte auf, an denen noch keine Datei liegt. Soll Claude sich etwas merken, sag es einfach — „merk dir, dass die API-Tests eine lokale Redis-Instanz brauchen“ wandert ins Auto-Memory. Soll es dagegen in der CLAUDE.md stehen, bitte ausdrücklich darum. Vorhandene Dokumentation musst du nicht abschreiben: die Import-Syntax @path/to/file zieht sie beim Start mit in den Kontext:

# Project Standards

@README.md
@docs/architecture.md
@package.json

Importierte Dateien dürfen weiter importieren, maximal vier Sprünge tief. Zeigt ein Import eines Projekts aus dem Arbeitsverzeichnis heraus — etwa in dein Home-Verzeichnis —, listet Claude Code die Dateien beim ersten Mal in einem Bestätigungsdialog auf; lehnst du ab, bleiben sie dauerhaft deaktiviert. Ein Pfad in Backticks wird übrigens nicht als Import gelesen, sondern bleibt Text.

Auto-Memory: was Claude sich selbst notiert

Auto-Memory ist Claudes eigenes Notizbuch. Während der Arbeit hält Claude dort fest, was in einer späteren Sitzung nützlich wäre: Build-Befehle, Debugging-Erkenntnisse, Architekturnotizen, deine Korrekturen. Jedes Projekt bekommt ein eigenes Verzeichnis unter ~/.claude/projects/<project>/memory/, abgeleitet aus dem Git-Repository — alle Worktrees desselben Repos teilen sich also ein Auto-Memory, und geteilt wird es zwischen Rechnern nicht. Darin liegt MEMORY.md als Index, daneben beliebige Themendateien wie debugging.md oder api-conventions.md .

Auch Subagenten können ein eigenes Auto-Memory führen. Details stehen in der Subagent-Konfiguration.

Beim Start jeder Unterhaltung lädt Claude Code die ersten 200 Zeilen oder die ersten 25 KB von MEMORY.md — je nachdem, was zuerst erreicht ist. Alles darüber bleibt draußen; deshalb hält Claude den Index kurz und lagert Details in Themendateien aus, die es bei Bedarf selbst nachliest. Pflegen musst du nichts, lesen und korrigieren darfst du jederzeit. Abschalten lässt sich Auto-Memory über den Schalter in /memory, über CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 oder über autoMemoryEnabled in den Einstellungen. Für einen anderen Speicherort setzt du autoMemoryDirectory auf einen absoluten oder mit ~/ beginnenden Pfad — aus Projekt- oder lokalen Einstellungen wird der Wert erst übernommen, nachdem du den Workspace-Trust-Dialog für den Ordner bestätigt hast:

{
  "autoMemoryEnabled": true,
  "autoMemoryDirectory": "/path/to/shared/memory"
}

In einem großen Monorepo sammeln sich schnell CLAUDE.md -Dateien fremder Teams an, die für deine Arbeit nichts beitragen. claudeMdExcludes überspringt sie anhand von Glob-Mustern, die gegen absolute Pfade geprüft werden:

{
  "claudeMdExcludes": ["packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md"]
}

CLAUDE.md - und CLAUDE.local.md -Dateien oberhalb deines Arbeitsverzeichnisses werden beim Start vollständig geladen; Dateien in Unterverzeichnissen erst dann, wenn Claude dort etwas liest. claudeMdExcludes kannst du auf jeder Einstellungsebene setzen — Benutzer, Projekt, lokal oder Managed Policy —, und die Listen addieren sich über die Ebenen hinweg. Nur die Managed-Policy- CLAUDE.md lässt sich nicht ausschließen; genau das macht sie zum verlässlichen Ort für organisationsweite Vorgaben.

Anweisungen schreiben, denen Claude folgt

Weil CLAUDE.md in jeder Sitzung mitgeladen wird, kostet jede Zeile Kontext — die Visualisierung des Kontextfensters zeigt dir, wo das passiert und wie viel Platz deine Anweisungen belegen. Als Richtwert gelten unter 200 Zeilen je Datei; längere Dateien verbrauchen mehr Kontext und werden schlechter befolgt. Wirksam sind konkrete, überprüfbare Sätze: „Rücke mit zwei Leerzeichen ein“ statt „Formatiere den Code ordentlich“. Widersprechen sich zwei Regeln, greift Claude womöglich willkürlich eine heraus — räume alte Anweisungen also regelmäßig auf. Wird es trotzdem zu viel, verlagere Teile in pfad-gebundene Regeln. Und was garantiert an einem festen Punkt passieren muss, etwa vor jedem Commit, gehört nicht in CLAUDE.md, sondern in einen Hook.