Understanding SessionStore vs AgentRunStore vs RuntimeEventStore in Apache Maka

Apache Maka implements three distinct durable stores—SessionStore for client-observable session state, AgentRunStore for model-execution compositions, and RuntimeEventStore for low-level runtime telemetry—each owned by different architectural modules to ensure reliable recovery and debugging.

Apache Maka separates durability concerns across three specialized storage abstractions within the Runtime Host architecture. These distinct stores provide the single source of truth for client continuity, model execution, and runtime diagnostics, allowing the system to recover exact states across process restarts.

SessionStore: Client-Facing Session Continuity

The SessionStore persists the immutable snapshot of a Session, including the conversation transcript, workspace metadata, and any live updates. According to the architecture documentation, "Durable Stores are the recovery source of truth" and this particular store enables the Session Continuity component to rebuild canonical state for clients.

Ownership: The SessionContinuityCoordinator class in packages/runtime/src/server/session-continuity-coordinator.ts owns this store. The architecture doc emphasizes that "Session Continuity owns Client observation" and uses this store to manage what exposed state clients receive.

Usage Pattern: Every time a client subscribes to a Session, the host rebuilds the canonical state from the SessionStore and streams size-limited live events. The coordinator exposes this through methods like openSubscription(sessionId), which returns the snapshot and sequence information needed to resume observation.

AgentRunStore: Model-Facing Run Composition

The AgentRunStore holds the durable execution record for a single Run (the execution of a Turn). It stores the immutable Run Composition—comprising the prompt, tool catalog, and provider options—along with the ordered AgentRun event stream that records every model-call and tool-output.

Ownership and Implementation: The RunComposer module (defined in packages/core/src/run-composition.ts) writes to this store through the DurableAgentRunStore implementation located in packages/storage/src/agent-run-store.ts. The schema definitions also appear in packages/storage/src/sqlite-runtime-store.ts.

Commit Process: Before the provider is called, the Run Composer commits the composition to the AgentRunStore (see step 2 in the architecture description at docs/architecture/runtime-host-architecture.md). This store serves as the single durable authority for "what happened in this run," capturing the high-level execution narrative distinct from low-level runtime noise.

RuntimeEventStore: Low-Level Execution Telemetry

The RuntimeEventStore records fine-grained runtime activities—model-call attempts, tool-result emissions, and intermediate events—that are not part of the high-level Run composition but are essential for exact replay and debugging. Unlike the structured AgentRun events, these telemetry entries capture the granular execution reality.

Ownership and Access: This store is exposed through packages/runtime/src/tool-output.ts and related runtime modules. It reads from the same underlying SQLite storage used by DurableAgentRunStore but provides a filtered view specific to runtime-only events. The implementation is also referenced in packages/runtime/src/tool-result-archive.ts.

Event Recording: When a Run is admitted, the Runtime writes each event via RuntimeEventStore.appendEvent(...). On recovery, the host "rereads durable facts" from this store to reconstruct the final execution state. This separation allows developers to debug provider interactions and tool executions without polluting the client-facing session state or the model’s run composition.

Practical Usage Examples

The following patterns demonstrate how to interact with each store according to the Apache Maka source code:

// 1️⃣ SessionStore – opening a Session subscription
import { SessionContinuityCoordinator } from '@maka/runtime-host';
const continuity = new SessionContinuityCoordinator(/* … */);
const { snapshot, nextSeq } = await continuity.openSubscription(sessionId);
// `snapshot` is rebuilt from the Session Store

// 2️⃣ AgentRunStore – committing a Run composition before provider dispatch
import { createSqliteAgentRunStore } from '@maka/storage';
import { RunComposer } from '@maka/core';
const runStore = createSqliteAgentRunStore(workspaceRoot);
const composer = new RunComposer(/* … */);
const runHeader = await composer.commit(runStore);   // persists to AgentRun Store

// 3️⃣ RuntimeEventStore – appending a model-call event
import { RuntimeEventStore } from '@maka/runtime';
const runtimeEvents = new RuntimeEventStore(runStore);
await runtimeEvents.appendEvent({
  type: 'modelCall',
  payload: { model: 'gpt-4', prompt: '…' },
  runId: runHeader.runId,
});

Summary

• SessionStore persists what the client sees—the Session state and live stream—owned by the SessionContinuityCoordinator.
• AgentRunStore persists what the model sees—the Run composition and ordered execution events—committed by the RunComposer before provider dispatch.
• RuntimeEventStore captures low-level runtime telemetry for replay and diagnostics, accessed through the runtime module's event API.
• All three stores serve as the recovery source of truth, enabling the Runtime Host to resume exact states after crashes or restarts.

Frequently Asked Questions

Which store contains the conversation history visible to the end user?

The SessionStore contains the client-visible conversation transcript and workspace metadata. When a user reconnects, the SessionContinuityCoordinator rebuilds the canonical state from this store in packages/runtime/src/server/session-continuity-coordinator.ts and streams the relevant events to the client interface.

When exactly does data get written to the AgentRunStore during execution?

The Run Composer commits the Run composition to the AgentRunStore immediately before the provider is called, as documented in step 2 of the Runtime Host architecture. This occurs in packages/core/src/run-composition.ts via the commit() method, ensuring the prompt, tool catalog, and provider options are durably persisted before any model interaction begins.

How does RuntimeEventStore differ from the event stream in AgentRunStore?

While the AgentRunStore maintains an ordered stream of high-level AgentRun events representing the logical execution of a Turn, the RuntimeEventStore captures fine-grained implementation details like individual model-call attempts and tool-result emissions. The RuntimeEventStore provides a filtered view of the underlying storage for debugging, whereas the AgentRunStore provides the authoritative "what happened" narrative for the Run.

Can these stores survive unexpected process crashes?

Yes, all three stores are durable by design. The architecture documentation specifies that "Durable Stores are the recovery source of truth." On restart, the Runtime Host rereads facts from these stores—specifically recovering session state from the SessionStore, run context from the AgentRunStore, and runtime telemetry from the RuntimeEventStore—to reconstruct the exact pre-crash execution state.

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