Stewie
Agent Context Crystallization

What is Agent Context Crystallization?

Agent Context Crystallization means saving the important parts of an AI agent's work before a long session is summarized, handed off, or closed. The saved record shows what the agent was doing, what it learned, what was decided, what remains open, and where to continue.

Compaction keeps the model running. Crystallization keeps the work recoverable.

The problem

AI coding agents can work across many files and tools for hours. When the conversation grows too large, the tool may compress older parts into a summary so the agent can keep going. The main goal may survive while useful details disappear.

The failure mode is familiar:

  • decisions become vague;
  • rejected options and the reasons behind them disappear;
  • failed approaches get tried again;
  • open questions turn into generic TODOs;
  • the user has to explain work the agent already did.

The session continued, but the work did not fully carry forward.

A simple example

An agent spends an hour fixing a login bug. It finds the cause, rules out two false leads, tests a patch, and leaves one replay check for later. Then the session compacts. The agent may remember “fix login” but forget why those paths were rejected or which check still needs to run.

A crystal saves those details before they disappear, so the next session can continue instead of starting the investigation again.

What crystallization does

Crystallization writes the important work state to a file that people and future agents can read. It records the current goal, decisions and whether they were confirmed, supporting files or test results, open questions, changed files, next actions, and a clear place to resume.

The artifact is called a crystal because it turns temporary session notes into a stable record. You can inspect it, edit it, commit it with the code, archive it, or import it into a larger memory system.

Checkpoints vs crystals

Checkpoint

A short save point during active work. Write one after a meaningful step: a decision was made, a test passed or failed, a risky path was discovered, the next action changed, or the agent is about to move into a new subtask.

Crystal

A fuller handoff record. Write one before compaction, session end, switching agents, handing work to another person, starting a fresh session tomorrow, or moving work across machines or harnesses.

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 records what changed in the code. A crystal explains what the agent was trying to do, why choices were made, what remains unresolved, and how to resume. A good crystal links to commits, files, and test runs instead of copying them.

AGENTS.md and CLAUDE.md are different again. They tell every agent how to work in a repo: its commands, style, and constraints. They should change slowly. A crystal records where one piece of work stands right now: what was tried, what broke, what remains open, and where the next agent should continue.

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, combine the recent checkpoints 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 control. It can live 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. A crystal does not need every detail. Keep the selection visible and editable. Ordinary compaction chooses for you and hides what it left out.
  • Resume from artifacts, not human memory. A future session should start from the latest crystal, not from the user retyping the same context again.
Where Stewie fits

agent-crystallize is the local-first, open-source CLI that puts this practice in your repo today. It writes checkpoints and crystals as plain Markdown, with no account required. It sits alongside Product Behavior Contracts, which capture what the product promises to do. They solve different problems: Git records code changes, crystals record the state of the work, and PBCs record product behavior.

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.

Further reading