# agent-memory-seed

Seed for an AI-legible project memory map: **fork it, don't sync it.**

Copy the files into a new repo, let the AI run the first-session interview, then delete the seed
scaffolding. Every project owns its own copy from then on; improvements that prove out somewhere
get brought back here deliberately, one at a time. Never try to keep the two in lockstep.

## Why it exists

Most "AI context" files die the same death: they grow. A rules file becomes a history file, a task
list becomes a second source of truth, and every session pays to skim it — which is how stale facts
survive. This seed is small because it separates four kinds of content that have four different
read frequencies:

| Kind | Home | Read |
|---|---|---|
| Rules + invariants | `AGENTS.md` | every session |
| Subsystem truth | `docs/ai/<topic>.md` | only the one matching the task |
| Lookups (hosts, paths, commands) | `docs/ai/environment.md` | grepped, never read |
| Retired decisions | `docs/ai/decisions.md` | only when re-opening one |

Caps are enforced by `scripts/verify.sh`, not promised: a commit that pads a capped file fails.

## What's here

```
AGENTS.md              the seed: rules, file map, per-file contents, first-session order
scripts/verify.sh      the one gate — doc budgets, clean build, tests, scope check
scripts/scope-check.sh fails if a commit touches files outside the declared list
templates/             fill-in skeletons the AI copies into the target project
```

## Use

```bash
git clone https://<host>/<owner>/agent-memory-seed.git <new-project>
cd <new-project>
rm -rf .git && git init -b main
```

Then, as the first prompt to the AI:

> Read AGENTS.md and follow it. Ask me the first-session questions one at a time, then build the
> memory map, then delete the seed scaffolding — `templates/` and the seed sections of README.

`templates/` is input, not output: copy each skeleton to its real path (`templates/handoff.md` →
`HANDOFF.md`) and fill it in. When the map is built, remove `templates/` and rewrite this README
for the actual project.

## The parts that matter most

1. **The caps + the gate.** Everything else degrades politely; a file without a failing check
   bloats silently.
2. **`HANDOFF.md` is overwritten, never appended.** History belongs to `git log`.
3. **A budget cut means moving detail out, never deleting a fact** — out to a subsystem doc, a
   lookup sheet, the decisions log, or git.

Anti-patterns and the full ruleset live in [`AGENTS.md`](AGENTS.md) §1 and §6.

## License

[CC0 1.0 Universal](LICENSE) — public domain. Copy it, rename it, sell it, no attribution needed.