What is Agent Context Crystallization?

The problem

AI coding agents now work across long sessions: many files, multiple tools, repeated test runs, several failed paths, and eventually one or more compactions. Compaction is useful, but it is lossy by design. When the active context gets too large, older conversation state is summarized so work can continue. The session survives, but the work state degrades.

The failure mode is familiar:

• decisions survive as vague summaries;
• tradeoffs and rejected alternatives disappear;
• failed approaches are retried because the agent no longer remembers why they failed;
• open loops flatten into generic TODOs;
• the human becomes the transport layer, re-explaining context the agent already had.

That re-explaining labor is lost context externalized onto the user.

What crystallization does

Agent Context Crystallization captures work context before the boundary destroys it. Instead of relying on chat history or hidden summaries, it writes durable artifacts that a future agent can reload directly: current focus, decisions and their authority, findings and evidence pointers, open loops, changed files, tests and verification, next actions, and resume prompts.

The artifact is called a crystal because it takes fluid, temporary session context and turns it into something stable enough to inspect, reuse, commit, ignore, archive, or import into a larger memory system.

Checkpoints vs crystals

Checkpoints preserve local progress. Crystals preserve resumable work state.

What this is not

It is not repository indexing. Repository indexing helps an agent search code. Crystallization helps an agent recover the work it just did with you.

It is not hidden chain-of-thought preservation. Crystals preserve durable work context: evidence, decisions, findings, open loops, verification, and resume state.

It is not a hosted memory service by default. The first useful form is local, plain, inspectable Markdown.

Why not just use Git — or AGENTS.md?

Git preserves what changed. Crystals preserve why it mattered, what was decided, what remains unresolved, and how to resume. A good crystal points to commits, files, and test runs rather than duplicating them. Git is the provenance backbone; crystals are the work-memory layer.

AGENTS.md and CLAUDE.md are different again: they tell agents how to work in a repo — conventions, commands, style, constraints — and they should stay relatively stable. Crystals capture the evolving state of a specific work session: what was just tried, what broke, what remains open, and where the next agent should resume. Instruction files are protocol. Crystals are work-state continuity.

The minimal workflow

During work, drop a lightweight checkpoint after a meaningful step:

agent-crystallize checkpoint \
  --body "Finished auth refactor. Tests pass. Need OAuth replay check next."

Before compaction or session end, roll the trail up into a crystal:

agent-crystallize now --from-checkpoints latest \
  --body "Ready to compact. Preserve latest state, open loops, and next action."

The default output is plain Markdown you own, committed next to the code it explains:

.agent-crystals/
  checkpoints/
  sessions/

Principles

• Capture before compaction. Don't wait until the context is already degraded. Checkpoint while work is active, then crystallize before compaction or handoff.
• Preserve evidence, not vibes. A crystal should point to files, commits, tests, commands, or transcript ranges. A decision without evidence becomes another vague summary.
• Make memory inspectable. The artifact should be readable by humans and agents alike. Plain Markdown is enough for the first layer.
• Keep it local-first. The default shouldn't require an account, server, hosted database, or runtime network dependency. A crystal should be useful as a local file.
• Select explicitly. Crystals are selective too — but the selection is visible, editable, and reviewable. Compaction's selection is implicit and opaque.
• Resume from artifacts, not human memory. A future session should start from the latest crystal, not from the user retyping the same context again.

Try it

Install the CLI — Apache-2.0, and it works with Codex, Claude Code, Cursor, or your own loop:

npm install -g @stewie-sh/agent-crystallize

Source on GitHub and npm.