Zecher keeps decisions, lessons and session handoffs in plain files across sessions and projects. Install, brain detection, eight prompts, outputs, CLI companions and limits.
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).
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.
identity.yaml, cross-project decisions, lessons and patterns, stack-preferences.md, projects/<hash>.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.
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.
Run it once after installing, then again when you add projects.
In your AI assistant
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/<hash>.yaml and the human-readable projects-index.md.
Use it at the start of a session, in a project you have not touched for a while.
In your AI assistant
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.
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
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-<topic>.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.
Use it when the notes may have drifted from the code.
In your AI assistant
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.
Nothing is changed until you approve each proposal.
In your AI assistant
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.
Use it before re-deciding something: it cross-references decisions, lessons, patterns and session notes.
In your AI assistant
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.
Use it when a lesson proved true in a second project. Zecher always asks before moving anything.
In your AI assistant
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.
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
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.
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/.
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.
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 <n> 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.