Anthropics Komponenten des Agent-Memory in Claude Code: MEMORY.md prüfen, Transkripte behalten, selbst einen Dreaming-Durchlauf fahren

Anthropics Engineering-Blog hat am 6. November einen langen Beitrag veröffentlicht: „The components of agent memory“. Er definiert Memory als Kontext, den Claude aus Erfahrung schreibt und in einer späteren Session liest (Weights, In-Context Learning und Compaction sind ausgeklammert), teilt es in vier Schichten und fährt Experimente zu mehreren davon. Liest man ihn neben der Claude-Code-Dokumentation, zeigt sich ein Widerspruch in den Standardeinstellungen: Claude Code behält die Notizen, bis jemand sie löscht, und räumt die Transkripte dahinter nach 30 Tagen weg, während der wichtigste Reparaturmechanismus des Beitrags genau darauf beruht, das eine gegen das andere zu prüfen.

Zuerst die Zahlen. Bei der Datenbank-Aufgabe aus CL-Bench 1.0 hebt Memory Opus 5.5 von 0,655 auf 0,838 Mean Reward und Opus 4.7 von 0,383 auf 0,700. Sonnet 4.6 bewegt sich kaum, 0,330 auf 0,364, bis man ihm sagt, es soll sein Memory lesen und seine Theorien testen. Dann erreicht es 0,641. Der Gewinn kam vom Lesen und Testen des Gespeicherten, nicht davon, mehr zu speichern.

Was folgt, ist das Audit, das ich nach diesem Beitrag auf einem Claude-Code-Setup laufen lassen würde. Am Ende steht der Konsolidierungsdurchlauf, den Anthropic Dreaming nennt, ausgeführt auf einer Kopie und mit einem Diff als Ergebnis.

Welche vier Schichten hat Anthropics Modell des Agent-Memory?

Von unten nach oben: Transkripte, Memory-Notizen, Memory-Repräsentationen und injizierter Kontext. Transkripte sind das durchsuchbare Ereignisprotokoll vergangener Sessions. Notizen sind das, was Claude bewusst aufgeschrieben hat, etwa Dateien in einem Memory-Verzeichnis. Repräsentationen sind strukturierte Formen, die Claude darüber pflegt, allen voran ein verlinktes Wiki. Injizierter Kontext ist das, was vor dem ersten Prompt in jede Session geladen wird.

Dreaming ist der Durchlauf, der Information zwischen diesen Schichten bewegt. In Anthropics Beschreibung prüft er Notizen gegen die ursprünglichen Transkripte, schreibt die falschen neu, baut Repräsentationen auf und dünnt sie aus und kann eine Notiz in die injizierte Schicht befördern. Das klarste Beispiel im Beitrag stammt aus einem Pokémon-Red-Lauf: Eine falsche Notiz darüber, wo das Pokémon-Center liegt, führte Claude in Mt. Moon dreimal über einen Einweg-Felsvorsprung. Nachdem ein Dreaming-Durchlauf die Notiz gegen das Session-Transkript geprüft und neu geschrieben hatte, kam Claude durch die Höhle.

Die Wiki-Ergebnisse würde ich zweimal lesen, weil sie in beide Richtungen schneiden. Beim Stainless-Korpus, rund 350.000 Dateien, stieg das Wiki allein von 13% auf 48% der bewerteten Kriterien, je mehr Sessions das Dreaming verarbeitete, und verlor trotzdem gegen einfache Suche mit 53%. Wiki plus Suche kam auf 61% und sparte etwa 20.000 Tokens pro Frage. Bei Harveys LAB-Fragen zu Fusionen, die Synthese über mehrere Dokumente verlangten, gewann das Wiki klar, 87% gegenüber 73% für Suche. Bei einer anderen LAB-Aufgabe wuchs das Wiki auf das 1,77-Fache seiner Quelle, 203 KB gegenüber 115 KB, und der Beitrag sagt, es habe „im Grunde nichts abstrahiert“. Eine Repräsentationsschicht hilft dort, wo die Antwort zusammengesetzt werden muss, und sie ist nicht von sich aus Kompression. Sie komprimiert nur, wenn etwas sie dazu zwingt.

