# How DeepSeek-Reasonix Maintains 90%+ Prefix Cache Efficiency: 3 Architectural Patterns

> Discover how DeepSeek-Reasonix achieves 90%+ prefix cache efficiency through immutable prefixes, isolated sessions, and strategic context compaction. Reduce token costs significantly.

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

---

**DeepSeek-Reasonix achieves over 90% prefix cache hit rates by enforcing immutable conversation prefixes, isolating planner and executor sessions, and strategically compacting context only at cache-reset points, reducing token costs to roughly one-fifth of standard requests.**

DeepSeek-Reasonix is an open-source agent framework designed to exploit the *byte-stable prefix cache* exposed by DeepSeek models. By ensuring that prompt prefixes remain identical across conversation turns, the system allows the model to reuse cached token embeddings rather than reprocessing the entire context. This article examines the specific mechanisms implemented in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) and [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go) that preserve this efficiency.

## The Byte-Stable Prefix Cache Foundation

DeepSeek models expose a **byte-stable prefix cache** that stores token embeddings for the initial portion of a prompt. When this prefix remains unchanged between turns, the model reuses cached computations rather than reprocessing the full context. According to the implementation details in `site/src/pages/index.astro`, this optimization reduces per-turn input token costs to approximately 20% of what a naive request that rebuilds the full context each time would incur.

## Three Mechanisms That Preserve Prefix Cache Efficiency

### 1. Append-Only, Cache-First Conversation Loop

The framework maintains prefix stability through an immutable transcript design. In [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go), the `Session` struct implements an append-only history slice that never mutates at the front:

```go
// internal/agent/agent.go (simplified)
type Session struct {
    history []Message // never mutated at the front
}

func (s *Session) Append(msg Message) {
    s.history = append(s.history, msg) // prepend-only → cache-friendly
}

```

Because `history` is only ever appended to, the model's prefix never shifts, preserving the cache validity across conversation turns.

### 2. Isolated Sessions for Planner and Executor

When operating in **two-model collaboration** mode, Reasonix prevents cache pollution by running the low-frequency planner and high-frequency executor in separate `Session` instances. The `Coordinator.Run` method in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) explicitly implements this separation:

```go
// internal/agent/coordinator.go (excerpt)
// The planner and executor each own a Session, guaranteeing
// that their prefix caches stay stable across turns.
func (c *Coordinator) Run(ctx context.Context, input string) error {
    // Planner runs in its own session
    planner := NewAgentSession(c.plannerModel, c.plannerConfig) // prefix-cache-stable
    plan, err := planner.Run(ctx, input)

    // Executor runs in a separate session, never mixing histories
    executor := NewAgentSession(c.execModel, c.execConfig) // prefix-cache-stable
    return executor.Run(ctx, plan)
}

```

The comment `// prefix-cache-stable` on line 44 explicitly documents this architectural intent, ensuring that each model's prefix cache stays warm and is never contaminated by the other model's conversation history.

### 3. Low-Frequency Context Compaction

As specified in [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md), Reasonix implements **strategic context compaction** when a model's token usage approaches its `context_window` limit. Rather than truncating arbitrary portions of the conversation, the system folds only assistant-side tool-call messages while preserving all user turns verbatim. Because this compaction aligns with deliberate *cache-reset points*—rare, intentional prefix changes—the system maintains cache hit rates above 90% even during long coding sessions.

## Configuration and Implementation Examples

To enable the two-model collaboration that keeps prefix caches stable, configure separate models in your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml):

```toml

# reasonix.toml – keep the planner's prefix cache warm

[agent]

# Planner runs on a different model, in its own session

planner_model = "deepseek-pro"        # ← separate model

planner_max_steps = 10                # low-frequency planning only

# Executor (default) continues the main session

max_steps = 0                         # unlimited for the executor

```

This configuration ensures that the planner's low-frequency operations do not pollute the executor's high-frequency cache, as each operates within its own isolated session context.

## Summary

- **Append-only history**: The `Session.Append` method in [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go) guarantees that conversation prefixes never shift, enabling cache reuse.
- **Session isolation**: [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) runs planner and executor in separate `NewAgentSession` instances, preventing cross-contamination of cached prefixes.
- **Strategic compaction**: Context management folds only assistant messages while preserving user turns, aligning compaction with rare cache-reset points to maintain 90%+ hit rates.
- **Cost reduction**: These mechanisms collectively reduce input token costs to roughly one-fifth of naive request patterns.

## Frequently Asked Questions

### What is a byte-stable prefix cache in DeepSeek models?

A **byte-stable prefix cache** is a feature of DeepSeek models that stores token embeddings for the initial portion of a prompt. When the bytes in the prefix remain identical across requests, the model can skip recomputing these embeddings and reuse the cached values, significantly reducing latency and token costs.

### How does the append-only pattern affect cache performance?

The append-only pattern ensures that the initial portion of the conversation transcript—the prefix—never changes. By restricting mutations to the end of the history slice in [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go), DeepSeek-Reasonix guarantees that the model sees the same prefix bytes on every turn, allowing the byte-stable cache to remain valid and achieve hit rates above 90%.

### Why does Reasonix use separate sessions for planner and executor?

Separate sessions prevent **cache pollution** between models with different conversation frequencies. The planner runs infrequently on complex reasoning tasks, while the executor runs frequently on coding tasks. By isolating them in distinct `Session` instances via `NewAgentSession` in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go), each model maintains its own warm prefix cache without interference from the other's message history.

### What happens when the context window fills up?

When token usage approaches the `context_window` limit, Reasonix performs a **low-frequency compaction** that folds only assistant-side tool-call messages while preserving user turns verbatim. As documented in [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/SPEC.md), this compaction occurs at deliberate cache-reset points, ensuring that the prefix cache remains stable for the vast majority of turns and maintains high efficiency even during extended sessions.