bmad+
Menu
ENChoose language
Get started
Browse the documentation

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.

On this page
  1. Synopsis
  2. What it reads and writes
  3. Exit codes
  4. Reading the output
  5. Errors and what to do
  6. Examples

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.

Synopsis

In your project terminal
npx bmad-plus memory [status] [-d <path>] [-l <code>]
npx bmad-plus memory export [-d <path>] [-l <code>]

Arguments and flags of memory
FlagArgumentDefaultWhat it does
[subcommand]status or exportstatusstatus prints the health report; export writes the global brain to a file in the project folder. Anything else prints an error.
-d, --directory <path>pathcurrent directoryProject 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, itnoneAccepted for consistency with the other commands. The report itself is always printed in English.

What it reads and writes

File access of memory
SubcommandReadsWrites
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.
exportThe 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.

Exit codes

Exit codes of memory
CodeMeaning
0The 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.

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

Errors and what to do

Messages printed by memory
MessageCauseWhat 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 ✗ missingA 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.

Examples

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

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
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