How Reasonix Performs Context Compaction and Memory Retrieval

Reasonix manages long conversations by automatically compressing historical messages into digests via context compaction while enriching responses with relevant past facts through BM25-powered memory retrieval.

The DeepSeek-Reasonix engine implements sophisticated context management to maintain extended reasoning sessions without exhausting token limits. By combining automated transcript summarization with semantic memory lookup, the system ensures relevant historical context remains accessible while preserving computational efficiency. Both mechanisms are wired directly into the core session controller and operate transparently during inference.

Context Compaction Mechanism

Reasonix prevents context window overflow by rewriting conversation history into compact summaries when token usage approaches configured thresholds.

Trigger Conditions and Configuration

Compaction activates automatically when a session’s token count nears the context_window limit defined in the provider configuration. The specific thresholds are controlled by config.Provider.Keep and config.Agent.CompactRatio parameters, which determine how much historical context to preserve versus summarize. These settings are defined in internal/config/render.go. Users can also invoke compaction manually through the compact CLI command, which immediately triggers the same rewrite process without waiting for the automatic threshold.

The Compaction Process

When triggered, the session controller calls the Compact method in internal/control/controller.go to execute a compaction pass. This process rewrites the session transcript by replacing older user and assistant exchanges with a digest that summarizes the work performed. The system inserts this digest as a <compaction-summary> tag formatted as a provider.RoleUser message, effectively compressing multiple turns into a single contextual block.

The compaction algorithm respects a keep policy that preserves critical messages—such as error states or user-marked items—ensuring essential context survives the summarization process. The implementation references beginRotation to manage the transition between full transcripts and compacted summaries.

Event Lifecycle and Persistence

The compaction workflow emits structured events defined in internal/event/event.go. CompactionStarted signals the beginning of the pass, while CompactionDone fires when the summary is ready, carrying payloads that include the trigger type, message count, and summary text. Tests in internal/eventwire/wire_test.go verify these payloads and validate summary length constraints.

After compaction completes, the rewritten transcript persists to disk via a standard snapshot operation. The original messages are discarded from the active inference context, immediately freeing token budget for continued reasoning while maintaining a concise record of prior interactions.

Memory Retrieval Architecture

Reasonix augments model responses with external knowledge through a dedicated memory subsystem that indexes and retrieves project-specific facts on demand.

Memory Store and Indexing

The system stores memory documents—such as project guidelines or user notes—within a memory.Set structure exposed to the runtime via internal/remote/workbench/runtime/catalog.go. Each document carries a type classification (e.g., project, global) and a body of free-form text.

To enable fast, relevance-based lookup, Reasonix indexes the memory set using a BM25 scorer implemented in internal/retrieval/bm25.go. This algorithm ranks saved agent history and memory documents by textual similarity, allowing the system to surface the most pertinent information without linear scanning.

Retrieval API and Citations

The remote protocol defines explicit methods for memory interaction, including memory/get, memory/suggestions, and memory/remember, registered in internal/remote/protocol/registry.go. When a tool invokes MethodMemoryGet, the controller queries the BM25 index and returns memory citations that can be injected into the active prompt context.

These citations manifest as MemoryCitation structs defined in internal/provider/provider.go. When a memory entry is utilized, the controller inserts the citation into the session context, allowing the model to reference prior facts without requiring the entire document to be re-prompted. The capabilities schema in internal/remote/protocol/schema.go defines the precise interface for these retrieval operations.

Privacy and Safety Controls

To prevent leakage of local knowledge to external services, Reasonix strips MemoryCitation fields from downstream LLM requests. The providers ignore this field during payload serialization to ensure privacy. This safety mechanism is enforced through test assertions in internal/provider/openai/openai_test.go and internal/provider/anthropic/anthropic_test.go, which verify that memoryCitations do not appear in the final API requests sent to OpenAI or Anthropic endpoints.

Practical Usage Examples

The following CLI interactions demonstrate how to trigger compaction and retrieve memory entries during an active Reasonix session.

To manually compact a conversation that has grown too large:

# From the Reasonix REPL

> compact
Compaction started...
Compaction done (summary inserted as <compaction-summary>).

This command invokes the controller’s Compact method, creating a <compaction-summary> block that replaces the historical transcript while preserving essential context.

To retrieve a specific memory entry using the BM25 index:

# In a Reasonix session

> /memory get "project goals"
{
  "type": "project",
  "body": "The project aims to provide a fast, locally‑run AI assistant."
}

This request hits the memory/get endpoint, which utilizes the BM25 scorer in internal/retrieval/bm25.go to locate the most relevant memory document matching the query.

Summary

• Automatic Triggering: Context compaction activates when token usage approaches the context_window threshold defined in internal/config/render.go, or manually via the compact command.
• Summarization Process: The Compact method in internal/control/controller.go rewrites transcripts into <compaction-summary> tags, emitting CompactionStarted and CompactionDone events during the operation.
• BM25 Retrieval: Memory documents are indexed using the BM25 algorithm in internal/retrieval/bm25.go, enabling fast lookup via memory/get and related RPC methods.
• Privacy Protection: Memory citations are automatically stripped from LLM requests before transmission, as verified in provider-specific test suites.

Frequently Asked Questions

What triggers automatic context compaction in Reasonix?

Automatic compaction triggers when the session’s token count approaches the configured context_window limit, specifically when it hits the ratio defined by config.Agent.CompactRatio. The system monitors usage continuously and initiates the compaction pass without user intervention to prevent context overflow.

How does Reasonix ensure memory citations don't leak to LLM providers?

The MemoryCitation struct is included in the internal session context but is explicitly excluded from the serialized request payload sent to external providers. Test files internal/provider/openai/openai_test.go and internal/provider/anthropic/anthropic_test.go assert that these citations are stripped before transmission, ensuring local knowledge remains private.

What indexing algorithm does Reasonix use for memory retrieval?

Reasonix implements BM25 scoring for memory retrieval, as defined in internal/retrieval/bm25.go. This probabilistic ranking function evaluates the relevance of memory documents to a given query term, enabling efficient retrieval from large memory sets without requiring vector embeddings.

Can users manually trigger context compaction during a session?

Yes, users can invoke the compact command from the Reasonix REPL at any time. This command calls the Compact method directly, immediately rewriting the session transcript into a summary digest regardless of the current token count, which is useful for forcing context cleanup before complex reasoning tasks.

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