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

> Discover how Prime Agent session compaction automatically reduces LLM context size by summarizing older messages. Learn what triggers this essential process.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: deep-dive
- Published: 2026-08-12

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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

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

```

*Source:* [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts)

### Manual TUI Invocation

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

```

*Source:* [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts)

### Event Listener

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts)

### Programmatic Trigger

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

```

*Source:* [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session.ts)

## Core Implementation Files

| File | Purpose |
|------|---------|
| [`packages/coding-agent/src/core/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/components/compaction-outcome-message.ts) | Success/failure UI rendering |
| [`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.