# Memory: decisions, lessons and the brain

> How BMAD+ keeps decisions, lessons and handoffs between sessions: project memory, the global or portfolio brain and its detection, Zecher, the mem and memory commands, what is never overwritten.

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

BMAD+ documentation › [Concepts](https://bmad-plus.rochetta.fr/docs/concepts/) › Memory: decisions, lessons and the brain

A new session of an AI assistant starts with nothing: it does not remember why you picked a library last week or what went wrong on Tuesday. The Memory pack fixes that with plain Markdown files in your project, a protocol that tells every agent when to read and write them, and an agent, Zecher, that keeps them tidy. This page explains where the memory lives, how an existing brain is detected and linked, which commands touch it, and what is guaranteed never to be overwritten. It is for anyone who works on the same project across several sessions, or on several projects that should share what they learn.

> **Note · The pack is optional and file-based** Memory is the pack `memory` (install with `--packs core,memory`). It needs Node.js only. Vector or RAG recall is an optional, local-only extra through a separately deployed MCP server that is not part of the npm package; without it, Markdown memory and the project scanner work unchanged.

<a id="two-levels"></a>
## Two levels: project memory and the brain

**Where memory lives**

| Level | Location | Holds |
| --- | --- | --- |
| Project memory | `.agents/memory/` in the project | Decisions, lessons, patterns, context and session handoffs for this one project. |
| Global brain | `~/.bmad-plus/brain/` | Your identity file, cross-project decisions, lessons and patterns, and an index of your BMAD+ projects. |
| Portfolio brain | A `_brain/` folder in the project or any parent folder | The same idea, owned by you with your own layout. It takes precedence over the global brain. |

The golden rule: information that applies to one project goes to project memory; information that applies to two or more projects is a candidate for the brain. Moving it from one to the other is never automatic. Zecher proposes, you approve.

<a id="brain-detection"></a>
## How an existing brain is detected

When the Memory pack is installed, BMAD+ looks for a brain before it creates anything. The first match wins.

**Brain resolution order**

| Order | Source | Recorded type |
| --- | --- | --- |
| 1 | The `BMAD_PLUS_BRAIN` environment variable, if it names a directory (otherwise a warning and the next rule). | `portfolio` |
| 2 | A `_brain/` directory in the project folder or any of its parents. | `portfolio` |
| 3 | `~/.bmad-plus/brain/`, if it exists. | `bmad-global` |
| 4 | `~/.claude/memory/`, only if it is a non-empty directory. | `claude-memory` |
| 5 | Nothing found: a new global brain is created at `~/.bmad-plus/brain/`. | `bmad-global` |

The result is written to `.agents/memory/.brain-link` so that every agent and command finds the same brain. A found brain is linked, never copied or rewritten: no duplication, no overwrite. A portfolio or `claude-memory` brain keeps its own conventions; BMAD+ does not create `identity.yaml` or `projects/` inside it, and it adds a project index entry only when the linked brain is the BMAD+ global one. Agents are told to read a portfolio brain’s own entry point (`README.md`, `AGENTS.md` or `HOT.md`) first and follow its layout.

**.agents/memory/.brain-link after a first install on a machine with no 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>
## The files, and when agents touch them

**Project memory files**

| File | What goes in | Written when |
| --- | --- | --- |
| `decisions.md` | Architecture-style records: context, decision, rationale, consequences, status (active, superseded, rolled-back). | A non-obvious choice is made. If you would explain the "why" to a colleague, it is a decision. |
| `lessons.md` | Context, impact and the rule to follow next time. | Something unexpected happens or an assumption proves wrong. Immediately, not at the end of the session. |
| `patterns.md` | Problem, shape, trade-off, status (candidate, then validated). | A solution works and could be reused. |
| `context.md` | The living state of the project, readable in 30 seconds. | The project changes meaningfully (new module, stack change, shift in architecture). |
| `sessions/` | A dated handoff per session: `YYYY-MM-DD-<topic>.md`. | The end of a session in which meaningful work was done. |

**The format of an entry in decisions.md (from the installed template)**

```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>
### The read and write protocol

1. Session start (read): `identity.yaml` of the brain, then the project’s `context.md`, `decisions.md` and `lessons.md`, and the latest handoff in `sessions/` when resuming. A missing file is skipped silently: memory is always optional.
2. During the session (write on trigger): decisions, lessons, patterns and context as in the table above.
3. Session end (persist): a handoff in `sessions/`, an updated `context.md`, a look at pending lessons, and a cross-project check that only proposes promotions.

<a id="guardrails"></a>
### The four guardrails

The generated instructions of every agent carry four behavioural rules, adapted from a community project inspired by Andrej Karpathy’s guidance (see the trust page for the credit). They tie the memory files to daily behaviour.

**G1 to G4**

| Rule | In short | Memory link |
| --- | --- | --- |
| G1 Think Before Coding | State assumptions; if uncertain, ask. | Check `decisions.md` before deciding again. |
| G2 Simplicity First | The minimum that solves the problem, nothing speculative. | Check `patterns.md` for an existing solution. |
| G3 Surgical Changes | Touch only what you must; match the existing style. | Log surprises in `lessons.md`. |
| G4 Goal-Driven Execution | Define success criteria before implementing. | Log non-obvious decisions in `decisions.md`. |

<a id="zecher"></a>
## Zecher, the memory agent

Zecher (the name means "remembrance" in Hebrew) is a utility agent: you or another agent calls it when memory needs attention. It is not an orchestrator. Its rules: never delete memory (archive, consolidate, never destroy), always ask before promoting to the brain, dates in ISO 8601 (`YYYY-MM-DD`, never "last week"), concise entries readable in ten seconds, and cross-references between a lesson and the decision it concerns.

**What you can ask Zecher**

| You say | What happens |
| --- | --- |
| "Zecher, consolidate memory" | Audit: reads the memory files and sessions; proposes duplicates to merge, active decisions older than 90 days to review and lessons to promote; applies only what you approve; archives stale entries with an `[ARCHIVED]` prefix. |
| "Zecher, scan projects in ~/dev" | Walks the folder for project markers, detects the stack and a status, shows a table and lets you confirm, edit, skip or install BMAD+ per project; then writes the index. |
| "Zecher, where were we?" | Rebuilds the state of the project from `context.md`, the latest handoff, the brain’s project entry, the last 10 Git commits and the instructions file; presents a short brief. |
| "Zecher, health check" | Checks that the memory files exist and are well formed, flags old active decisions and lessons that keep recurring, and reports statistics. |
| "Zecher, what do we know about [topic]?" | Cross-references all memory files. |
| "Zecher, promote lesson [X] to global" | Proposes moving an insight to the brain; moves it only with your approval. |

<a id="commands"></a>
## The commands: memory, scan and mem

**Memory-related commands**

| Command | What it does |
| --- | --- |
| `memory status` | Health report of the project memory and of the linked brain, as a percentage of checks. |
| `memory export` | Writes `bmad-brain-export-<YYYY-MM-DD>.md` in the project folder: a portable Markdown archive of the brain. |
| `scan [path]` | Finds projects, detects stacks and indexes them in the global brain. `--depth` (default 4), `--active-days` (30), `--paused-days` (180), `--yes` to index without prompting. Status: active under 30 days, paused 30 to 180, archived beyond. |
| `mem recall <query>` | Ranked retrieval over the journal and the memory notes. `--limit` (default 8), `--scope project\|portfolio`, `--portfolio PATH`, `--json`. |
| `mem recall ... --ranking evidence --context-scope PATHS` | Opt-in ranking that rechecks sources and Nexus acceptance and gives current, relevant evidence a bounded boost. It requires an explicit non-empty scope. |
| `mem write` | Appends a structured event to the journal `.bmad/memory/journal.ndjson`: `--agent`, `--cli` (claude-code, gemini-cli, codex-cli, cursor, opencode, aider, antigravity), `--model`, `--task`, `--outcome success\|failure\|partial\|abandoned`, and optional signals `--eval 0-1`, `--accept true\|false\|0-1`, `--ci pass\|fail\|0-1`. |
| `mem reinforce --pattern ID` | Folds a reward into a pattern’s score (`.bmad/memory/pattern-scores.json`). A promotion is only ever PROPOSED, when the mean reaches 0.7 over at least 3 updates. These signals are self-reported and do not feed evidence ranking. |
| `mem observe --input FILE` | Associates one exact Markdown section of your memory with an already verified and accepted Nexus task (input: run, task, file and heading, scope paths, your interpretation, optional supersedes or contradicts). It records provenance; it does not prove that the lesson caused the success. |
| `mem outcomes` | Lists the recorded observations and whether each is still eligible (source or artifact changes, supersession and contradictions make an observation ineligible). |

**Writing to the journal, recalling, exporting**

```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
# Before the recall, a decision entry in the format shown above was appended by hand to decisions.md. Without an accepted Nexus task there is no observation, so evidence ranking has nothing to add to the plain ranking.
```

Output captured from a real run. Source: bmad-plus 0.23.0, 2026-10-19

<a id="never-overwritten"></a>
## What is never overwritten

- Install and update never overwrite `decisions.md`, `lessons.md` or `patterns.md`, never delete `sessions/`, and keep your edits to `context.md` and `identity.yaml`. Missing files are created from templates; existing ones are left alone.
- A detected brain is linked, not copied or rewritten. Global brain files are created only when missing; an interrupted older install could leave a "half brain", and the current code completes it idempotently without touching what exists.
- Uninstall removes the files BMAD+ owns and keeps `.agents/memory/`, `_bmad/config.yaml` and everything that is yours or modified (see the next block).
- Memory initialisation failure is not fatal: if the home folder is read-only (a container, CI), the install continues and warns.
- Shared writers use `.bmad/memory/writer.lock`. After an interruption, inspect the owner and the files before any manual recovery; do not remove a live writer’s lock, and corrupt outcome evidence is never reset automatically.

**After uninstall, memory is still there**

```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
# Folders that only held empty directories and the project’s own files (README.md, docs) are left out of this excerpt. The global brain in the home folder was not touched.
```

Output captured from a real run. Source: bmad-plus 0.23.0, 2026-10-19

<a id="example-memory-where-were-we"></a>
### Resume a project cold with Zecher

Use at the start of a session when you or the assistant have lost the thread, with the Memory pack installed.

**In your AI assistant**

```text
Zecher, where were we? Rebuild the state of this project from context.md, the latest session handoff, the brain entry and the last commits. Tell me what was decided, what is unfinished and which lessons apply to the next task. Say plainly which of these you could not find, and do not guess.
```

**What you should get** A short "state of the project" brief: what the project is, its stack, what was last worked on, open questions from the last session, known issues and lessons. Missing sources are named as missing. Nothing is written unless you ask for a handoff.

<a id="example-memory-consolidate-with-approval"></a>
### Tidy the memory without losing anything

Use when the memory files have grown and contain repeated or stale entries.

**In your AI assistant**

```text
Zecher, consolidate memory. First only audit: list the duplicates and the active decisions older than 90 days, and propose what to merge, archive or promote to the global brain. Apply nothing until I approve each change, archive instead of deleting, and write dates as YYYY-MM-DD.
```

**What you should get** A findings list (N duplicates, M stale entries, K promotion candidates) and a question per proposed change. After your approval, duplicates are merged keeping the richest version, stale entries are moved down with an `[ARCHIVED]` prefix, and approved insights are promoted to the brain. Nothing is deleted.

**See also**

- [The Memory pack](https://bmad-plus.rochetta.fr/docs/packs/memory-pack/)
- [Reference: bmad-plus memory](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/)
- [Reference: bmad-plus mem](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/)
- [Reference: bmad-plus scan](https://bmad-plus.rochetta.fr/docs/reference/cli-scan/)
- [Trust and ownership](https://bmad-plus.rochetta.fr/docs/security/trust-and-ownership/)
- [Nexus and durable runs](https://bmad-plus.rochetta.fr/docs/concepts/nexus-orchestration/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Concepts](https://bmad-plus.rochetta.fr/docs/concepts/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)