How the Reasonix History Tool Provides BM25 Retrieval Over Past Sessions

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, 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, 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.

// 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 and tested in desktop/history_test.go. This function performs a disk-only load that decodes JSONL entries into HistoryMessage objects without initializing a controller.

// 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 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, 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 serves as the orchestration layer between the BM2S retrieval engine and the frontend. When a user requests history, this function coordinates multiple data sources:

// 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 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, 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 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.

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 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 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.

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