# Memory pack: Zecher and the persistent brain
> Zecher keeps decisions, lessons and session handoffs in plain files across sessions and projects. Install, brain detection, eight prompts, outputs, CLI companions and limits.
Canonical: https://bmad-plus.rochetta.fr/docs/packs/memory-pack/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT
BMAD+ documentation › [Packs](https://bmad-plus.rochetta.fr/docs/packs/) › Memory pack: Zecher and the persistent brain
An AI assistant starts every session knowing nothing about yesterday. The Memory pack fixes that with plain Markdown files: what was decided and why, what went wrong, which patterns worked, where the project stands, and a handoff note at the end of each session. Zecher is the agent that maintains those files: it consolidates them, scans your machine for projects, rebuilds the context of a cold session and checks the memory’s health. There are two levels of memory, one per project and one shared across projects (a global brain).
## When to use it
- You work on the same project over many sessions and keep re-explaining the decisions already taken.
- You juggle several projects and want one index of them, with their stack, status and last activity.
- You already keep a notes folder (`_brain/` or `~/.claude/memory/`): the pack links to it instead of making a second one.
## What is installed
The pack is packaged in `.agents/skills/pack-memory/`: the orchestrator `memory-orchestrator.md`, the agent `zecher-agent.md`, two shared documents (`shared/memory-protocol.md` and `shared/karpathy-guardrails.md`) and templates for `decisions.md`, `lessons.md`, `patterns.md`, `context.md`, `session-handoff.md` and `identity.yaml`. At install time it also creates the memory of your project and links it to a brain; when no brain is found, a new global brain is created in `~/.bmad-plus/brain/`, outside the project. If that step fails, the install continues.
**The two levels of memory**
| Level | Location | Holds |
| --- | --- | --- |
| Project memory | `.agents/memory/` | `decisions.md`, `lessons.md`, `patterns.md`, `context.md`, `sessions/YYYY-MM-DD-.md` |
| Global brain | `~/.bmad-plus/brain/` | `identity.yaml`, cross-project decisions, lessons and patterns, `stack-preferences.md`, `projects/.yaml` and `projects-index.md` |
| Portfolio brain | `_brain/` in the project or any parent folder | Your own notes layout; it takes precedence over the global brain and keeps its own conventions |
The golden rule: information that applies to one project goes into project memory; information that applies to two or more projects is a candidate for the global brain, and only with your approval.
### How a brain is found
1. The environment variable `BMAD_PLUS_BRAIN`, if it points to a folder, overrides everything.
2. A `_brain/` folder in the project or in any parent folder (a portfolio brain).
3. The global brain `~/.bmad-plus/brain/`, only if it already exists (missing files are completed, nothing is overwritten).
4. Claude’s own memory folder `~/.claude/memory/`, only if it is not empty; it is linked, not copied.
5. Nothing found: a new global brain is created in `~/.bmad-plus/brain/` (with `identity.yaml`, the three shared notes files and `projects/`) and linked.
**.agents/memory/.brain-link records which brain was linked**
```json
{ "linked_brain": "D:\\workspace\\_brain", "brain_type": "portfolio", "linked_at": "2026-05-17T09:00:00Z" }
```
`brain_type` is `portfolio` (a workspace `_brain/` or the environment variable), `bmad-global` (`~/.bmad-plus/brain`) or `claude-memory` (`~/.claude/memory`). A portfolio brain keeps its own layout: agents read its entry point first and do not create `identity.yaml` or `projects/` inside it uninvited.
## Quick start
1. **Install the pack** Core is added automatically. Only Node.js 20 is needed: the memory is files, with no database and no vector service.
```sh
npx bmad-plus install --packs memory
```
2. **Let Zecher index your projects once** Zecher walks a folder, detects each project’s stack and status and asks you to confirm, edit or skip every entry before writing it.
```sh
Zecher, scan projects in ~/dev
```
3. **Start each later session with a recall** Ask for the state of the project before asking for work.
```sh
Zecher, where were we?
```
## Copyable examples
### Index your projects
Run it once after installing, then again when you add projects.
**In your AI assistant**
```text
Zecher, scan projects in ~/dev
```
**What you should get** Zecher finds project roots by marker files (`package.json`, `Cargo.toml`, `go.mod`, `.git` and others), skipping `node_modules`, `vendor`, `dist` and similar, then shows a table of project, stack, status (active under 30 days, paused 30 to 180, archived beyond), whether BMAD+ is installed and the last change. For each row you choose confirm, edit, skip or install BMAD+; only confirmed projects are written to `~/.bmad-plus/brain/projects/.yaml` and the human-readable `projects-index.md`.
### Rebuild the context of a cold session
Use it at the start of a session, in a project you have not touched for a while.
**In your AI assistant**
```text
Zecher, where were we?
```
**What you should get** Zecher reads `.agents/memory/context.md`, the latest handoff in `.agents/memory/sessions/`, the project’s entry in the global brain, the last ten git commits and `AGENTS.md` or `CLAUDE.md`, then gives a short "state of the project": what it is, its stack, what was last worked on, open questions from the previous session, known issues and lessons.
### Close a session with a handoff
Use it before you stop. "Handoff" is not one of Zecher’s fixed phrases, so describe what you want recorded and ask for the split between done and planned yourself.
**In your AI assistant**
```text
Zecher, update this project’s memory from the changes and checks we actually completed. Separate implemented, tested, published and still pending work. Record decisions and useful evidence, archive superseded notes without deleting them, and write a short prompt for the next session. Keep project memory local and exclude secrets.
```
**What you should get** Zecher updates `context.md`, writes a dated handoff file `.agents/memory/sessions/YYYY-MM-DD-.md` and a restart prompt. The handoff template (`session-handoff.md`) has the headings What changed, Decisions made, Open questions, Next steps and Files modified; the split into implemented, tested, published and pending, and the restart prompt that names the next unfinished task, come from your request, not from the template. Entries are never destroyed: superseded ones are archived.
### Check the memory’s health
Use it when the notes may have drifted from the code.
**In your AI assistant**
```text
Zecher, health check
```
**What you should get** A report: whether the memory files exist and are well-formed, decisions still marked active after more than 90 days (candidates for review), lessons that keep recurring (so the lesson was not learned), and statistics such as entries per file and last updated dates.
### Consolidate duplicates and stale entries
Nothing is changed until you approve each proposal.
**In your AI assistant**
```text
Zecher, consolidate memory
```
**What you should get** Three phases. Audit: Zecher reads every memory file and session note. Propose: it reports how many duplicates, stale entries and candidates for the global brain it found and asks you to approve each change. Execute: approved merges keep the richest version, stale entries are moved to the bottom with an `[ARCHIVED]` prefix, and approved entries move up to the global brain.
### Ask what the notes say about a topic
Use it before re-deciding something: it cross-references decisions, lessons, patterns and session notes.
**In your AI assistant**
```text
Zecher, what did we decide about the authentication strategy, and what went wrong the last time?
```
**What you should get** An answer drawn from the memory files by cross-referencing decisions, lessons, patterns and session notes. Zecher’s rules ask for ISO dates and for links between a lesson and the decision it refers to. Check the entries it cites: if the notes hold nothing on the topic, an assistant can still fill the gap, so ask it to name its source.
### Promote a lesson to the global brain
Use it when a lesson proved true in a second project. Zecher always asks before moving anything.
**In your AI assistant**
```text
Zecher, promote the lesson "never run migrations on startup" from this project to the global brain.
```
**What you should get** Zecher shows the entry and the target file and waits for your approval, then moves it to the global `lessons.md`. If your brain is a portfolio brain, the move follows its own governance and conventions rather than the global layout.
### Tie a note to a verified outcome
Advanced: only after a Nexus task was independently verified and accepted. It records provenance; it does not prove the note caused the success.
**In your AI assistant**
```text
Zecher, record that the lesson under "Cache invalidation" in .agents/memory/lessons.md applied to the accepted Nexus task cache-fix of run small-change. Write the observation file, run bmad-plus mem observe on it, then show bmad-plus mem outcomes.
```
**What you should get** The observation JSON names the run, the task, one memory section (file and heading), its scope paths and your interpretation. `mem observe` writes a receipt to `.bmad/memory/outcomes.ndjson` (not to the event journal); `mem outcomes` lists which receipts are still eligible, excluding stale, superseded or contradicted ones. A later `mem recall --ranking evidence` gives eligible evidence a bounded boost; the default lexical recall is unchanged.
## Command-line companions
**Commands that read or write memory**
| Command | What it does |
| --- | --- |
| `bmad-plus memory status` | Health of the project memory and of the global brain |
| `bmad-plus memory export` | Writes `bmad-brain-export-.md` in the project folder |
| `bmad-plus scan ` | The command-line project scanner; default depth 4, active under 30 days, paused under 180 |
| `bmad-plus mem recall`, `write`, `reinforce`, `observe`, `outcomes` | Query and update the project journal; evidence-based ranking is opt-in with `--ranking evidence` |
## What it writes and where
- In the project: `.agents/memory/` (the four Markdown files, `sessions/`, `.brain-link`) and, for the CLI journal, `.bmad/memory/journal.ndjson` and `.bmad/memory/pattern-scores.json`, plus `.bmad/memory/outcomes.ndjson` for outcome receipts.
- In your home folder, only if the global brain is used: `~/.bmad-plus/brain/` with `identity.yaml`, shared notes and the project index.
- Reinstalling or updating never overwrites `decisions.md`, `lessons.md` or `patterns.md` and never deletes `sessions/`.
## Data flows and prerequisites
Node.js 20 only. Memory is local files: the pack opens no network connection and has no off-machine flow of its own. A vector or RAG recall service is an optional, local, separately deployed addition that is not part of the npm package, and `--provision-python` does not install it; Markdown memory and the scanner work without it. What your assistant reads from memory goes to its model like any other context, so keep secrets out of the notes.
## Limits and gotchas
> **Warning · Nothing runs by itself** The pack supplies instructions and files for your assistant to follow. No hook is installed at session start or end, so a session that ends without an agent turn has no guaranteed handoff. Ask for the handoff before you stop.
> **Note · Scan depth** The command `bmad-plus scan` walks 4 levels by default (`--depth ` changes it). When you ask Zecher to scan in chat, state the depth you want so both give the same result.
> **Note · Memory is not proof** Notes are context to check against the current code, not facts. Outcome records tie a note to an accepted task; they do not show that the note improved the assistant’s results, and persistence alone does not either.
> **Note · Provenance** The memory architecture is inspired by the author’s own portfolio-notes method. The four behavioural guardrails (think before coding, simplicity first, surgical changes, goal-driven execution) are adapted from a community project of Karpathy-inspired guidance; see THIRD-PARTY-LICENSES.md.
**See also**
- [All ten packs side by side](https://bmad-plus.rochetta.fr/docs/packs/packs-overview/)
- [Memory, how it works](https://bmad-plus.rochetta.fr/docs/concepts/how-memory-works/)
- [memory command reference](https://bmad-plus.rochetta.fr/docs/reference/cli-memory/)
- [mem command reference](https://bmad-plus.rochetta.fr/docs/reference/cli-mem/)
- [scan command reference](https://bmad-plus.rochetta.fr/docs/reference/cli-scan/)
[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Packs](https://bmad-plus.rochetta.fr/docs/packs/)
[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)