Core Functionalities of Apache Maka: A Deep Dive Into the Agent Workspace Architecture

Apache Maka is a high-performance agent workspace that records every language model action into an append-only event log, turning the log itself into a persistent, queryable runtime that supports Desktop, TUI, and CLI interfaces.

The core functionalities of Apache Maka center on a single Runtime Host architecture that executes agent sessions while maintaining an immutable record of all interactions. As an incubating Apache project, Maka treats the event log as the primary source of truth, enabling complete session recovery and auditability across multiple UI front-ends.

Runtime Host and Event-Driven Architecture

At the heart of Maka lies the Runtime Host, implemented in packages/runtime-host/, which serves as the exclusive owner of the event log.

The Runtime Host executes AgentRun sessions and mediates all communication between language models and tools. According to ARCHITECTURE.md, this backend spine writes every step to a RuntimeEvent log, ensuring that the Desktop, TUI, and CLI clients remain thin renderers that project log state into UI views rather than maintaining their own session state.

This design means that regardless of which interface you use, the Runtime Host maintains the canonical record in runtime.sqlite. The host handles model output, tool calls, permission decisions, and recovery logic, making the system inherently reproducible and debuggable.

Session Management and Recovery

The SessionManager class tracks the complete lifecycle of a workspace session, providing capabilities for resume, recovery, and context projection.

When a user disconnects or an application crashes, Maka can restore the exact session state by replaying the immutable event log. This functionality resides in the Runtime Host implementation and leverages the storage layer to project historical context back into the UI without losing intermediate states or tool outputs.

Model and Tool Runtime Integration

Maka provides a unified protocol for interacting with diverse LLM providers and external tools.

The Model & Tool Runtime layer handles:

• LLM Providers: Cloud APIs, local models, and compatible gateways
• Tool Execution: File system operations, shell commands, web fetching, and OS-level control
• Permission Logging: Every tool call and permission decision is recorded as an immutable event

The @maka/computer-use package specifically manages backend selection between local direct-peer connections and remote protocol implementations for actions requiring OS-level control, allowing the agent to safely execute system commands while maintaining a complete audit trail.

Storage Layer and Persistence

All workspace data persists locally in a SQLite database (runtime.sqlite) stored under the Electron user-data folder.

The @maka/storage package implements the SQLite-backed operational state, while configuration credentials and artifact files remain organized within the standard application data directories. This approach enables:

• Complete offline operation
• Fast local querying of session history
• Portable workspace backups
• Zero external database dependencies

You can access the persistent log directly using standard SQLite tools:

import { open } from 'sqlite';
import sqlite3 from 'sqlite3';

async function readLog() {
  const db = await open({
    filename: `${process.env.ELECTRON_USER_DATA}/runtime.sqlite`,
    driver: sqlite3.Database,
  });
  const rows = await db.all('SELECT * FROM runtime_events ORDER BY id DESC LIMIT 10');
  console.table(rows);
}
readLog();

Multi-Interface UI Architecture

Maka supports three distinct front-ends through the @maka/ui package, which supplies shared conversation components, Markdown rendering, and artifact handling primitives:

1. Desktop: Electron + React renderer located in apps/desktop/ providing a rich graphical interface with hot-module-replacement support
2. TUI: Terminal UI built on the same Runtime Host for keyboard-driven workflows
3. CLI: Non-interactive command-line client in packages/cli/ for scripting and automation

All interfaces communicate with the single Runtime Host, ensuring consistent behavior and state across Desktop, terminal, and scripted environments.

Core Contracts and Package Structure

The @maka/core package establishes pure TypeScript contracts for sessions, events, permissions, and connections. These contracts allow other packages to operate without side-effects, ensuring type safety across the monorepo.

Key packages include:

• packages/core/: Pure contracts and type definitions
• packages/runtime/: AgentRun implementation, model adapters, and recovery logic
• packages/storage/: SQLite persistence layer
• packages/eval/: Benchmarking and evaluation framework

Evaluation Framework for Agent Benchmarking

The @maka/eval package provides a reproducible evaluation harness for researchers. It defines experiment cells, attempts, and results structures that enable standardized benchmarking against task sets.

Researchers can run evaluation cells to compare model performance across versions:

npm --workspace @maka/eval run eval:run -- \
  --cell ./docs/eval/example-cell.json

This framework collects metrics and results in a structured format, facilitating reproducible AI research within the Maka environment.

Practical Usage Examples

Setting up the Desktop development environment with live reload:

git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run dev

Executing a single turn via CLI:

npm run build
npm run cli:dev -- run "Summarize this repository"

Summary

• Runtime Host: The packages/runtime-host/ directory contains the single source of truth that executes AgentRun sessions and maintains the append-only event log.
• Immutable Logging: Every model message, tool call, and permission decision writes to RuntimeEvent entries in runtime.sqlite, enabling full session replay and audit.
• SessionManager: Handles lifecycle management, resume capabilities, and context projection from logs to UI without state duplication.
• Unified Storage: @maka/storage implements SQLite persistence for configuration, credentials, and runtime state under the user-data folder.
• Multi-Interface Support: Desktop (Electron), TUI, and CLI clients in apps/desktop/ and packages/cli/ all consume the same Runtime Host API.
• Evaluation Tools: @maka/eval provides standardized benchmarking through experiment cells and structured result collection.
• Core Contracts: @maka/core maintains pure TypeScript definitions ensuring type safety across the agent workspace.

Frequently Asked Questions

What makes Apache Maka different from other agent frameworks?

Apache Maka distinguishes itself by treating the event log as the runtime itself rather than a secondary audit feature. While other frameworks may store conversation history, Maka's Runtime Host in packages/runtime-host/ uses the append-only RuntimeEvent log as the primary source of truth, enabling any UI client to project the exact session state at any point without maintaining parallel state machines.

How does Maka handle session recovery after crashes?

The SessionManager class implements recovery by replaying the immutable event log from runtime.sqlite. Since every model interaction, tool execution, and state change is logged as a RuntimeEvent, the system can reconstruct the exact workspace context by reading sequential entries from the SQLite database, allowing users to resume interrupted sessions without data loss.

Can I use Apache Maka without the Desktop GUI?

Yes. Maka provides a CLI and TUI in packages/cli/ that communicate with the same Runtime Host as the Desktop application. You can run non-interactive commands using npm run cli:dev -- run "your prompt here" or build the CLI for scripting workflows, making the agent workspace fully operable in headless or terminal-only environments.

Where does Maka store conversation history and artifacts?

All data persists locally in SQLite format at runtime.sqlite within the Electron user-data folder, managed by @maka/storage. This includes the complete event log, configuration, credentials, and artifact files, ensuring complete privacy and offline capability without external database dependencies.

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