Drei-Ebenen-Gedächtnis: Wie ich meiner KI das Erinnern beigebracht habe

Jede KI-Session fängt bei null an. Leere Tafel. Die KI von gestern — die deine Codebasis kannte, sich an die Entscheidung erinnerte, ein bestimmtes Pattern zu vermeiden, wusste, warum du in Session 3 diesen architektonischen Kompromiss gemacht hast — weg. Du verbringst die ersten 20 Minuten damit, Kontext neu zu erklären, den du schon längst erklärt hattest, und siehst zu, wie der Agent dieselben tastenden ersten Schritte macht wie beim letzten Mal.

Das hat mich genug gestört, dass ich was dagegen gebaut habe. Keine ausgefeilte Vektordatenbank. Kein RAG-System. Etwas viel Einfacheres: eine Drei-Ebenen-Speicherarchitektur, die KI-Kontext behandelt wie ein Computer seine Daten.

Die drei Ebenen

Ebene 1: STATUS.md — RAM

STATUS.md ist das Arbeitsgedächtnis des Agenten. Eine einzelne Datei, die zu Beginn jeder Session neu geschrieben wird. Inhalt: aktueller Projektstand, aktive Arbeitspunkte, frische Entscheidungen, offene Fragen — alles, was der Agent braucht, um direkt dort weiterzumachen, wo wir aufgehört haben.

Das Ziel: vollständige Kontext-Wiederherstellung in unter 60 Sekunden. Ein Agent, der STATUS.md gelesen hat, soll „wo stehen wir?” beantworten können, ohne mich zu fragen.

Das ist wie RAM — schnell, flüchtig, immer aktuell, wird jedes Mal überschrieben.

Ebene 2: Tagesjournale — Festplatte

Am Ende jeder Session schreibt der Agent einen Journaleintrag. Nur anhängen, nie nachträglich bearbeiten. Jeder Eintrag dokumentiert: was geliefert wurde, welche Entscheidungen gefallen sind, was gelernt wurde, was noch unklar ist.

Die Journale sind die dauerhafte Aufzeichnung. Wenn STATUS.md verloren geht oder veraltet ist, lässt sie sich aus den Journalen rekonstruieren. Zum täglichen Lesen sind sie nicht gedacht — sie sind das Archiv, das man aufschlägt, wenn man verstehen muss, warum etwas so ist, wie es ist.

Ebene 3: Facts — Destilliertes Wissen

Facts sind Muster, die aus den Journalen kondensiert werden. Die Regel: Taucht etwas in 3 oder mehr Journaleinträgen auf, wird es zum Fact befördert. Ein Fact ist dauerhaft, knapp und gehört dem Projekt — nicht einer einzelnen Session.

Typische Beispiele: „Maven braucht immer das -pl module-Flag, sonst baut er das Falsche.” „Die CI-Pipeline behandelt Checkstyle-Warnungen als Fehler — nicht die Regel abschwächen, den Code fixen.” „Wenn der Type-Checker sich über nullable Optionals beschwert, liegt das eigentliche Problem meist zwei Ebenen höher bei einem fehlenden Null-Check.”

Das sind keine Dinge, die du jede Session neu entdecken willst.

Die entscheidende Einsicht: Komprimieren statt Erzählen

Die wichtigste Erkenntnis: Zustand wiederherstellen, nicht Geschichte nacherzählen.

Der naive Ansatz ist, der KI die ganze Story zu erzählen. „Wir haben in Session 1 angefangen, uns für diese Architektur entschieden, in Session 4 ein Problem mit X getroffen und es mit Y gelöst…” Das ist langsam, token-teuer, und versetzt den Agenten in einen passiven Zuhör-Modus statt in einen aktiven Arbeitsmodus.

Der bessere Weg ist Komprimierung. STATUS.md erzählt keine Geschichte. Es zeigt einen Zustand. Fünf Stichpunkte statt fünf Seiten. Was jetzt gilt — nicht wie wir dahin gekommen sind.

