# Memory

This directory holds long-running session memory for human maintainers of this repository.

## Purpose

Memory files capture the state that must persist across AI-assisted development sessions:
- What phase the project is in
- What tasks are active, backlogged, or completed
- Which architectural decisions have been made
- Which risks are open
- Which interfaces and contracts are in play
- Domain terminology
- A ready-made prompt to resume an AI session

## What goes here

| File | Purpose | Template |
|------|---------|---------|
| `STATE.md` | Current system state snapshot | `templates/STATE.md` |
| `TASKS.md` | Task queue and backlog | `templates/TASKS.md` |
| `DECISIONS.md` | Architectural decision log | `templates/DECISIONS.md` |
| `RISKS.md` | Risk register | `templates/RISKS.md` |
| `INTERFACES.md` | Interface and contract ledger | `templates/INTERFACES.md` |
| `GLOSSARY.md` | Domain terminology | `templates/GLOSSARY.md` |
| `RESUME_PROMPT.md` | AI session resume scaffold | `templates/RESUME_PROMPT.md` |

## What does NOT go here

- `context/` — Agent-bootstrap runtime context packs (a separate, orthogonal surface).
- `artifacts/context/` — Machine-generated context maps (CI output, read-only).
- Secrets, API keys, tokens, passwords, or PII.

## Governance

Memory files are validated by `script/memory-drift-check`. CI runs it on every PR in warn-only mode.

See `docs/governance/MEMORY_GOVERNANCE_SPEC_v1.md` for the full protocol.

## Setup (Adopted Repositories)

```bash
# Copy templates and populate them
cp templates/STATE.md      STATE.md
cp templates/TASKS.md      TASKS.md
cp templates/DECISIONS.md  DECISIONS.md
cp templates/RISKS.md      RISKS.md
cp templates/INTERFACES.md INTERFACES.md
cp templates/GLOSSARY.md   GLOSSARY.md

# Replace <!-- REQUIRED: ... --> markers with actual content
# Then verify:
script/memory-drift-check

# Export a portable context bundle:
script/context-export
```
