TL;DR: Compaction is lossy by design, and the loss compounds across passes. After a few compactions, your agent remembers the gist but loses the why — and you become its memory, re-typing the same constraints week after week. agent-crystallize is a small open-source CLI that fixes this at the boundary: checkpoint work context into durable local Markdown before it gets compressed away.
Somewhere in your last long agent session, you caught yourself typing the same architecture constraint for the third time that week.
Not because the agent is bad. Because you compacted. And compaction is lossy — not as a bug, but as the whole point.
What compaction actually does
Long coding sessions outgrow the context window. Across major harnesses — Codex, Claude Code, Cursor — the pattern is similar: when the active context gets too large, older conversation state is compacted or summarized so work can continue on top of the compressed version. The model survives. The session keeps going.
But summarization under a budget means every pass discards detail that nobody explicitly chose to discard. And it compounds: compact a summary of a summary and you get generational photocopy loss. The what survives in blurry form. The why turns to soup.
You can see the symptoms in any multi-day agent project:
- Decisions survive as vague one-liners, with the tradeoffs and the rejected alternatives gone.
- Failed approaches disappear entirely — so the agent cheerfully re-attempts the exact path that broke production last Tuesday.
- Open loops get flattened into generic TODOs that no longer say what to verify or why it mattered.
- Edge cases you spent an hour reasoning through evaporate.
- And you — the human — become the transport layer, manually re-briefing the agent on things it already knew.
That last one is the tell. The re-explaining labor you're doing is the lost context, externalized onto you. The model survives, but the work does not.
The workaround everyone does and nobody names
Ask people how they cope with long-session decay and you'll hear the same move: "I just start a fresh session for each task."
It works, sort of. A fresh window doesn't hallucinate stale context. But look at what you're actually doing: you're accepting total amnesia to avoid partial confusion. Every fresh session starts from zero, so every fresh session starts with you re-explaining — the architecture, the constraints, what was already tried, what's off-limits. You've traded compaction's slow leak for a scheduled, manual re-briefing ritual. The cost didn't go away. It moved onto your calendar.
Your repo's instruction files don't save you here either. CLAUDE.md and AGENTS.md tell agents how to work in your repo — conventions, commands, style. They're meant to stay stable — they shouldn't become the running log of what this week's work decided, found, and left unresolved. That's a different kind of context with a different lifecycle, and today it mostly lives in the doomed part of the window.
Crystallize before the boundary
The fix shape is simple: capture work context before the boundary destroys it, in a form the next window can reload verbatim instead of re-deriving.
Concretely, that means two artifacts, written as plain Markdown into your repo:
- A checkpoint — a lightweight save-point during active work. What changed, what was decided, what was verified, what comes next. Thirty seconds to write, cheap enough to do after every meaningful step.
- A crystal — a fuller handoff artifact before compaction, session end, or agent handoff. It rolls up recent checkpoints and preserves the things summaries flatten: decisions with their authority, findings with evidence pointers, open loops, reality checks from actual commands and tests, and a resume prompt that says exactly where to restart.
Git already preserves your code history. Crystals preserve the work context around it — why the change mattered, what remains open, how to resume. Good crystals point at commits, files, and test runs instead of duplicating them.
We call this practice Agent Context Crystallization. To be precise about what it is not: this is not repository knowledge indexing; it is work-state continuity for coding-agent sessions. The problem isn't that agents can't search your codebase. It's that the work they just did with you evaporates at every context boundary.
What changed for me
I'll offer my own usage as the honest benchmark, because the behavior shift surprised me.
Before: I spawned new sessions constantly — roughly one per task — because long sessions degraded and I'd rather re-brief a blank agent than argue with a confused one. That re-briefing was a tax I'd stopped noticing.
Since adopting crystallization: I run a single long session per project. Compaction stopped being scary — with hooks configured, a checkpoint fires before the boundary, and the agent picks up from a concrete artifact afterward. Fresh sessions stopped being scary too — a new day or a new machine cold-starts from the latest crystal instead of from my memory of what I told it last time. I only open parallel sessions now when work is genuinely parallel.
The boundaries didn't go away. They became non-events.
One honest caveat: crystals are selective too. No artifact preserves everything, and pretending otherwise is how you end up trusting a summary you shouldn't. The difference is who selects and how. Compaction's selection is implicit, opaque to the active session, and hard to recover without transcript archaeology. A crystal's selection is explicit, inspectable Markdown sitting in your repo, appended to — never silently overwritten. When it's wrong, you can see that it's wrong.
Try it
agent-crystallize is the local-first CLI slice of this practice, open source under Apache-2.0. No account, no runtime network dependency, no telemetry, no hosted anything — it writes Markdown files into .agent-crystals/ in your repo and gets out of the way.
npm install -g @stewie-sh/agent-crystallize
# during work — lightweight save-point
agent-crystallize checkpoint \
--body "Finished auth refactor. Tests pass. Need OAuth replay check next."
# before compaction / session end — roll up into a handoff crystal
agent-crystallize now --from-checkpoints latest \
--body "Ready to compact. Preserve latest state and next action."
It works with any harness that can run a shell command — Codex, Claude Code, Cursor, or your own loop — and it ships hook examples for Codex and Claude Code: load recent crystal pointers at session start, checkpoint before compaction, record compact summaries when useful, and drop cadence checkpoints after sustained activity.
If you've felt the third re-explanation of the week, you already know whether you need this. Stop being your agent's memory.
— Vinh, founder of Stewie
