Long-running coding work accumulates two kinds of context:
- facts needed to continue safely;
- history explaining how the team discovered those facts.
They are not equally valuable at retrieval time.
A new agent usually needs the exact checkpoint, the decisions that must not drift, the files or state it may own, the next exit gate, and a few known failure modes. Giving it the entire conversation or a large project summary forces the model to rediscover that small working set inside thousands of irrelevant tokens.
The recovery packet is a layered alternative.
Four retrieval tiers
The Agent Field Notes corpus now exposes four deliberate costs:
selector find the relevant note from triggers and status
capsule recover the operational decision in roughly 150–300 tokens
full note load rationale, alternatives, formulas, and examples
source inspect code, tests, commits, or primary upstream evidence
An agent begins at the cheapest tier. It moves downward only when the current tier cannot answer the question.
llms.txt is a selector, not a compressed encyclopedia. It provides retrieval triggers, failure signatures, status, dependencies, links, and approximate context cost. The individual Markdown page begins with the recovery capsule. llms-full.txt exists for deliberate corpus ingestion, not as the default prompt attachment.
What belongs in the capsule
A capsule is not an abstract. An abstract describes the document; a recovery capsule restores the decision state.
It contains:
- Retrieve when — the task situation that makes the note relevant.
- Decision — the selected architectural action.
- Invariant — the property future work may not violate.
- Failure signature — what the mistake looks like in practice.
- Minimal safe implementation — the smallest path known to preserve the invariant.
- Rejected shortcut — the tempting approach that already failed review.
- Evidence — the test or checkpoint supporting the decision.
- Claim boundary — what the evidence does not authorize.
Removing any one of these creates a predictable failure. Without the invariant, an optimization can preserve the prose while changing the model. Without the failure signature, the note is hard to retrieve from symptoms. Without the rejected shortcut, the next agent repeats the same plausible mistake. Without the claim boundary, a structural test becomes a support claim.
Store decisions, not progress narration
“Metal lane is 80% complete” is useful for coordination and nearly useless as durable memory. It becomes false as soon as the next commit lands.
“Only template-authored atoms may become trusted control IDs” remains useful across implementations. It can be tested, linked, superseded, and retrieved by a future agent facing a literal-token injection bug.
Durable notes should therefore be created for:
- architectural choices;
- invariants and ownership;
- rejected alternatives;
- failure and rollback semantics;
- measured thresholds;
- upstream behavior imported as local regression evidence.
Routine progress, conversation, temporary estimates, and unreviewed patches stay out of the corpus.
Make dependencies explicit
Notes form a graph, not a timeline.
prerequisites tells an agent which decisions must already hold. related_notes offers optional context. supersedes prevents an older record from silently remaining authoritative after a later decision replaces it.
This is more reliable than relying on publication order. A Phase 8 quantization decision may depend on a Phase 2 artifact invariant while being unrelated to several chronologically intervening notes.
Estimate context before loading it
The machine index includes approximate token counts for both capsule and full note. The estimate is intentionally simple—UTF-8 source bytes divided by four—and is labelled approximate.
Its purpose is not billing precision. It lets an orchestrator choose between a 200-token recovery and a 2,000-token rationale before spending the context.
When exact constants or code are needed, the note points to evidence rather than copying an entire source file into the narrative.
A bounded handoff workflow
At a safe checkpoint:
- record the immutable commit or evidence revision;
- list decisions that constrain the next task;
- state byte, file, cache, or state ownership;
- name the one active exit gate;
- record known failure signatures and stop conditions;
- link only the minimum source files or upstream diffs;
- mark explicitly what remains unsupported;
- let the receiving agent request deeper context only when blocked.
The receiving agent should be able to answer three questions from the capsule alone:
What may I change?
What must remain true?
What evidence proves I am done?
If it cannot, the handoff is incomplete. If answering requires the entire transcript, the project memory has not been compressed into operational knowledge.
The general rule
Context should be progressive and evidence-linked.
Do not optimize by deleting the reasoning that future maintainers may need. Move it to a deeper retrieval tier. Do not optimize by pasting everything into every agent. Put a decision-complete capsule in front of the rationale and give the agent a trustworthy way to descend.
The goal is not the fewest possible tokens. It is the fewest tokens that preserve authority, failure boundaries, and the ability to continue without repeating settled work.