Context discipline: multi-day work without rot

You already use Claude Code. What you probably don't have yet is a way to keep a piece of work coherent across more than one sitting. Sessions sprawl, the agent starts forgetting decisions it made an hour ago, and by the next morning the thread you were pulling on is gone. The model didn't fail you there. Your memory setup did, and it has a fix.

The context window is working memory, not storage. Everything the agent knows in a session competes for the same finite space: your prompts, its own reasoning, every file it read, every diff it wrote. On a long session the early detail falls out of scope. The constraint you agreed on at message five is no longer in front of the model at message eighty, so it quietly contradicts it. This is context rot, and the naive fix of never closing the session makes it worse. You're just filling the window faster with more stuff to forget.

So stop treating the conversation as the record. Push the durable parts out into docs, and let each session load only what it needs.

Docs are the memory the session doesn't have#

Two kinds of stable documents carry what a conversation can't.

CONTEXT.md holds the domain glossary and the project truths: the terms, the invariants, whatever is simply true about this codebase. When Permaflux-os grew a skills library, the first artifact wasn't code. It was a new CONTEXT.md holding the glossary for it. If the agent and I don't share the words, everything downstream drifts.

ADRs (architecture decision records) capture why a decision was made, one file per decision, numbered so they accrete. Permaflux-os carries fourteen right now, 0001-monorepo-architecture.md through 0014-build-circuit-and-backlog.md. The numbering matters: a decision recorded in ADR-0012 survives the session that made it. Two hundred sessions later, a fresh agent reads the ADR instead of re-litigating the choice, or worse, silently reversing it because the reasoning was never written down.

SESSION_STATE.md: the resume point#

CONTEXT.md and ADRs are stable. The thing that changes every few hours is where you are, and that lives in a SESSION_STATE.md. Mine opens by telling the next reader exactly what it's for:

The resume point. Updated at every phase boundary. The morning handoff lives at the very top once the night is done. If the session died, start here.

My overnight "Night-N" builds run as a loop around this file. The session starts by reading SESSION_STATE.md to reload where the last one stopped, and ends by writing a fresh "Morning handoff" block at the top: what shipped, what's green, what still needs me. The next night reads that block first. Sessions that never share a context window pass the file between them like a baton.

A skeletal version, distilled from the real one:

# Session State

The resume point. Newest handoff on top. If the session died, start here.

## Night N — Morning handoff
**Last updated:** <date>. Branch `<branch>` — NOT merged, for your review.
`npm test` green (<n> tests). Typechecks, builds, lint clean.

Shipped: <one paragraph — what landed, per slice>.

### What needs you
- <the review / decision / live check only you can do>
- <the next thing to pick up>

## (older handoffs below, untouched)

Notice what it doesn't do: it doesn't restate the ADRs or re-explain the domain. It references branches, tests, and decisions by name and points at them. The resume point is a pointer, not a copy.

Handoffs: compacting a session into a boot doc#

When a conversation has to survive a session boundary, don't rely on scrollback. Write a handoff, a document that compacts the current conversation into something a fresh agent can boot from. The /handoff skill does exactly this. It summarizes the thread into a markdown file and deliberately avoids duplicating what already lives in PRDs, ADRs, plans, or commits. It references those by path and captures only the live state that would otherwise be lost.

Claude Code gives you two lighter in-session tools for the same pressure. /compact summarizes the current conversation in place so you can keep going on a smaller footprint, which is what you want mid-task when you just need headroom. /context shows what's actually consuming the window right now. Reach for a written handoff instead of /compact when the work has to outlive this session: you're closing the laptop, handing to a parallel agent, or expecting to resume tomorrow. /compact keeps one session breathing. A handoff starts the next one clean.

Auto-memory: the override channel for stale facts#

Docs go stale. CLAUDE.md is checked into the repo and lags reality, still asserting something that stopped being true two refactors ago. Claude Code's persistent auto-memory covers exactly that gap. On this very site, CLAUDE.md §3 still lists the host as Vercel, but memory carries a correction: the site actually ships as a Next.js static export on Cloudflare, overriding CLAUDE.md §3. The agent reads both and trusts the memory. You don't have to win the race to keep every doc perfectly current, because you have a channel for correcting the record without rewriting it.

Write long things to a file, reply with a summary#

I learned this one the hard way, and the receipts are in my own usage report. Several sessions produced truncated handoffs. The agent hit the output length limit mid-document, the handoff cut off, and the next session booted from half a doc. Continuity broke at exactly the moment it was supposed to be protected.

The rule I codified afterward: write long artifacts (handoffs, audits, PRDs) to a markdown file, then reply with a three-line summary plus the path. The file is the durable artifact. The chat reply is just a receipt. A summary can't overflow the output limit, and the real work sits safely on disk where the next session reads it in full.

Here's the whole loop, a night session that opens by reading state and closes by writing the handoff:

The conversation is disposable. The docs are not. Next up is planning: how to turn a vague idea into a plan the agent can actually execute against, before you write a single prompt.