# How Reasonix Implements Context Compaction When the Context Window Limit Is Reached

> Learn how Reasonix implements context compaction to prevent prompt overflow. It summarizes conversation history to preserve key information, ensuring your AI stays within token limits.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Reasonix prevents prompt overflow by automatically summarizing older conversation history into a structured compaction summary once token usage exceeds 80% of the context window, preserving the system prompt, key facts, and recent messages while archiving the folded content.**

DeepSeek-Reasonix manages long-running LLM conversations by implementing an intelligent **context compaction** system that triggers when token usage approaches the model's configured limit. The system automatically folds historical dialogue into concise, structured summaries while preserving critical context, ensuring the agent maintains coherent reasoning without exceeding hardware constraints.

## Detecting the Compaction Trigger

The compaction process begins in [`internal/agent/compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/compact.go) where the `maybeCompact` function (line 81) monitors token consumption during each turn. This function checks the current `u.PromptTokens` against configured **compact-ratio** thresholds: a soft limit at 50% that emits informational notices only, and a hard limit at 80% that initiates automatic folding. Once the hard ratio is exceeded, `maybeCompact` invokes `compact` (line 119) with the trigger identifier `"auto"`.

## Planning the Compaction Region

Inside `compact`, the `planCompaction` function (line 99) determines exactly which messages to fold by calculating two critical boundaries. First, it establishes a **pinned prefix** (`pinnedPrefixLen`) that must remain verbatim, including the system prompt, the initial user turn, and any existing compaction summaries. Second, it allocates a **tail budget** of 16 KB tokens and walks backward from the newest messages until this budget fills, marking the `tailStart` index. The function returns the range `msgs[head:start]` representing the foldable middle section.

## Partitioning and Economic Checks

The `partitionFold` function (line 84) separates the target region into two categories: **kept** messages (small user turns, prior summaries, and messages protected by the *keep* policy) and **fold** messages eligible for summarization. Before invoking the LLM, Reasonix performs a `foldEconomics` validation (line 13) to ensure the foldable portion justifies an API call; if the segment is too small, the compaction aborts unless the `force` flag is set.

## Generating the Structured Summary

When economics validate, `summarizeWithRetry` calls `summarize` (line 44) to generate the briefing. This function sends a specialized `summarySystemPrompt` (lines 48–79) instructing the model to produce a structured document covering standing facts, goals, decisions, files, commands, errors, and next steps. The call respects a `summaryTimeout` (line 46) and streams the response to capture usage statistics.

## Reconstructing the Session

After summarization, Reasonix rebuilds the message list atomically using `session.Replace`. The new transcript structure consists of: the original prefix (`msgs[:head]`), all kept messages, a single **compaction summary** wrapped in `<compaction-summary>` tags (lines 58–62), and the unchanged recent tail (`msgs[start:]`). A rewrite counter increments (line 66) to track compaction frequency.

## Archiving and Event Emission

If an archive directory is configured, `archiveMessages` (lines 20–40) writes the folded messages to a timestamped `.jsonl` file. Reasonix emits three events to update UI components: `CompactionStarted` before summarization, `CompactionDone` containing the summary, fold count, and archive path (lines 68–70), and a fallback mechanical fold (plain text) if summarization fails (lines 46–52).

## Handling Pathological Loops

To prevent infinite compaction cycles, a *stuck* guard (lines 28–34) detects when compaction fires on consecutive turns and disables auto-compaction while emitting a warning. Users retain the ability to force compaction manually using the `/compact` command, which bypasses the guard.

## Code Examples

**Automatic compaction triggered by window limits:**

```go
// Inside the turn‑processing loop (simplified)
usage, _ := provider.GetUsage()               // provider‑specific token usage
agent.maybeCompact(ctx, usage)                // Auto‑compact when usage exceeds the configured ratio

```

**Manual compaction via the `/compact` command:**

```go
// The UI sends a `CompactionStarted` event with trigger "manual"
agent.compact(ctx, "manual", userFocus, false) // `userFocus` is optional extra guidance

```

**Inspecting the resulting session after compaction:**

```go
for i, m := range agent.session.Messages {
    fmt.Printf("%d [%s] %s\n", i, m.Role, m.Content)
}

```

The output will contain a single user message that starts with `<compaction-summary>` – the compacted briefing.

## Key Source Files

- **[`internal/agent/compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/compact.go)** – Core implementation of context compaction, including detection, planning, summarisation, and archiving.
- **[`internal/event/event.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/event/event.go)** – Definition of the `CompactionStarted` and `CompactionDone` events used to surface progress.
- **[`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go)** – Provides the `Message` and `Usage` types that the compaction logic operates on.
- **[`internal/cli/chat_tui.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/cli/chat_tui.go)** – Renders the compaction summary card in the terminal UI (`compactionCardLines`).

## Summary

- **Context compaction** triggers automatically when token usage exceeds 80% of the configured window, or manually via the `/compact` command.
- The system preserves a **pinned prefix** (system prompt, first turn, existing summaries) and a **16 KB tail** of recent messages while folding the middle section.
- Reasonix validates **fold economics** to avoid API calls for insignificant token savings, unless the `force` flag overrides this check.
- Summaries follow a structured format wrapped in `<compaction-summary>` tags and are stored alongside archived original messages in timestamped `.jsonl` files.
- A **stuck guard** prevents infinite compaction loops by disabling auto-compaction when it fires on consecutive turns.

## Frequently Asked Questions

### At what token threshold does Reasonix automatically compact context?

Reasonix initiates automatic compaction when `u.PromptTokens` exceeds the **hard ratio** of 80% of the configured context window. A **soft ratio** at 50% only emits informational warnings without triggering the fold.

### How does Reasonix decide which messages to keep versus fold?

The `planCompaction` function calculates a pinned prefix containing the system prompt and initial turns, plus a tail budget of 16 KB for recent messages. The `partitionFold` function then categorizes the remaining middle section into **kept** messages (small user turns, prior summaries) and **fold** messages eligible for summarization.

### What happens if the summarization API call fails during compaction?

If the LLM summarization fails, Reasonix falls back to a **mechanical fold** that compresses the foldable messages into plain text rather than a structured summary. The system still emits a `CompactionDone` event to notify the UI of the fallback.

### Can users manually trigger context compaction?

Yes. Users can invoke the `/compact` command at any time, which calls `agent.compact` with the `"manual"` trigger and optional `userFocus` guidance. Manual compaction bypasses the stuck-guard protection that disables auto-compaction after consecutive folds.