# Understanding the Four Clear Layers of the Apache Maka Runtime System

> Explore the four clear layers of the Apache Maka runtime system: Runtime Event Log, SessionManager, Agent Graph, and Storage. Understand event sourcing, execution, coordination, and persistence.

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

---

**The Apache Maka runtime system is deliberately divided into four distinct layers—Runtime Event Log, SessionManager with AgentRun, Agent Graph, and Storage—that create an orchestration boundary separating event sourcing, execution lifecycle, workflow coordination, and state persistence.**

Apache Maka organizes its execution environment into a stable, layered architecture defined in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md). These four clear layers of the Apache Maka runtime system ensure that each component protects a distinct kind of stability while isolating the model loop from higher-level concerns.

## Layer 1: Runtime Event Log (The Canonical Event Source)

The **Runtime Event Log** serves as the single source of truth for all model messages, tool calls, tool results, and termination facts. According to the architecture documentation found at [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) lines 45-48, this layer records the full execution history immutably, while downstream processes like "context pruning" or "compaction" only modify the view, never the underlying truth.

### Implementation Details

In [`packages/runtime/src/RuntimeEventLog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/RuntimeEventLog.ts), the system implements this append-only log pattern. The log maintains every interaction in chronological order, enabling perfect replay and auditability of agent executions. Downstream layers consume this log to reconstruct state, but no layer can mutate historical events.

### Accessing the Runtime Event Log

```typescript
import { RuntimeEventLog } from '@maka/runtime';

// Retrieve the full log for a given run
async function getRunLog(runId: string) {
  const events = await RuntimeEventLog.fetch(runId);
  return events;
}

```

## Layer 2: SessionManager and AgentRun (Execution Lifecycle)

The **SessionManager** and **AgentRun** components own the execution lifecycle, including admissions, client capabilities, interactions, and the public protocol. As documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) line 46, this layer manages sessions, turns, and runs, providing the control plane for user interactions.

### Implementation Details

The [`packages/runtime/src/SessionManager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/SessionManager.ts) file implements session admission policies and lifecycle management. It coordinates between the user-facing API and the underlying execution engine, ensuring proper isolation between concurrent runs while maintaining client capability negotiations.

### Managing Sessions via SessionManager

```typescript
import { SessionManager } from '@maka/runtime';

// Start a new session and obtain its identifier
async function startSession(userId: string) {
  const session = await SessionManager.create({ owner: userId });
  return session.id;
}

```

## Layer 3: Agent Graph (Workflow Coordination)

The **Agent Graph** schedules dependent work by creating child sessions and feeds every activation back through the same Runtime Host. Located at [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) line 47, this layer provides the coordination plane for multi-agent workflows, enabling complex DAG-style execution patterns where agents depend on results from other agents.

### Implementation Details

Found in [`packages/runtime/src/AgentGraph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentGraph.ts), this layer maintains the execution graph structure. It handles the queuing of child sessions, dependency resolution between agents, and the routing of results back to parent contexts through the Runtime Host abstraction.

### Scheduling Work with the Agent Graph

```typescript
import { AgentGraph } from '@maka/runtime';

// Queue a child session that runs a tool
async function scheduleTool(sessionId: string, toolName: string) {
  const child = await AgentGraph.schedule({
    parentSession: sessionId,
    tool: toolName,
  });
  return child.id;
}

```

## Layer 4: Storage (Interactive State Persistence)

The **Storage** layer holds the interactive runtime state, typically using SQLite stores through [`packages/storage/src/SQLiteStore.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/SQLiteStore.ts). As specified in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) line 48, this layer deliberately does **not** contain evaluation-specific roots, task-run ledgers, or experiment result authority—it focuses strictly on operational runtime state.

### Implementation Details

This separation ensures that the runtime remains lightweight and ephemeral. The storage layer persists session context, checkpoint data, and temporary computation results, while long-term authoritative records remain in the Runtime Event Log or external evaluation frameworks.

### Persisting State in Storage

```typescript
import { Storage } from '@maka/storage';

// Store a simple key-value pair for the current run
async function storeState(runId: string, key: string, value: any) {
  await Storage.put(runId, { [key]: value });
}

```

## How the Layers Form an Orchestration Boundary

Together, these four layers create an "orchestration boundary" that isolates the model loop from higher-level concerns. The **Runtime Event Log** provides immutable history, the **SessionManager** controls execution admission, the **Agent Graph** coordinates multi-agent workflows, and **Storage** handles mutable operational state. This separation ensures that failures in one layer do not corrupt the others—particularly protecting the integrity of the event log from storage failures or graph scheduling errors.

## Summary

- **Runtime Event Log**: Immutable append-only record of all messages, tool calls, and results located in [`packages/runtime/src/RuntimeEventLog.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/RuntimeEventLog.ts)
- **SessionManager + AgentRun**: Lifecycle management and protocol handling implemented in [`packages/runtime/src/SessionManager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/SessionManager.ts)
- **Agent Graph**: Multi-agent workflow coordination and child session scheduling found in [`packages/runtime/src/AgentGraph.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentGraph.ts)
- **Storage**: Ephemeral runtime state persistence via [`packages/storage/src/SQLiteStore.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/SQLiteStore.ts), excluding evaluation authority

## Frequently Asked Questions

### How does the Runtime Event Log differ from the Storage layer?

The **Runtime Event Log** serves as the immutable source of truth for all execution history, while the **Storage** layer maintains mutable operational state. According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), context pruning only affects views of the log, never the log itself, whereas Storage actively manages temporary state that can be modified during execution.

### Can I interact with multiple layers simultaneously in Apache Maka?

Yes. Components typically coordinate across layers—for example, `SessionManager` creates entries in both the **Runtime Event Log** and **Storage** while the **Agent Graph** schedules work that updates both the log and child session states. However, the architecture enforces that the Event Log remains the authoritative source for historical facts.

### Why does the Storage layer exclude evaluation-specific data?

The **Storage** layer intentionally excludes evaluation roots and experiment results to maintain clear separation of concerns. As documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) line 48, this ensures the runtime focuses on operational state (like sessions and checkpoints) while evaluation frameworks handle their own persistence, preventing circular dependencies between execution and measurement systems.

### What happens if the Agent Graph fails during execution?

Because the **Agent Graph** exists as a distinct layer from the **Runtime Event Log**, failures in graph scheduling do not corrupt the execution history. The log maintains all previously completed tool calls and messages, allowing the system to reconstruct state from the log and potentially retry graph operations without losing execution context.