# How Context Token Estimation Triggers Compaction in Prime Agent

> Discover how Prime Agent uses context token estimation to automatically trigger compaction, optimizing LLM context window usage and performance. Learn more!

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

---

**Prime Agent monitors LLM context size by estimating token counts after every turn, automatically triggering compaction when usage exceeds a configurable threshold of the model's context window.**

Prime Agent, developed by PrimeIntellect-ai/prime-agent, implements an intelligent context management system that prevents token overflow during extended coding sessions. The system relies on continuous **context token estimation** to decide when the conversation history has grown too large for the model's limits. When the estimate crosses a predefined percentage of the context window, the agent automatically initiates compaction to summarize or drop older messages.

## The Token Estimation Pipeline

The estimation process combines exact token counts from completed LLM responses with heuristic calculations for pending messages.

### Character-Based Heuristics for Pending Messages

At the core of the system is the `estimateContextTokens` function defined in [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) at line 196. This function iterates through the session's message list, summing the exact token usage reported by the model for completed turns. For trailing messages—such as pending tool results or queued user input—it applies a cheap character-based heuristic to predict token costs without expensive tokenizer calls.

### Session-Wide Token Calculation

After every turn or when new messages are added, the agent session invokes the estimator at line 7909 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):

```typescript
const estimate = estimateContextTokens(messages);

```

This call returns a token total that represents the current memory footprint of the conversation, including both confirmed usage and estimated overhead from incomplete operations.

## Threshold Detection and Automatic Triggering

Once calculated, the token estimate undergoes a threshold comparison to determine if compaction is necessary.

### Configurable Context Window Limits

The estimated token total (`estimate.tokens`) is compared against the model's maximum context window size, as configured in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts). The `compaction` option block within the session settings manager defines three critical parameters: whether auto-compaction is enabled, how many recent tokens to preserve, and the percentage threshold that triggers action.

### The Compaction Request Flow

When the estimate exceeds the configured percentage threshold (typically checked around lines 7910–7920 in [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts)), the session emits a `compaction_start` event. According to the source code in [`packages/coding-agent/src/modes/daemon/daemon-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/daemon/daemon-mode.ts), the daemon orchestrates the actual compaction operation—either summarizing older messages into condensed representations or removing them entirely. Upon completion, the system emits a `compaction_end` event and resets the token counter using the newly compacted context for subsequent turns.

## Manual vs. Automatic Compaction

While automatic triggering occurs when `estimateContextTokens` signals an overflow risk, users retain control over the process. The same mechanism powers the manual `/compact` command, which calls `session.requestCompaction({ reason: "manual" })` directly. Both pathways ensure the conversation stays within token limits while preserving recent, relevant context according to the `keep-recent-tokens` configuration.

## Code Examples

The following patterns demonstrate how Prime Agent implements token monitoring and compaction triggering:

```typescript
// Estimate tokens for the current session
import { estimateContextTokens } from "./core/compaction/index.js";

const estimate = estimateContextTokens(session.messages);
console.log(`Estimated tokens: ${estimate.tokens}`);

// Trigger compaction if over 80% of the model's context window
if (estimate.percent > 80) {
  await session.requestCompaction({ reason: "auto-threshold" });
}

// Manual compaction from the UI (e.g., /compact command)
await session.requestCompaction({ reason: "manual" });

```

## Summary

- **Continuous Monitoring**: Prime Agent's `estimateContextTokens` function runs after every turn at line 7909 in [`agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session.ts), combining exact token counts with character-based heuristics for pending messages.
- **Automatic Triggering**: When estimates exceed the configured percentage of the model's context window, the system emits a `compaction_start` event and executes compaction via the daemon mode handler.
- **Configuration Control**: Thresholds and preservation rules live in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts), allowing customization of the auto-compaction behavior.
- **Dual Pathways**: Both automatic thresholds and manual `/compact` commands utilize the same `requestCompaction` API, ensuring consistent context management.

## Frequently Asked Questions

### What specific function calculates token estimates in Prime Agent?

The `estimateContextTokens` function in [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) (starting at line 196) handles all token calculations. It walks the message list to sum exact token usage from completed LLM responses while applying character-based heuristics to estimate costs for pending or incomplete messages.

### At what point does automatic compaction trigger?

Automatic compaction triggers when the estimated token count exceeds a configurable percentage of the model's total context window. This check occurs immediately after the estimation call at line 7909 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), with the specific threshold percentage defined in the compaction settings within [`settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/settings-manager.ts).

### Can users manually initiate compaction?

Yes. Users can trigger the same compaction mechanism manually using the `/compact` command, which invokes `session.requestCompaction({ reason: "manual" })`. This executes the identical summarization logic used during automatic compaction, governed by the same `keep-recent-tokens` settings.

### Where are the auto-compaction settings stored?

The configuration for automatic compaction—including the enabled flag, preservation rules, and threshold percentage—resides in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/settings-manager.ts) within the `compaction` option block of the session settings manager.