What util-compaction does—and what it cannot promise
An agent that works across many turns accumulates instructions, messages, and tool results. Eventually that history can compete with the available context window. util-compaction helps manage that pressure by invoking Pi's native compaction when estimated context reaches a configured threshold.
Use the built-in settings
/settings:util-compaction
/settings:util-compaction on
/settings:util-compaction off
/settings:util-compaction <tokens>
The default proactive threshold is 100,000 estimated tokens. Compaction is triggered after the agent settles, not as an exact guarantee of what the next provider request will contain. The package also contains context-output safety handling to limit model-visible tool text.
The important distinction: a threshold is not a promise that every request fits. Providers count tokens differently, large indivisible messages may remain, and preserved instructions still need room. A good system should fail clearly when it cannot fit rather than silently remove critical instructions.
Operate it with measurements
- Establish what your provider actually reports for input, cached input, and output.
- Observe representative multi-turn workflows, not just a single prompt.
- Keep full output or logs outside the model-visible context where appropriate.
- Test compaction, recovery, and failure paths before changing production settings.
- Treat cache and cost improvements as measured results, not assumptions.
The context-router article describes a separate, deterministic approach to older tool history. The two components have different responsibilities; neither turns a context window into an unlimited resource.
Install from the Pi extensions repository and reload an existing session. Consult the implementation and project documentation before changing thresholds or deploying to a different environment.
Need help with long-running agent workflows and context management? Email Nikhil at Swamix Global AI Solutions · swamix.com
Common questions
What triggers util-compaction?
The extension invokes Pi's native compaction after the agent settles when estimated context reaches its configured proactive threshold.
Does compaction guarantee that a provider request fits?
No. Token estimation, preserved messages, and provider-specific limits can still leave a request too large; measure actual usage and handle failure clearly.
