# How DeepSeek-Reasonix Handles Context Compaction: Understanding compact_ratio, soft_compact_ratio, and tool_result_snip_ratio

> Understand DeepSeek-Reasonix context compaction. Learn how compact_ratio, soft_compact_ratio, and tool_result_snip_ratio manage token limits and optimize summarization for better performance.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-06

---

**DeepSeek-Reasonix uses a tiered context compaction system with three configurable ratios—`compact_ratio` (hard limit), `soft_compact_ratio` (telemetry threshold), and `tool_result_snip_ratio` (pre-compaction trimming)—to manage token limits by summarizing old messages, preserving cache prefixes, and truncating stale tool outputs.**

As implemented in `esengine/DeepSeek-Reasonix`, the engine constantly monitors the ratio of used tokens to the model's maximum context window. When conversation history approaches configurable thresholds, the system triggers different compaction strategies to maintain performance without exceeding limits.

## Understanding the Three Compaction Ratios

DeepSeek-Reasonix defines three distinct thresholds in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) that control when and how the prompt history is modified.

### compact_ratio – The Hard Compaction Trigger (Default: 0.8)

The **`compact_ratio`** parameter sets the *hard limit* for context compaction. When the prompt reaches 80% of the model's maximum token count, Reasonix initiates a **summary-compaction** step.

According to the source code in `site/src/pages/docs.astro`, the engine sends older messages to the model for summarization, then replaces the original text with the resulting summary. This restores the session's token budget and allows the conversation to continue. The effective value can be inspected via CLI and overridden per-project.

### soft_compact_ratio – The Cache Preservation Threshold (Default: 0.5)

The **`soft_compact_ratio`** (default 0.5 or 50%) operates as a **notice-only** threshold defined in [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml). When the token ratio exceeds this value, the engine emits a *soft-compact* event for UI and telemetry purposes, but **does not** rewrite the prompt.

This threshold ensures that the cache-first prefix—the portion of context kept untouched for reuse—is preserved and not prematurely altered. It gates UI cues and diagnostic metrics while maintaining the integrity of cached conversation segments.

### tool_result_snip_ratio – Pre-Summary Trimming (Default: 0.6)

The **`tool_result_snip_ratio`** (default 0.6 or 60%) provides *pre-summary trimming* before hard compaction executes. When the prompt size falls below `compact_ratio` but above this threshold, the engine identifies stale tool-result blocks (such as long JSON dumps from previous tool calls) and truncates them to shorter placeholders (e.g., "[tool output omitted]").

If the prompt remains above `compact_ratio` after this snipping operation, the full summary compaction proceeds. This prevents huge tool outputs from dominating the token budget before the expensive summarization step runs.

## The Context Compaction Execution Flow

The compaction process follows a strict sequence as implemented in the Reasonix engine:

1. **Token tracking** – Each turn adds to the prompt token count, calculating `usedTokens / maxContextTokens`.

2. **Soft-compact checkpoint** – When the ratio exceeds `soft_compact_ratio`, Reasonix emits a soft-compact event for UI/telemetry only. No prompt modification occurs at this stage.

3. **Tool-result snipping** – If the ratio remains below `compact_ratio` but exceeds `tool_result_snip_ratio`, the engine replaces old tool-result blocks with placeholders to reclaim space.

4. **Hard compaction** – Once the ratio reaches `compact_ratio`, the engine calls the model to **summarize** the oldest conversation segments. The summary replaces old messages, shrinking the prompt below the threshold.

5. **Persistence** – After compaction, the compacted session saves to disk via `POST /compact` in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go), enabling recovery to replay the shortened history.

## Configuring Compaction Ratios in Practice

You can inspect and modify these parameters using the Reasonix CLI or by editing configuration files directly.

Show the effective compact ratio:

```bash
reasonix config compact-ratio

```

Override the ratio for the current project to 75%:

```bash
reasonix config compact-ratio --local 75

```

Inspect session compaction status:

```bash
reasonix status

```

The CLI implementation in [`internal/cli/cli.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/cli/cli.go) handles these commands:

```go
// In internal/cli/cli.go – printing the compact‑ratio
fmt.Printf("compact_ratio = %s (%s)\n",
    formatCompactRatioPercent(cfg.Agent.CompactRatio),
    compactRatioSource())

```

The HTTP endpoint that triggers compaction resides in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go):

```go
// In internal/serve/serve.go – endpoint that triggers a compact
func (s *Server) compact(w http.ResponseWriter, r *http.Request) {
    // … invoke session.Compaction() which performs the summarisation …
    s.logCompaction()
}

```

## Key Source Files and Implementation Details

| File | Role |
|------|------|
| [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) | Defines the three ratio fields (`CompactRatio`, `SoftCompactRatio`, `ToolResultSnipRatio`) |
| [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml) | Documents default values and comments for each ratio threshold |
| `site/src/pages/docs.astro` | UI documentation explaining compaction behavior |
| [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) | Implements the `POST /compact` HTTP endpoint for persisting compacted sessions |
| [`internal/cli/cli.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/cli/cli.go) | Handles `reasonix config compact-ratio` commands and output formatting |
| [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md) | Formal specification of the tiered compaction behavior |

## Summary

- **`compact_ratio`** (default 0.8) triggers hard compaction by summarizing old messages when the context reaches 80% capacity.
- **`soft_compact_ratio`** (default 0.5) provides telemetry and UI notifications at 50% capacity without modifying prompts, preserving cache prefixes.
- **`tool_result_snip_ratio`** (default 0.6) truncates stale tool outputs to placeholders before hard compaction runs.
- The compaction flow progresses from soft notification to tool-result snipping to full summarization, with persistence via the `/compact` endpoint.

## Frequently Asked Questions

### What happens when context reaches compact_ratio?

When the token ratio hits `compact_ratio` (default 80%), DeepSeek-Reasonix initiates hard compaction. The engine sends the oldest conversation segments to the model for summarization, replaces the original text with the summary, and removes the old messages from the context window. This occurs in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) via the compaction endpoint, and the shortened session persists to disk to maintain state across restarts.

### What's the difference between soft and hard compaction?

**Soft compaction** triggers at `soft_compact_ratio` (50%) and performs no text modification—it only emits telemetry events and UI notifications to signal that the cache-first prefix should be preserved. **Hard compaction** triggers at `compact_ratio` (80%) and actually rewrites the prompt by summarizing and removing old content to free token budget.

### How does tool_result_snip_ratio prevent token overflow?

The `tool_result_snip_ratio` (60%) acts as a pre-processing filter before hard compaction. When context size exceeds 60% but remains below 80%, the system truncates stale tool-result blocks (like large JSON responses) to short placeholders such as "[tool output omitted]". This reclaims space from verbose tool outputs before the expensive summarization step executes, preventing tool results from consuming disproportionate token budget.

### Can I disable context compaction in DeepSeek-Reasonix?

While you cannot fully disable compaction without risking context window overflow, you can adjust the thresholds. Set `compact_ratio` closer to 1.0 (e.g., 0.95) to delay compaction until the context is nearly full, though this leaves minimal buffer for new messages. Use `reasonix config compact-ratio --local 95` to apply project-specific overrides, or modify [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml) to adjust default behavior across sessions.