Context Optimization
Tool responses — file reads, command output, search results — are often the largest contributor to token usage and context-window pressure. AIControls compresses them in transit, keeps a retrievable copy of the original, and does it in a way that doesn't break your provider's prompt caching.
Compression is a preview feature. Results vary by tool and content type — monitor the Context Savings dashboard after enabling it.
Why compress tool responses
Every tool response an agent sees — a Read of a large file, a Bash command with verbose output, a Grep across a big codebase — is added to the conversation and resent to the model on every subsequent turn. Left unmanaged, this drives up two costs at once:
- Token spend — you pay for every token in every tool response, every turn it stays in context.
- Context-window pressure — as the window fills, the agent has less room for the parts of the conversation that actually matter, and eventually the client has to compact (summarize and discard) older turns.
Compression shrinks tool-response content before it reaches the model, while leaving a trail back to the full original in case it's needed later.
Two places compression happens
AIControls compresses tool output at two different points, because tools reach the model through two different paths:
| Path | What it covers | Where it's controlled |
|---|---|---|
| MCP tool responses | Results from MCP servers you've connected — the tools proxied through AIControls itself | Settings → Compression, always active once compression is enabled |
| Built-in tool results | Results from tools that run inside the coding agent itself — Bash, Read, Grep, Edit, WebFetch, and similar — which never pass through an MCP server | Settings → Compression → Also compress local/built-in tool results (off by default) |
Built-in tool results only ever appear as tool_result content in the messages your agent resends to the model — there's no MCP call for AIControls to intercept. To compress them, AIControls rewrites the outbound request to the model, replacing the tool result content with its compressed form before forwarding it. See Optimize Cost for how to turn this on.
Both paths apply the same rules — mode selection, tool/agent overrides, and thresholds all behave identically regardless of which path a given tool result took.
Compression modes
Each response is compressed using one of these modes. More aggressive modes save more tokens but discard more of the original structure.
| Mode | What it does | Typical size reduction |
|---|---|---|
| Off | No compression applied. | — |
| Conservative | Normalizes whitespace and collapses blank-line runs only. | ~5–15% |
| Standard | Conservative, plus deduplicates repeated lines within the response. | ~15–40% |
| Aggressive | Standard, plus removes near-empty lines. | ~40–70% |
| ML | Sends the content to the Compression Service for model-based reduction. | ~90–95% |
| Semantic | Sends the content to the Compression Service for LLM-based summarization, preserving meaning at a higher reduction than structural modes. Applied via tool/agent/content-type rules rather than the default mode. | Highest of any mode |
| AST (code-aware) | Parses source code and keeps only signatures, imports, and type declarations, stripping function bodies. Turned on with the Use code-aware (AST) compression toggle. | Highest for source code |
ML, Semantic, and AST modes require the Compression Service to be configured for your workspace. When it isn't reachable, Semantic and AST fall back to Aggressive, and ML falls back to Standard, so a response is never dropped or left unprocessed because the service is unavailable.
Rule precedence
A tool response's effective compression mode is decided by the first rule that matches, in this order:
- Trusted MCP servers — responses from an allowlisted server are never compressed, regardless of any other rule.
- Never-compress tools — an explicitly excluded tool is never compressed, regardless of any other rule.
- Per-agent rule — an override that applies to a specific agent.
- Per-tool rule — an override that applies to a specific tool name.
- Content-type rule — an override based on detected content (JSON, code, plain text, binary).
- Default mode — the workspace-wide fallback set in Settings → Compression.
Binary and image content is never compressed. Trusted-server and never-compress-tools rules, per-agent overrides, and per-tool overrides are workspace-level configuration managed on your behalf — talk to your AIControls contact if you need one added.
Visible to policies
For MCP tool calls, the base compression mode from steps 1–4 and 6 above (the trusted-server, never-compress, agent, and tool rules, and the workspace default) is exposed to every policy as object.defaults.compression.mode, with object.defaults.compression.matchedOn explaining which rule picked it. This lets a policy read or log the mode a tool call is about to get — for example, to flag calls where compression was skipped for a trusted server. It does not reflect the content-type rule or the context-pressure escalation described below, since neither has run yet at the point a policy evaluates.
Compression has no meaning for LLM calls — a single LLM request can carry many built-in tool results, each compressed independently — so object.defaults.compression is absent there, the mirror image of object.defaults.routing being absent for MCP tool calls.
Unlike routing overrides, a patchType: Defaults policy that sets compression.mode currently has no effect on the mode actually applied — this namespace is read-only in the current release. Support for policy-driven compression overrides is planned for a later release.
Escalating under context pressure
As a session's context window fills up, AIControls automatically escalates compression past whatever the default mode or a matched rule would otherwise apply — it never downgrades to something less aggressive than a rule already produced. The escalation floor increases with context fill:
| Context window fill | Minimum mode applied |
|---|---|
| 30% or higher | Conservative |
| 50% or higher | Standard |
| 70% or higher | Aggressive |
| 85% or higher | ML |
This means a session that starts with light compression automatically compresses harder as it approaches the point where the client would otherwise have to compact the conversation — buying more turns before that happens.
Retrieving the original content
Compression is designed to be lossless in practice, not just in theory — the original content is never gone, just moved out of the live context.
- Retrieval hint — every compressed response gets a short marker appended (
nirmata_retrieve hash=...) pointing to its original. nirmata_retrievetool — call this tool, available on the Admin MCP Server, with the hash from a hint to fetch the exact original content back.- Pre-compaction manifest — right before your client compacts the conversation, AIControls injects a manifest listing every compressed response from the session (tool name, hash, and when it was compressed), so the agent can proactively retrieve anything it still needs before that context is summarized away.
- Retention — originals are kept for 7 days, then purged. Retrieval requests for an expired or unknown hash return a clear "not found" error rather than failing silently.
Prompt caching is preserved
Compressing a tool result changes its bytes — which could easily break your provider's prompt caching, since cache hits depend on an exact byte match against a previously seen prefix. This matters most for built-in tool results: your coding agent resends the same tool result in full on every subsequent turn, and if AIControls compressed it a little differently each time — because context pressure had climbed, or a setting changed mid-session — the cached prefix would be invalidated on every turn, costing more in repeated cache writes than the compression saved.
AIControls avoids this by deciding once, per unique tool result, and remembering that decision: the first time a given tool result is seen, AIControls compresses it (or decides not to) and stores that outcome. Every later turn that resends the exact same original content gets back the exact same compressed bytes — replayed, not recomputed — even if the current default mode or context pressure would otherwise produce a different result. The compressed content your provider sees is therefore byte-for-byte identical every time it recurs, so the cached prefix stays valid and cache reads keep hitting instead of being paid for again.