The context window is a workbench, not a warehouse. Compaction answers "it does not fit right now"; memory answers "will we remember next time". Both are lossy. The safe pattern is to get anything important into human-readable files early, and to treat compaction as tidying the workbench, not as the only safety net.
Companion to MCode Engineering Notes 03, "Keeping long sessions sharp".
Plain-text checklist: checklists/long-session.md.
This skill has two modes. Pick the one that matches the request.
Mode A - the session you are in right now
- Sort what is in context into three bins.
- Drop: things you can fetch again or no longer need (large file reads, test logs, search results, abandoned attempts).
- Summarize: this-session-only story (where we are, next step, open bugs and leads, files recently touched).
- Write to a file: anything that would hurt if lost or is needed in a later session (decisions and their reasons, progress, todos, acceptance criteria, long-lived rules).
- Write the third bin down now, in the project's progress or design doc,
or via
handoff-doc. - Choose the next move:
- Same task, history just long: compact, and say what comes next and what must be kept (for example "focus on the auth refactor, drop the test debugging").
- New task: start a new session.
- Compacted several times and drifting, or repeating questions already answered, or breaking earlier constraints: write a hand-off doc and start fresh with it.
- Went the wrong way: rewind to before the mistake instead of compacting, so the wrong attempt does not end up in the summary.
Mode B - reviewing an agent's design
Read the agent's code and configuration and answer each item with evidence (file and line, config key, or observed behaviour):
- Are old tool results cleared before resorting to a full summary?
- Are tool calls and their results kept in pairs when results are cleared? Many model APIs reject orphaned calls.
- Do key decisions and constraints get written to files, not only kept in the conversation?
- Does manual compaction accept instructions about what to keep and what comes next?
- Does automatic compaction trigger early enough to leave room for output and for the summary itself? Can the session continue if compaction fails (quota, smaller model)?
- Can the compaction request reuse the prompt cache? Does compaction run so often that it keeps invalidating the cache?
- Does compaction change only what the model sees, leaving the user's visible history intact? Is it kept out of user-facing budgets such as step limits?
- Is the model told that context is managed automatically, so it does not stop half way to "continue next turn"?
- Is project memory (
AGENTS.mdor similar) short and limited to stable rules? - Is memory scoped (session, project, user)? Are temporary progress and todos kept out of long-term memory?
- When memory exceeds its injection budget, is truncation visible, and are the most important rules guaranteed to load?
- Can a human open, edit and switch off the memory? Rules that must be enforced belong in hooks, not in memory.
Output
For Mode A: the three bins, what you wrote to which file, and the chosen next move. For Mode B: a table of the items with pass / fail / unknown, the evidence, and the top fixes in priority order.