# What Is the Runtime Event Log in Maka? Architecture, Persistence, and Reproducibility Explained

> Discover Maka's Runtime Event Log the single source of truth for agent actions enabling replay, checkpointing, and exact reproducibility. Learn its architecture and persistence.

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

---

**The Runtime Event Log in Maka is the single source of truth for everything an agent does during execution, persisting ordered, immutable facts that enable replay, checkpointing, and exact reproducibility.**

The Runtime Event Log sits at the heart of Maka's architecture, solving a fundamental problem in agent-based systems: how to maintain a reliable, queryable history of model interactions without scattering state across multiple components. This article explains what the Runtime Event Log is, why it's designed as an append-only log of facts, and how developers can leverage it for debugging, testing, and building derived views.

## What the Runtime Event Log Stores

The Runtime Event Log captures **four categories of facts** generated during agent execution:

- **Model messages** — inputs and outputs exchanged with the language model
- **Tool calls** — requests made to external tools and services
- **Tool results** — responses returned from those tools
- **Termination events** — signals that the agent run completed or exited

These facts are written in **JSON Lines format** (`.jsonl`), with one JSON object per line representing a single event. This format balances human readability with efficient streaming and append operations.

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 Runtime Event Log "is the canonical source for model messages, tool calls, tool results, and termination facts"【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/docs/architecture/runtime-core-architecture-draft.md†L35-L67】.

## Why the Log Is Central to Maka's Architecture

Maka's design principle is simple: **system state at any point in time is a projection over the ordered log**. Rather than maintaining mutable state in memory, core components derive their view of reality by reading the Runtime Event Log.

This architectural decision provides three critical benefits:

1. **Durability** — Process restarts, session reconnections, and even cross-machine handoffs preserve complete execution history
2. **Reproducibility** — Any agent run can be replayed exactly by reprocessing the same ordered events
3. **Flexibility** — Multiple projections (UI views, checkpoints, analytics) can coexist without synchronization overhead

The `SessionManager`, `RuntimeKernel`, `AgentRun`, and UI components all consume projections of the Runtime Event Log rather than maintaining private state【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/docs/architecture/runtime-core-architecture-draft.md†L419-L428】.

## How to Access and Parse the Runtime Event Log

The Maka CLI exposes the Runtime Event Log through the `MAKA_MCP_STDIO_EVENT_LOG` environment variable, which specifies the path where events are written.

### Reading the Log in Node.js

```typescript
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}`);
  }
}

```

This pattern demonstrates how the Runtime Event Log enables **time-travel debugging** — you can reconstruct exactly what the model saw and produced at any moment.

### Log File Format and Structure

Events in the Runtime Event Log share a common envelope structure:

```json
{
  "event": "modelMessage",
  "timestamp": "2024-01-15T09:23:47.123Z",
  "runId": "run-abc123",
  "role": "assistant",
  "content": "I'll help you analyze that data..."
}

```

The `event` field discriminates between fact types, while `runId` and `timestamp` provide ordering and grouping context.

## Testing and Verification with the Runtime Event Log

Maka's test suite uses the Runtime Event Log for end-to-end assertions. The integration test 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 this pattern【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts†L61-L70】:

```typescript
// Test setup: configure log output path
const logPath = join(tmpDir, 'stdio-events.jsonl');
const env = {
  ...process.env,
  MAKA_MCP_STDIO_EVENT_LOG: logPath,
};

```

Later, the test verifies execution by asserting on specific events in the log【grep†/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/apache/maka/main/packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts†L280-L285】:

```typescript
// Verify the run produced an expected termination event
const events = await readLogFile(logPath);
const exitEvent = events.find(e => e.event === 'exit');
expect(exitEvent).toBeDefined();
expect(exitEvent.code).toBe(0);

```

This approach eliminates flaky tests that depend on timing or internal state — assertions run against the durable, observable Runtime Event Log.

## Key Source Files for the Runtime Event Log

| File | Purpose |
|------|---------|
| [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) | Primary architectural documentation defining the Runtime Event Log's role as canonical source |
| [`docs/architecture/runtime-core-architecture-draft.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.zh-CN.md) | Chinese translation of architecture docs |
| [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) | High-level system diagram including the Runtime Event Log |
| [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts) | CLI entry point wiring `MAKA_MCP_STDIO_EVENT_LOG` to the runtime host |
| [`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) | Integration tests demonstrating log creation and verification |

## Summary

- **The Runtime Event Log is Maka's single source of truth**, persisting immutable, ordered facts about model messages, tool calls, tool results, and termination events.
- **All components read projections** of this log rather than maintaining private state, enabling exact reproducibility and flexible derived views.
- **The log uses JSON Lines format** written to a path specified by `MAKA_MCP_STDIO_EVENT_LOG`, making it accessible for debugging, testing, and custom tooling.
- **Architecture documentation in** [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) **establishes** that system state is always a projection over the ordered log, not independent mutable state.

## Frequently Asked Questions

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

The Runtime Event Log uses **JSON Lines** (`.jsonl`) format, with one JSON object per line. Each line represents a single runtime event with fields for event type, timestamp, run identifier, and event-specific payload. This format supports efficient append operations and streaming reads.

### How do I enable the Runtime Event Log in Maka?

Set the `MAKA_MCP_STDIO_EVENT_LOG` environment variable to a file path before running the Maka CLI. The [`runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli.ts) entry point wires this variable to the runtime host, causing all events to be written to that path. Integration tests in [`tui-mcp-remote-integration.test.ts`](https://github.com/apache/maka/blob/main/tui-mcp-remote-integration.test.ts) demonstrate this pattern.

### Can I replay an agent run from the Runtime Event Log?

**Yes.** Because the log contains the complete ordered history of facts, you can reconstruct the exact execution sequence by reprocessing events. The code example above shows parsing model messages; extending this to replay tool calls and responses yields bit-for-bit reproducible behavior.

### Why does Maka use an append-only log instead of a database?

The append-only log design guarantees **immutability and total ordering** — critical properties for debugging non-deterministic agent behavior. Projections can be rebuilt from any point in the log without complex migration or synchronization logic. This approach trades query flexibility for simplicity, durability, and verifiability.