How Maka’s Log‑Centric Architecture Works: Immutable Events as the Source of Truth

Apache Maka treats autonomous agent execution as an append‑only log where every action is captured as a typed RuntimeEvent, making the immutable event stream the single source of truth while deriving all state through deterministic projections.

Apache Maka reimagines autonomous agent state management through a log‑centric architecture that eliminates mutable runtime variables. Instead of updating state in place, the system permanently records every invocation detail—user prompts, tool calls, permission decisions, and errors—as typed events in a SQLite runtime_events table. This design ensures that the log is the runtime, with the agent’s current state calculated as a pure projection over the complete, immutable history.

Core Principles of the Log‑Centric Design

The Append‑Only Runtime Event Log

At the foundation of Maka’s implementation lies the RuntimeEvent type hierarchy defined in packages/core/src/runtime-event.ts. Every fact about an agent’s execution—whether text content, function calls, or tool dispatches—is encoded using encodeCanonicalRuntimeEvent and appended permanently to storage via packages/storage/src/sqlite-runtime-store.ts. These events are never altered or deleted, creating an auditable, crash‑recoverable history that serves as the canonical record for the entire system.

import { encodeCanonicalRuntimeEvent } from '@maka/core/canonical-runtime-event';
import { RuntimeEvent } from '@maka/core/runtime-event';
import { sqliteRuntimeStore } from './sqlite-runtime-store';

const toolCall: RuntimeEvent = {
  id: 'evt-123',
  invocationId: 'inv-456',
  runId: 'run-789',
  sessionId: 'sess-001',
  turnId: 'turn-01',
  ts: Date.now(),
  partial: false,
  role: 'tool',
  author: 'tool',
  content: {
    kind: 'function_call',
    id: 'call-1',
    name: 'grep',
    args: { pattern: 'TODO' },
  },
  actions: {
    toolDispatch: {
      protocol: 't1_after_preflight_v1',
      operationId: 'op-42',
      providerToolCallId: 'ptc-99',
      toolName: 'grep',
      canonicalArgsHash: 'sha256:...',
      recoveryMode: 'replay_safe',
    },
  },
};

await sqliteRuntimeStore.appendEvent(encodeCanonicalRuntimeEvent(toolCall));

Deterministic State Projection

Rather than storing mutable state objects, Maka derives the agent’s condition at any moment by projecting views over the immutable log. The architecture follows this core principle:

Agent State(t) = Project(RuntimeEvent Log[0…t], policy, runtime configuration)

This projection model allows the UI, LLM, and persistence layers to consume the same factual base at different resolutions. Because the log is append‑only, every subsystem interprets an identical, ordered history guaranteed by the runtime’s internal protocol (e.g., TOOL_BOUNDARY_PROTOCOL_V1).

From Log to Model Context: Building Replay Plans

When preparing context for the LLM, Maka does not feed raw log entries directly. Instead, the runtime constructs a model‑replay plan using buildRuntimeEventModelReplayPlan from packages/runtime/src/model-history.ts. This process, also supported by projectRuntimeEventsToStoredMessages, filters hidden events, rejoins function‑call pairs with their results, and prunes oversized tool outputs into lightweight placeholders to respect token budgets.

import { buildRuntimeEventModelReplayPlan } from '@maka/runtime';

const plan = buildRuntimeEventModelReplayPlan(events, {
  highWater: events.length,  // Use the full committed prefix
  maxTokens: 16_000,         // Model context budget
});

The resulting projection preserves semantic fidelity while ensuring the model receives only the relevant, properly formatted context needed for the next inference.

Managing Scale: Compaction and Checkpoints

Unbounded log growth would eventually overwhelm memory and context windows. Maka addresses this through log compaction implemented in packages/runtime/src/openai-codex-history-compactor.ts. Periodic checkpoints summarize early log segments, replacing verbose event sequences with concise summaries while storing bulky artifacts in a separate ArtifactStore and replacing them with placeholders in the active log.

import { createLogCompactionCheckpoint } from '@maka/runtime';

const checkpoint = await createLogCompactionCheckpoint({
  prefixEvents: events.slice(0, 10_000),
  summaryGenerator: async (segment) => {
    // Call a summarisation model
    return 'Summary of first 10k events';
  },
});

await sqliteRuntimeStore.storeCheckpoint(checkpoint);

These checkpoints maintain the complete canonical record for audit purposes while allowing the runtime to discard verbose historical details from active projections.

Crash Recovery and Transaction Boundaries

Maka’s durability guarantees rely on strict transaction boundaries that divide the log into prefix (committed) and suffix (uncommitted) segments. The SQLite storage layer ensures that only events in the committed prefix are considered authoritative for recovery. Snapshots—such as workspace version authority—are built from a stable prefix plus a high‑water mark, enabling safe continuation after interruption without replaying speculative or incomplete operations.

Summary

• Maka’s log‑centric architecture treats the append‑only RuntimeEvent stream as the single source of truth, eliminating mutable state from the runtime.
• Agent state is derived through deterministic projections over the immutable log, allowing multiple consumers to interpret the same history at different resolutions.
• Model‑replay plans constructed via buildRuntimeEventModelReplayPlan optimize LLM context by pruning hidden events and restructuring tool results while preserving semantic meaning.
• Compaction checkpoints and artifact offloading manage unbounded growth without losing the complete historical record.
• Transaction boundaries between committed prefixes and uncommitted suffixes enable robust crash recovery and consensus across replicas.

Frequently Asked Questions

What makes Maka’s log‑centric architecture different from traditional agent state management?

Traditional systems store mutable state variables that are updated in place, risking data loss on crashes and making audit trails incomplete. Maka’s approach treats the execution history as an immutable append‑only log where every fact is preserved as a typed RuntimeEvent, ensuring complete auditability and deterministic reconstruction of any previous state through projections.

How does Maka prevent the LLM context window from overflowing with long conversation histories?

The runtime uses buildRuntimeEventModelReplayPlan to intelligently compress the log by stripping hidden events, rejoining function calls with their results, and replacing large tool outputs with placeholders. Additionally, periodic compaction checkpoints summarize older log segments while storing full artifacts in ArtifactStore, keeping the active context within token limits without losing historical fidelity.

Can Maka recover from crashes without losing progress?

Yes. The SQLite storage layer in packages/storage/src/sqlite-runtime-store.ts maintains a strict boundary between committed (prefix) and uncommitted (suffix) log segments. After a crash, the runtime replays only the committed prefix up to the high‑water mark, ensuring exactly‑once semantics for durable events while safely discarding incomplete suffix operations.

Where are the core data structures for RuntimeEvent defined?

The canonical schema, type hierarchy (including RuntimeEventTextContent, RuntimeEventFunctionCallContent, and RuntimeEventToolDispatch), and validation logic are defined in packages/core/src/runtime-event.ts, while the durable SQLite persistence implementation resides in packages/storage/src/sqlite-runtime-store.ts.

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