Gedächtnis des KI-Agenten zwischen Sitzungen: Fortschrittsdatei, Entscheidungsprotokoll, Git und Init-Skript

Warum der Agent sich an nichts erinnert

Das Modell speichert keinen Zustand zwischen einzelnen Läufen. Alles, was der Agent über Ihre Aufgabe »weiß«, liegt im Kontextfenster der aktuellen Sitzung: gelesene Dateien, Befehlsausgaben, der Dialog mit Ihnen. Schließt sich die Sitzung oder läuft der Kontext über, beginnt die neue bei null und sieht nur das, was auf der Festplatte steht.

Ein nützliches Bild: ein brillanter Ingenieur, der jeden Morgen mit vollständig gelöschtem Gedächtnis zur Arbeit kommt. Er findet sich im Code schnell zurecht, erinnert sich aber nicht, welche Architekturvariante man gestern gewählt hat, warum die übrigen verworfen wurden und in welchem Zustand die Tests sind. Ohne Notizen verbringt er fünfzehn bis zwanzig Minuten mit Erkundung und baut mit hoher Wahrscheinlichkeit das wieder, was Sie bewusst verworfen haben.

Deshalb ist das Gedächtnis eines KI-Agenten keine Eigenschaft des Modells, sondern ein Teil des Harness: eine Menge von Dateien und Regeln, die Sie selbst entwerfen. Die gute Nachricht ist, dass dafür keine Vektordatenbanken und Spezialdienste nötig sind. Einige Markdown-Dateien, Git und Disziplin genügen.

Warum ein großes Kontextfenster das Problem nicht löst

Man könnte meinen, es reiche, auf ein Modell mit einem größeren Fenster zu warten. Doch eine komplexe Aufgabe füllt jedes Fenster: Der Agent liest die Codebasis, sammelt die Historie der Entscheidungen, bekommt ausführliche Testausgaben und behält den ganzen Dialog. Die Ansprüche wachsen mit dem Fenster. Das ist ein architektonisches Problem, keine Frage der Größe.

Es gibt noch einen zweiten Effekt. Nahe der Grenze des Fensters beginnen viele Modelle, sich zu beeilen: Sie überspringen die Prüfung und wählen die einfache statt der richtigen Lösung. Anthropic beschreibt diese Beobachtung für die eigenen Modelle; wie stark der Effekt ausfällt, unterscheidet sich von Modell zu Modell. Eine lange Sitzung am Rand des Kontexts birgt also nicht nur das Risiko, Informationen zu verlieren, sondern auch das, die Qualität der Arbeit zu verschlechtern.

Kompaktierung: was erhalten bleibt und was verloren geht

Kompaktierung bedeutet, den frühen Teil des Dialogs zu einer kurzen Zusammenfassung zu verdichten, um in derselben Sitzung Platz zu schaffen. In Claude Code erledigt das der Befehl /compact, außerdem erfolgt sie automatisch, wenn das Limit naht. Der Befehl /clear dagegen leert den Verlauf und beginnt das Gespräch neu.

Das Problem der Kompaktierung: Die Zusammenfassung behält meist das »Was« und verliert das »Warum«. Fertiger Code bleibt in den Dateien, die Überlegungen – warum Variante B gewählt wurde, warum keine Bibliothek genommen wurde, warum eine Optimierung bewusst ausgelassen wurde – schrumpfen auf ein paar Worte oder verschwinden. Der nächste Schritt des Agenten »verbessert« dann eine bewusste Entscheidung, weil er die Gründe nicht mehr sieht.

Eine praktische Faustregel ohne komplizierte Kennzahlen: Wenn die Aufgabe etwa 60 % des Fensters belegt, hören Sie auf, Code zu schreiben, und bereiten Sie die Übergabe vor. Ist der Kontext dagegen zu 40 % belegt und das Ende der Aufgabe in Reichweite, reicht die Kompaktierung.

Vier Artefakte, aus denen das Gedächtnis des Agenten besteht

Statt auf das Gedächtnis des Modells zu hoffen, legen Sie ein Bordbuch an. Es besteht aus vier Teilen, jeder mit einer eigenen Rolle.

1. PROGRESS.md – wo wir jetzt stehen.
2. DECISIONS.md – warum es so und nicht anders gemacht wurde.
3. Git-Commits – kostenlose Kontrollpunkte des Zustands.
4. Schichtprotokoll in AGENTS.md – was beim Beginn und beim Ende zu tun ist.

PROGRESS.md: die Fortschrittsdatei

Sie beantwortet eine Frage: In welchem Zustand befindet sich das Projekt gerade? Der Agent liest sie zu Beginn der Sitzung als Erstes und aktualisiert sie zuletzt vor dem Ende. Die Datei bleibt kurz; man schreibt sie um, statt endlos anzuhängen, denn die Historie lebt in Git.

# PROGRESS.md

## Aktuelles Ziel
Suche im Produktkatalog (Funktion search-01)

