Long-running agent sessions eventually hit the same problem: the model keeps accumulating chat history, tool outputs, intermediate decisions, and execution traces until the prompt becomes expensive or unstable. AIClaw has a built-in answer for that problem. It does not simply drop old messages. It compresses the middle of the conversation into a structured summary and keeps the parts that still matter for the next step.
This is not a new release post. It is a deeper look at one existing AIClaw runtime feature: context compression.
AIClaw is designed for tool-using work, not short chatbot replies. A single task can include:
That is useful context, but it also means the prompt grows fast. If the runtime sends everything back to the model forever, cost increases and the model starts paying attention to the wrong parts of the history.
The README describes this capability briefly as:
Runtime compression: Long middle context can be summarized during execution.
The implementation behind that line is more specific than it sounds.
The decision lives in internal/agent/context_compressor.go
and is wired into the main execution loop in internal/agent/run.go
.
Before each LLM round, AIClaw checks whether the current prompt is too large relative to the model context window.
The current defaults are straightforward:
If the model provider reports real prompt-token usage, AIClaw uses that. Otherwise it falls back to an internal estimate. That matters because the trigger is based on actual prompt pressure, not just message count. AIClaw uses a four-phase flow.
Before asking the model to summarize, AIClaw trims older tool messages outside the protected tail window. Tool outputs in that middle region are truncated to 200 runes. That keeps huge logs from dominating the summary prompt.
This is an important design choice. The runtime does not try to summarize raw noise at full size first. It reduces obviously low-value bulk before paying for the summarization call.
The compressor preserves:
The part in the middle becomes the candidate for compression.
Instead of generating a vague paragraph, AIClaw asks for a strict template with sections like:
This is a practical choice for agent continuity. The summary is meant to preserve execution state, not produce pretty prose.
After summarization, AIClaw inserts a [Context Compression Summary]
message and appends a note to the system prompt that earlier conversation has been compressed.
The result is smaller than the original history, but still carries forward the task objective, decisions, blockers, touched files, and next action.
A subtle detail in the implementation is that AIClaw does not cut through an assistant/tool-call group. The compressor aligns the preserved tail boundary backward so a tool call and its tool results stay together.
That matters because broken tool-call sequences are confusing for the next model round. If an assistant message says it called a tool but the corresponding tool results are missing from the preserved tail, the reconstructed context becomes misleading.
There are tests for this behavior in internal/agent/context_compressor_test.go
.
AIClaw also keeps the previous compression summary in memory during the active run. On the next compression pass, it does not start from zero. It sends:
Then it asks the model to merge them into an updated structured summary.
This makes repeated compression cheaper and more stable in long tasks. Instead of re-summarizing the entire old middle history every time, AIClaw incrementally rolls forward the important state.
The main execution loop prefers the agent's FastModelName
for compression when one is configured; otherwise it falls back to the primary model. That is a good default for a local-first agent platform:
Imagine a debugging session where an AIClaw agent:
Without compression, the conversation history gradually becomes a pile of stale tool output. With compression, AIClaw can keep the current tail intact while rolling earlier work into a structured checkpoint that still remembers:
That is the difference between “shorter prompt” and “runtime continuity.”
AIClaw is opinionated about execution state. It already treats plan state, generated files, execution steps, memory, and conversation history as first-class runtime data. Context compression fits the same design philosophy.
The goal is not to make the transcript prettier. The goal is to keep an agent useful after a long stretch of real work.
If you are building agents that mostly answer in one turn, this feature is easy to ignore. If you are building agents that browse, edit, run commands, and recover from failure across many rounds, it becomes part of the reliability story. AIClaw keeps that logic in the runtime rather than pushing the entire burden onto prompt engineering.
internal/agent/context_compressor.go
: compression thresholds, protected windows, summary prompt, iterative summary logicinternal/agent/run.go
: where compression is triggered in the execution loopinternal/agent/context_compressor_test.go
: tests for summary injection, iterative updates, tool-group preservation, and duplicate-note preventionREADME.md
: product-level runtime compression descriptionAIClaw is open source, self-hosted, and built for agents that do more than chat. Context compression is one of the small runtime details that makes that practical over longer sessions.