How Context Engine v2 Manages Memory Retrieval and Compaction in Reasonix

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, 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 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 (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. 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 – Houses the session controller, memory loading logic, and the Compact method.
• internal/projectiondb/projectiondb.go – Manages the in-memory SQLite connection and fallback mechanisms (lines 28–63).
• internal/migration/migration.go – Handles legacy memory imports into the projection format.
• internal/sessioncatalog/catalog.go – Determines whether a session runs in memory-only mode.
• internal/taskmonitor/memory.go – Provides the in-memory store used by the compaction ticker.

Practical Code Examples

Retrieving a Memory Citation

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

// 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, AGENTS.md, memory/*.md) hydrate the projection at session startup via 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).
• 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, 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 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.

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