# bmad-plus memory

> Read the health of the project memory and of the global brain, and export the global brain to one Markdown file. Flags, what it reads and writes, output, exit codes and errors.

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

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › bmad-plus memory

BMAD+ keeps two kinds of memory in plain Markdown files. The project memory lives in `.agents/memory/` inside your project (decisions, lessons, patterns, the current context and one handoff note per session). The global brain lives in `~/.bmad-plus/brain` and is shared by all your projects. `bmad-plus memory` answers “is my memory in good shape?” with a read-only report, and can copy the global brain into one portable file. It is for anyone who installed the Memory pack (agent Zecher) and wants to check it or take a backup of what the brain knows.

<a id="synopsis"></a>
## Synopsis

**In your project terminal**

```sh
npx bmad-plus memory [status] [-d <path>] [-l <code>]
npx bmad-plus memory export [-d <path>] [-l <code>]
```

**Arguments and flags of memory**

| Flag | Argument | Default | What it does |
| --- | --- | --- | --- |
| `[subcommand]` | `status` or `export` | `status` | `status` prints the health report; `export` writes the global brain to a file in the project folder. Anything else prints an error. |
| `-d, --directory <path>` | path | current directory | Project folder: where `.agents/memory/` is read and where the export file is written. |
| `-l, --lang <code>` | en, fr, es, de, pt-br, ru, zh, he, ja, it | none | Accepted for consistency with the other commands. The report itself is always printed in English. |

<a id="reads-writes"></a>
## What it reads and writes

**File access of memory**

| Subcommand | Reads | Writes |
| --- | --- | --- |
| `status` | `.agents/memory/decisions.md`, `lessons.md`, `patterns.md`, `context.md`, `sessions/*.md`, `.brain-link`; in the global brain `identity.yaml`, `decisions.md`, `lessons.md`, `patterns.md`, `projects/*.yaml`, `projects-index.md`. | Nothing. |
| `export` | The global brain: `identity.yaml`, `decisions.md`, `lessons.md`, `patterns.md` and every `projects/*.yaml`. | `bmad-brain-export-<YYYY-MM-DD>.md` in the project folder (replaced if it already exists that day). |

Two details matter. First, the report always inspects the global brain at `~/.bmad-plus/brain`, even when your project is linked to another brain (a `_brain/` folder in a parent directory, the `BMAD_PLUS_BRAIN` variable); the link is shown on the “Linked brain” line. Second, `export` does not touch the project memory, only the global brain. An “entry” in the counts is a line that starts with `### ` in the Markdown file.

<a id="exit-codes"></a>
## Exit codes

**Exit codes of memory**

| Code | Meaning |
| --- | --- |
| 0 | The command ran to its end. This includes an unknown subcommand and an export with no global brain: both print an error line but do not set a failing code, so do not use `memory` as a CI gate. |

<a id="real-output"></a>
## Reading the output

The health score is the share of passed checks out of at most ten. For the project memory the five checks are: `decisions.md`, `lessons.md`, `patterns.md` and `context.md` exist, and `sessions/` holds at least one `.md` handoff. For the global brain they are: `identity.yaml`, `decisions.md`, `lessons.md`, `patterns.md` and the `projects/` folder exist. A part that is not installed is left out of the score instead of counting as zero. Green from 80%, yellow from 50%.

**memory status (values illustrative)** (Simulated)

```text
$ npx bmad-plus memory status
Project Memory (/home/ana/shop)
  decisions.md     ✓  3 entries  2026-10-12
  lessons.md       ✓  1 entries  2026-10-02
  patterns.md      ✓  0 entries  2026-09-30
  context.md       ✓  2026-10-17
  sessions/        ✓  2 handoff(s)
  Linked brain: /home/ana/.bmad-plus/brain
Global Brain (/home/ana/.bmad-plus/brain)
  identity.yaml    ✓
  decisions.md     ✓  0 entries
  lessons.md       ✓  0 entries
  patterns.md      ✓  0 entries
  projects/        ✓  1 project(s) indexed
  projects-index   ·
Health: 100% (10/10 checks)
Done!
```

Illustrative transcript, not captured from a real run. Source: tools/cli/commands/memory.js (status branch, message templates); the numbers and paths are made up

**memory export (path illustrative)** (Simulated)

```text
$ npx bmad-plus memory export
Brain exported to: /home/ana/shop/bmad-brain-export-2026-10-18.md
Done!
```

Illustrative transcript, not captured from a real run. Source: tools/cli/commands/memory.js (export branch, message template); the path is made up

> **Note · Check before you share the export** The export copies your global decisions, lessons and project cards verbatim, plus `identity.yaml` (your name and language). Read it before you send it to someone or commit it.

<a id="errors"></a>
## Errors and what to do

**Messages printed by memory**

| Message | Cause | What to do |
| --- | --- | --- |
| `Not installed. Run: npx bmad-plus install (select Memory pack)` | There is no `.agents/memory/` folder in the project. | Install the Memory pack: `npx bmad-plus install --packs memory`. |
| `Not initialized. Run: npx bmad-plus install (select Memory pack)` | There is no `~/.bmad-plus/brain` folder on this machine. | Install the Memory pack in any project; it creates the global brain unless it finds another brain to link. |
| `Global brain not found. Nothing to export.` | Export looks only at `~/.bmad-plus/brain`. | Run the install above, or use `scan` to start filling the brain. |
| `Unknown subcommand: <name>` | Anything other than `status` or `export`. | Use `status` or `export`. For recall and journal actions use `mem`. |
| `identity.yaml    ✗ missing` | A global brain without its identity file (a “half brain”). | Re-run the Memory pack install; it completes the missing files and never overwrites existing ones. |

<a id="examples"></a>
## Examples

<a id="example-cli-memory-status"></a>
### Check the health of your memory

The Memory pack is installed and you want to know what is missing before you rely on it.

**In your AI assistant**

```text
Run `bmad-plus memory status` in this project and tell me which memory files are missing or empty.
```

**What you should get** The command prints one block for the project memory and one for the global brain. Each file shows a tick or a cross, its number of `### ` entries and its last modification date, `sessions/` shows the number of handoffs, and the last line gives the health percentage with the number of checks passed. Nothing is changed on disk.

<a id="example-cli-memory-export"></a>
### Take a backup of the global brain

You are about to reinstall your machine and want a readable copy of what the brain holds.

**In your AI assistant**

```text
Export my global brain with `bmad-plus memory export` and tell me where the file is.
```

**What you should get** A file named `bmad-brain-export-<date>.md` is written in the project folder. It starts with `# BMAD+ Brain Export` and the export time, then one section per global file (`identity.yaml`, `decisions.md`, `lessons.md`, `patterns.md`) in a code fence, then a `Projects` section with one fenced YAML card per indexed project. The command prints the full path.

**See also**

- [mem: recall and journal actions](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/)
- [scan: index your projects in the brain](https://bmad-plus.rochetta.fr/docs/reference/cli-scan/)
- [install: add the Memory pack](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [Project layout](https://bmad-plus.rochetta.fr/docs/reference/project-layout/)
- [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/)

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

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