# How Prime Agent Implements Session Compaction and Branch Summarization

> Discover how Prime Agent implements session compaction and branch summarization to keep long interactive sessions lightweight and efficient. Learn the technical details.

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

---

**Prime Agent keeps long-running interactive sessions lightweight by compacting old transcript entries and creating short branch summaries for alternate conversation paths.**

Managing long-running conversations with large language models presents a significant challenge: context windows fill up, token costs rise, and navigation becomes unwieldy. The PrimeIntellect-ai/prime-agent repository solves this through an elegant architecture that implements **session compaction** to compress historical context and **branch summarization** to manage divergent conversation paths. These mechanisms ensure that extended interactive coding sessions remain responsive and navigable without losing critical information.

## Session Compaction

When a session's token usage exceeds configured thresholds, Prime Agent triggers an asynchronous compaction process that collapses older transcript entries into condensed metadata, freeing up context window space while preserving semantic meaning.

### The Compaction Trigger and Process

The compaction workflow begins when you invoke `session.compact()` or when an extension detects high token usage. According to the source code in [`packages/coding-agent/src/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts), this public method initiates the operation and sets internal flags to track pending work.

The core logic resides in [`packages/coding-agent/src/session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/session.ts), where the internal `_compact()` routine walks the transcript from the oldest entries forward. It groups consecutive messages that are no longer needed for immediate context and replaces each group with a single **compact metadata** entry. This compact line contains a concise summary (for example, "compact summary of 123 tokens") that represents the collapsed content.

### Async Operation and Auto-Refine

Compaction runs asynchronously to prevent blocking the main execution thread. The session stores a pending `_compactionOperation` promise and blocks further refinement operations until compaction completes. This guarantees that subsequent conversation turns see a consistent, token-reduced context.

After compaction finishes, the system automatically schedules an **auto-refine** step. As implemented in [`packages/coding-agent/src/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts), the session sets `_compactAutoRefinePending` to true, prompting the LLM to review the newly created summary and add any missing information during the next refinement cycle.

### Implementation Verification

The behavior is rigorously tested in the codebase. The `trigger-compact` extension test in [`packages/coding-agent/test/trigger-compact-extension.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/trigger-compact-extension.test.ts) verifies that compaction only triggers when token counts cross the configured threshold. Additionally, [`packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/test/suite/agent-session-serialized-refine.test.ts) confirms that manual `session.compact()` calls correctly set `_compactAutoRefinePending` and that subsequent refine operations execute after compaction completes.

## Branch Summarization

Prime Agent supports **branches**—alternate conversation paths created via commands like `/branch`. For each branch, the system maintains a short summary that aids navigation and provides context without requiring users to replay the entire conversation history.

### Creating and Summarizing Branches

When you create a branch using `createBranch()` (defined in [`packages/coding-agent/src/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts)), the engine records the first few messages of that path and generates a one-line description. The `summarizeBranch()` helper in [`packages/coding-agent/src/branch.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/branch.ts) produces this human-readable summary, which is then stored alongside the branch metadata in `SessionBranch` objects.

These summaries update dynamically whenever the branch undergoes compaction or refinement, ensuring they remain accurate representations of the branch's current state.

### UI Integration

Branch summaries integrate directly into the user interface. As shown in [`packages/tui/test/select-list.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/test/select-list.test.ts), the TUI "select-list" component renders branch labels alongside their summaries (for example, "branch #2 – summary of recent actions"), enabling quick identification and navigation between multiple conversation threads.

## Working with Compaction and Branches

The following examples demonstrate how to interact with these features programmatically.

To manually compact a session when token usage grows too high:

```typescript
// Compact the current session when token usage is high
await harness.session.compact();               // Starts async compaction
await harness.session.waitForCompaction();     // Optional: wait for it to finish

```

To create a new branch and access its summary:

```typescript
// Create a new branch and immediately get its summary
const branch = await harness.session.createBranch('experiment-1');
console.log('Branch summary:', branch.summary);

```

You can also build extensions that trigger automatic compaction based on custom logic:

```typescript
// Example of a custom extension that triggers automatic compaction
import triggerCompactExtension from './extensions/trigger-compact.js';

export default function myExtension(context) {
  // Auto-compact when token count > 100k
  if (context.tokensUsed > 100_000) {
    await context.session.compact();
  }
}

```

## Summary

- **Session compaction** in Prime Agent asynchronously collapses old transcript entries into compact metadata lines when token thresholds are exceeded, managed via `session.compact()` in [`packages/coding-agent/src/harness.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/harness.ts) and the internal `_compact()` routine in [`packages/coding-agent/src/session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/session.ts).
- The compaction process sets `_compactionOperation` promises to ensure consistency and triggers `_compactAutoRefinePending` to prompt LLM review of new summaries.
- **Branch summarization** creates concise one-line descriptions for alternate conversation paths, generated by `summarizeBranch()` in [`packages/coding-agent/src/branch.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/branch.ts) and stored in `SessionBranch` objects.
- Both features are thoroughly tested, with verification in [`trigger-compact-extension.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/trigger-compact-extension.test.ts) and [`agent-session-serialized-refine.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/agent-session-serialized-refine.test.ts) for compaction logic, and [`select-list.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/select-list.test.ts) for UI integration of branch summaries.

## Frequently Asked Questions

### What triggers session compaction in Prime Agent?

Session compaction triggers when the session's token usage exceeds a configured threshold. You can manually invoke it via `session.compact()` or configure extensions to monitor `context.tokensUsed` and trigger compaction automatically when limits are reached.

### How does Prime Agent ensure data consistency during asynchronous compaction?

The system stores the compaction work as a `_compactionOperation` promise and blocks further refinement operations until this promise resolves. This prevents race conditions and ensures that subsequent conversation turns always see a consistent, fully compacted context window.

### What happens to branch summaries when a branch is compacted?

Branch summaries update dynamically whenever a branch undergoes compaction or refinement. The `summarizeBranch()` helper regenerates the one-line description based on the branch's current state, ensuring that UI labels in components like the TUI select-list remain accurate and useful for navigation.

### Can I wait for compaction to complete before executing other operations?

Yes. After calling `session.compact()`, you can await `harness.session.waitForCompaction()` to pause execution until the asynchronous compaction process finishes. This is useful when you need to guarantee that context reduction has occurred before sending new messages to the LLM.