How Reasonix's Cache-Aware Context Maintenance Works: DeepSeek Prefix Caching Explained

Reasonix achieves >90% cache-hit rates and reduces token billing to roughly one-fifth of naive costs by maintaining a byte-stable system-prompt prefix constructed from immutable standing instructions, tool schemas, and memory blocks, while treating all mutable data as append-only turn tails that do not invalidate the cached prefix.

Reasonix is an open-source coding agent built on DeepSeek's LLM that implements sophisticated cache-aware context maintenance to optimize long-running AI sessions. According to the esengine/DeepSeek-Reasonix source code, the system exploits DeepSeek's automatic prefix cache by ensuring the initial bytes of every request remain identical across turns. This architectural decision allows the LLM provider to reuse cached prefix computations, dramatically reducing latency and token costs for extended coding workflows.

The Byte-Stable Prefix Architecture

The foundation of Reasonix's cache-aware context maintenance lies in constructing a byte-stable prefix that DeepSeek's infrastructure can cache and reuse across multiple turns. This prefix comprises three immutable components that are never mutated mid-session.

Core Components of the Immutable Prefix

Component	Source Location	Stability Guarantee
Base prompt	REASONIX.md and standing instruction files	Loaded once at boot, never changed during session
Tool schema	internal/tool package	Generated and injected during initial composition
Memory block	internal/memory/Set (memory.go)	Folded into prompt once per turn via Compose, but base prompt remains unchanged

DeepSeek's automatic prefix cache recognizes the exact byte sequence of this combined prefix, allowing subsequent requests to skip recomputation and billing only for the new tail content.

The Compose Function Implementation

In internal/memory/memory.go, the Compose function constructs this cache-stable prefix by concatenating the base system prompt with the memory block:

// Compose folds the memory block onto the base system prompt …
func Compose(base string, s *Set) string {
    block := s.Block()
    if block == "" {
        return base
    }
    if strings.TrimSpace(base) == "" {
        return block
    }
    return strings.TrimRight(base, "\n") + "\n\n" + block
}

The returned string serves as the cache-stable prefix that remains constant across all turns in a session.

Keeping the Prefix Cache Warm

Reasonix employs a disciplined protocol to ensure the prefix cache remains warm throughout long-running sessions, minimizing cold-start penalties and token costs.

Session Initialization and Memory Loading

At program startup, memory.Load discovers all standing-instruction files and the auto-memory index, producing a memory.Set:

mem := memory.Load(memory.Options{CWD: "."})

This operation reads version-controlled files like REASONIX.md and AGENTS.md, ensuring that restarting the agent reloads identical bytes, automatically warming the cache again.

Append-Only Turn Tails

For each user interaction, the controller appends only the new user message after the cached prefix. The controller.Compose method (referenced in internal/control/controller.go) handles this append-only operation, ensuring no modifications occur to the prefix bytes that DeepSeek has cached.

Queuing Mutable Changes Without Cache Invalidation

When documents are edited via memory.Set.WriteDoc or new facts are remembered, Reasonix saves changes to disk without touching the active prefix. These edits are queued as turn-tail notes and incorporated only when the next session starts, as implemented in the memory management logic. This design prevents mid-session cache invalidation while ensuring persistence across restarts.

When the Prefix Cache Invalidates

The architecture deliberately breaks the cache only in controlled scenarios to maintain predictable performance characteristics.

System-Prompt Upgrades: Changing REASONIX.md or any standing-instruction file alters the base bytes, forcing DeepSeek to treat the next request as a cold start.

Provider Configuration Changes: Switching models or altering provider-level settings triggers cache reset logic in desktop/session_prompt.go, where the controller logs a warning and resets the cache state.

Explicit Invalidation: Direct mutations to the prefix through deliberate API calls (detected in session_prompt.go) cause subsequent turns to miss the cache and incur normal billing rates.

CI pipelines enforce this discipline through cache-impact labels, ensuring ordinary code changes do not unintentionally modify standing instruction files.

Cache-Aware Compaction Strategy

