How to Avoid Losing Recent State During Context Compaction in Prime Agent

Set the keepRecentTokens configuration option to a value greater than zero to guarantee the newest N tokens survive when Prime Agent compacts conversation context.

Prime Agent manages long-running conversations by periodically compacting context to stay within model token limits. Without proper configuration, this compaction process can discard recent messages, causing the agent to lose track of the latest user inputs or intermediate reasoning steps. Configuring the compaction settings correctly ensures critical recent state remains intact while still reducing overall token usage.

Understanding Context Compaction Risks

Context compaction is the process where older messages are merged into a summary and the transcript is rebuilt to conserve tokens. When the compaction routine discards the newest tokens, the agent can lose the most recent user input or pending commands, resulting in unexpected behavior or broken conversation continuity. The Prime Agent codebase provides specific safeguards to prevent this data loss.

Configuring keepRecentTokens to Preserve Recent Messages

The primary mechanism to avoid losing recent state during context compaction is the keepRecentTokens field within the session's compaction configuration object. This setting instructs the compaction routine exactly how many of the latest tokens must be retained unchanged during the shrink-and-rebuild step.

The default value is 0, which means the system keeps nothing and may discard recent messages. Setting keepRecentTokens to any value greater than or equal to 1 ensures that the newest specified number of tokens survive the compaction process untouched.

Where the Setting is Applied

The session's configuration object is passed to the AgentSession constructor or updated via session.setSettings. Before starting a compaction pass, the routine reads settings.compaction.keepRecentTokens to determine the preservation threshold. This implementation resides in the core session logic at packages/coding-agent/src/agent-session.ts.

How the Compaction Implementation Protects Recent Tokens

When the transcript is rebuilt, the code explicitly extracts the last N tokens (where N equals keepRecentTokens) before discarding the remainder. This shrinking logic lives in the TUI rendering pipeline at packages/tui/src/tui.ts#L1805, where the comment "shrink — a rebuild or compaction that replaces the transcript with..." marks the exact point where the recent slice is saved and later concatenated back to the summary.

The test suite verifies this preservation behavior at packages/coding-agent/test/suite/agent-session-compaction.test.ts#L2733, confirming that configured recent tokens remain intact after compaction.

Practical Implementation Examples

Create a session with a compaction policy that protects recent context:

import { AgentSession } from "packages/coding-agent/src/agent-session";

const session = new AgentSession({
  compaction: {
    // Preserve the newest 5 tokens when a compaction runs
    keepRecentTokens: 5,
    // Optional: trigger compaction after 2k tokens accumulated
    triggerThreshold: 2000,
  },
});

Force a manual compaction that respects the recent token preservation:

await session.compact(); // automatically retains the 5 newest tokens

Verify that the last messages survived the compaction:

const lastMessage = session.messages[session.messages.length - 1];
console.log("Latest unchanged message:", lastMessage.content);

Adjust the preservation policy at runtime after a long discussion:

session.setSettings({
  compaction: {
    keepRecentTokens: 10, // increase retention for subsequent compactions
  },
});

Key Files and Types

The CompactionSettings interface defining these options is located in packages/coding-agent/src/types.ts. This type is used throughout the codebase to ensure type safety when configuring compaction behavior.

Summary

• Set keepRecentTokens: Configure this option to a value ≥ 1 to prevent recent message loss during compaction.
• Default is unsafe: The default value of 0 means no recent tokens are preserved, risking state loss.
• Implementation location: The preservation logic executes at packages/tui/src/tui.ts#L1805 during the transcript rebuild phase.
• Runtime adjustable: Modify keepRecentTokens mid-session using session.setSettings() to adapt to changing conversation needs.
• Verified behavior: Test coverage at packages/coding-agent/test/suite/agent-session-compaction.test.ts#L2733 confirms recent token persistence.

Frequently Asked Questions

What is the default value of keepRecentTokens in Prime Agent?

The default value is 0, which instructs the compaction routine to keep no recent tokens. This means the system may discard the newest messages during compaction unless explicitly configured otherwise.

How does the compaction process decide which tokens to keep?

The compaction implementation extracts the last N tokens (where N equals the configured keepRecentTokens value) before processing older messages into a summary. These extracted tokens are then appended unchanged to the compacted transcript, ensuring the most recent conversation context survives the rebuild.

Can I change the keepRecentTokens setting after a session has started?

Yes, you can adjust the setting at runtime by calling session.setSettings() with a new compaction object containing the updated keepRecentTokens value. The next automatic or manually triggered compaction will respect the new preservation threshold.

Where is the compaction logic implemented in the Prime Agent codebase?

The core compaction logic resides in packages/coding-agent/src/agent-session.ts, which reads the keepRecentTokens setting and orchestrates the merge process. The actual transcript rebuilding and token slicing occurs in packages/tui/src/tui.ts around line 1805, where the shrinking and reconstruction take place.

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