# What Is the Runtime Event Log in Apache Maka? The Single Source of Truth for Agent Execution

> Discover the Apache Maka Runtime Event Log, the immutable record of agent execution facts. Learn how this single source of truth enables replay, recovery, and state projections.

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

---

**The Runtime Event Log in Apache Maka is an immutable, ordered record of every fact generated during agent execution, serving as the single source of truth that enables replay, recovery, and state projections across all system components.**

Apache Maka is an open-source framework for building reliable AI agents. At its core, the Runtime Event Log persists every model message, tool call, and termination event in a durable, append-only stream, ensuring that system state remains reproducible and recoverable.

## Core Purpose of the Runtime Event Log

The Runtime Event Log functions as the **single source of truth** for everything an agent does during execution. Rather than scattering state across multiple modules, Maka centralizes all execution facts into one ordered, immutable sequence.

According to the architecture documentation in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md), the log stores "model messages, tool calls, tool results, and termination facts" (lines 35-67). System state at any point in time is derived as a **projection** over this ordered log, not as independent state stored in memory (lines 419-428).

This design guarantees **exact reproducibility** across process restarts, session reconnections, and UI refreshes.

## How the Runtime Event Log Works

### Event Persistence and Ordering

During execution, the model loop generates discrete *facts*: messages sent to the model, tool invocations, tool results, and termination events. These facts are immediately persisted to the Runtime Event Log in strict chronological order.

The log uses an append-only write pattern. Once written, events become immutable, preventing state corruption or history manipulation.

### State Projections vs. Private State

Higher-level components—`SessionManager`, `RuntimeKernel`, `AgentRun`, the UI layer, and replay/recovery logic—do not maintain private copies of execution history. Instead, each component reads **projections** of the Runtime Event Log.

For example, when displaying a chat history, the UI queries the log for `modelMessage` events rather than caching messages internally. When recovering from a crash, the `RuntimeKernel` rebuilds its state by replaying the ordered facts from the log.

## Accessing the Runtime Event Log in Practice

The Maka CLI exposes the Runtime Event Log through the `MAKA_MCP_STDIO_EVENT_LOG` environment variable, which specifies the path to a JSON Lines file containing all runtime events.

### Reading the Log File

Each line in the log represents a single JSON object describing one runtime event. Below is a practical example for reading and replaying model messages:

```typescript
// Example: reading the Runtime Event Log produced by the CLI
import { readFile } from 'node:fs/promises';

// The CLI sets MAKA_MCP_STDIO_EVENT_LOG to the path of the JSON-Lines file.
const logPath = process.env.MAKA_MCP_STDIO_EVENT_LOG;
if (!logPath) {
  throw new Error('Runtime Event Log path not provided');
}

// Each line is a JSON object describing a single runtime event.
const raw = await readFile(logPath, 'utf-8');
const events = raw
  .trim()
  .split('\n')
  .map(line => JSON.parse(line));

// Simple replay: print every model message in order
for (const ev of events) {
  if (ev.event === 'modelMessage') {
    console.log(`[${ev.timestamp}] ${ev.role}: ${ev.content}`);
  }
}

```

### Log Verification in Testing

The test suite in [`packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts) demonstrates how the CLI injects the log path and asserts on its contents. Lines 61-70 configure the environment variable to write to `stdio-events.jsonl`, while lines 280-285 verify the presence of specific events such as the `exit` event.

## Architecture Integration: Components That Depend on the Log

The Runtime Event Log is not an ancillary feature—it is the canonical data backbone of the system. Key files illustrating this integration include:

- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)**: Defines the log as the "canonical source for model messages, tool calls, tool results, and termination facts."
- **[`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts)**: The CLI entry point that wires `MAKA_MCP_STDIO_EVENT_LOG` to the runtime host, ensuring events are written to disk.
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)**: High-level diagrams depicting the log as the central persistence mechanism enabling durability guarantees.

Because the log is durable, you can restart a process, open a new session, or build alternative projections (such as checkpoint snapshots) without losing the exact sequence of agent interactions.

## Summary

- The **Runtime Event Log** is the immutable, ordered record of all facts generated during an Apache Maka agent's execution.
- Components like `SessionManager`, `RuntimeKernel`, and the UI derive their state as **projections** over the log rather than storing private state.
- The log enables **exact reproducibility**, allowing for process recovery, session replay, and checkpointing.
- Access the log via the `MAKA_MCP_STDIO_EVENT_LOG` environment variable, which points to a JSON Lines file.
- As implemented in the Apache Maka source code, this design pattern ensures that system state at any moment is simply a view over the ordered history of events.

## Frequently Asked Questions

### What file format does the Runtime Event Log use?

The Runtime Event Log uses **JSON Lines (JSONL)** format, where each line contains a single JSON object representing one runtime event. This append-only structure allows for efficient streaming writes and straightforward line-by-line parsing during replay or analysis.

### How does the Runtime Event Log enable agent recovery?

Because the log is **durable and ordered**, the `RuntimeKernel` can rebuild the entire system state after a crash by replaying events from the beginning of the log up to the failure point. Since components read projections of the log rather than maintaining independent state, recovery guarantees exact consistency with the pre-crash execution history.

### Which environment variable configures the Runtime Event Log path?

The **`MAKA_MCP_STDIO_EVENT_LOG`** environment variable specifies the filesystem path where the CLI writes the JSON Lines log file. Setting this variable in [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts) activates the logging mechanism, as verified in [`packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts).

### Can the Runtime Event Log be read while the agent is still running?

Yes. Because the log follows an append-only write pattern, readers can safely stream or tail the file while the agent continues execution. The immutable nature of existing entries ensures that partial reads will never encounter corrupted or half-written events.