Session Compaction

Long sessions consume more tokens and cost more. Arcana's compaction system automatically summarizes older parts of the conversation when you approach the context limit, keeping sessions going without hitting a wall.

How It Works

When token usage reaches the compaction threshold (default 85% of the model's context window), Arcana:

Identifies the oldest messages in the session
Summarizes them using the utility model
Replaces the original messages with the summary
Preserves key facts and context in the summary

The agent retains awareness of what was discussed, just in compressed form.

Auto-Compaction

By default, compaction is automatic. It triggers when usage exceeds the threshold:

# Default: triggers at 85% of context window
arcana
# ... long session ...
# "Session compacted: 45,000 tokens → 12,000 tokens"

Manual Compaction

# In the TUI, type:
/compact

# Or from CLI:
arcana run --compact "continue where we left off"

Configuration

Compaction settings in ~/.arcana/config.json:

{
  "compaction": {
    "auto": true,
    "threshold_percent": 85,
    "intra": true,
    "intra_min_steps": 3,
    "intra_min_tokens": 5000
  }
}

Config Reference

Key	Type	Default	Description
`compaction.auto`	boolean	`true`	Enable automatic compaction
`compaction.threshold_percent`	number	`85`	Trigger when usage reaches this % of context (1–100)
`compaction.intra`	boolean	`true`	Mid-loop compact during multi-step tool runs
`compaction.intra_min_steps`	number	`3`	Min agent loop steps before intra compact
`compaction.intra_min_tokens`	number	`5000`	Min usage before intra compact is worth it

Intra-Loop Compaction

During complex multi-step tool runs (e.g., refactoring multiple files), the agent loop can consume many tokens. Intra-loop compaction summarizes intermediate steps mid-execution.

# Example: agent runs 10 tool calls in a loop
# After step 3, if tokens > 5000 and steps >= 3:
# "Compacting intermediate steps..."
# Agent continues with summarized context

Set "intra": false to only compact between user turns.

Disabling Compaction

{
  "compaction": {
    "auto": false
  }
}

Manual /compact still works when auto is disabled.

When Compaction Happens

Trigger	When	Can disable?
Auto (between turns)	Usage > threshold at end of turn	Yes (`auto: false`)
Intra-loop	Mid-execution during tool loops	Yes (`intra: false`)
Manual	User types `/compact`	No

Tips

Lower the threshold (e.g., 70%) if you want more aggressive cost savings
Higher thresholds (e.g., 90%) preserve more context but cost more
Use a cheap utility model for compaction summaries to save costs
Compaction preserves key facts — the agent remembers what was discussed
Long sessions with many tool calls benefit most from intra-loop compaction

Last updated: Jul 24, 2026