# How the Reasonix History Tool Provides BM25 Retrieval Over Past Sessions

> Discover how the Reasonix history tool leverages BM25 retrieval to access past sessions efficiently, persisting and indexing conversations for quick context surfacing without full reloads.

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

---

**The Reasonix history tool implements BM25 retrieval across chat sessions by persisting conversations as JSONL files, indexing them with the BM2S (Back-Memory-to-Session) engine, and surfacing relevant historical context without reloading full runtime states.**

The esengine/DeepSeek-Reasonix desktop application maintains a sophisticated history subsystem that enables users to retrieve semantically relevant interactions from any previous session. By combining disk-efficient serialization with lightweight indexing in [`desktop/memory_suggestions.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/memory_suggestions.go), the tool delivers BM25-style search capabilities while keeping the UI responsive.

## Persisting Sessions as JSONL for Cross-Session Retrieval

Cross-session BM25 retrieval begins with durable persistence. In [`desktop/sessions.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/sessions.go), the `Session.Save` method writes every conversation turn—including user messages, assistant responses, tool calls, and UI events—as individual JSON lines to a per-tab session file.

```go
// desktop/sessions.go
func (s *Session) Save(path string) error {
    // Writes each Message as a JSON line – user, assistant, tool calls, UI events, etc.
}

```

Each tab maintains its own `*.jsonl` file registered in the tab management system, creating a chronological archive that the BM2S retriever can scan independently of active runtimes.

## Loading History Without Runtime Overhead

To display history without the cost of resuming a full session, Reasonix uses `previewSessionMessages` implemented in [`desktop/history.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/history.go) and tested in [`desktop/history_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/history_test.go). This function performs a disk-only load that decodes JSONL entries into `HistoryMessage` objects without initializing a controller.

```go
// desktop/history_test.go – test helper
func previewSessionMessages(dir, path string) ([]HistoryMessage, error) {
    // Opens the JSONL file, decodes each line into a HistoryMessage,
    // and returns the slice. No controller is started.
}

```

This approach parses both conversation messages and UI events—such as planner phases and notices—ensuring the history view accurately reflects past visual states while remaining decoupled from live execution contexts.

## Archiving Payloads for Efficient BM25 Indexing

Before indexing occurs, the `historyMessages` function in [`desktop/history.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/history.go) normalizes raw session data to prevent bloated indexes. The routine implements aggressive archiving strategies for large payloads that would otherwise degrade BM25 retrieval performance.

**Large tool arguments** are flagged with `ArgumentsArchived = true`, dropping raw strings in favor of concise `Subject` and `Summary` fields. Similarly, **tool outputs** exceeding size thresholds receive `ToolResultArchived` markers according to the source code. Error messages undergo bounded truncation via `maxErrorPreview` to respect UTF-8 boundaries while preserving readable snippets.

The function also preserves critical metadata for retrieval quality, copying `MemoryCitations`, `CheckpointTurn`, and planner phase information into the indexed representation. This ensures BM25 results contain sufficient context for relevance ranking while maintaining lightweight transfer to the UI.

## The BM2S Retrieval Engine Implementation

The core BM25 retrieval capability resides in [`desktop/memory_suggestions.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/memory_suggestions.go), where the `memorySuggestions` function implements the Back-Memory-to-Session algorithm. This engine enables cross-session semantic search without requiring active tab contexts.

The retrieval process follows four distinct stages:

1. **Directory Scanning**: The engine enumerates all `*.jsonl` files across the session directory, including archived tabs and closed sessions.
2. **Metadata Indexing**: Each message receives a `MessageMeta` record containing session ID, turn index, and content fingerprints for BM25-style term frequency analysis.
3. **Query Matching**: Incoming queries match against indexed metadata using high-performance substring search or vector-store lookup, depending on the configured retrieval mode.
4. **Result Hydration**: Matching `HistoryMessage` objects are reconstructed from disk, excluding archived heavy payloads to ensure sub-millisecond response times.

Because large tool data remains archived on disk, the BM2S engine can safely query arbitrary historical sessions without causing UI latency or memory pressure.

## Exposing BM25 Results Through the UI Layer

The `HistoryForTab` method in [`desktop/app.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/app.go) serves as the orchestration layer between the BM2S retrieval engine and the frontend. When a user requests history, this function coordinates multiple data sources:

```go
// desktop/app.go (excerpt)
func (app *App) HistoryForTab(tabID string) []HistoryMessage {
    tab := app.tabs[tabID]
    // 1️⃣ Load the pinned session file if the controller isn’t ready yet.
    // 2️⃣ Call previewSessionMessages to get a raw slice.
    // 3️⃣ Run historyMessages to archive large payloads.
    // 4️⃣ Append any in‑memory planner phases/events stored in the tab struct.
    // 5️⃣ Return the final slice for the UI.
}

```

When the user provides a search term, the backend handler in [`desktop/handlers.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/handlers.go) invokes `memorySuggestions(query)` to execute BM25 retrieval across all session files, merging cross-session matches into the tab’s history view. The HTTP endpoint `GET /api/history` serializes results for the frontend, delivering role, content, reasoning chains, and archived payload references as a unified JSON response.

## Summary

- **Session Persistence**: Reasonix stores all interactions as JSONL files in [`desktop/sessions.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/sessions.go), creating a durable corpus for BM25 retrieval over past sessions.
- **Zero-Runtime Loading**: The `previewSessionMessages` function enables fast history access without resuming session controllers.
- **Intelligent Archiving**: `historyMessages` in [`desktop/history.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/history.go) prunes large payloads while preserving metadata essential for relevance ranking.
- **BM2S Engine**: `memorySuggestions` implements the BM25 retrieval algorithm across sessions by indexing `MessageMeta` records and matching queries against historical content.
- **UI Integration**: `HistoryForTab` combines live session data with BM2S search results through the `/api/history` endpoint defined in [`desktop/handlers.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/handlers.go).

## Frequently Asked Questions

### What is BM2S in the context of Reasonix history retrieval?

BM2S stands for **Back-Memory-to-Session**, the subsystem that implements BM25 retrieval across past conversation sessions. According to the esengine/DeepSeek-Reasonix source code, it indexes archived JSONL session files and surfaces relevant historical messages when the user searches their history or when the system needs to augment current context with past interactions.

### How does Reasonix prevent history retrieval from slowing down the UI?

The system employs aggressive payload archiving in [`desktop/history.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/history.go) to strip large tool arguments and outputs before they reach the indexing stage. By marking heavy content with `ArgumentsArchived` and `ToolResultArchived` flags, the BM2S engine indexes only lightweight metadata while keeping full payloads accessible on disk for on-demand fetching.

### Can Reasonix retrieve history from sessions that are no longer open?

Yes. Because `memorySuggestions` scans the entire session directory for all `*.jsonl` files—not just active tabs—it can perform BM25 retrieval across closed, archived, or previously deleted tabs that remain on disk. This enables truly cross-session memory without requiring tabs to remain loaded in memory.

### What distinguishes BM2S from standard BM25 implementations?

While traditional BM25 operates on static document collections, BM2S in [`desktop/memory_suggestions.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/memory_suggestions.go) extends the algorithm to streaming conversation data by treating each session file as a dynamic document corpus. It adds conversation-specific metadata such as `CheckpointTurn` and `MemoryCitations` to standard term frequency ranking, enabling contextual retrieval that understands dialogue structure and AI reasoning chains.