Chat is RAM. The repo is disk.
Conversation context is working memory for one run: prompts, searches, raw tool output, tentative diagnoses, corrections, and false starts. It is useful because it is quick and disposable. Assume it will disappear, be compacted, or become hard for someone else to find.
Durable repo-local knowledge is the smaller set of accepted facts stored in versioned files: the command every agent should run, the product decision a future change must preserve, the current task’s next action, or the test that catches a repeated mistake. A fresh agent, teammate, or CI job can inspect it without recovering the original conversation.
The goal is not to save chat. It is to select what should still change behavior after the chat is gone. If you prefer the visual treatment, use the image-slide version.
Why does this matter now? Caleb Gross describes generative AI as making “substantial form without discernible intent” unusually easy; applying that observation to code is author synthesis (You can just say it). Maggie Appleton argues that cheap implementation pushes team alignment onto the critical path (One Developer, Two Dozen Agents, Zero Alignment). Addy Osmani calls the gap between existing code and human understanding comprehension debt. Repo-local knowledge does not solve those problems by itself, but it keeps intent and understanding from living only in a private thread.
Preserve the parts that change the next run; let the rest expire.
chat exploration
├─ leave in chat
│ ├─ false starts
│ ╰─ temporary hypotheses
╰─ save in the repo
├─ useful decisions
├─ proof commands
╰─ next actionDurable context is useful because it filters, not because it hoards. Keep accepted constraints, proof commands, decisions, task state, examples the agent should copy, and mistakes that should become checks. Leave behind transient prompts, abandoned hypotheses, duplicate logs, and explanations that only made sense in the moment.
Simon Willison calls an LLM a lossy encyclopedia: broad knowledge is compressed, and exact details disappear. For exact technical work, a correct repo-local example beats expecting the model to infer the rule. That example might be this repository’s test command, migration rule, security boundary, preferred component, or recent product decision.
That distinction also explains why a short prompt can work. In one Amp example, Thorsten Ball asked for a UI change and a Storybook screenshot. The agent found layered AGENTS.md files containing the dev-server, browser-automation, Storybook, port, and check instructions, then completed the work and returned screenshots (00:20:22–00:22:55). The prompt carried the task; the repository carried the recurring procedure.
Do not confuse durable with authoritative. A committed note can be stale. For substantial work, name the current source of truth and say what wins when a work item, design note, code, and test disagree. Do not store secrets, credentials, personal data, machine-specific absolute paths, temporary portal URLs, or short-lived resource IDs as repository memory.
Choose a file based on who needs the fact, when they need it, and whether a check can enforce it.
Use this placement guide:
| Need | Store it here |
|---|---|
Shared command or safety rule (npm run check) |
Root AGENTS.md. |
| Directory rule (source-only content must not enter public builds) | Nested AGENTS.md beside that tree. |
| Repeated workflow (content review with required checks) | .agents/skills/<name>/; add scripts only when useful. |
| Resumable task (status, blocker, next action) | Work item index.md under .agents/work/; add a plan or progress log when needed. |
| Domain fact with an existing owner (classification codes) | Update the source enum and its consumer or focused test; do not copy the list into AGENTS.md. |
| Mechanical invariant (excerpt ranges are half-open) | Schema, guard, test, or other executable check. |
AGENTS.md is a predictable starting point for setup, commands, conventions, and safety rules. It should point to deeper truth instead of containing everything the project knows. Put a directory-specific rule near that directory so unrelated work does not pay to read it.
Agent Skills are for procedures with a recognizable trigger and repeatable steps. A skill can bundle instructions, scripts, references, and assets. Compatible agents first see its name and description, then load the full instructions when the task calls for them; OpenAI’s Codex Skills documentation describes the same progressive-disclosure pattern. A formatting preference is not a skill. A source-review workflow with required checks can be.
Use a work item only when continuity has value. dot-agents uses index.md as the entry point for current status and the exact next action; research, plans, progress, and handoffs are optional. A typo fixed and verified in one conversation needs no task folder.
Explore in chat, write down accepted state, and finish with the smallest reusable improvement.
Use this loop:
AGENTS.md, a full procedure to a skill, a mechanical requirement to a script or test, or a design choice to a short decision note. Then remove the completed task notes; Git history keeps the record without loading it into future runs.This article owns that storage decision. Brief the Agent Like a Capable Co-Worker covers the initial assignment. Right-Sized Threads, Durable State covers continuation, fresh workers, and handoffs. Make the Agent Prove It covers risk-scaled verification. Link to those contracts instead of copying them into every work item.
Durable guidance must stay scoped, current, reviewable, and cheaper than rediscovery.
Five habits keep the repository from becoming a larger context problem:
npm test passed at commit abc123” can be checked. “Everything looks good” cannot.Durable does not mean permanent. Boris Cherny describes deleting system guidance for each new model, observing behavior, and restoring instructions only after repeated failures; he recommends periodically retesting project guidance, skills, and hooks (00:03:21–00:08:54).
The same rule applies to procedures. Nick Nisi and Zack Proser describe comparing tasks with and without a skill, and Nisi reports that an over-prescriptive Next.js skill made their approximate evaluation worse (00:29:24–00:30:27, 01:09:30–01:10:28). Their figures are informal; the durable lesson is to test whether guidance still helps instead of preserving it by default.
Promote the smallest artifact that makes the next run better.
Start with the smallest response to a problem you have seen more than once:
| Repeated pain | Smallest useful change |
|---|---|
| Agent misses the same command. | Add it to the relevant AGENTS.md. |
| Team repeats a workflow by hand. | Add a skill, script, or checklist. |
| Work cannot resume after interruption. | Add a work item with status and next action. |
| The same bug returns. | Add a test, fixture, lint rule, or CI check. |
| A design choice keeps being reopened. | Add a short decision note or known-good example. |
| Guidance keeps being ignored or misapplied. | Narrow it, move it closer to its use, or delete it. |
Do not design a perfect memory system. Fix one repeated loss of context, then check whether the next run actually improves. Someone must own the loop: notice what helped, store it in the right place, and remove it when it stops helping.
Start with one real task. Write down what made the agent better. Repeat.
AGENTS.md instructions and screenshot proof.AGENTS.md, Agent Skills, and Codex Skills — source material for map and procedure conventions.dot-agents — source material for file-backed task state.