How Apache Maka Ensures Data Durability with the Runtime Event Log

Apache Maka guarantees data durability through an append-only Runtime Event Log backed by SQLite, ensuring every model interaction, tool call, and permission decision is permanently recorded to disk and can be reliably replayed after crashes.

Apache Maka is an open-source AI application platform that treats session history as the single source of truth. At the heart of its architecture lies the Runtime Event Log, an immutable sequence of events stored in a local SQLite database that enables crash recovery and complete session replay without data loss.

Append-Only Architecture for Immutable History

The Runtime constructs a single, sequential stream of RuntimeEvent objects that is never rewritten or modified. According to the project architecture documentation, this log feeds both the UI and recovery layers, ensuring that the historical record serves as the sole source of truth rather than any transient runtime state.

Event Sequence Integrity

Every interaction processed by the Runtime—including model prompts, tool executions, permission decisions, and termination results—is appended to the end of the log as a discrete, immutable entry. Because the log is strictly append-only, existing records cannot be overwritten or corrupted by ordinary operations, guaranteeing that past sessions remain tamper-evident and recoverable.

SQLite Persistence and File Storage

The live event log persists in a file named runtime.sqlite located within the Electron user-data directory. Unlike older JSON-L transcript formats, this SQLite database serves as the authoritative source for all restored sessions, surviving process termination, system crashes, or power loss.

Durable Storage Implementation

The storage layer implements durability through two critical components:

• packages/storage/src/sqlite.ts – Provides the SQLite wrapper that manages the runtime_events table and ensures ACID-compliant disk writes.
• packages/runtime-host/src/eventLog.ts – Contains the core logic for constructing and appending immutable RuntimeEvent objects to the persistent store.

Because SQLite writes data directly to a durable file on disk, the log maintains integrity even when the host process terminates unexpectedly.

Safe Session Recovery and Replay

Maka implements controlled replay semantics to ensure durability without wasting tokens or re-executing unnecessary operations.

Safe Boundary Resume

By default, resuming interrupted turns is disabled to prevent unintended side effects. When explicitly enabled via the MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 environment variable, Maka reads the persisted log from runtime.sqlite and replays events up to the last safe boundary. This approach re-issues model calls only when necessary, avoiding stale token reuse while guaranteeing that no event is lost during recovery.

Security Isolation from Credentials

Durability guarantees do not compromise security. Sensitive credential material—including API keys and authentication tokens—is stored separately in credential-vault.json and explicitly excluded from the Runtime Event Log. This architectural separation ensures that durable session logs can be inspected, backed up, or shared without exposing secret authentication data.

Working with the Runtime Event Log Programmatically

You can interact with the durable event store using the @maka/storage and @maka/runtime-host packages.

Querying Historical Events

Access the SQLite backing store to inspect past interactions:

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

// Open the SQLite store that backs the event log
const db = await open('runtime.sqlite');

// Query the latest 10 events for the current session
const recentEvents = await db.all(`
  SELECT id, type, timestamp, payload
  FROM runtime_events
  ORDER BY timestamp DESC
  LIMIT 10;
`);

console.log('Last events:', recentEvents);

Appending Custom Events

The Runtime Host exposes an append method for recording custom events within the same durable stream:

import { RuntimeHost } from '@maka/runtime-host';

async function recordCustomEvent(host: RuntimeHost, payload: any) {
  await host.eventLog.append({
    type: 'custom',
    timestamp: Date.now(),
    payload,
  });
}

This pattern mirrors the internal implementation used when recording model responses, tool calls, or permission decisions.

Summary

• Append-only design: Events are permanently added to the runtime_events table without overwriting existing data, creating an immutable history.
• SQLite durability: The runtime.sqlite file in the Electron user-data folder survives crashes and power loss, serving as the authoritative source for session restoration.
• Safe replay semantics: Controlled session recovery via the MAKA_RUNTIME_SAFE_BOUNDARY_RESUME environment variable enables resumable turns without token waste.
• Security isolation: Credentials stored in credential-vault.json remain separate from the event log, ensuring durable logs contain no secret material.

Frequently Asked Questions

Where is the Runtime Event Log stored on disk?

The Runtime Event Log lives in a file named runtime.sqlite located in the Electron user-data directory. This SQLite database contains the runtime_events table and serves as the authoritative source for session restoration, distinct from older JSON-L transcript files that are not imported during recovery.

What happens to my session if Maka crashes?

Because every event is written to disk via SQLite before acknowledgment, a crash does not result in data loss. When safe resume is enabled with MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1, Maka reads the persisted log from runtime.sqlite and replays events up to the last safe boundary, restoring session state without requiring manual intervention or losing interaction history.

Are API keys and secrets stored in the Runtime Event Log?

No. API keys and other credential material are stored separately in credential-vault.json within the same user-data directory. The Runtime Event Log intentionally excludes secrets, ensuring that durable session records can be shared or inspected without exposing sensitive authentication data.

How can I query the Runtime Event Log programmatically?

Applications can access the log using the @maka/storage package to open runtime.sqlite and execute SQL queries against the runtime_events table. The @maka/runtime-host package also provides the RuntimeHost.eventLog.append() method for recording custom events within the same durable, append-only stream.

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