Files

T

gramps b5e3dbe614 Seed an AI-legible project memory map that stays small

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.

2026-10-30 06:51:19 -07:00

2.6 KiB

Raw Permalink Blame History

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

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

The caps + the gate. Everything else degrades politely; a file without a failing check bloats silently.
HANDOFF.md is overwritten, never appended. History belongs to git log.
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 §1 and §6.

License

CC0 1.0 Universal — public domain. Copy it, rename it, sell it, no attribution needed.

2.6 KiB Raw Permalink Blame History