## Zustand
- HEAD: 4f2a9c1
- make check: grün, 142/142 Tests
- Erledigt: Index in PostgreSQL (tsvector), Endpunkt GET /search
- Geprüft: Unit-Tests + manueller Aufruf per curl mit 3 Suchbegriffen

## Blockaden
- Keine Daten zur Morphologie für Kasachisch – warten auf Entscheidung

## Nächster Schritt
Paginierung für GET /search ergänzen, Kriterium: Test für die 2. Seite

Beachten Sie die vier Felder, die für eine Übergabe ausreichen: Commit-Hash, Anteil der bestandenen Tests, Blockaden und nächster Schritt. Kann eine frische Sitzung anhand dieser Datei nicht eindeutig weiterarbeiten, fehlt dem Muster ein Feld.

DECISIONS.md: das Entscheidungsprotokoll

Hier steht das »Warum«, das bei der Kompaktierung verloren geht. Format eines Eintrags: Entscheidung, Begründung, was verworfen wurde und warum, Einschränkungen.

## 2026-03-14 – Cache der Benutzereinstellungen in Redis
- Entscheidung: Redis, TTL 5 Minuten, aktive Invalidierung beim Schreiben.
- Begründung: wird bei jeder Anfrage gelesen, das Datenvolumen ist winzig.
- Verworfen: materialized view in PostgreSQL – Änderungen zu häufig,
  der Pflegeaufwand lohnt sich nicht.
- Einschränkung: Zahlungseinstellungen nicht cachen.

Die wertvollste Zeile hier ist »Verworfen«. Sie verhindert, dass die nächste Sitzung die Entscheidung zu der Variante zurückoptimiert, die bereits geprüft und verworfen wurde. Das Entscheidungsprotokoll wächst nur: Alte Einträge werden nicht gelöscht, sondern als durch neuere ersetzt markiert.

Git-Historie als Kontrollpunkte

Commits sind bereits eingebaute, versionierte Schnappschüsse des Zustands. Der Agent kann git log und git diff lesen und rekonstruieren, was sich geändert hat. Damit die Historie als Gedächtnis funktioniert, muss die Commit-Nachricht das Vorhaben erklären, nicht den Diff nacherzählen.

# schlecht
git commit -m "update search.py"

# gut
git commit -m "search: tsvector-Index statt LIKE

LIKE '%q%' nutzt keinen Index, bei 200k Produkten dauert die Abfrage 1.8 s.
Die Paginierung fehlt noch, siehe PROGRESS.md."

Kleine, häufige Commits nach jedem grünen Testlauf liefern außerdem einen Rücksprungpunkt. Ist eine Sitzung in die falsche Richtung gelaufen, ist es einfacher, zum letzten geprüften Zustand zurückzukehren, als halbfertige Änderungen zu entwirren.

Schichtprotokoll in AGENTS.md

Die Zustandsdateien nützen wenig, wenn der Agent nicht von ihnen weiß. Deshalb schreibt man in die Eingangsdatei der Anweisungen (AGENTS.md oder CLAUDE.md) ein kurzes Protokoll: was beim Beginn und beim Ende zu tun ist.

## Beginn der Schicht
1. PROGRESS.md und DECISIONS.md lesen.
2. Die aktive Aufgabe in .agent/feature_list.json finden.
3. make check ausführen – sicherstellen, dass das Repository konsistent ist.
4. Mit dem »nächsten Schritt« weitermachen, ohne Gelöstes erneut zu öffnen.

## Ende der Schicht
1. make check ausführen, den grünen Zustand committen.
2. PROGRESS.md aktualisieren: HEAD, Tests, Blockaden, nächster Schritt.
3. Neue Entscheidungen in DECISIONS.md ergänzen.
4. Nichts Unfertiges im Arbeitsverzeichnis zurücklassen.

Das Protokoll sollte kurz bleiben: Es sind einige Zeilen in der Eingangsdatei, kein eigenes Mammutwerk.

Init-Skript: wie man den Sitzungsstart beschleunigt

Damit der Agent sich das Bild nicht selbst zusammensuchen muss, geben Sie ihm ein Skript, das die Umgebung prüft und den Zustand ausgibt. Das Skript sollte idempotent sein – man darf es beliebig oft starten – und mit einer klaren Bereitschaftsmeldung enden.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Umgebung =="
command -v uv >/dev/null || { echo "FAIL: uv ist nicht installiert"; exit 1; }
uv sync --frozen

echo "== 2. Repository =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: Arbeitsverzeichnis ist unsauber"
else
  echo "OK: sauber"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Prüfung =="
make check

echo "== 4. Zustand =="
cat PROGRESS.md

echo "Bereit zur Arbeit"

Im Schichtprotokoll genügt dann eine Zeile: »Starte scripts/init.sh«. In Claude Code lässt sich dieser Start mit einem Hook auf den Sitzungsbeginn (Ereignis SessionStart) automatisieren; ohne Hook führt der Agent das Skript aber ebenfalls aus, wenn die Anweisung in der Datei steht.

