Memory Bank

---
name: memory-bank
description: >
  Maintains a lightweight, always-current "project encyclopedia" in
  `.memory-bank/` — capturing architecture, stack, conventions, key entities,
  and active tasks. After each meaningful change, the AI suggests concise
  updates or explicitly confirms no update is needed.
when_to_use: >
  After every chat interaction that may alter stable project knowledge:
  architecture decisions, API contracts, conventions, stack changes, new tasks.
  Skip for local implementation details, temporary experiments, minor refactors,
  and style-only changes.
applies_to: Claude Code, Cursor, Codex
language: en
---

# Memory Bank Steward — A Skill for Keeping Project Knowledge Current

This skill describes **how** to maintain a living project knowledge base, not
**what** to store in it. It activates after each chat message: evaluate whether
an important, lasting fact has changed, suggest a concise update if yes, and
explicitly say "no update needed" if not.

The Memory Bank is a lightweight, always-current "project encyclopedia." It
describes architecture, stack, conventions, key entities, and active tasks — the
things a new contributor (human or AI) needs to orient quickly.

---

## Memory Bank structure

```
.memory-bank/
├── index.md                          # Table of contents, quick orientation
├── product-overview/                 # What the product does, who it serves
├── steerings/                        # How to work in this project
│   ├── development-conventions.md    # Code style, branching, review norms
│   └── testing-conventions.md        # Test strategy, frameworks, coverage goals
├── tech-details/                     # Stack, architecture, module interactions
└── tasks/                            # Current and planned work (SDD-level)
```

`index.md` is the entry point. It links to every other file and gives a
one-paragraph orientation for a newcomer.

---

## Phase 1 — Evaluate

After each chat message, decide whether the conversation produced a fact that
belongs in the Memory Bank. Ask two questions:

1. **Is it stable project knowledge?** Architecture, public APIs, contracts,
   schemas, conventions, stack details, deployment, CI/CD, core entities,
   workflows, or current tasks qualify. Temporary fixes, local helpers, and
   one-off experiments do not.

2. **How important is it?**

| Level | Meaning  | Example                                    | Action        |
|-------|----------|--------------------------------------------|---------------|
| 3     | Major    | New module, API, or architectural change   | Suggest       |
| 2     | Moderate | New convention, interface, or contract     | Suggest       |
| 1     | Minor    | Internal helper refactor                   | Skip          |
| 0     | Noise    | Typo fix, formatting                       | Skip          |

Only suggest an update when importance is **≥ 2**.

### Anti-patterns

- Suggesting updates for every file touch.
- Recording implementation details that will change next sprint.
- Duplicating information already present in `.memory-bank/`.
- Including secrets, tokens, credentials, or private data — **never**.

---

## Phase 2 — Suggest (when update is needed)

Use this structured format so suggestions are machine-parseable and easy to
review:

```
MEMORY_SUGGESTION
version: 1
importance: <2|3>
summary: "<short summary>"
rationale: "<why this matters for the project>"
changes:
  - path: ".memory-bank/<folder>/<file>.md"
    op: "<create|update|append>"
    section: "<section heading or null>"
    content_format: "<md|yaml|mermaid|diff>"
    content: |-
      <concise, factual update>
validation:
  conflicts_checked: true
  secrets_present: false
END
```

### Field guide

| Field            | Notes                                                        |
|------------------|--------------------------------------------------------------|
| `importance`     | 2 or 3 only — lower values should not reach this phase       |
| `summary`        | ≤ 15 words                                                   |
| `rationale`      | Why a future reader (or AI) needs this fact                   |
| `path`           | Relative to project root, always starts with `.memory-bank/` |
| `op`             | `create` for new files, `update` to replace a section, `append` to add to end |
| `section`        | Markdown heading to target; `null` for whole-file ops        |
| `content_format` | `md` for prose, `yaml` for structured data, `mermaid` for diagrams, `diff` for patches |
| `content`        | The actual text — concise and factual                        |
| `conflicts_checked` | Confirm you read existing `.memory-bank/` to avoid dupes |
| `secrets_present`   | Must be `false` — abort if you catch yourself including secrets |

### Style rules

- Be concise and factual — no filler, no opinions.
- Prefer short Mermaid or C4 diagrams over long prose for architecture.
- Prefer minimal YAML contracts over verbose descriptions for APIs.
- One fact per suggestion; split compound changes into separate entries.
- Always read existing `.memory-bank/` content before suggesting, to avoid
  duplicates and contradictions.

---

## Phase 3 — Decline (when no update is needed)

When nothing in the conversation warrants a Memory Bank change, say so
explicitly:

```
NO_MEMORY_UPDATE
reason: "<why not — one sentence>"
```

This is the expected outcome for most messages. Silence is not acceptable — the
user should always know whether you considered the Memory Bank.

---

## Bootstrapping a new Memory Bank

If `.memory-bank/` does not exist yet and the conversation reveals facts at
importance ≥ 2, suggest creating the directory with at least `index.md`. A
minimal bootstrap looks like:

```
MEMORY_SUGGESTION
version: 1
importance: 3
summary: "Initialize Memory Bank"
rationale: "Project has no .memory-bank/ yet; creating the foundation."
changes:
  - path: ".memory-bank/index.md"
    op: "create"
    section: null
    content_format: "md"
    content: |-
      # Memory Bank — <Project Name>

      ## Overview
      <one paragraph: what this project is and who it serves>

      ## Structure
      - [Development Conventions](steerings/development-conventions.md)
      - [Testing Conventions](steerings/testing-conventions.md)
      - [Tech Details](tech-details/)
      - [Tasks](tasks/)
validation:
  conflicts_checked: true
  secrets_present: false
END
```

---

## Default rule

**When unsure — do not suggest an update.** A missing fact can be added later;
a wrong or noisy fact erodes trust in the Memory Bank.