Reasonix implements cache-aware compaction (documented in docs/research/cache-aware-compaction-design.md) to manage long-running sessions without losing cache benefits. This strategy periodically compacts session history by removing stale or duplicated tail content while preserving the immutable prefix. The compaction algorithm ensures that even after hours of conversation, the cached prefix remains valid and warm.

Complete Implementation Example

The following example demonstrates building a prompt with a warm prefix using Reasonix's internal packages:

package main

import (
    "fmt"
    "reasonix/internal/memory"
    "reasonix/internal/control"
)

func main() {
    // Load the immutable memory set (docs, global guidance, auto-memory)
    mem := memory.Load(memory.Options{CWD: "."})

    // Base system prompt – normally read from REASONIX.md
    base := "You are a helpful coding assistant."

    // Compose the prefix (base + memory block). This is the cached prefix.
    prefix := memory.Compose(base, mem)

    // Create a controller that will use this prefix for each turn
    ctrl := control.NewController(prefix)

    // Simulate a user turn
    userInput := "Explain how the prefix cache works."
    fullPrompt := ctrl.Compose(userInput) // returns prefix + userInput

    fmt.Println(fullPrompt)
}

Key implementation details illustrated:

• memory.Load discovers standing docs from the cache-stable file set
• memory.Compose builds the immutable prefix that DeepSeek caches
• controller.Compose appends new turn content after the cached region
• Document edits via mem.WriteDoc persist to disk without affecting the current prefix until the next session reload

Summary

• Byte-stable prefixes: Reasonix constructs immutable system prompts from REASONIX.md, tool schemas, and memory blocks in internal/memory/memory.go to create cacheable byte sequences.
• Append-only architecture: The controller adds only new user messages as turn tails, leaving the cached prefix untouched across turns for >90% cache-hit rates.
• Deferred mutation: Changes to documents or memory via Set.WriteDoc are queued to disk and incorporated only at session restart, preventing mid-session cache invalidation.
• Controlled invalidation: Cache breaks occur only during system-prompt upgrades, provider configuration changes, or explicit invalidation paths in desktop/session_prompt.go.
• Compaction support: Cache-aware compaction removes stale tail content while preserving the immutable prefix, maintaining cache warmth during long-running sessions.

Frequently Asked Questions

How does Reasonix achieve >90% cache-hit rates with DeepSeek?

Reasonix achieves high cache-hit rates by ensuring the initial bytes of every LLM request remain identical across turns. The system constructs a byte-stable prefix from immutable standing instructions (REASONIX.md), tool schemas, and memory blocks that DeepSeek's infrastructure caches automatically. By appending only new user inputs as mutable tails and never modifying the prefix mid-session, subsequent turns reuse the cached computation, resulting in cache-hit rates exceeding 90% and reducing token costs to approximately one-fifth of naive implementations.

What happens when I edit a document during an active Reasonix session?

When you edit a document using memory.Set.WriteDoc, Reasonix saves the change to disk immediately but does not modify the active prefix currently held in memory. The edit is treated as a queued note that will be incorporated into the prefix only when the next session starts and memory.Load re-reads the standing instruction files. This design ensures that mid-session edits do not invalidate the warm prefix cache, maintaining optimal performance during your current coding workflow.

Which files control the immutable prefix in Reasonix?

The immutable prefix is controlled by standing instruction files stored in the project root, primarily REASONIX.md and AGENTS.md, along with the auto-memory index managed by internal/memory/memory.go. The tool schema definitions from the internal/tool package are also folded into this prefix during initial composition. These files are version-controlled and loaded once at boot time via memory.Load, ensuring byte-stable prefixes that survive session restarts and maximize cache reuse.

When does Reasonix intentionally break the prefix cache?

Reasonix invalidates the prefix cache only in three controlled scenarios: when standing instruction files like REASONIX.md are modified (system-prompt upgrades), when provider configuration changes such as model switching occur (handled in desktop/session_prompt.go), or through explicit invalidation API calls. The codebase includes CI checks with cache-impact labels to prevent unintentional prefix modifications during ordinary development, ensuring cache stability remains predictable.

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