Skip to main content
Long-running agents accumulate transcripts that eventually exceed the model’s context window. Swarms ships a ContextCompressor that summarizes the active memory near the limit and archives the raw transcript — the agent keeps running without manual pruning.

​
When to use it

  • max_loops="auto" or any long-running iterative task.
  • Agents that produce or consume large tool outputs.
  • Multi-session agents whose MEMORY.md would otherwise grow unbounded.

​
How it fires

Compression runs at the top of a loop iteration when all of the following hold:
  • context_compression=True on the agent
  • Token usage of the active prompt ≥ threshold * context_length
  • The agent is at the start of an iteration (not mid tool-call)
The default threshold is 0.9 — compression fires at ~90% of the context window.

​
Default behavior

Compression is enabled by default. Just construct the agent normally:
When the prompt approaches the limit, Swarms:
  1. Summarizes the current transcript with an LLM call.
  2. Copies MEMORY.md to archive/history_<timestamp>.md.
  3. Wipes MEMORY.md and re-seeds it with the summary as a single System message.
  4. Rebuilds conversation_history (system prompt + rules + summary).
The agent keeps running with a small active context; the full pre-compaction transcript stays in archive/.

​
Tune the compressor

Swap the default ContextCompressor after construction to change the threshold, summarizer model, or summary length:
Lower threshold for agents with large tool outputs so you compress before any single iteration overflows.

​
Manual compaction

You can compact memory yourself at any time — useful after a clear milestone (research phase done, plan finalized):
Manual compaction follows the same archive → wipe → re-seed flow as automatic compression.

​
Disable compression

When you want the active MEMORY.md to keep the raw transcript intact:
Use this for short tasks, or when downstream tooling parses the unmodified transcript.

​
What ends up on disk

After compaction:
On the next run, Swarms preloads the compact summary from MEMORY.md — the archive is preserved for forensics but does not enter the active context.

​
Tips

  • Keep compression on for autonomous loops; the cost of one summary call is small versus a context-overflow failure.
  • Lower threshold (0.6–0.75) for agents that emit long structured outputs.
  • Use a cheaper summarizer_model (Haiku) to keep compaction lightweight.
  • Compact manually at major milestones to lock in important state with a hand-written summary.

​
See also