Was ins Gedächtnis des Agenten gehört und was nicht

Der größte Fehler ist, das Gedächtnis zur Müllhalde zu machen. Jede Zeile, die der Agent beim Start liest, belegt Platz im Kontext, und Unwichtiges verdrängt das Wichtige.

Trennen Sie außerdem nach Lebensdauer. Die Projektregeln ändern sich selten und betreffen alle Aufgaben – ihr Platz ist die Eingangsdatei der Anweisungen. Der Zustand ändert sich in jeder Sitzung – sein Platz ist die Fortschrittsdatei. Vermischt man beides, wächst die Eingangsdatei schnell mit veralteten Notizen.

Erste Sitzung: die Initialisierung als eigene Phase

Das Gedächtnis zwischen Sitzungen hilft wenig, wenn schon die erste Sitzung im Chaos endet. Ein typisches Bild: Sie schreiben in ein frisches Repository »füge eine Suche hinzu«, und nach einer halben Stunde zeigt sich, dass das Testframework falsch konfiguriert ist und das Format der Migrationen nicht passt. Die Suche existiert, aber das Fundament ist schief.

Der Grund: Umsetzung und Initialisierung optimieren verschiedene Dinge. Die Umsetzung optimiert die Zahl fertiger Funktionen in dieser Sitzung, die Initialisierung die Geschwindigkeit und Verlässlichkeit aller folgenden. Der Agent neigt zum sichtbaren Ergebnis, also zum Code. Deshalb sollte man die Initialisierung in eine eigene Sitzung mit einem klaren Fertigkriterium aus vier Punkten auslagern.

• Starten: make setup und make dev funktionieren auf einem frischen Klon.
• Prüfen: es gibt make test und mindestens einen echten, bestehenden Test.
• Fortschritt sehen: die Zustandsdatei existiert und ist lesbar.
• Die Arbeit übernehmen: es gibt eine Aufgabenliste mit Abnahmekriterien.

Wenn Sie oft neue Projekte beginnen, legen Sie eine Repository-Vorlage an: Makefile, Testframework, Gerüst der AGENTS.md, Ordner .agent/, scripts/init.sh, Linter und CI. Dann reduziert sich die Initialisierung auf die Besonderheiten des konkreten Projekts.

Wie man prüft, dass das Gedächtnis funktioniert

Die ehrlichste Kennzahl ist die Zeit vom Start einer neuen Sitzung bis zur ersten sinnvollen Änderung am Code. Ohne Artefakte sind das meist fünfzehn bis zwanzig Minuten Erkundung, bei einer guten Übergabe zwei bis drei. Messen Sie es einmal vorher und einmal nachher, dann sehen Sie, ob sich die Disziplin lohnt.

Die zweite Methode ist der Kaltstart-Test. Öffnen Sie eine frische Sitzung, schreiben Sie »mach weiter« und stellen Sie fünf Fragen: Was ist das aktuelle Ziel, in welchem Zustand sind die Tests, welche Entscheidung wurde zum Hauptthema getroffen und warum, was blockiert, was ist der nächste Schritt? Beantwortet der Agent alle fünf anhand der Dateien, ohne zu raten, ist das Gedächtnis richtig aufgebaut. Jede unsichere Antwort zeigt ein fehlendes Feld in der Vorlage.

Typische Fehler

• Die Fortschrittsdatei wächst nur. Nach einem Monat stehen darin Hunderte Zeilen Historie. Schreiben Sie sie auf den aktuellen Zustand um; die Historie gehört in Git.
• Keine Zeile »Verworfen«. Ein Entscheidungsprotokoll ohne verworfene Varianten schützt nicht vor erneutem Streit.
• Der Agent aktualisiert den Zustand »nach Gefühl«. Schreiben Sie auf, wie geprüft wurde: Befehl und Ergebnis, nicht »alles funktioniert«.
• Übergabe am Rand des Fensters. Nahe der Kontextgrenze beeilt sich der Agent bereits; beginnen Sie die Übergabe rechtzeitig, etwa bei 60 %.
• Unsauberes Arbeitsverzeichnis am Ende. Halbfertige Änderungen ohne Commit verwirren die nächste Sitzung.

Kurz gesagt

Das Gedächtnis eines KI-Agenten zwischen Sitzungen baut man nicht auf dem Modell, sondern auf Dateien: PROGRESS.md hält den aktuellen Zustand fest, DECISIONS.md die Gründe und verworfenen Varianten, Git-Commits sind Kontrollpunkte mit erklärtem Vorhaben, und das Schichtprotokoll in AGENTS.md sorgt dafür, dass all das gelesen und aktualisiert wird. Das Init-Skript verkürzt den Start auf einen Befehl, und der Kaltstart-Test zeigt, ob die Einträge reichen. Das Bordbuch des Agenten und der Bootstrap-Vertrag werden im Kurs zum Harness-Engineering praktisch durchgespielt.