# How Context Engine v2 Manages Memory Retrieval and Compaction in Reasonix

> Discover how Reasonix v2's context engine optimizes memory retrieval and compaction using an in-memory SQLite database and efficient state persistence. Learn more.

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

---

**Reasonix v2’s context engine leverages an in-memory SQLite projection database for O(log n) memory retrieval and executes a compaction routine via `ctrl.Compact()` that serializes, deduplicates, and atomically persists session state to durable storage.**

The DeepSeek-Reasonix repository implements a high-performance context management system where the **context engine v2** maintains conversational memory through a hybrid storage model. This architecture separates hot in-memory queries from cold durable storage, ensuring rapid context retrieval while keeping the long-term knowledge base compact and consistent.

## Architecture of the Context Engine v2

### In-Memory SQLite Projection

The engine instantiates a **projection database** using an in-process SQLite connection configured with `file:reasonix-…?mode=memory&cache=shared`. This allows the session to operate entirely in RAM, eliminating filesystem I/O during active queries.

### Durable Memory Hierarchy

Persistent knowledge resides in Markdown files such as [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md), and user-defined `*.md` documents under the `memory/` directory. These files represent the durable layer that hydrates the in-memory projection at session startup.

## Memory Retrieval Workflow

### Loading Durable Memory at Session Start

During initialization, the engine walks the `memory/` hierarchy, parses each file into **MemoryCitation** records, and inserts them into the in-memory SQLite projection. This logic resides in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) around line 800, where the session controller populates the projection database before serving any queries.

### Querying the Projection

All subsequent context-fetch operations—such as `ReadMemory` and `FindMemory`—execute SQL SELECT statements against the shared in-memory connection. This guarantees **O(log n)** lookup performance without touching the filesystem.

### Fallback to Memory-Only Mode

If the cache directory is unavailable or read-only, the engine silently switches to a pure memory-only mode. As implemented in [`internal/projectiondb/projectiondb.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/projectiondb/projectiondb.go) (lines 28–63), the connection string explicitly sets `mode=memory`, ensuring the session continues operating even on network-mounted or restricted volumes.

## Memory Compaction Strategy

### The Compact Method

When a session ends, the controller invokes `ctrl.Compact()` defined in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go). This method serializes the current in-memory projection to a temporary SQLite file on disk, preparing it for long-term storage.

### Deduplication and Expiration

During compaction, the engine merges duplicate citations and discards expired entries. This process, coordinated between the `sessioncatalog` and `projectiondb` packages, shrinks the database size and updates the shared-cache flags to maintain consistency.

### Atomic Persistence

The compacted snapshot is written atomically to the session’s `memory/` directory, replacing the previous durable state. Because compaction operates on an in-memory buffer until the final write, a crash before completion cannot corrupt the existing durable memory files.

## Key Implementation Files

- [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) – Houses the session controller, memory loading logic, and the `Compact` method.
- [`internal/projectiondb/projectiondb.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/projectiondb/projectiondb.go) – Manages the in-memory SQLite connection and fallback mechanisms (lines 28–63).
- [`internal/migration/migration.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/migration/migration.go) – Handles legacy memory imports into the projection format.
- [`internal/sessioncatalog/catalog.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/sessioncatalog/catalog.go) – Determines whether a session runs in memory-only mode.
- [`internal/taskmonitor/memory.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/taskmonitor/memory.go) – Provides the in-memory store used by the compaction ticker.

## Practical Code Examples

### Retrieving a Memory Citation

```go
// ctx represents an active Reasonix session; projID is the current project identifier.
mem, err := ctx.MemoryStore.ReadMemory(ctx, projID, "user.md")
if err != nil {
    log.Fatal(err)
}
fmt.Println("Retrieved content:", mem.Content)

```

This call executes a SELECT against the in-memory projection populated at session start.

### Compacting a Finished Session

```go
// ctrl is the session controller obtained from the running session.
if err := ctrl.Compact(); err != nil {
    log.Fatalf("Compaction failed: %v", err)
}
fmt.Println("Session compacted and persisted to disk")

```

The `Compact` operation writes the in-memory state to a temporary file and atomically replaces the previous snapshot in the `memory/` directory.

## Summary

- **Context Engine v2** uses an in-memory SQLite projection database for sub-millisecond memory retrieval.
- Durable memory files ([`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md), `memory/*.md`) hydrate the projection at session startup via [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go).
- Queries run against the in-memory SQLite connection, falling back to pure memory mode if the cache is unavailable ([`internal/projectiondb/projectiondb.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/projectiondb/projectiondb.go)).
- The `ctrl.Compact()` method serializes, deduplicates, and atomically persists the session state to disk on close.
- Compaction operates in-memory until the final write, preventing corruption of durable storage during crashes.

## Frequently Asked Questions

### What storage backend does Reasonix Context Engine v2 use?

Reasonix v2 uses an in-process **SQLite** database running in memory mode (`mode=memory`) as its primary projection layer, while durable knowledge persists as Markdown files on disk.

### How does Reasonix handle memory queries if the cache directory is unavailable?

The engine automatically falls back to an **in-memory-only** connection string configured in [`internal/projectiondb/projectiondb.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/projectiondb/projectiondb.go), allowing the session to continue without filesystem cache access.

### What happens during the compaction process in Reasonix?

The `ctrl.Compact()` method in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/serve.go) serializes the in-memory projection, merges duplicate **MemoryCitation** records, removes expired entries, and writes the optimized snapshot to the `memory/` directory.

### Where does Reasonix store the compacted memory snapshots?

Compacted snapshots are persisted to the session’s `memory/` directory as optimized SQLite files, which serve as the durable layer for subsequent session initializations.