When your assistant "loses context," which of the four things did it actually lose? The conversation it was holding, the rules it was supposed to follow, the facts about the project, or the record of how you got here? Nobody usually checks, because all four travel under the same word. An AI coding context glossary is only worth writing if it does that separating work, so what follows is a map of how the four relate rather than another explanation of any one of them.
The cost of the confusion is small and constant. You paste a decision into CLAUDE.md where it slowly rots. You keep a 4,000-line transcript as if it were documentation. You write a sharp little rule into a notes file the assistant never reads. Each of those is a filing error, and filing errors are cheap to avoid once the categories are clear.
"Context" is doing too much work in that sentence
Four distinct things get called context in a normal week of AI-assisted work:
- the window, which is runtime state and disappears
- the instructions, which are rules you want re-read at the start of every session
- the memory, which is facts and decisions you want stated once and kept
- the trace, which is the raw conversation that produced a result
They differ on two axes that matter more than anything else: how long they live, and whether the assistant reads them automatically. Get those two right and the rest follows.
The window: what the model can hold right now
The context window is the amount of text the model can attend to in a single session: your messages, its replies, the files it opened, the tool output it got back. It is a working set, not storage. When it fills, something has to go, and what goes is usually the part you most wanted kept, the reasoning from forty minutes ago.
Two consequences people miss. First, nothing you say in a session survives it by default. Second, a long window is not the same as good context. A session stuffed with three irrelevant files and a failed build log is worse than a short one pointed at the right place. If the mechanics are fuzzy, the piece on what is a context window and why your assistant forgets covers them properly.
The window is the only one of the four that you cannot file anything into permanently. Everything else exists because the window ends.
Instructions: what you repeat, every time
CLAUDE.md (read by Claude Code) and AGENTS.md (read by Codex and several other agents) hold standing rules. Run this test command. Use pnpm, not npm. Do not touch generated/. Write migrations as separate files.
The defining property is repetition. Instructions are re-read at the start of every session, which means every line in them costs window space forever. That cost is the reason instruction files should be short and imperative, and the reason a dated decision does not belong in one:
## Commands
- Test: `pnpm test`
- Lint: `pnpm lint --fix`
## Rules
- No new dependencies without asking.
- Migrations go in `migrations/`, one file per change.
If you are running more than one assistant, the question of one file or two, and how to stop them drifting, is its own problem: see CLAUDE.md vs AGENTS.md.
Memory and decision records: what you tell it once
Project memory is the layer that answers "what did we decide, and why, and where are we?" It is facts, not rules. It changes often. It is referenced when relevant rather than loaded unconditionally.
### No background job runner yet (2026-09-18)
Decision: handle retries inline; revisit if we add a second worker.
Why: one process, one deploy target; a queue is more ops than the problem needs.
Status: Active
A decision record is the formal end of this spectrum: options considered, choice, reason, consequence. AI coding decision records earn their keep in a specific moment, when a fresh session cheerfully re-proposes the thing you rejected in August and you have no written reason to point at. The split between rules and facts is the single most useful distinction here, and CLAUDE.md vs project memory draws it line by line; the format itself is in lightweight decision records.
A transcript is a trace, not a rule or a fact
A saved session is evidence. It shows how a conclusion was reached, including the dead ends. That makes it valuable for a narrow set of purposes (tracing a regression, understanding a design that looks wrong, onboarding someone into a gnarly subsystem) and almost useless as a reference document. Nobody reads 300 turns to find out which database you picked.
The right relationship is one line of memory with a pointer to the transcript. The memory entry is what gets read; the session is what you open when the entry is not enough. Which ones to keep at all is a judgment call, handled in AI coding sessions worth keeping.
Where teams file things wrong
Four mistakes account for most of it.
Decisions in the instruction file. CLAUDE.md grows a "Decisions" section, every session pays for it in tokens, and the entries go stale because nobody prunes a file they only append to. Move them to memory and leave a rule behind if a rule is what you actually wanted.
Rules in the memory file. "Always run the type check before pushing" sitting in notes means the assistant may never see it. Rules go where they are read automatically.
Transcripts as documentation. If the answer is in a session nobody will open, the answer is not written down.
Nothing in the window. The opposite failure: perfect files, and a session where the assistant was never told to read them. Instruction files load automatically; memory and sessions usually do not. You have to point at them.
An AI coding context glossary that fits on one page
| Lives | Read when | Holds | Fails by | |
|---|---|---|---|---|
| Window | One session | Always, it is the session | Messages, files, tool output | Filling up with noise |
| Instructions | Until you edit them | Start of every session | Rules, commands, boundaries | Growing long and stale |
| Memory | Life of the project | When you or the assistant pull it in | Decisions, facts, open threads | Never pruned, or never read |
| Sessions | Frozen once saved | When you need the reasoning | Full conversation, dead ends included | Kept indiscriminately |
One operational note. These four live in different places by default: instructions at the project root, memory in whatever notes file you chose, sessions in your assistant's local history on one specific machine. Git carries the first two if you commit them and not the third. That split is why we built PrjLab to version instructions, memory and saved sessions together beside the code under .prjcontext/, so a prj push moves the whole picture and a prj clone brings it back on another machine. If the categories above are already clear in your head, the getting-started guide shows what a first push captures.
Hand a confused teammate the table. Then ask them which of the four was missing the last time the assistant guessed wrong. It is almost always a different layer than they assumed.
