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

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 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. 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, 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:

reasonix config compact-ratio

Override the ratio for the current project to 75%:

reasonix config compact-ratio --local 75

Inspect session compaction status:

reasonix status

The CLI implementation in internal/cli/cli.go handles these commands:

// 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:

// 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	Defines the three ratio fields (CompactRatio, SoftCompactRatio, ToolResultSnipRatio)
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	Implements the POST /compact HTTP endpoint for persisting compacted sessions
internal/cli/cli.go	Handles reasonix config compact-ratio commands and output formatting
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 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 to adjust default behavior across sessions.

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