Das Memory-System von Claude Code erklaert

1. Was das Memory-System ist und wovon es sich abgrenzt

Das Memory-System von Claude Code beschreibt die Faehigkeit, strukturierte Notizen ueber Projekte, Nutzerpraeferenzen und wiederkehrende Korrekturen automatisch anzulegen und sessionuebergreifend verfuegbar zu halten. Das unterscheidet sich fundamental von einer manuell geschriebenen CLAUDE.md-Datei: Waehrend CLAUDE.md vom Entwickler bewusst formuliert und ins Repository committet wird, entsteht Memory oft beilaeufig, aus einer Korrektur in einer Konversation oder aus wiederholtem Feedback zu einem bestimmten Vorgehen.

Der zentrale Unterschied zum Kontextfenster einer einzelnen Session ist die Persistenz. Das Kontextfenster einer Konversation ist nach deren Ende verloren, alles, was nicht explizit gespeichert wurde, muss in der naechsten Session neu erklaert werden. Das Memory-System loest genau dieses Problem, indem es relevante Informationen aus einer Session extrahiert und in einer Form ablegt, die auch in kommenden, komplett neuen Sessions wieder zugaenglich ist, ohne dass der Nutzer sie erneut formulieren muss.

2. Wie Erinnerungen automatisch entstehen und aktualisiert werden

Eine Erinnerung im Memory-System entsteht typischerweise aus einem wiederkehrenden Muster: Korrigiert ein Nutzer denselben Aspekt einer Antwort mehrfach, etwa eine bevorzugte Formatierung oder einen bestimmten technischen Ansatz, erkennt das System dieses Muster und haelt es als Notiz fest. Anders als eine einmalige Korrektur innerhalb einer Session, die nur fuer den aktuellen Kontext gilt, wird ein wiederholtes Muster zu einer dauerhaften Praeferenz, die in zukuenftigen Sessions automatisch beruecksichtigt wird.

Wichtig ist dabei die Aktualisierungslogik: Eine bestehende Erinnerung im Memory-System wird nicht einfach dupliziert, wenn sich eine Praeferenz aendert, sondern die urspruengliche Notiz wird ueberschrieben oder praezisiert. Widerspricht eine neue Beobachtung einer alten Erinnerung deutlich, etwa wenn ein Projekt von einem Framework auf ein anderes wechselt, sollte die veraltete Information ersetzt werden, statt beide widerspruechlichen Notizen parallel bestehen zu lassen. Genau das ist einer der Punkte, an denen manuelles Nachsehen und gezieltes Korrigieren sinnvoll bleibt.

# Simplified illustration of the update logic behind the memory system
# 1. A pattern repeats across several turns in a conversation
# 2. The system checks whether a related memory note already exists
# 3. Existing note found -> refine or overwrite it, do not duplicate
# 4. No note found -> create a new one with a timestamp and source context

# Example: a preference gets confirmed for the third time
echo "User confirmed again: prefers Repository pattern over direct Model access"
# -> existing note in project_seosuite.md gets updated, not duplicated

3. Aufbau der Memory-Dateien: Struktur und Speicherort

Technisch werden Erinnerungen als einfache, lesbare Markdown-Dateien abgelegt, aehnlich wie CLAUDE.md, aber an einem separaten Speicherort ausserhalb des Projekt-Repositories. Das ist bewusst so gestaltet: Waehrend CLAUDE.md mit dem Team geteilt und versioniert wird, bleibt das Memory-System in der Regel persoenlich und projektuebergreifend, es gehoert zum Nutzer, nicht zum Repository. Jede Notiz ist in Klartext lesbar, es gibt keine versteckte Datenbank oder proprietaeres Binaerformat.

Diese Lesbarkeit hat einen praktischen Vorteil: Wer wissen will, was genau im Memory-System ueber ein bestimmtes Projekt gespeichert ist, kann die entsprechende Datei direkt oeffnen und durchsehen, statt auf eine Blackbox angewiesen zu sein. Der folgende Ausschnitt zeigt beispielhaft, wie eine solche automatisch gepflegte Memory-Notiz strukturiert sein kann, mit klarer Quellenangabe und Zeitstempel fuer Nachvollziehbarkeit.

