Context Compaction
Long conversations eventually approach the model’s context window. Instead of failing or silently dropping history, ChatShell compacts older messages automatically so the conversation can keep going.
How It Works
Section titled “How It Works”After a turn completes, ChatShell estimates the context size of the conversation. When it gets close to the model’s window limit:
- A recent window (about 20,000 tokens) is kept verbatim — the AI always sees your latest exchange in full.
- The older prefix is compacted: either into a bitmap archive (vision-capable models) or a text summary (everything else).
- Cut points only fall on user-message boundaries, so tool-call chains are never split mid-flight.
Compaction is method-aware:
| Model | Method | Result |
|---|---|---|
| Vision-capable | Bitmap archive — the discarded transcript is rendered into compact text images the model reads visually | Near-verbatim recall of compacted history at a fraction of the token cost |
| Text-only | LLM-generated summary of the discarded prefix | Facts carried forward in condensed form |
The bitmap technique is adapted from the open-source oh-my-pi project (MIT), with CJK text fully supported.
What You See
Section titled “What You See”- Your history is never trimmed in the UI. The transcript stays complete on this device and in sync; only the model’s working context shrinks.
- No configuration required. Compaction triggers automatically, per conversation, based on each model’s actual context window.
- Summaries use the tiny model when one is configured (see Auxiliary Models), keeping compaction cheap instead of billing your main model for it.
When It Triggers
Section titled “When It Triggers”The threshold adapts to the model: compaction starts when the conversation’s context reaches the model’s window minus a safety reserve (15% of the window, with a 16k-token floor). If the model’s window size is unknown, a 128k window is assumed.