Gedächtnis: Entscheidungen, Erkenntnisse und das Brain

Eine neue Sitzung eines KI-Assistenten beginnt bei null: Er weiß nicht mehr, warum du letzte Woche eine Bibliothek gewählt hast oder was am Dienstag schiefging. Das Memory-Pack behebt das mit einfachen Markdown-Dateien in deinem Projekt, einem Protokoll, das jedem Agenten sagt, wann er sie liest und schreibt, und einem Agenten, Zecher, der sie in Ordnung hält. Diese Seite erklärt, wo das Gedächtnis liegt, wie ein vorhandenes Brain erkannt und verknüpft wird, welche Befehle es berühren und was garantiert nie überschrieben wird. Sie richtet sich an alle, die über mehrere Sitzungen am selben Projekt arbeiten oder an mehreren Projekten, die teilen sollen, was sie lernen.

Zwei Ebenen: Projektgedächtnis und Brain#

Die goldene Regel: Informationen, die ein Projekt betreffen, gehören ins Projektgedächtnis; Informationen, die zwei oder mehr Projekte betreffen, sind Kandidaten für das Brain. Die Übernahme von einem zum anderen ist nie automatisch. Zecher schlägt vor, du genehmigst.

Wie ein vorhandenes Brain erkannt wird#

Ist das Memory-Pack installiert, sucht BMAD+ ein Brain, bevor es etwas anlegt. Der erste Treffer gewinnt.

Das Ergebnis wird in .agents/memory/.brain-link festgehalten, damit jeder Agent und jeder Befehl dasselbe Brain findet. Ein gefundenes Brain wird verknüpft, nie kopiert oder umgeschrieben: keine Duplikate, kein Überschreiben. Ein Portfolio- oder claude-memory-Brain behält seine eigenen Konventionen; BMAD+ legt darin weder identity.yaml noch projects/ an und ergänzt einen Projektindex-Eintrag nur, wenn das verknüpfte Brain das globale BMAD+-Brain ist. Agenten sollen zuerst den eigenen Einstiegspunkt eines Portfolio-Brains (README.md, AGENTS.md oder HOT.md) lesen und seiner Struktur folgen.

{
  "linked_brain": "/work/demo/home/.bmad-plus/brain",
  "brain_type": "bmad-global",
  "linked_at": "2026-10-19T02:13:36.733Z"
}

Die Dateien und wann Agenten sie anfassen#

### YYYY-MM-DD — <short title>
- **Context**: why the decision was needed
- **Decision**: what was chosen
- **Rationale**: why
- **Consequences**: what this unlocks / forecloses
- **Status**: active / superseded / rolled-back

Das Lese- und Schreibprotokoll#

1. Sitzungsbeginn (Lesen): identity.yaml des Brains, dann context.md, decisions.md und lessons.md des Projekts und bei Wiederaufnahme die letzte Übergabe in sessions/. Eine fehlende Datei wird still übersprungen: Gedächtnis ist immer optional.
2. Während der Sitzung (Schreiben bei Auslöser): Entscheidungen, Erkenntnisse, Muster und Kontext wie in der Tabelle oben.
3. Sitzungsende (Sichern): eine Übergabe in sessions/, ein aktualisierter context.md, ein Blick auf offene Erkenntnisse und eine projektübergreifende Prüfung, die nur Übernahmen vorschlägt.

Die vier Leitplanken#

Die generierten Anweisungen jedes Agenten tragen vier Verhaltensregeln, angepasst aus einem Community-Projekt, das von Andrej Karpathys Ratschlägen inspiriert ist (Quellenangabe auf der Vertrauensseite). Sie verbinden die Gedächtnisdateien mit dem Alltagsverhalten.

Zecher, der Gedächtnis-Agent#

Zecher (der Name bedeutet auf Hebräisch „Erinnerung“) ist ein Hilfsagent: Du oder ein anderer Agent rufen ihn, wenn das Gedächtnis Aufmerksamkeit braucht. Er ist kein Orchestrator. Seine Regeln: Gedächtnis nie löschen (archivieren, konsolidieren, nie zerstören), vor einer Übernahme ins Brain immer fragen, Daten nach ISO 8601 (YYYY-MM-DD, nie „letzte Woche“), knappe Einträge, in zehn Sekunden lesbar, und Querverweise zwischen einer Erkenntnis und der betroffenen Entscheidung.

Die Befehle: memory, scan und mem#

