How Prefix Cache Optimization Works with the DeepSeek API in Reasonix

Reasonix leverages DeepSeek's byte-stable prefix cache to reuse hidden states for static system prompts and tool definitions, reducing billable tokens by only computing new message suffixes while keeping the prefix append-only.

The esengine/DeepSeek-Reasonix repository implements a conversational AI framework that exploits DeepSeek's automatic prefix matching to minimize redundant computation across turns. By treating system prompts and tool schemas as immutable prefixes, the library ensures that only new user messages trigger fresh forward passes, while static context remains cached at the provider level.

Understanding Byte-Stable Prefix Caching

DeepSeek's API implements a byte-stable prefix cache that stores hidden states for specific byte sequences. When a prompt's prefix bytes match a cached entry exactly, the model reuses the precomputed KV cache instead of recomputing attention weights for those tokens.

The Append-Only Guarantee

Reasonix maintains cache hits by ensuring the prefix remains append-only. Once the system prompt and tool definitions establish the initial byte sequence, subsequent turns append new messages without reordering or modifying existing content. This stability guarantees that the byte signature remains identical across API calls, triggering DeepSeek's cache hit mechanism.

Structuring the Provider Prefix

The library constructs a provider prefix that encompasses all static conversation metadata. According to the source code in internal/guardian/guardian.go, this includes the system prompt and prior transcript context that must "stay in the prefix cache" to maintain computational efficiency (view source).

Freezing System Prompts and Tool Definitions

As implemented in esengine/DeepSeek-Reasonix, tool registrations and system instructions become immutable components of the provider prefix. The following pattern demonstrates how static tool definitions integrate into the cached prefix:

// Register a static tool – its definition becomes part of the provider prefix
registry.Add(tool.NewBuiltin("todo", todoCmd))

// The session's provider prefix is built once and reused
session := reasonix.NewSession(opts...)
session.Start() // sends system prompt + tool definitions (cached)
session.SendUserMessage("Write a Go function…") // only the new user message is fresh

Per-Conversation Cache Scoping

The internal/memory/doc.go file explains that Reasonix "rides DeepSeek's automatic prefix cache at zero per-turn" by scoping cached content to individual conversation sessions (view source). Each session maintains its own isolated prefix state, preventing cross-contamination while maximizing reuse within long-running conversations.

Cache Invalidation Rules

The prefix cache persists only while the underlying byte sequence remains unchanged. Reasonix explicitly invalidates the cache when structural modifications occur.

Deliberate Changes That Reset the Cache

According to desktop/session_prompt.go, the system invalidates "the whole conversation's provider prefix cache" exclusively when detecting differing system prompts or provider configurations (view source). The following operation demonstrates a forced cache reset:

// Changing the system prompt forces a new prefix → cache miss
session.SetSystemPrompt("You are a helpful AI.") // triggers cache invalidation
session.SendUserMessage("Explain prefix caching.") // fresh computation for whole prompt

Routine Operations Preserving the Cache

Adding user messages, updating tool arguments within existing schemas, or generating intermediate plan steps does not modify the provider prefix. These operations append new tokens to the suffix while leaving the cached prefix bytes untouched, maintaining the 80–90% cache-hit rates observed in long sessions.

Detecting Cache Misses in Production

Reasonix provides visibility into cache performance through byte-level validation. The test suite in desktop/session_prompt_bytes_test.go confirms that modifying the system prompt produces a detectable cache miss by comparing byte sequences before and after the change (view source).

When cache misses occur, the library logs the event and rebinds the request bytes, allowing developers to track the performance impact of prompt modifications. The site/src/pages/docs.astro file documents this as the "Cache-first loop" feature, emphasizing zero-cost prefix reuse during standard conversational flows (view source).

Summary

• Byte-stable matching: DeepSeek's API identifies cached prefixes by exact byte sequence matching, not semantic similarity.
• Append-only architecture: Reasonix maintains cache validity by appending new messages without reordering static system prompts or tool definitions.
• Scoped invalidation: Only structural changes—system prompt edits, tool registration changes, or provider configuration updates—invalidate the cached prefix.
• Production visibility: The codebase includes testing utilities in desktop/session_prompt_bytes_test.go to verify cache behavior and detect misses during development.

Frequently Asked Questions

What triggers a prefix cache miss in Reasonix?

A cache miss occurs exclusively when the provider prefix bytes change, specifically through system prompt modifications, tool schema additions or removals, or provider configuration updates. Routine user message additions do not trigger misses because they append to rather than modify the existing prefix.

How much does prefix caching reduce API costs?

Reasonix achieves approximately 80–90% cache-hit rates during long conversational sessions by reusing hidden states for static prefixes. This optimization eliminates billable input tokens for cached portions of the prompt, significantly reducing costs for multi-turn interactions with complex system instructions.

Can I manually invalidate the prefix cache?

Yes, calling session.SetSystemPrompt() or modifying the tool registry explicitly invalidates the provider prefix cache, forcing fresh computation on the next API call. This behavior is implemented in desktop/session_prompt.go to ensure developers can trigger full recomputation when context requirements change.

Does adding user messages break the prefix cache?

No, adding user messages preserves the prefix cache because Reasonix appends these messages to the suffix of the prompt without modifying the static prefix bytes. The internal/guardian/guardian.go implementation ensures that user messages remain outside the cached prefix boundary while maintaining the append-only guarantee required for DeepSeek's optimization.

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