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

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, 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:

// 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 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: Defines the log as the "canonical source for model messages, tool calls, tool results, and termination facts."
• 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: 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 activates the logging mechanism, as verified in 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.

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