# Gedächtnis: Entscheidungen, Erkenntnisse und das Brain

> Wie BMAD+ Entscheidungen, Erkenntnisse und Übergaben bewahrt: Projektgedächtnis, globales oder Portfolio-Brain samt Erkennung, Zecher, mem- und memory-Befehle und was nie überschrieben wird.

Canonical: https://bmad-plus.rochetta.fr/de/docs/concepts/how-memory-works/
Language: de
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ Dokumentation › [Konzepte](https://bmad-plus.rochetta.fr/de/docs/concepts/) › 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.

> **Hinweis · Das Pack ist optional und dateibasiert** Das Gedächtnis ist das Pack `memory` (Installation mit `--packs core,memory`). Es braucht nur Node.js. Vektor- oder RAG-Abruf ist ein optionales, rein lokales Extra über einen separat betriebenen MCP-Server, der nicht zum npm-Paket gehört; ohne ihn funktionieren Markdown-Gedächtnis und Projekt-Scanner unverändert.

<a id="two-levels"></a>
## Zwei Ebenen: Projektgedächtnis und Brain

**Wo das Gedächtnis liegt**

| Ebene | Ort | Inhalt |
| --- | --- | --- |
| Projektgedächtnis | `.agents/memory/` im Projekt | Entscheidungen, Erkenntnisse, Muster, Kontext und Sitzungsübergaben nur dieses einen Projekts. |
| Globales Brain | `~/.bmad-plus/brain/` | Deine Identitätsdatei, projektübergreifende Entscheidungen, Erkenntnisse und Muster sowie ein Index deiner BMAD+-Projekte. |
| Portfolio-Brain | Ein Ordner `_brain/` im Projekt oder in einem übergeordneten Ordner | Dieselbe Idee, in deiner Hand, mit deiner eigenen Struktur. Er hat Vorrang vor dem globalen 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.

<a id="brain-detection"></a>
## Wie ein vorhandenes Brain erkannt wird

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

**Reihenfolge der Brain-Auflösung**

| Reihenfolge | Quelle | Erfasster Typ |
| --- | --- | --- |
| 1 | Die Umgebungsvariable `BMAD_PLUS_BRAIN`, wenn sie ein Verzeichnis benennt (sonst eine Warnung und die nächste Regel). | `portfolio` |
| 2 | Ein Verzeichnis `_brain/` im Projektordner oder in einem seiner übergeordneten Ordner. | `portfolio` |
| 3 | `~/.bmad-plus/brain/`, falls vorhanden. | `bmad-global` |
| 4 | `~/.claude/memory/`, nur wenn es ein nicht leeres Verzeichnis ist. | `claude-memory` |
| 5 | Nichts gefunden: Ein neues globales Brain wird unter `~/.bmad-plus/brain/` angelegt. | `bmad-global` |

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.

**.agents/memory/.brain-link nach einer Erstinstallation auf einer Maschine ohne Brain**

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

<a id="memory-files"></a>
## Die Dateien und wann Agenten sie anfassen

**Dateien des Projektgedächtnisses**

| Datei | Was hineingehört | Geschrieben wenn |
| --- | --- | --- |
| `decisions.md` | Einträge im Architekturstil: Kontext, Entscheidung, Begründung, Folgen, Status (aktiv, ersetzt, zurückgenommen). | Eine nicht offensichtliche Wahl wird getroffen. Würdest du einem Kollegen das „Warum“ erklären, ist es eine Entscheidung. |
| `lessons.md` | Kontext, Auswirkung und die Regel für das nächste Mal. | Etwas Unerwartetes geschieht oder eine Annahme erweist sich als falsch. Sofort, nicht am Sitzungsende. |
| `patterns.md` | Problem, Form, Abwägung, Status (Kandidat, dann validiert). | Eine Lösung funktioniert und ließe sich wiederverwenden. |
| `context.md` | Der lebendige Zustand des Projekts, in 30 Sekunden lesbar. | Das Projekt ändert sich wesentlich (neues Modul, Stack-Wechsel, Architekturwende). |
| `sessions/` | Eine datierte Übergabe je Sitzung: `YYYY-MM-DD-<topic>.md`. | Das Ende einer Sitzung, in der wesentliche Arbeit geleistet wurde. |

**Das Format eines Eintrags in decisions.md (aus der installierten Vorlage)**

```md
### 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
```

<a id="protocol"></a>
### 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.

<a id="guardrails"></a>
### 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.

**G1 bis G4**

| Regel | Kurz gesagt | Bezug zum Gedächtnis |
| --- | --- | --- |
| G1 Think Before Coding | Annahmen nennen; bei Unsicherheit fragen. | `decisions.md` prüfen, bevor man erneut entscheidet. |
| G2 Simplicity First | Das Minimum, das das Problem löst, nichts Spekulatives. | In `patterns.md` nach einer vorhandenen Lösung suchen. |
| G3 Surgical Changes | Nur anfassen, was nötig ist; den vorhandenen Stil beibehalten. | Überraschungen in `lessons.md` festhalten. |
| G4 Goal-Driven Execution | Erfolgskriterien vor der Implementierung festlegen. | Nicht offensichtliche Entscheidungen in `decisions.md` festhalten. |

<a id="zecher"></a>
## 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.

**Was du Zecher fragen kannst**

| Du sagst | Was geschieht |
| --- | --- |
| „Zecher, konsolidiere das Gedächtnis“ | Audit: liest die Gedächtnisdateien und Sitzungen; schlägt zusammenzuführende Duplikate, aktive Entscheidungen über 90 Tage zur Prüfung und zu übernehmende Erkenntnisse vor; wendet nur Genehmigtes an; archiviert veraltete Einträge mit dem Präfix `[ARCHIVED]`. |
| „Zecher, scanne die Projekte in ~/dev“ | Durchsucht den Ordner nach Projektmarkern, erkennt Stack und Status, zeigt eine Tabelle und lässt dich je Projekt bestätigen, bearbeiten, überspringen oder BMAD+ installieren; schreibt dann den Index. |
| „Zecher, wo waren wir?“ | Rekonstruiert den Projektzustand aus `context.md`, der letzten Übergabe, dem Projekteintrag im Brain, den letzten 10 Git-Commits und der Anweisungsdatei; präsentiert eine kurze Zusammenfassung. |
| „Zecher, Gesundheitscheck“ | Prüft, dass die Gedächtnisdateien existieren und wohlgeformt sind, meldet alte aktive Entscheidungen und wiederkehrende Erkenntnisse und berichtet Statistiken. |
| „Zecher, was wissen wir über [Thema]?“ | Gleicht alle Gedächtnisdateien ab. |
| „Zecher, übernimm Erkenntnis [X] ins Globale“ | Schlägt vor, eine Erkenntnis ins Brain zu verschieben; verschiebt nur mit deiner Genehmigung. |

<a id="commands"></a>
## Die Befehle: memory, scan und mem

**Gedächtnisbezogene Befehle**

| Befehl | Was er tut |
| --- | --- |
| `memory status` | Gesundheitsbericht des Projektgedächtnisses und des verknüpften Brains, als Prozentsatz bestandener Prüfungen. |
| `memory export` | Schreibt `bmad-brain-export-<YYYY-MM-DD>.md` in den Projektordner: ein portables Markdown-Archiv des Brains. |
| `scan [path]` | Findet Projekte, erkennt Stacks und indexiert sie im globalen Brain. `--depth` (Standard 4), `--active-days` (30), `--paused-days` (180), `--yes` zum Indexieren ohne Rückfrage. Status: aktiv unter 30 Tagen, pausiert 30 bis 180, archiviert darüber. |
| `mem recall <query>` | Nach Relevanz geordneter Abruf über Journal und Gedächtnisnotizen. `--limit` (Standard 8), `--scope project\|portfolio`, `--portfolio PATH`, `--json`. |
| `mem recall ... --ranking evidence --context-scope PATHS` | Optionales Ranking, das Quellen und Nexus-Akzeptanz erneut prüft und aktuellen, relevanten Belegen einen begrenzten Schub gibt. Es verlangt einen ausdrücklichen, nicht leeren Bereich. |
| `mem write` | Hängt ein strukturiertes Ereignis an das Journal `.bmad/memory/journal.ndjson` an: `--agent`, `--cli` (claude-code, gemini-cli, codex-cli, cursor, opencode, aider, antigravity), `--model`, `--task`, `--outcome success\|failure\|partial\|abandoned` und optionale Signale `--eval 0-1`, `--accept true\|false\|0-1`, `--ci pass\|fail\|0-1`. |
| `mem reinforce --pattern ID` | Rechnet eine Belohnung in den Score eines Musters ein (`.bmad/memory/pattern-scores.json`). Eine Übernahme wird nur VORGESCHLAGEN, wenn der Mittelwert bei mindestens 3 Updates 0,7 erreicht. Diese Signale sind selbstberichtet und speisen das Beleg-Ranking nicht. |
| `mem observe --input FILE` | Verknüpft einen exakten Markdown-Abschnitt deines Gedächtnisses mit einer bereits verifizierten und akzeptierten Nexus-Aufgabe (Eingabe: Lauf, Aufgabe, Datei und Überschrift, Scope-Pfade, deine Deutung, optional supersedes oder contradicts). Es hält Herkunft fest; es beweist nicht, dass die Erkenntnis den Erfolg verursachte. |
| `mem outcomes` | Listet die erfassten Beobachtungen und ob jede noch geeignet ist (Änderungen an Quelle oder Artefakt, Ablösung und Widersprüche machen eine Beobachtung ungeeignet). |

**Ins Journal schreiben, abrufen, exportieren**

```text
$ 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.
```

Ausgabe eines echten Laufs. Quelle: bmad-plus 0.23.0, 2026-10-19

<a id="never-overwritten"></a>
## 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.

**Nach der Deinstallation ist das Gedächtnis noch da**

```text
$ 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.
```

Ausgabe eines echten Laufs. Quelle: bmad-plus 0.23.0, 2026-10-19

<a id="example-memory-where-were-we"></a>
### Ein Projekt mit Zecher kalt wieder aufnehmen

Nutze es zu Beginn einer Sitzung, wenn du oder der Assistent den Faden verloren habt, mit installiertem Memory-Pack.

**In deinem KI-Assistenten**

```text
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.
```

**Das solltest du erhalten** Eine kurze „Projektstand“-Zusammenfassung: was das Projekt ist, sein Stack, woran zuletzt gearbeitet wurde, offene Fragen der letzten Sitzung, bekannte Probleme und Erkenntnisse. Fehlende Quellen werden als fehlend genannt. Es wird nichts geschrieben, außer du verlangst eine Übergabe.

<a id="example-memory-consolidate-with-approval"></a>
### Das Gedächtnis aufräumen, ohne etwas zu verlieren

Nutze es, wenn die Gedächtnisdateien gewachsen sind und wiederholte oder veraltete Einträge enthalten.

**In deinem KI-Assistenten**

```text
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.
```

**Das solltest du erhalten** Eine Befundliste (N Duplikate, M veraltete Einträge, K Übernahmekandidaten) und eine Frage je vorgeschlagener Änderung. Nach deiner Freigabe werden Duplikate unter Beibehaltung der reichhaltigsten Fassung zusammengeführt, veraltete Einträge mit dem Präfix `[ARCHIVED]` nach unten verschoben und genehmigte Erkenntnisse ins Brain übernommen. Nichts wird gelöscht.

**Siehe auch**

- [Das Memory-Pack](https://bmad-plus.rochetta.fr/de/docs/packs/memory-pack/)
- [Referenz: bmad-plus memory](https://bmad-plus.rochetta.fr/de/docs/reference/cli-memory/)
- [Referenz: bmad-plus mem](https://bmad-plus.rochetta.fr/de/docs/reference/cli-mem/)
- [Referenz: bmad-plus scan](https://bmad-plus.rochetta.fr/de/docs/reference/cli-scan/)
- [Vertrauen und Eigentum](https://bmad-plus.rochetta.fr/de/docs/security/trust-and-ownership/)
- [Nexus und dauerhafte Läufe](https://bmad-plus.rochetta.fr/de/docs/concepts/nexus-orchestration/)

[BMAD+ Dokumentation](https://bmad-plus.rochetta.fr/de/docs/) · [Konzepte](https://bmad-plus.rochetta.fr/de/docs/concepts/)

[Quellcode auf GitHub](https://github.com/lrochetta/BMAD-PLUS)