context-memory-hygiene

# Context & Memory Hygiene > Status: v0.1 baseline draft — derived from the case catalog and axis definitions; awaiting trace evidence from Fable 5.1 case runs. ## When to apply - You are about to read files, dump logs, or pull in references and must decide how much to actually load. - The context window is filling and older content is at risk of being crowded out or compacted. - A session will resume later, or hand off to another agent, and state must survive the boundary. - You are unsure whether to trust a remembered value or re-derive it from the current source. - You caught yourself loading a whole file/log/repo to use one function or one line from it. - Work spans multiple sessions and you need a durable record that is not the transcript itself. ## Core loop 1. **State what the current step actually needs.** Before loading anything, name the specific fact, symbol, or slice the next action requires. "I need the signature of `parseConfig`", not "I need the config module". The need defines the read, not the file size. 2. **Read the minimum that satisfies the need.** Load the smallest slice that answers it — a function range over a whole file, a grep hit over a full log, the relevant section over an entire doc. Broad reads spend context you will want later for reasoning. 3. **Distinguish durable facts from transient noise.** As you work, separate the few facts worth keeping (the decision made, the interface agreed, the root cause found) from the bulk you can discard (intermediate output, explored-and-rejected paths, raw dumps). Only durable facts earn a place in persisted memory. 4. **Persist durable state outside the transcript.** Write what must survive a resume or handoff into a real artifact — a handoff note, a state file, a scratch record — not just the conversation. Context can be compacted or lost; an artifact is recallable. Capture: goal, current state, what's done/verified, what's open, the next action. 5. **Drop what no longer pays rent.** Actively let go of content whose job is done: closed sub-investigations, superseded plans, verbose output you already extracted the answer from. Keeping it "just in case" pollutes the context that steers you. 6. **On resume, re-ground before you trust recall.** After a resume or compaction, re-read the handoff artifact and re-probe anything that may have changed, rather than acting on a possibly-stale memory of where things stood. Recall is a hypothesis until re-grounded. 7. **Choose re-derive vs recall by cost and staleness.** Recall a fact if it is cheap-to-store and stable; re-derive it if it is stale-prone or cheaper to recompute than to have carried. A branch name, a file's current contents, a test result after edits — re-derive. A design decision or an interface contract — recall from the persisted note. 8. **Keep the working set lean.** Periodically ask what is currently loaded that no longer serves the task, and shed it. A tight working set of exactly-relevant context outperforms a large one padded with residue. ## Heuristics - Load the slice, not the file: a function range or grep hit beats reading the whole thing for one fact. - If you extracted the answer from a dump, drop the dump; keep the answer. - Anything that must outlive this session goes in an artifact, never only in the transcript. - A handoff note has five fields: goal, state, done/verified, open, next action — write all five. - Re-derive stale-prone facts (branch, file contents, test status after edits); recall stable ones (decisions, contracts). - After compaction or resume, treat every prior fact as unverified until re-grounded from an artifact or probe. - "Might need it later" is how context fills with noise; load on demand, not on speculation. - Prefer one lean reference over three overlapping ones; redundant context dilutes the signal that steers you. - Cost test for recall: if re-deriving is cheaper than the risk of acting on a stale memory, re-derive. - The transcript is not memory: important state survives only if you deliberately wrote it somewhere durable. - Summarize before you compact, not after: distill the durable facts into an artifact while the detail is still in context, because after compaction the detail you needed to summarize is already gone. - Load references at the moment of use, not at the start "to have them"; early bulk reads age into noise. ## Anti-patterns - **Load-everything.** Reading an entire file, log, or module to use one symbol from it, crowding out the context you need for reasoning. → Corrective: name the need, load the slice that answers it, stop there. - **Transcript-as-memory.** Assuming important state is safe because it's "in the conversation", then losing it to compaction. → Corrective: persist durable facts into an artifact the moment they're established. - **Stale recall after resume.** Acting on a remembered branch, value, or file state that changed while you were away. → Corrective: re-read the handoff and re-probe changeable facts before the first action. - **Hoarding.** Keeping closed investigations, rejected paths, and raw output "just in case", polluting the working set. → Corrective: drop content once its answer is extracted; a lean context steers better. - **Redundant re-derivation.** Re-computing an expensive, stable fact every time instead of recording it once. → Corrective: persist stable decisions and contracts; re-derive only what actually goes stale. - **Handoff amnesia.** Ending a session or delegating without writing down goal/state/open/next. → Corrective: write the five-field handoff before the boundary, not after someone asks where things stood. ## Relation to existing axes - **vs exploration-strategy:** exploration is about *acquiring* an accurate model of an unfamiliar codebase — what to read to understand it. Context-memory-hygiene is about *managing* what stays loaded, persisted, or dropped once acquired — the economics of the window and cross-session memory. Exploration decides what to learn; this decides what to keep, write down, and let go. - **vs incremental-safety:** incremental-safety keeps the *system* green across a sequence of edits. Context-memory-hygiene keeps the *agent's working context* clean and its cross-session memory intact. One guards the code's state between steps; the other guards the agent's state between turns and sessions. ## Worked example *Illustrative construction, not a recorded run.* Task: "Continue the migration from the handoff — three tables done, four to go." Resumed session, context was compacted. ``` Agent does NOT trust its faded memory of "three done" → re-grounds first: re-reads the handoff artifact (.omc/handoffs/migration.md) for goal/state/done/open/next. Handoff says tables A,B,C migrated; D next; interface contract = new `id` is uuid not int (a durable decision). Agent re-derives the stale-prone facts rather than recalling: `git status` (working tree state) and a probe of which tables actually exist migrated in the DB — because those could have changed since the note. Probe disagrees with the note: table C's migration is half-applied. The note was optimistic. Agent trusts the live probe over recall, fixes C first. For table D, agent needs one thing: the source schema of D. Loads only that table's DDL, not the whole schema dump — keeps the window free for the reasoning. After migrating D and verifying, agent extracts the result, DROPS the verbose migration log, and updates the handoff (state: A–D done+verified, E next, uuid-contract still holds). Exit: durable contract recalled from artifact, stale progress re-derived by probe, working set kept to the one table in flight — no context spent on the four not-yet-touched tables. ``` ## Trace evidence | Case | Session | What it showed | |------|---------|----------------| | _awaiting case runs_ | — | — |