$ npx bmad-plus mem write --agent atelier --cli claude-code --task "Design read for the Orbit landing page: one job, the loyalty card sign-up" --outcome success --ci pass
mem write: event 912e91734848 appended (2026-10-19T02:13:48.840Z)
  agent=atelier cli=claude-code model=- outcome=success
  task: Design read for the Orbit landing page: one job, the loyalty card sign-up
$ npx bmad-plus mem recall "loyalty card sign-up"
mem recall: 2 match(es) for "loyalty card sign-up" (scope: project)
  1. [0.707] event journal.ndjson#912e91734848
     atelier claude-code Design read for the Orbit landing page: one job, the loyalty card sign-up success {"ci":"pass"}
  2. [0.522] note decisions.md § 2026-10-18 — The landing page has one job, the loyalty card sign-up
     2026-10-18 — The landing page has one job, the loyalty card sign-up - **Context**: design read for the Orbit landing pa…
$ npx bmad-plus mem outcomes
mem outcomes: no observations.
$ npx bmad-plus memory export
◆  📦 Brain exported to: /work/demo/app/bmad-brain-export-2026-10-19.md
# Vor dem Abruf wurde in decisions.md von Hand ein Entscheidungseintrag im oben gezeigten Format ergänzt. Ohne akzeptierte Nexus-Aufgabe gibt es keine Beobachtung, das Beleg-Ranking fügt dem einfachen Ranking also nichts hinzu.

Was nie überschrieben wird#

• Installieren und Aktualisieren überschreiben nie decisions.md, lessons.md oder patterns.md, löschen nie sessions/ und behalten deine Änderungen an context.md und identity.yaml. Fehlende Dateien werden aus Vorlagen angelegt; vorhandene bleiben unangetastet.
• Ein erkanntes Brain wird verknüpft, nicht kopiert oder umgeschrieben. Dateien des globalen Brains werden nur angelegt, wenn sie fehlen; eine unterbrochene ältere Installation konnte ein „halbes Brain“ hinterlassen, und der aktuelle Code vervollständigt es idempotent, ohne Vorhandenes anzufassen.
• Deinstallieren entfernt die Dateien, die BMAD+ gehören, und behält .agents/memory/, _bmad/config.yaml und alles, was dir gehört oder geändert wurde (siehe nächster Block).
• Ein Fehler bei der Gedächtnis-Initialisierung ist nicht fatal: Ist das Home-Verzeichnis schreibgeschützt (Container, CI), läuft die Installation weiter und warnt.
• Geteilte Schreiber nutzen .bmad/memory/writer.lock. Nach einer Unterbrechung prüfe Besitzer und Dateien vor jeder manuellen Wiederherstellung; entferne nie die Sperre eines lebenden Schreibers, und beschädigte Ergebnisbelege werden nie automatisch zurückgesetzt.

$ npx bmad-plus uninstall --yes
●  BMAD+ v0.23.0 (installed 2026-10-19)
●  Selected packs: core, memory
◇  ✅ BMAD+ removed (60 items)
└  Project memory, settings, and unknown or modified files have been preserved.
$ find . -path ./.git -prune -o -print | sort
./.agents/memory/.brain-link
./.agents/memory/context.md
./.agents/memory/decisions.md
./.agents/memory/lessons.md
./.agents/memory/patterns.md
./.agents/memory/sessions
./.bmad/memory/journal.ndjson
./_bmad/config.yaml
./bmad-brain-export-2026-10-19.md
# Ordner, die nur leere Verzeichnisse enthielten, und die eigenen Dateien des Projekts (README.md, docs) fehlen in diesem Auszug. Das globale Brain im Home-Verzeichnis wurde nicht berührt.

Zecher, wo waren wir? Rekonstruiere den Zustand dieses Projekts aus context.md, der letzten Sitzungsübergabe, dem Brain-Eintrag und den letzten Commits. Sag mir, was entschieden wurde, was unfertig ist und welche Erkenntnisse für die nächste Aufgabe gelten. Nenne klar, was du nicht finden konntest, und rate nicht.

Zecher, konsolidiere das Gedächtnis. Prüfe zuerst nur: Liste die Duplikate und die aktiven Entscheidungen über 90 Tage auf und schlage vor, was zusammenzuführen, zu archivieren oder ins globale Brain zu befördern ist. Wende nichts an, bis ich jede Änderung genehmigt habe, archiviere statt zu löschen und schreibe Daten als YYYY-MM-DD.