Wo liegt jede Memory-Schicht in Claude Code?

Zwei der vier Schichten sind eingebaut, eine ist eingebaut, läuft aber ab, und eine gibt es nicht, solange du sie nicht selbst baust. Auf Claude Code 2.1.319:

Layer                 Claude Code                                         Lifetime
transcripts           ~/.claude/projects/<project>/*.jsonl                swept once older than
                      (subagents under <session>/subagents/)              cleanupPeriodDays (default 30)
memory notes          ~/.claude/projects/<project>/memory/*.md            kept until edited or deleted
representations       none built in
injected context      CLAUDE.md files + first 200 lines or 25KB of        every session
                      memory/MEMORY.md

Themendateien werden beim Start nicht geladen. Claude liest eine, wenn es entscheidet, dass es sie braucht, meist auf Grundlage ihres einzeiligen Eintrags in MEMORY.md. Der Index ist der einzige Teil der Notizschicht, der garantiert im Kontextfenster steht. Das ist dasselbe Kartenproblem, das ich in dem Essay über Markdown-Memory beschrieben habe: Jenseits der Grenze findet eine Notiz nur ein Agent, der schon daran gedacht hat, nachzusehen.

Dreaming selbst gibt es in Claude Code nicht. Anthropic liefert es als Dreams in Claude Managed Agents aus, als Research Preview hinter einer Zugangsanfrage und dem Beta-Header dreaming-2026-04-21. Ein Dream nimmt einen Memory-Store und 1 bis 100 Session-Transkripte und schreibt einen neuen Store, mit zusammengeführten Duplikaten und ersetzten widersprochenen Einträgen. Der Eingabe-Store wird nie verändert, du prüfst also die Ausgabe und hängst sie an oder verwirfst sie. Diese Designentscheidung lohnt sich zu kopieren, auch dort, wo die API nicht verfügbar ist.

Wie prüfst du MEMORY.md gegen die 200-Zeilen- und 25KB-Grenze von Claude Code?

Miss jeden Index und such nach zwei Dingen, die das Größenlimit nicht zeigt: Indexzeilen, die auf eine nicht mehr existierende Datei zeigen, und Themendateien, die der Index nie nennt. Dieses Skript erledigt alle drei Prüfungen über alle Projekte:

#!/usr/bin/env bash
# Audit Claude Code auto memory indexes: size against the 200-line / 25KB load,
# index lines pointing at missing files, topic files the index never names.
# Raw-file numbers: Claude Code measures the index after stripping frontmatter
# and HTML comments, so treat this as an approximation.
# Usage: memory_audit.sh [projects_dir]   (default ~/.claude/projects)
ROOT="${1:-$HOME/.claude/projects}"
for idx in "$ROOT"/*/memory/MEMORY.md; do
  [ -f "$idx" ] || continue
  dir=$(dirname "$idx")
  lines=$(awk 'END { print NR }' "$idx")     # counts a last line with no newline
  bytes=$(wc -c < "$idx")
  status=ok                                   # 25KB taken as 25,600 bytes
  if [ "$lines" -gt 200 ] || [ "$bytes" -gt 25600 ]; then status=CUT
  elif [ "$lines" -gt 160 ] || [ "$bytes" -gt 20480 ]; then status=near   # my 80% mark
  fi
  links=$(grep -oE '\]\([^)]+\.md\)' "$idx" | sed -E 's/^\]\(//; s/\)$//' | sort -u)
  dangling=0
  while IFS= read -r f; do
    [ -n "$f" ] && [ ! -f "$dir/$f" ] && dangling=$((dangling+1))
  done <<< "$links"
  orphans=0                                   # whole file name, linked or not
  for f in "$dir"/*.md; do
    b=$(basename "$f"); [ "$b" = MEMORY.md ] && continue
    grep -qE "(^|[^[:alnum:]_.-])${b//./\\.}([^[:alnum:]_.-]|\$)" "$idx" || orphans=$((orphans+1))
  done
  printf '%-5s %4d lines %6d bytes  dangling=%d orphans=%d  %s\n' \
    "$status" "$lines" "$bytes" "$dangling" "$orphans" "$(basename "$(dirname "$dir")")"
done | sort -k2 -nr

Der Anfang der Ausgabe auf meinem Rechner, Projektnamen ersetzt:

near   184 lines  10393 bytes  dangling=0 orphans=0  project-a
ok     110 lines   9578 bytes  dangling=0 orphans=2  project-b
ok      90 lines  10204 bytes  dangling=0 orphans=3  project-c

Keiner meiner Indizes liegt über der Grenze. Beim größten greift das Zeilenlimit zuerst: 25KB auf 200 Zeilen sind 128 Bytes pro Zeile, dieser Index liegt bei etwa 56, er würde also bei rund 11KB die 200 Zeilen erreichen. Das Byte-Limit wird erst relevant, wenn Einträge lang werden, und das heißt meistens, dass sie Inhalt tragen, der in eine Themendatei gehört. Die near-Marke ist meine eigene 80%-Schwelle, nicht das, was Claude Code für seine Erinnerung verwendet.

Die Spalte orphans würde ich mir zuerst ansehen. Die Größe überwacht Claude Code bereits: Nachdem Claude MEMORY.md geschrieben hat, erinnert es Claude daran, einen Index nahe am Limit zu kürzen, und gibt bei einem Index darüber einen Fehler zurück. Niemand überwacht eine Themendatei, die aus dem Index gefallen ist, durch eine manuelle Änderung oder eine Konsolidierung, die ihre Zeile weggemergt hat. Die Datei liegt noch auf der Platte, und Claude kann sie per Auflisten oder Durchsuchen des Ordners noch finden, aber der Startindex kündigt sie nicht mehr an. Eine Session, die nicht danach sucht, sieht sie also nicht. Für jede verwaiste Datei gilt: Zeile in MEMORY.md wieder eintragen oder Datei löschen. Eine dangling Zeile ist der umgekehrte Fall und kann einfach weg.

Für die Orphan-Prüfung habe ich zwei falsche Versionen gebraucht. Den Dateinamen als einfachen Teilstring zu suchen, übersieht eine echte verwaiste Datei, deren Name das Ende eines anderen Dateinamens ist, note.md versteckt sich also hinter other_note.md. Ihn nur als Linkziel zu suchen, markiert eine Notiz, die der Index in Backticks nennt und die Claude problemlos liest. Auf meinen eigenen Ordnern hat diese Version einen falschen Orphan gemeldet. Den Namen als ganzes Token zu suchen, vermeidet beides.

Das Audit hat noch etwas zutage gebracht. Claude Code schreibt einen modified-Zeitstempel ins Frontmatter einer Memory-Datei, wenn Claude sie schreibt, und auf meinem Rechner haben nur wenige Themendateien einen. Die mtime der Datei ist der Fallback, und sie ist ein schwacher Beleg: Sie sagt, wann sich die Datei zuletzt geändert hat, nicht, wann ihr Inhalt zuletzt gestimmt hat, und ein Kopieren oder Wiederherstellen kann sie zurücksetzen. Nutz sie, um zu entscheiden, welche Notizen du zuerst nachprüfst, nicht, um zu entscheiden, welche veraltet sind: ls -lt --time-style=+%F ~/.claude/projects/<project>/memory/.

Wie lange behält Claude Code die Transkripte, die ein Dreaming-Durchlauf braucht?

Standardmäßig dreißig Tage, und das Löschen passiert lautlos. cleanupPeriodDays legt fest, wie lange Session-Transkripte aufbewahrt werden. Der Standard ist 30, das Minimum 1, und ein Hintergrund-Sweep nach dem Start einer Session löscht ältere Transkriptdateien ohne Meldung. Das Memory-Verzeichnis ist ausdrücklich vom Sweep ausgenommen. Notizen bleiben, bis jemand sie bearbeitet oder löscht.

Leg das neben den Beitrag. Dreaming korrigiert eine Notiz, indem es sie gegen die Transkripte testet, und Anthropic räumt in den offenen Fragen ein, dass Notizen „von Anfang an falsch“ sein können. Eine Notiz überlebt standardmäßig die Session, aus der sie stammt. Sobald dieses Transkript alt genug für den Sweep ist, ist der Beleg, der die Notiz widerlegen könnte, weg, die Notiz aber nicht. Je länger eine Notiz lebt, desto weniger Belege bleiben, um sie zu prüfen.

Meine eigenen Einstellungen behalten Transkripte 36500 Tage, also praktisch für immer. Wenn du irgendeine Art von Konsolidierungsdurchlauf willst, setz den Wert in ~/.claude/settings.json deutlich über das Alter der Notizen, die du nachprüfen willst:

{
  "cleanupPeriodDays": 365
}

Das hat zwei Kosten. Transkripte sammeln sich in einem aktiven Projekt an, und sie enthalten alles, was durch eine Session gelaufen ist: Tool-Ergebnisse, Dateiinhalte, jedes Secret, das ausgegeben wurde. Ein Durchlauf, der sie liest, sollte nur ein aktuelles Zeitfenster kopieren und seine Kopie danach löschen. Das Skript unten macht beides.

Was sollten Memory-Anweisungen in Claude Code sagen: wofür Memory da ist oder Regeln für seine Nutzung?

Wofür es da ist. Anthropics Satz ist eindeutig: „Wir haben festgestellt, dass es hilft, Claude zu sagen, wofür Memory da ist, aber nicht, wie es zu benutzen ist.“ Als das Team eine feste Regel hinzufügte, „nur Fehlschläge festhalten“, verlor Opus 5 0,234 seines Memory-Gewinns und Opus 4.7 0,150. Sonnet 4.6 verlor nur 0,020, weil es kaum Gewinn zu verlieren hatte. Was ihm half, war die Aufforderung, sein Memory zu lesen und seine Theorien zu testen, und das hat seinen Score fast verdoppelt.

Die eingebauten Auto-Memory-Anweisungen von Claude Code mischen beides: einen Zweck (speichern, was in einer künftigen Unterhaltung nützlich wäre) neben Regeln (vier Notiztypen, nichts, was sich aus dem Code ableiten lässt, nichts, was schon in CLAUDE.md steht). Was du in CLAUDE.md ergänzt, entfernt diese Defaults nicht. Dein Hebel ist also, was du hinzufügst, und die Belege sprechen für einen Satz zum Zweck statt einer weiteren Formatregel. Etwa so in der CLAUDE.md eines Projekts:

## Memory
Memory exists so a future session repeats nothing I already corrected and
keeps what was tested here. Before acting on a memory note, check it against
the code or a command; if they disagree, trust the check and fix the note.

Die CL-Bench-Ergebnisse stammen aus einer Datenbank-Aufgabe, nicht aus einer Claude-Code-Session. Die Übertragung ist also eine vernünftige Wette und kein gemessenes Ergebnis. Der zweite Satz ist die billige Hälfte von Dreaming: Eine Notiz wird in dem Moment getestet, in dem sie benutzt wird, und genau dann kostet eine falsche Notiz etwas. Es bleibt trotzdem ein Satz, den das Modell überspringen kann, und das ist die Grenze jeder Regel in dieser Datei. Der Durchlauf unten hängt nicht davon ab, dass der Agent ans Prüfen denkt.

Wie fährst du selbst einen Dreaming-Durchlauf auf dem Memory von Claude Code?

Stell den Memory-Ordner zuerst unter git, damit eine akzeptierte Änderung ein Commit ist und eine schlechte ein Revert. Dann kopier den Ordner und ein aktuelles Fenster an Transkripten in ein Scratch-Verzeichnis, lass ein headless claude -p die Notizen gegen die Transkripte prüfen und nur die Kopie umschreiben, und lies den Diff. Das bildet die Eigenschaft von Anthropics Dreams nach, die hier am meisten zählt: Die Eingabe wird nie verändert.

#!/usr/bin/env bash
# Local dream pass: check a copy of Claude Code auto memory against recent transcripts.
# Usage: dream.sh <full path to ~/.claude/projects/<project>> [days, default 14]
set -euo pipefail
[ $# -ge 1 ] || { echo "usage: dream.sh <project dir> [days]" >&2; exit 64; }
PROJ=$(realpath -e -- "$1"); DAYS="${2:-14}"
[[ "$DAYS" =~ ^[1-9][0-9]*$ ]] || { echo "days must be a positive integer" >&2; exit 64; }
[ -d "$PROJ/memory" ] || { echo "no memory/ in $PROJ" >&2; exit 66; }
WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT    # transcripts never outlive the run
OUT="${OUT:-$PWD/dream-$(date +%F)}"; mkdir -p "$OUT"
cp -r "$PROJ/memory" "$WORK/memory"
# top-level transcript files modified in the last $DAYS days
find "$PROJ" -maxdepth 1 -type f -name '*.jsonl' -mtime -"$DAYS" -exec cp -t "$WORK" -- {} +
ls "$WORK"/*.jsonl > /dev/null 2>&1 || { echo "no transcripts in the window" >&2; exit 65; }
cd "$WORK"
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude -p "$(cat <<'PROMPT'
./memory is an agent's memory. The *.jsonl files here are recent session transcripts.
Memory exists so a future session repeats nothing the user already corrected and keeps what was tested.
Check every note in ./memory against the transcripts. Where a transcript contradicts a note,
rewrite the note to match the latest evidence. Where a correction or tested rule appears in the
transcripts and no note holds it, add one and index it in ./memory/MEMORY.md. Leave notes the
transcripts do not mention unchanged. Edit only files under ./memory. Then write ./CHANGES.md:
one line per change, with the transcript file and the line that justifies it.
PROMPT
)" --restricted --tools "Read,Grep,Glob,Edit,Write" --permission-mode acceptEdits \
   --no-session-persistence < /dev/null > "$OUT/run.log" 2>&1
rc=0; diff -ruN "$PROJ/memory" "$WORK/memory" > "$OUT/memory.diff" || rc=$?
[ "$rc" -le 1 ] || exit "$rc"
cp -r "$WORK/memory" "$OUT/memory"; cp "$WORK/CHANGES.md" "$OUT/" 2>/dev/null || true
echo "review: $OUT/memory.diff  $OUT/CHANGES.md  (proposed files in $OUT/memory)"

Die Sicherheit steckt in den Flags, nicht im Prompt. --restricted beschränkt die Datei-Tools auf das Arbeitsverzeichnis, also die Scratch-Kopie, und --tools lässt kein Tool übrig, das Befehle ausführt. --no-session-persistence verhindert, dass der Durchlauf ein eigenes Transkript speichert, das sonst eine frische Kopie von allem wäre, was er gerade gelesen hat, unter einem neuen Projektordner und so lange aufbewahrt, wie deine Retention es zulässt. CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 hindert ihn daran, eigene Memories zu schreiben. Der trap löscht die kopierten Transkripte, wenn das Skript endet, und Diff, vorgeschlagene Dateien und CHANGES.md bleiben zur Prüfung in $OUT. Zwei Grenzen solltest du kennen: Das Fenster umfasst Dateien, die in den letzten N Tagen geändert wurden, eine lange Session, die gestern fortgesetzt wurde, kommt also komplett mit. Und Subagent-Transkripte in jedem Session-Ordner bleiben außen vor. Der Durchlauf wird wie jeder andere Lauf abgerechnet und skaliert mit der Menge an Transkript, die er liest, also fang mit ein paar Tagen an.

Ich habe es auf Claude Code 2.1.319 gegen ein synthetisches Setup laufen lassen, nicht gegen mein echtes Memory: zwei Notizen (Tests laufen mit npm test und brauchen ein lokales Redis; Staging wird aus einem staging-Branch deployt) und ein vierzeiliges Transkript vom 1. November, in dem der User sagt, das Projekt sei letzte Woche auf pnpm umgezogen und Redis sei weg, und der Agent 214 bestandene Tests meldet. In drei Läufen hat der Durchlauf jedes Mal die Test-Notiz geändert und die Deploy-Notiz in Ruhe gelassen, weil kein Transkript sie erwähnte. Zwei der Läufe, mit einer früheren Version des Skripts, haben außerdem ein Datum ergänzt. Das ist der zweite davon:

-Run tests with `npm test`; the suite needs a local Redis on port 6379.
+Run tests with `pnpm test` (project moved from npm to pnpm in late Oct 2026; `npm test` is outdated).
+No Redis needed: tests use an in-memory fake. Verified 2026-11-01: 214 tests passed.

Das ist das Ergebnis, das du willst, und ein Detail darin ist der Grund, warum du den Diff liest, statt den Ordner blind zurückzukopieren. „Late Oct 2026“ steht nicht im Transkript. Der User hat „letzte Woche“ gesagt, und der Durchlauf hat daraus ein eigenes Datum gemacht. Das Datum und die Testanzahl in der nächsten Zeile stehen beide im Transkript, der Monat nicht. Es ist eine plausible Schlussfolgerung und zugleich eine neue, unbelegte Behauptung in einer Datei, die monatelang als Fakt behandelt wird. CHANGES.md hat dafür Zeile 3 angegeben, und Zeile 3 enthält sie nicht. Der dritte Lauf hat die Notiz ohne Datum geschrieben. Prüfen, bearbeiten, die akzeptierten Dateien von Hand zurückkopieren, committen.

Was behebt ein Dreaming-Durchlauf im Agent-Memory nicht?

Ein Durchlauf, der nur Transkripte liest, sieht keine Änderung, die keine Session miterlebt hat. Er korrigiert eine Notiz, der das Protokoll widerspricht, und die Mt.-Moon-Notiz war auf eine Weise falsch, die derselbe Lauf aufgedeckt hat. Eine Abhängigkeit, die sich im Commit eines Kollegen geändert hat, oder eine Entscheidung aus einem Meeting hinterlässt in keinem Transkript eine Zeile, und der Durchlauf behält die alte Notiz genauso selbstsicher wie vorher. Als ich geschrieben habe, dass ein lesbares Memory immer noch ein Memory ist, fehlte ein Signal von außerhalb der Sessions, wenn sich die Welt bewegt. Die Prüfung gegen das Protokoll liefert keins. Anthropics Wiki-Pipeline prüft Aussagen zusätzlich gegen Quelldokumente, und ein lokaler Durchlauf könnte ebenso das Repository oder dessen git log lesen. Was die Transkriptprüfung tatsächlich ändert, ist, wer sie ausführt: ein eigener Schritt statt des Agents mitten in der Aufgabe. Anthropic sagt offen, dass das Rechenleistung kostet und dass es womöglich nicht praktikabel ist, jedes Memory laufend zu prüfen.

Was Dreaming richtig macht, ist die Form des Schreibens. Der Eingabe-Store bleibt unberührt, und die Ausgabe ist ein separater Store, den du bewusst übernimmst. Das ist der versionierte Datensatz, den ein Dokument-Memory meiner Argumentation nach braucht. Lokal ist das der git-Commit vor dem Durchlauf. Derselbe Beitrag liefert auch Belege für den anderen Punkt aus diesem Essay, nämlich wer welche Seite schreiben darf: Agents, die in eine gemeinsame Tabelle mit Fusionskonditionen schrieben, behielten 41 von 57 Fakten, und eine Seite pro Vertrag, mit direkt zitierten Konditionen, behielt alle 57.

Die Repräsentationsschicht verdient dasselbe Misstrauen wie die Notizen. Weights umgehen das Problem, weil es gar keine Datei gibt, die wachsen kann, und zahlen dafür auf andere Weise. Ein Wiki, das über seine Quelle hinauswächst, hat nichts abstrahiert, egal wie gut es bei den Fragen abgeschnitten hat, für die es gebaut wurde. Wenn du eins für Claude Code baust, lass die Suche daneben bestehen und miss es so wie den Index: daran, was es kostet, es zu laden, und ob etwas darin nie gelesen wird.

Wenn deine MEMORY.md auf 200 Zeilen zugeht, ist Kürzen der naheliegende Schritt, und es beantwortet die halbe Frage. Es hält den Index unter der Grenze. Es sagt dir nicht, welche Einträge noch stimmen. Diese zweite Frage braucht die Belege, und in einem Standard-Setup werden die nach einem Monat weggeräumt. Setz cleanupPeriodDays vor dem nächsten Sweep hoch, und kürze dann, solange die Transkripte zum Prüfen noch da sind.