# Recipe: in-repo agent memory (AG-17)

> **Audience:** any agent working in a federation repo.
> **Rule:** [AG-17](../standards/AGENTS.md#AG-17). See also
> [AG-05](../standards/AGENTS.md#AG-05) (verify before acting),
> [AG-08](../standards/AGENTS.md#AG-08) (durable, not ephemeral), DOC-07
> (`docs/claude/CLAUDE.md`), DOC-19 (`LESSON_LEARNED.md`).

Runtime auto-memory is machine-local and private — it does not survive a fresh
clone, a new machine, or a different agent. **`docs/memory/` is the committed
tier:** durable, federation-scoped facts that travel with the repo.

## Layout

```
docs/memory/
  MEMORY.md          # the index — one line per fact, pointing at a topic file
  <topic>.md         # one durable fact per file, with frontmatter
```

`MEMORY.md` is loaded first; keep it to one line per entry:

```markdown
# Memory index — <repo>

- [Title](topic-slug.md) — one-line hook
```

Each topic file holds one fact:

```markdown
---
name: <kebab-slug>
description: <one-line summary — used to judge relevance on recall>
metadata:
  type: user | feedback | project | reference
---

<the fact. For feedback/project, add **Why:** and **How to apply:** lines.
Link related memories with [[their-slug]].>
```

## Discipline (inherits AG-05 / AG-08)

- **Durable only.** Project state, conventions learned through correction,
  external-system pointers. NOT session logs, NOT "what I did today."
- **Verify before acting.** A path or version recalled from a topic file MUST
  be re-checked against the live tree before you act on it (AG-05).
- **Keep it current.** Update or delete a memory that turns out wrong; never
  silently propagate a stale one.
- **One fact per file**, linked from `MEMORY.md`. Keep the index small so it
  loads fully — move detail into the topic file, not the index line.

## Relationship to the other docs

| File | Role |
|---|---|
| `docs/memory/` (AG-17) | granular, evolving, indexed durable memory |
| `docs/claude/CLAUDE.md` (DOC-07) | curated dense-lookup briefing (what's built / gotchas) |
| `LESSON_LEARNED.md` (DOC-19) | append-only, dated log of non-obvious lessons |

They complement — not replace — each other.

## Setup

New repos inherit a seeded `docs/memory/MEMORY.md` from the cookiecutter.
Existing repos: `mgf-fed catch-up --apply` seeds it. A seeded index (just
the header) is conformant — presence is the bar; `mgf-fed app-doctor` checks it.
