Memory Bank layout¶
.memory-bank/ is the inviolable memory subsystem: the one layer Memory Bank
never touches without your consent and never lets an agent silently skip. Every
file below has a single responsibility and — for most of them — a hard
invariant that keeps the bank trustworthy across sessions, agents, and months
of history. This page documents those invariants; the full generation format
for each file lives in references/structure.md.
.memory-bank/
├── status.md current snapshot
├── checklist.md ⬜/✅ tasks for active plans
├── roadmap.md direction + active plans
├── progress.md append-only history
├── backlog.md ideas (I-NNN) + ADRs (ADR-NNN)
├── notes/ short reusable knowledge
├── plans/ detailed multi-stage plans
├── specs/ spec triples (requirements/design/tasks)
└── codebase/ living project map + graph.json
status.md — current snapshot¶
Purpose: in 30 seconds, understand where the project is right now.
Invariant: recommended ≤60 lines; it reflects facts, not plans — update
it on actual completion, not on planning. Active-plan and recently-done blocks
are marker-managed (<!-- mb-active-plans --> / <!-- mb-recent-done -->) and
upserted by mb-plan-sync.sh / mb-plan-done.sh, not hand-edited into
duplication.
checklist.md — operational to-do¶
Purpose: the step list for active plans only — not an archive.
Invariant: items flip ⬜ → ✅ immediately when a task is genuinely
done, never batched at session end. When a plan completes, mb-plan-done.sh
removes its whole section (the durable record already lives in
plans/done/<file>.md); any section left behind that is fully ✅ and links
to a plans/done/... file gets collapsed to a one-line summary by
/mb compact --apply (via mb-checklist-prune.sh) — no day-based aging, just
"is this section done and already archived." A soft cap of ≤100 lines (warned
above 120) keeps it a working list, not a history log.
roadmap.md — direction + active plans¶
Purpose: the single source of truth for what is in progress and where the
project is heading.
Invariant: holds direction and links only — historical "what was done"
belongs in progress.md, raw ideas belong in backlog.md. When the active
plan changes, roadmap.md, status.md, and checklist.md update together;
they must never drift out of sync with the plan file that is the actual
source of truth for tasks and DoD.
progress.md — append-only history¶
Purpose: the durable log of finished work, one dated entry per session.
Invariant: append-only. Never rewrite or delete an old entry — if a
past entry was wrong, add a new note correcting it, don't edit history.
/mb compact never touches progress.md; it only operates on plans/ and
notes/. This is what makes "what actually happened, in order" reconstructable
months later, even across agents.
backlog.md — ideas + ADR registry¶
Purpose: a live idea parking lot plus an architecture-decision journal.
Invariant: ID monotonicity. I-NNN (ideas) and ADR-NNN (architecture
decisions) are each monotonic across the whole file, zero-padded to 3 digits,
generated by mb-idea.sh / mb-adr.sh — IDs are never reused, even after
an idea is declined or superseded. Idea status follows a fixed lifecycle
(NEW → TRIAGED → PLANNED → DONE, or DEFERRED / DECLINED); priority is one
of HIGH | MED | LOW.
notes/ — knowledge notes¶
Purpose: short, reusable, standalone lessons for future sessions.
Invariant: 5–15 lines, patterns not chronology. A note captures a
conclusion or anti-pattern worth remembering ("token bucket beats sliding
window here because…"), not a session diary — that's what progress.md is
for. Files are named YYYY-MM-DD_HH-MM_<topic>.md; optional frontmatter
(importance: low) hints to /mb compact that a note with no incoming
references can be archived after 90 days.
plans/ — detailed multi-stage plans¶
Purpose: the source of truth for stage breakdown, SMART DoD, and TDD
requirements for a piece of work.
Invariant: files are named YYYY-MM-DD_<type>_<topic>.md (feature,
fix, refactor, experiment); every stage carries a Definition of Done and
explicit TDD requirements, not just a task name. <!-- mb-stage:N --> markers
let tooling (mb-plan-sync.sh, /mb work) parse stages precisely. Completed
plans move to plans/done/ — they don't stay in the active directory
accumulating alongside live work.
specs/ — spec triples¶
Purpose: the executable counterpart to a plan for larger, spec-driven
features: one directory per topic, three files with one concern each —
requirements.md (Kiro user stories + EARS acceptance criteria),
design.md (architecture, interfaces, decisions, risks), tasks.md
(numbered, checkbox-compatible work items).
Invariant: REQ-IDs in requirements.md are unique and traceable into
tasks.md via **Covers:** REQ-NNN; tasks.md blocks carry
<!-- mb-task:N --> markers so they are parsed and executed as first-class
work items, not read as a scaffold for humans only. See
SDD flow for the full discuss → sdd → work pipeline this feeds.
codebase/ — living project map¶
Purpose: a structured, regenerable snapshot of the codebase, read at
session start and consumed by planning/implementation agents.
Invariant: four prose docs (STACK.md, ARCHITECTURE.md,
CONVENTIONS.md, CONCERNS.md, each capped around 70 lines) plus a
structural graph.json (nodes/edges — modules, functions, classes) and
god-nodes.md (hotspots by connectivity). These are generated artifacts —
/mb map and /mb graph --apply regenerate them; they are not meant to be
hand-authored prose that silently drifts from the real code.
Why the invariants matter¶
Every rule above exists so that an agent — the same one, a different one, or
you three weeks later — can reconstruct what was done, what is being done,
what was decided, and what was learned the hard way purely by reading the
bank. Break append-only on progress.md, reuse an I-NNN, or let
checklist.md drift from the plan, and that reconstruction quietly stops
being trustworthy. See Overview for how this memory layer
stacks with rules, pipeline configuration, and agent prompts.