Bei einem Projekt, das ich mehrere Wochen laufen hatte, hab ich das gemessen: Die vollständige Journalhistorie war über 50.000 Wörter. STATUS.md waren 4.000 Wörter. Der Agent konnte den Kontext allein aus STATUS.md vollständig wiederherstellen. Das ist Faktor 12,5 — gleicher praktischer Nutzen, ein Bruchteil der Tokens.

Warum das den Unterschied macht

Ohne persistentes Gedächtnis ist jede Session Session 1. Der Agent ist fähig, aber ohne Vorwissen. Er kennt die Konventionen nicht, die Stolperfallen, die Entscheidungen, die schon gefallen sind. Entweder erklärt man alles neu — oder man schaut zu, wie er dieselben Fehler nochmal macht.

Mit persistentem Gedächtnis weiß Session 24, was Session 1 gelernt hat. Der Agent häuft Domänenwissen an. Er macht Fehler nicht zweimal. Er trifft schneller bessere Entscheidungen, weil der Kontext einfach da ist.

Das Gedächtnissystem ist nicht nur Komfort — es ist die Identität des Agenten. Ohne es: ein fähiges Tool. Mit ihm: etwas, das sich mehr nach Kollege anfühlt. (Diese Identität wurde konkret, als das System einen Namen bekam — mehr dazu in Cairn benennen.)

Der Fehlerfall, der das bewiesen hat

Das tägliche Journalsystem hab ich erst in Session 23 eingeführt. Die Sessions 3 bis 22 hatten keine Journale. Die Lücke ist real — 20 Sessions Arbeit ohne formale Aufzeichnung.

Als ich das System dann aufgebaut hatte, bin ich zurückgegangen und hab diese 20 Sessions aus der Git-Historie rekonstruiert — Commit-Nachrichten, PR-Beschreibungen, Kommentare — und später aus 700 MB Claude Code Gesprächsprotokollen, die bis November 2025 zurückreichten. Es hat mehrere Stunden gedauert und etwas Unvollkommenes ergeben, aber Rekonstruierbares. Diese Vergangenheit gab dem System etwas zum Lernen.

Die Lektion war nicht: unvollkommenes Gedächtnis ist okay. Die Lektion war: selbst lückenhaftes Gedächtnis — selbst teilweise rekonstruiertes — ist dramatisch besser als keins. Der Agent, der diese rekonstruierten Journale gelesen hat, hat sich anders verhalten als einer, der kalt startet. Er wusste Dinge, die er aus STATUS.md allein nie hätte wissen können.

Wenn ich es nochmal täte: Journale von Session 1 an führen, auch wenn sie grob sind. Die Git-Historie ist ein Fallback, kein Ersatz.

So richtet man es ein

In der Praxis sind es drei Dinge:

1. Eine STATUS.md-Datei im Projektstamm, mit der Anweisung an den Agenten, sie als Erstes zu lesen und vor dem Sessionende zu aktualisieren.
2. Ein journal/-Verzeichnis mit einer Datei pro Session, benannt nach dem Schema YYYY-MM-DD-session-N.md.
3. Ein facts/-Verzeichnis mit thematisch sortierten Fact-Dateien — eine für den Tech-Stack, eine für Projektkonventionen, eine für wiederkehrende Stolperfallen.

Der Agent bekommt klare Anweisungen in der CLAUDE.md: STATUS.md beim Sessionstart lesen, während der Arbeit ins heutige Journal schreiben, Muster zu Facts befördern, wenn sie dreimal aufgetaucht sind.

Das ist das ganze System. Keine Spezialwerkzeuge, keine externen Dienste. Nur strukturierte Markdown-Dateien und die Disziplin, sie aktuell zu halten.

Die KI macht das nicht von selbst. Man muss es einrichten, in die Anweisungen einbauen und die Disziplin durchhalten. Aber einmal am Laufen zahlt es sich bei jeder einzelnen Session aus. (Was passiert, wenn man die Disziplin schleifen lässt, steht in The Memory Bloat Crisis — nach zwei Wochen waren die Agent-Dateien auf 95 KB angewachsen.)