context-memory-hygiene

name	context-memory-hygiene
description	Invoke when deciding what to load into context, what to persist across turns or sessions, and what to drop — reads only what the task needs, writes durable handoffs, avoids context pollution, and chooses when to re-derive versus recall.

Context & Memory Hygiene

Status: v0.1 baseline draft — derived from the case catalog and axis definitions; awaiting trace evidence from Fable 5 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	—	—