# How Reasonix Performs Context Compaction and Memory Retrieval

> Discover how Reasonix achieves context compaction and memory retrieval to manage long conversations by summarizing past messages and enriching responses with relevant facts.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: internals
- Published: 2026-08-05

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/openai_test.go) and [`internal/provider/anthropic/anthropic_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash

# 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:

```bash

# 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/render.go), or manually via the `compact` command.
- **Summarization Process**: The `Compact` method in [`internal/control/controller.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/openai_test.go) and [`internal/provider/anthropic/anthropic_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.