Understanding Apache Maka Architecture Layers: A Deep Dive into the Runtime Stack

Apache Maka organizes execution through a single Runtime Host that coordinates four distinct architectural layers—Runtime Event Log, SessionManager & AgentRun, Agent Graph, and Storage—to provide immutable history, lifecycle management, work scheduling, and state persistence.

Apache Maka is an open-source framework designed for orchestrating AI agent execution with strict observability and reproducibility. Understanding its Apache Maka architecture layers is essential for developers extending the system or debugging complex agent interactions. The codebase implements a clear separation of concerns through distinct runtime layers that operate beneath a unified Runtime Host authority.

The Runtime Host: Central Execution Authority

According to the ARCHITECTURE.md specification, all execution flows through the Runtime Host, which serves as the system's sole execution authority. Whether accessed via Desktop, TUI, CLI, or automated bots, every client submits work requests to this central authority. The Runtime Host governs admission control, client capabilities, permission handling, and the public protocol, delegating actual execution operations to the underlying layers while maintaining single-point oversight.

The Four Core Layers of Apache Maka

The internal architecture separates responsibilities into four specialized layers that handle everything from event immutability to persistent storage.

Runtime Event Log

The Runtime Event Log functions as the canonical source of truth for every model message, tool call, tool result, and termination fact. Implemented in [packages/core/src/event-log.ts](https://github.com/apache/maka/blob/main/packages/core/src/event-log.ts), this layer maintains an immutable history where pruning or compaction only affect projections fed to providers, never the underlying log itself.

SessionManager and AgentRun

The SessionManager and AgentRun classes, located in [packages/runtime/src/session-manager.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), own the execution lifecycle of individual sessions. This layer manages turn identity, continuation logic, and recovery mechanisms. While the Runtime Host provides the public protocol boundary, it relies on these components to govern actual session state transitions and agent execution contexts.

Agent Graph

The Agent Graph layer handles dependent work scheduling by spawning child sessions. Every activation, even those originating from graph operations, routes back through the Runtime Host to maintain centralized control. The implementation in [packages/runtime/src/agent-graph.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph.ts) provides the reconciliation logic for complex multi-agent workflows and recursive session management.

Storage Layer

The Storage layer persists interactive runtime state using SQLite-backed stores defined in [packages/storage/src/sqlite-store.ts](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-store.ts). Crucially, this layer does not own Eval-specific roots such as TaskRun ledgers or experiment results, maintaining a clean boundary between runtime state and evaluation data.

Package Structure and Code Boundaries

The architecture manifests concretely in the repository's package layout, mapping directly to the conceptual layers:

• packages/core – Pure contracts for sessions, runtime events, agent runs, permissions, and protocol definitions.
• packages/runtime – Implements SessionManager, AgentRun, model adapters, tool integration, context handling, recovery, and graph reconciliation.
• packages/runtime-host – The sole hosted execution authority and the public client/protocol entry point.
• packages/storage – Interactive state stores and SQLite control planes for the Storage layer.
• packages/eval – Experiment definitions, cells, attempts, and result selection (distinct from runtime state).
• packages/cli – User-facing interfaces including the maka run and maka eval commands.
• apps/desktop/src/main – Electron app composition and product-entry adapters.

Working with the Architecture Layers

The following examples demonstrate how developers interact with these layers in practice.

Invoking the Runtime Host via CLI

# Execute a session through the CLI entry point

maka run --model=gpt-4o-mini "Summarize the latest Apache Maka release notes."

This command, implemented in [packages/cli/src/cli.ts](https://github.com/apache/maka/blob/main/packages/cli/src/cli.ts), creates a Runtime Host client that forwards the request to the SessionManager, which spawns an AgentRun while appending all events to the Runtime Event Log.

Inspecting the Runtime Event Log

import { EventLog } from '@maka/core';

// Retrieve the full log for the current session
const log = await EventLog.load(sessionId);
log.entries.forEach(entry => console.log(entry.type, entry.payload));

Scheduling Dependent Work with Agent Graph

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

const graph = new AgentGraph(session);
graph.schedule(async (child) => {
  await child.runTool('search', { query: 'Apache Maka architecture' });
});
await graph.run();

Persisting State in the Storage Layer

import { SqliteStore } from '@maka/storage';

const store = new SqliteStore('session.db');
await store.save('conversation', { messages: [] });
const data = await store.load('conversation');
console.log(data);

Summary

• Apache Maka architecture layers separate concerns into Runtime Event Log, SessionManager/AgentRun, Agent Graph, and Storage.
• The Runtime Host provides the single execution authority that coordinates all layers and handles admission control.
• The Runtime Event Log maintains immutable execution history in packages/core/src/event-log.ts.
• SessionManager and AgentRun handle session lifecycle management via packages/runtime/src/session-manager.ts.
• Agent Graph enables dependent work scheduling and child session spawning through packages/runtime/src/agent-graph.ts.
• Storage persists interactive runtime state exclusively through packages/storage/src/sqlite-store.ts, separate from evaluation data.

Frequently Asked Questions

What is the difference between the Runtime Host and the SessionManager in Apache Maka?

The Runtime Host acts as the central gatekeeper and protocol boundary that all clients interact with, handling admission control, permissions, and the public API surface. The SessionManager, implemented in packages/runtime/src/session-manager.ts, manages the actual execution lifecycle, turn identity, and recovery mechanisms for individual sessions once admitted by the Host.

How does the Runtime Event Log ensure immutability?

The Runtime Event Log, defined in packages/core/src/event-log.ts, serves as the canonical record for all model messages and tool interactions. While projections of this log may be pruned or compacted for provider consumption, the underlying log structure remains immutable, ensuring complete auditability of agent execution history according to the architecture specification.

Can the Storage layer handle evaluation-specific data?

No. According to the architecture specification, the Storage layer in packages/storage/src/sqlite-store.ts explicitly handles only interactive runtime state. Evaluation-specific concepts like TaskRun ledgers and experiment results belong to the separate @maka/eval package, maintaining strict boundaries between runtime and evaluation concerns.

How does the Agent Graph layer interact with the Runtime Host?

Even when the Agent Graph schedules dependent work by spawning child sessions in packages/runtime/src/agent-graph.ts, every activation routes back through the Runtime Host. This design guarantees that the Host maintains single-point control over all execution, regardless of whether work originates from direct client requests or internal graph reconciliation processes.

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