Design overview and the Memory Bank

title: “Design and the Memory Bank” type: “explanation” layout: “default” —

This explanation describes the repository design and the Memory Bank concept used for agent workflows.

Purpose

Explain why instruction files exist, how automated agents use them, and how contributors should think about the Memory Bank.

Key ideas

Instruction files in _instructions/ and prompt files in _prompts/ act as configuration and behavioral guidance for agents. They contain applyTo patterns and usage notes so automation can pick the right instructions.
The Memory Bank (see .github/instructions/memory-bank.instructions.md) is a set of markdown files that maintain important project state across sessions: projectbrief.md, productContext.md, activeContext.md, etc.

How agents use these files

Agents read instruction files with applyTo metadata to determine which rules apply to which parts of the repository.
When making changes, agents are expected to update the Memory Bank files to record decisions and progress.

Design patterns and contributor expectations

Keep instruction files explicit: state audience, intent, and any constraints.
Follow the principle of least surprise: changes to instruction files must include a log entry in the Memory Bank where relevant.

Security notes

Treat all inputs as untrusted. Do not hardcode API keys or secrets in prompt or instruction files. Use environment variables and document them in docs/reference/repo-structure.md or the specific instruction file.