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.

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: <phase>

## 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: Requirements → Design → Tasks → Implementation → Validation.
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.

/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	a progress.md you add yourself
Stale todos	delete them, or move them to progress.md

Do not duplicate. Link and summarise.

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

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

Obvious drift is handled immediately. Anything requiring architectural interpretation — redefined boundaries, a new layering — is summarised and confirmed with you first. That is also what /sdd-architecture-update is for.

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.