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 when all of the following hold:
  • context_compression=True on the agent
  • Token usage of agent.short_memory ≥ threshold * context_length
  • The agent is at a check point: the top of each subtask iteration with max_loops="auto", or the top of each loop with an integer max_loops
The default threshold is 0.9 — compression fires at ~90% of the context window. context_length defaults to the model’s input window, so set it lower if you want compression to start sooner.

​
Default behavior

Compression is enabled by default. Just construct the agent normally:
When the conversation approaches the limit, Swarms:
  1. Summarizes the conversation with an LLM call.
  2. With persistent_memory=True, copies MEMORY.md to archive/history_<timestamp>.md, then wipes it and re-seeds it with the summary as a single System message.
  3. Rebuilds agent.short_memory (system prompt + rules + summary).
  4. In an autonomous run, rebuilds the request as the summary plus the prompt for the subtask in progress.
The agent keeps running with a small active context; with persistent memory on, the full pre-compaction transcript stays in archive/. Compression does not run during the planning or final-summary phases of an autonomous run.
With an integer max_loops, compression currently compacts agent.short_memory and MEMORY.md but does not shrink the request the run sends. A compaction at the start of a run can also leave that request with only the system prompt. Use max_loops="auto" when you rely on compression. See Agent Memory.

​
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, with persistent_memory=True:
The next time an agent with this agent_name is constructed, Swarms loads the compact summary from MEMORY.md into agent.short_memory. The archive is preserved for forensics but is never loaded.

​
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