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.

Two levels: project memory and the 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.

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.

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.

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

The files, and when agents touch them#

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

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.

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.

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.

The commands: memory, scan and 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
# 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.

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.

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

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.

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.