# How Apache Maka Ensures Data Durability with the Runtime Event Log

> Apache Maka ensures data durability with an append-only Runtime Event Log backed by SQLite. Replay every model interaction, tool call, and permission decision after crashes.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.