Memory Bank

Memory Bank

The Memory Bank lives in .memory-bank/ and is the version-controlled source of truth for project context. It is what separates SDD from a chat session: close the tool, come back next week, switch to the other assistant — the context is still there, in Markdown, in your repository, reviewable in a pull request.

Four files:

File	What belongs in it
projectbrief.md	mission, primary users, success criteria
systemPatterns.md	architecture decisions and patterns (long-lived)
techContext.md	stack, constraints, build/run/test info
activeContext.md	current focus, active spec, recent changes, decisions in flight, blockers, next steps, validation state

They are written in DocLanguage (see Configuration), kept concise, factual and actionable.

Somebody has to read them. AGENTS.md instructs the assistant to open .memory-bank/activeContext.md before continuing existing work — it names the active spec and its plan, which are read next. /sdd-specify, /sdd-plan and /sdd-compile all list it among the files they load. That sounds obvious until you notice how many memory systems are written faithfully and retrieved by nobody: a memory with no reader is just a diary.

activeContext.md — the one with a hard rule

It stays under two screen pages. It is a working and handoff context, not a changelog and not a second spec. It must answer in 30 seconds: what are we working on, which spec is authoritative, what was recently decided or changed, what is next, and what does the agent need to know right now?

Structure

Last updated: <date>
Current branch: <branch>
Current phase: specify | plan | act

## Now
One sentence: the current goal of this session or work track.

## Active Spec
Link to the relevant spec file(s), current task ID, acceptance criteria in focus.

## Changed Recently
Only actual changes since the last update: files/modules affected, tests/checks run.

## Decisions in Flight
Short-lived decisions not yet permanent enough for systemPatterns.md.

## Blockers / Questions
Open items blocking progress.

## Next
Numbered, concrete, immediately actionable steps.

## Validation
Current test/check status: done, pending, known issues.

When to update it

1. At the end of each relevant coding session.
2. After an important decision.
3. After a phase transition (specify → plan → act) or a lifecycle move (backlog → active → done).
4. Before a context reset or a new agent session.
5. After a bugfix with regression risk.
6. Always when switching from one active spec to another.

Refresh the Last updated line every single time. A date set once and never touched again is worse than no date at all: it makes a stale file look current, and /sdd-compile compares that line against your newest commit to tell you when the code moved and the Memory Bank did not.

/sdd-lifecycle updates it automatically whenever a spec becomes active or is completed.

What does not belong in it

If activeContext.md is growing past two pages, the surplus belongs somewhere more permanent:

Content	Correct place
Full requirements	the spec under .specs/
Full technical design	the spec, or systemPatterns.md
Full task list	the spec's .plan.md file
Long-term architecture decisions	systemPatterns.md
Tech stack, setup, dependencies	techContext.md
Project vision, goals, scope	projectbrief.md
Historical progress over weeks	nowhere — that is what git history is for
Stale todos	delete them, or move the live ones to the plan's Notes:

Do not duplicate. Link and summarise. And never route content into a file this template does not declare: the Memory Bank is these four files, and a spec's only companion is its .plan.md. An invented fifth file is one no command reads and no command syncs — an invisible second memory store, which is precisely what autoMemoryEnabled: false exists to prevent.

Automatic sync

The constitution requires the assistant to update these files in the same change set as the code whenever it notices — or causes — architecture-relevant drift.

Triggers: new, removed or moved source modules and projects · new top-level folders · new or changed entrypoints · build and deploy pipeline changes · boundary changes between modules or layers · new architectural decisions or constraints · new user-stated coding style guidelines (which go to Style & Output Preferences in AGENTS.md instead).

Writing a spec, a plan or a Memory Bank file is not a trigger — otherwise every /sdd-specify run would kick off a drift check on a Markdown file in backlog/.

Sync targets: the architecture: snapshot in AGENTS.md · systemPatterns.md · activeContext.md (a "Changed Recently" and a "Next" entry).

The snapshot is proposed, then written after you confirm — there is exactly one gate for that write, and /sdd-architecture-update is the command that performs it. An earlier version of these rules let obvious drift be written immediately while the command asked first, which meant the same change resolved differently depending on which file happened to be in context. One action, one autonomy level.

Why not Claude Code's auto memory?

.claude/settings.json sets "autoMemoryEnabled": false on purpose. Claude Code's auto memory is a machine-local, per-repository note store — effectively a second, invisible Memory Bank that your teammates never see and your other assistant cannot read. This template keeps exactly one visible source of truth.

To re-enable it, set it to true or remove the key. Copilot ignores the setting entirely. See Configuration.