gramps
b5e3dbe614
One file (AGENTS.md) that bootstraps the rest: rules, the file map to create, what belongs in each file, the first-session interview order, and the list of anti-patterns that killed the previous map (1,308-line guide, 63 task files, narrative history inline, sessions skimming 56k tokens of context). Separates four kinds of content by read frequency: rules/invariants -> AGENTS.md (every session) subsystem truth -> docs/ai/<topic>.md (only the matching one) lookups -> environment.md (grepped, never read) retired decisions -> decisions.md (only when re-opening one) Caps are enforced, not promised: scripts/verify.sh checks doc budgets before the build, so a commit that pads a capped file fails. Proven both ways — it passes clean and exits 1 on an over-cap file. scripts/scope-check.sh blocks edits outside the declared file list. templates/ holds fill-in skeletons for the seven files a project must create. CC0: copy it, rename it, sell it, no attribution needed.
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# 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.
|