How Context Token Estimation Triggers Compaction in Prime Agent

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 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:

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. 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), the session emits a compaction_start event. According to the source code in 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:

// 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, 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, 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 (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, with the specific threshold percentage defined in the compaction settings within 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 within the compaction option block of the session settings manager.

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