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

> Learn how to prevent state loss during context compaction in Prime Agent. Set keepRecentTokens to preserve your latest N tokens and maintain conversation flow.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-09-05

---

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

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

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

```

Verify that the last messages survived the compaction:

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

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts) around line 1805, where the shrinking and reconstruction take place.