How Session Compaction Works in Prime Agent to Reduce Context Size and What Triggers It

Prime Agent's session compaction automatically trims the LLM transcript by replacing older messages with a concise summary when token limits are reached or when manually invoked.

Prime Agent maintains a rolling transcript of every interaction exchanged with the LLM. Because LLMs have a finite token window, the transcript can eventually exceed the model's context limit, causing performance degradation or outright failures. The session compaction subsystem automatically — or manually — trims the transcript by replacing groups of older messages with a compaction summary. This summary is a short compactionSummary message that retains essential reasoning and state while discarding token-heavy content.

How Compaction Reduces Context Size

The compaction process follows a six-step pipeline implemented in packages/coding-agent/src/core/agent-session.ts:

1. Token tracking — The session manager tracks the token count of the full transcript, including user, assistant, and internal messages.

2. Threshold evaluation — When the token total crosses settings.compaction.maxTokens, the manager schedules a compaction operation.

3. Summary generation — The compaction operation builds a prompt that asks the LLM to summarize the oldest segment while preserving tool calls and stateful variables needed for later turns. This logic lives in packages/coding-agent/src/modes/interactive/components/compaction-summary-message.ts.

4. Transcript replacement — The LLM returns a short compactionSummary message. The session manager replaces the selected old messages with this single summary.

5. Size reduction — The new transcript is dramatically smaller, often less than 5% of the original, as verified in packages/coding-agent/test/suite/agent-session-compaction.test.ts.

6. Continued operation — Subsequent turns use the shortened transcript, keeping the LLM inside its token window and improving latency. The TUI in packages/tui/src/tui.ts handles redraw logic after this "shrink."

What Triggers Session Compaction

Prime Agent implements four distinct triggers for compaction:

Automatic Threshold-Based Compaction

Enabled when settings.compaction.maxTokens is a positive value. The manager checks token count after each turn and triggers compaction when the limit is exceeded. The test file agent-session-compaction.test.ts distinguishes this with a "threshold" reason string versus "manual" for user-initiated compaction.

Manual /compact Command

Users can issue /compact or /compact <reason> in the TUI. This queues compaction immediately regardless of token usage. The tui-render.test.ts verifies that scrollback is preserved "when a still-tall transcript shrinks (rebuild/compaction)."

Kernel Restart / Session Reload

When the Python kernel restarts, the session treats this as a compaction point, summarizing previous state so the new kernel starts with clean context. The system-prompt.test.ts references this behavior as "kernel restart or compaction."

Overflow Compaction During Retry

If a turn fails due to token budget exhaustion, the runtime performs compaction before retrying. The agent-session-retry-events.test.ts confirms that retry state remains active during "overflow compaction."

Event-Driven Architecture

Compaction is asynchronous: the session accepts new input while the LLM generates the summary. Once complete, the session:

• Emits compaction_start with the reason
• Inserts the compactionSummary message
• Emits compaction_end with statistics (severity "warning" if no-op)

These events enable the terminal UI to redraw without losing scrollback position.

Configuration and Code Examples

Adjusting Automatic Thresholds

{
  "compaction": {
    "enabled": true,
    "maxTokens": 8192,
    "keepRecentTokens": 500
  }
}

Source: packages/coding-agent/src/core/agent-session.ts

Manual TUI Invocation

await session.command("/compact manual");

Source: packages/tui/src/tui.ts

Event Listener

session.on("event", (ev) => {
  if (ev.name === "compaction_start") {
    console.log("Compaction began:", ev.reason);
  }
  if (ev.name === "compaction_end") {
    console.log("Compaction finished:", ev.stats);
  }
});

Source: packages/coding-agent/src/core/agent-session.ts

Programmatic Trigger

await session.triggerCompaction({ reason: "custom-maintenance" });

Source: packages/coding-agent/src/core/agent-session.ts

Core Implementation Files

File	Purpose
packages/coding-agent/src/core/agent-session.ts	Token tracking, compaction scheduling, triggerCompaction() API, event emission
packages/coding-agent/src/modes/interactive/components/compaction-summary-message.ts	Summary message generation for LLM prompt
packages/coding-agent/src/modes/interactive/components/compaction-outcome-message.ts	Success/failure UI rendering
packages/tui/src/tui.ts	Terminal redraw after compaction, scrollback preservation
scripts/session-context-stats.mjs	Token statistics computation
packages/coding-agent/test/suite/agent-session-compaction.test.ts	Verification of manual/threshold triggers and event ordering

Summary

• Session compaction in Prime Agent replaces old transcript messages with a concise compactionSummary to stay within LLM token limits
• Four triggers: automatic threshold, manual /compact command, kernel restart, and overflow retry
• Key method: triggerCompaction() in agent-session.ts with configurable reason
• Asynchronous design: Events (compaction_start, compaction_end) notify UI of progress
• Preserve state: Tool calls and variables are retained in the summary while bulk content is discarded

Frequently Asked Questions

What is the default token threshold for automatic compaction?

Prime Agent does not enforce a default maxTokens value. Automatic compaction only activates when settings.compaction.maxTokens is explicitly set to a positive integer in configuration.

Can I disable automatic compaction entirely?

Yes. Set "compaction": { "enabled": false } or omit maxTokens from settings. Manual compaction via /compact remains available regardless of automatic settings.

Does compaction lose information from my session?

No. The LLM-generated summary preserves essential reasoning, tool call results, and stateful variables needed for subsequent turns. Only redundant or token-heavy content is condensed.

How do I know when compaction has occurred?

Listen for compaction_start and compaction_end events on the session object, or observe the TUI which updates to show a summary message in place of the original transcript segment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}