# Understanding SessionStore vs AgentRunStore vs RuntimeEventStore in Apache Maka

> Learn the differences between Apache Maka's SessionStore AgentRunStore and RuntimeEventStore. Understand their roles in session state model execution and runtime telemetry for reliable recovery and debugging.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-26

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/run-composition.ts)) writes to this store through the `DurableAgentRunStore` implementation located in [`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts). The schema definitions also appear in [`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

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

```

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

```

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.