Repo context & memory
An agent is only as good as the context it loads. This standard defines what lives where in every RAPID repo, so agents start each session with sharp, current context — and so the knowledge a loop earns is deposited, not lost. Knowledge silos are on the problem list RAPID exists to fix; don't rebuild them out of wikis and chat history.
The layout
Every RAPID repo carries three kinds of agent-facing context, each with a different lifecycle:
| Location | Holds | Lifecycle |
|---|---|---|
CLAUDE.md (repo root) | Stable facts: what this repo is, key commands, architecture pointers, conventions, links to the standards that apply. | Changes rarely; reviewed like code. |
memory/ (gotchas) | Hard-won fixes and non-obvious traps — one fact per file: symptom → root cause → fix → verification → date/author. | Grows continuously; pruned when stale. |
Runbooks (docs/runbooks/) | How to operate and diagnose the service: dashboards, known failure modes (linked to gotchas), escalation, agent-executable vs human-only steps. | Updated when the service changes. |
Decision history lives in ADRs (see Decision records); the PFD, design pack and gate cards live where the process puts them. This standard governs the context layer that sits alongside them.
Rules
- One fact per memory file, with a one-line description so its relevance is obvious at recall time. A gotcha that costs more than ~30 minutes to solve gets captured before the ticket closes.
CLAUDE.mdis for stable facts only. Anything volatile (a current bug, a temporary workaround) belongs in a gotcha or a runbook, not here — otherwise the context bloats and token spend rises for no benefit.- Agents read gotchas and the relevant runbook at session start, and write new ones as part of Flow-state — the same PR that removes the friction records the lesson.
- Prune on a cadence. Stale context is worse than none: it misleads. Flow-state includes a memory-pruning step; anything an agent flags as no-longer-true is removed, not left to rot.
- Write for both readers. Context is prose a human can skim and an agent can load. If an agent can't be pointed at it, it doesn't exist.
Why this is capital
This is the mechanism behind "velocity compounds." Every loop deposits a little more accurate context — a gotcha never re-hit, a runbook step that makes the next incident faster, a CLAUDE.md line that stops an agent guessing. The next turn starts from a better position than the last. The capital-deposit rate is a first-class RAPID metric precisely because this is where compounding comes from.
This standard is the general form; the per-repo starting point (a seeded CLAUDE.md, memory/ and runbook stubs) ships with the RAPID project scaffold — a later toolkit pass.