# Inspecting where Claude Code stores memory notes
ls -la ~/.claude/projects/*/memory/

# Example structure of a memory file for a specific project
cat ~/.claude/projects/-home-user-projects-mironsoft/memory/project_seosuite.md

# Project: Mironsoft_SeoSuite

## Current status (last updated 2026-07-28)
- Core module structure done: ViewModels, Repositories, ACL, system.xml
- Missing: hreflang tag generation for category pages
- Next step: add unit tests for the meta description generator

## Recurring preference
- User always wants full file paths mentioned when creating new files
- User prefers Repository pattern over direct Model access

4. Wann Claude Code sich etwas merkt und wann nicht

Nicht jede Aussage in einer Konversation wird zu einer dauerhaften Erinnerung im Memory-System. Einmalige, kontextspezifische Details, etwa eine spezifische Fehlermeldung, die in genau diesem Moment relevant war, bleiben im Kontextfenster der jeweiligen Session und werden nicht persistiert. Was tatsaechlich als Erinnerung festgehalten wird, sind wiederkehrende Muster: Praeferenzen, die mehrfach bestaetigt wurden, Projektstatus-Informationen, die fuer zukuenftige Arbeit relevant bleiben, und explizite Anweisungen des Nutzers, sich etwas dauerhaft zu merken.

Der Unterschied zwischen einer beilaeufigen Erwaehnung und einer tatsaechlichen Praeferenz ist dabei entscheidend fuer die Qualitaet des Memory-Systems. Eine einmalige Entscheidung fuer diese eine Aufgabe sollte nicht automatisch zu einer generellen Regel fuer alle zukuenftigen Aufgaben werden. Wer explizit moechte, dass etwas dauerhaft gemerkt wird, sollte das auch explizit so formulieren, statt darauf zu vertrauen, dass jede beilaeufige Aeusserung automatisch zu einer Memory-Notiz wird.

5. Eigene Erinnerungen gezielt steuern und korrigieren

Da Memory-Dateien als lesbare Markdown-Dateien vorliegen, lassen sie sich direkt manuell bearbeiten, genau wie eine CLAUDE.md-Datei. Ist eine automatisch angelegte Erinnerung im Memory-System veraltet oder schlicht falsch, kann sie geoeffnet und korrigiert werden, ohne auf ein automatisches Update warten zu muessen. Das ist besonders wichtig, wenn sich ein Projekt grundlegend aendert, etwa ein Wechsel von einem Framework zu einem anderen, und die alte Erinnerung sonst weiterhin falsche Annahmen in zukuenftige Sessions einbringen wuerde.

Ein zweiter Weg der aktiven Steuerung ist eine explizite Anweisung innerhalb einer Konversation, etwa "merke dir fuer zukuenftige Sessions, dass dieses Projekt ausschliesslich Repository-Pattern statt direktem Model-Zugriff nutzt". Solche expliziten Anweisungen werden zuverlaessiger im Memory-System festgehalten als beilaeufige Aussagen, weil die Absicht, etwas dauerhaft zu speichern, klar erkennbar ist. Regelmaessiges, bewusstes Durchsehen der Memory-Dateien, aehnlich einem Code-Review, verhindert, dass sich veraltete oder widerspruechliche Notizen unbemerkt ansammeln.

# Manually correcting an outdated memory note after a framework switch
cd ~/.claude/projects/-home-user-projects-mironsoft/memory/

# Open the relevant file directly in an editor
$EDITOR project_seosuite.md

# Or correct it via a quick inline replacement
sed -i 's/uses Symfony Console commands/uses Magento CLI commands/' \
  project_seosuite.md

# Verify the correction took effect
grep -n "CLI commands" project_seosuite.md

6. Memory ueber mehrere Projekte und Sessions hinweg

Das Memory-System unterscheidet typischerweise zwischen projektspezifischen Notizen, die nur fuer ein bestimmtes Repository relevant sind, und projektuebergreifenden Praeferenzen, die den generellen Arbeitsstil eines Nutzers betreffen. Eine Notiz wie "dieses Projekt nutzt PHP 8.4 mit Constructor Property Promotion" gehoert eindeutig zum jeweiligen Projekt, waehrend eine Praeferenz wie "Erklaerungen auf Deutsch, Code-Kommentare auf Englisch" projektuebergreifend gilt und in jeder Session, unabhaengig vom aktuellen Repository, beruecksichtigt werden sollte.

Diese Trennung ist wichtig, damit Memory nicht zu einer unuebersichtlichen Ansammlung projektspezifischer Details wird, die faelschlich auf ein anderes Projekt angewendet werden. Wer an mehreren, technisch unterschiedlichen Projekten gleichzeitig arbeitet, etwa einem Magento-Projekt und einem separaten React-Projekt, profitiert davon, dass das Memory-System projektspezifische Details korrekt trennt, statt eine Technologie-Praeferenz aus einem Projekt faelschlich auf ein technisch komplett anderes Projekt zu uebertragen.

7. Datenschutz und Kontrolle: Was im Memory landet

Weil das Memory-System Informationen aus Konversationen extrahiert und dauerhaft speichert, ist Kontrolle darueber, was tatsaechlich gespeichert wird, eine berechtigte Datenschutzfrage. Sensible Informationen, etwa Zugangsdaten, interne Kundendaten oder vertrauliche Geschaeftsdetails, sollten grundsaetzlich nicht Teil einer Konversation sein, aus der Erinnerungen extrahiert werden, unabhaengig davon, ob das Memory-System aktiv ist oder nicht. Diese Vorsicht gilt fuer jede KI-gestuetzte Entwicklungsumgebung, nicht spezifisch nur fuer Claude Code.

Da Memory-Dateien als lesbare Klartext-Dateien im lokalen Dateisystem liegen, unterliegen sie denselben Zugriffsrechten wie jede andere lokale Datei. Wer im Team an gemeinsam genutzten Rechnern oder in geteilten Umgebungen arbeitet, sollte diese Speicherorte in die eigene Backup- und Zugriffskontrolle einbeziehen, genauso wie andere lokale Konfigurationsdateien. Regelmaessiges Durchsehen der Memory-Dateien dient also nicht nur der Qualitaetssicherung, sondern auch der Kontrolle darueber, welche Informationen tatsaechlich dauerhaft abgelegt wurden.

# Checking access permissions on the local memory directory
ls -ld ~/.claude/projects/*/memory/
stat -c "%A %U %n" ~/.claude/projects/*/memory/*.md

# Restricting access on a shared machine (owner-only read/write)
chmod 700 ~/.claude/projects/*/memory/
chmod 600 ~/.claude/projects/*/memory/*.md

8. Grenzen des Memory-Systems in der Praxis

Das Memory-System ersetzt keine bewusst gepflegte Projektdokumentation. Waehrend Memory beilaeufig aus Konversationen entsteht, sollten grundlegende Architekturentscheidungen, Coding-Standards und Team-Konventionen weiterhin explizit in CLAUDE.md dokumentiert werden, weil diese Datei versioniert, im Team geteilt und bei Bedarf im Pull-Request-Review sichtbar ist. Memory ergaenzt diese bewusste Dokumentation, ersetzt sie aber nicht.

Eine weitere praktische Grenze: Das Memory-System kann nur Muster erkennen, die tatsaechlich innerhalb von Konversationen auftauchen. Eine Praeferenz, die nie explizit geaeussert oder korrigiert wurde, wird auch nicht automatisch gemerkt, unabhaengig davon, wie selbstverstaendlich sie fuer den Nutzer erscheinen mag. Wer moechte, dass eine bestimmte Regel zuverlaessig beachtet wird, sollte sie entweder explizit im Memory-System festhalten lassen oder, bei sicherheitskritischen Regeln, besser direkt als Hook implementieren, der unabhaengig vom Memory-Zustand deterministisch greift.

9. Memory im Vergleich zu CLAUDE.md und Kontextfenster

Drei verschiedene Mechanismen tragen Information ueber eine Konversation hinaus oder innerhalb von ihr, mit unterschiedlicher Reichweite und unterschiedlichem Kontrollgrad.

Die Tabelle zeigt die komplementaeren Rollen: Das Kontextfenster deckt den unmittelbaren Moment ab, das Memory-System traegt beilaeufig entstandene, persoenliche Praeferenzen ueber Sessions hinweg, und CLAUDE.md bleibt der bewusst gepflegte, versionierte Ort fuer alles, was das gesamte Team kennen und einhalten soll. Wer alle drei Ebenen bewusst nutzt, statt sie zu vermischen, erhaelt ein Gesamtsystem, in dem jede Information am richtigen Ort landet.

10. Zusammenfassung

Das Memory-System von Claude Code haelt automatisch wiederkehrende Praeferenzen und Projektstatus ueber einzelne Sessions hinweg fest, gespeichert als lesbare Markdown-Dateien ausserhalb des Repositories. Anders als CLAUDE.md, das bewusst formuliert und im Team geteilt wird, entsteht Memory oft beilaeufig aus wiederholten Korrekturen und explizitem Feedback, bleibt aber persoenlich und nicht versioniert.

Manuelle Kontrolle bleibt wichtig: veraltete oder falsche Erinnerungen lassen sich direkt in den Memory-Dateien korrigieren, sensible Informationen sollten von vornherein nicht Teil von Konversationen sein. Fuer dauerhafte, teamweite Regeln bleibt CLAUDE.md die richtige Ebene, fuer sicherheitskritische Regeln ein deterministischer Hook. Wer Kontextfenster, Memory-System und CLAUDE.md bewusst als drei unterschiedliche Werkzeuge einsetzt, nutzt Claude Code effizienter und nachvollziehbarer.

11. FAQ: Das Memory-System von Claude Code