compact_force_ratio vs compact_ratio for Context Management in DeepSeek-Reasonix

The compact_ratio (default 0.8) initiates soft compaction by trimming stale tool results and summarizing history when the prompt reaches 80% of the model's context window, while compact_force_ratio (default 0.9) acts as a hard ceiling that forces aggressive compaction of even low-value folds when the prompt hits 90% of the window.

Managing long-running conversations in large language models requires careful control of the context window. In the esengine/DeepSeek-Reasonix repository, two configurable thresholds—compact_ratio and compact_force_ratio—govern when the engine compresses accumulated dialogue to prevent token overflow. These settings, defined in the configuration layer and exposed through the CLI, determine whether the agent performs gentle cleanup or forced summarization.

What Are compact_ratio and compact_force_ratio?

The configuration fields reside in the AgentConfig struct within internal/config/config.go. Both are floating-point values representing fractions of the model's maximum context window size.

compact_ratio: The Soft-Compact Threshold

When the accumulated prompt length reaches the fraction defined by compact_ratio (default 0.8), the engine enters a soft-compaction phase:

1. Stale tool-result trimming: Old tool execution results are replaced with lightweight placeholders.
2. Summarization: If the prompt remains above the threshold after trimming, older conversation turns are summarized to reduce token count.

This approach attempts to preserve as much conversational history as possible while keeping the prompt manageable.

compact_force_ratio: The Hard-Compact Ceiling

compact_force_ratio (default 0.9) serves as a high-water mark safety mechanism. When the prompt reaches this fraction of the context window, the engine forces compaction regardless of the perceived value of the folds:

• It overrides the normal decision logic that might skip low-value summaries.
• It guarantees the prompt will never exceed the model's hard token limit by aggressively compressing content.

How the Two Thresholds Work Together

The context-management logic evaluates these thresholds sequentially during each turn:

1. Check compact_ratio: At 80% capacity, the engine trims tool results and attempts gentle summarization.
2. Check compact_force_ratio: If the prompt continues growing and hits 90%, the engine forces a fold (summary) even if the content seems valuable, acting as a circuit breaker against overflow.

This staged approach balances preservation of dialogue quality with system stability.

Configuring the Context Management Thresholds

You can adjust these values via configuration files, environment variables, or programmatically.

Via the TOML Configuration File

The reasonix.example.toml demonstrates the default user-level settings:

[agent]
compact_ratio       = 0.8   # Start soft compaction at 80% of context window

compact_force_ratio = 0.9  # Force compaction at 90% regardless of fold value

Reference: reasonix.example.toml (source)

Via the Command Line Interface

The CLI exposes these as compact-ratio and compact-force-ratio commands:

# View current global values

reasonix config compact-ratio
reasonix config compact-force-ratio

# Set soft-compact start to 75%

reasonix config compact-ratio 75

# Set a project-local hard limit of 85% (overrides global for current project)

reasonix config compact-force-ratio --local 85

The CLI prints human-readable descriptions defined in internal/config/render.go, which pulls the default values from the configuration struct.

Reference: internal/cli/cli.go (source)

Programmatic Access in Go

When integrating the library directly, access these thresholds through the loaded configuration:

package main

import (
    "fmt"
    "github.com/esengine/DeepSeek-Reasonix/internal/config"
)

func main() {
    cfg := config.NewDefaultConfig()
    
    // Access ratios from the AgentConfig struct
    fmt.Printf("Soft threshold:  %.0f%%\n", cfg.Agent.CompactRatio * 100)
    fmt.Printf("Force threshold: %.0f%%\n", cfg.Agent.CompactForceRatio * 100)
}

The struct fields are defined with TOML tags for serialization:

type AgentConfig struct {
    CompactRatio      float64 `toml:"compact_ratio"`
    CompactForceRatio float64 `toml:"compact_force_ratio"`
    // ... other fields
}

Reference: internal/config/config.go (source)

Summary

• compact_ratio (0.8 default): Triggers soft compaction; trims stale tool results and optionally summarizes older turns to keep the prompt under the context limit.
• compact_force_ratio (0.9 default): Acts as a hard ceiling; forces mandatory compaction of any remaining folds to prevent context overflow as the prompt approaches the absolute token limit.
• Configuration: Set via reasonix.example.toml, CLI commands (reasonix config), or the AgentConfig struct in Go code.
• Source locations: Defined in internal/config/config.go, rendered in internal/config/render.go (lines 230-238), documented in site/src/pages/docs.astro (lines 326-332), and exposed via internal/cli/cli.go.

Frequently Asked Questions

What happens if compact_force_ratio is set lower than compact_ratio?

This creates an inverted threshold where the hard limit triggers before the soft limit. The engine will skip the gentle trimming phase and immediately force aggressive compaction once the lower threshold is reached. While functional, this configuration eliminates the staged cleanup strategy and is generally discouraged.

How do these ratios interact with the model's actual token limit?

The ratios are multiplied against the model's configured maximum context window (e.g., 128,000 tokens). A compact_ratio of 0.8 translates to 102,400 tokens for a 128k model. The compaction logic monitors the current prompt length against these calculated fractional limits, ensuring proactive management before the absolute token boundary is reached.

Can I disable forced compaction by setting compact_force_ratio to 1.0?

Setting the ratio to 1.0 effectively disables the forced compaction trigger, as the prompt cannot exceed 100% of the context window. However, this removes the safety margin and risks hitting the model's hard token limit, which would cause an error. It is safer to retain a small buffer (e.g., 0.95) rather than disabling it entirely.

Where are the default values defined in the source code?

Default values are hardcoded in the AgentConfig struct within internal/config/config.go (approximately lines 1275-1278) and are rendered into human-readable output by internal/config/render.go (lines 230-238). The reasonix.example.toml file in the repository root provides a documented template showing these defaults for end-user configuration.

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