What Is the Storage Package in Apache Maka? A Deep Dive into the Persistence Layer

The storage package in Apache Maka is the centralized persistence layer that provides SQLite-backed TypeScript modules for managing operational state, configuration, artifacts, and session data across the runtime host.

The storage package forms the backbone of durable state management in Apache Maka, encapsulating all disk-based persistence behind a thin, type-safe TypeScript API. Located in packages/storage, this layer ensures that every turn, tool execution, and configuration change survives process crashes and can be reconstructed deterministically. By centralizing SQLite operations, it enables seamless data sharing across desktop, TUI, and CLI interfaces while maintaining a single source of truth.

Core Responsibilities of the Storage Package

The storage package handles five critical persistence domains that together constitute the runtime’s complete state.

Operational State and Runtime Events

At the heart of the system lies the operational state, which maintains an append-only record of every turn, model message, tool call, and permission check. The operational-state-store.ts module writes these events to runtime.sqlite, creating an immutable log that serves as the foundation for debugging, replay, and audit trails.

Configuration and Credential Vaults

Workspace-wide settings and sensitive credentials live in dedicated configuration stores. The settings-store.ts module persists user preferences, API keys, and JSON-based configuration files (such as settings.json) with type-safe read/write operations that protect against schema drift.

Artifact and Payload Persistence

Generated artifacts, file attachments, and transcript archives require long-term storage. The artifact-stores.ts module manages these binary and JSON payloads, storing both the data and metadata necessary for later retrieval, querying, or conversation replay.

Session and Conversation Management

Session-level metadata—including todo lists, conversation histories, and off-loaded context snapshots—resides in the session-store.ts module. This store enables the runtime to suspend and resume long-running conversations without losing intermediate state.

Auxiliary Stores for Memory and Secrets

Beyond core operations, the package provides specialized stores for long-term memory, plan authorities, execution records, and managed secrets. These auxiliary stores support advanced agent capabilities like persistent planning and secure credential access across process lifetimes.

Key Source Files and Architecture

The architecture centers on a façade pattern that exposes all stores through a unified entry point while isolating SQLite implementation details.

stable-storage.ts: The Central Façade

The stable-storage.ts file serves as the high-level entry point for the entire package. It initializes database connections and provides factory methods for accessing individual stores, ensuring that all SQLite handles are managed consistently across the codebase.

operational-state-store.ts: Immutable Event Logs

This module implements the append-only runtime event log. Every state transition is written as an immutable record, making the event stream a first-class artifact that can be inspected for debugging or replayed for deterministic testing.

settings-store.ts: Workspace Configuration

Responsible for persisting workspace-wide configuration and credential vaults, this store handles typed JSON serialization and ensures that settings remain consistent across desktop, TUI, and CLI clients.

artifact-stores.ts: Generated Artifacts

Tool outputs and user-uploaded files flow through this store, which manages both blob storage and relational metadata in runtime.sqlite, enabling efficient querying of artifact provenance and relationships.

session-store.ts: Session Metadata

This module provides CRUD operations for sessions, todo items, and conversation snapshots, allowing the runtime to offload large context windows to disk and reload them on demand.

How to Interact with the Storage Layer

Other packages such as @maka/runtime and @maka/runtime-host consume the storage API through simple async/await patterns.

Logging Runtime Events

To append an event to the immutable runtime log, import the operational state store and call the append method:

import { RuntimeEvent } from '@maka/core';
import { operationalStateStore } from '@maka/storage';

async function logEvent(event: RuntimeEvent) {
  const store = await operationalStateStore.open();
  await store.append(event);
}

Reading Workspace Settings

Retrieve typed configuration data using the settings store façade:

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

async function getWorkspaceSettings() {
  const store = await settingsStore.open();
  const settings = await store.readAll();
  return settings;
}

Persisting Tool Artifacts

Store generated files and metadata through the artifact store:

import { artifactStore } from '@maka/storage';
import { Artifact } from '@maka/core';

async function saveArtifact(artifact: Artifact) {
  const store = await artifactStore.open();
  await store.put(artifact.id, artifact);
}

Benefits of Centralized Persistence

Consolidating all state management into the storage package delivers three architectural advantages for the Apache Maka runtime.

Durable, Append-Only Logs – The runtime event log is treated as a first-class artifact, enabling forensic inspection and deterministic replay of any conversation turn.

Deterministic Crash Recovery – If a turn crashes, the host reconstructs the exact state from stored snapshots in runtime.sqlite, ensuring no conversational context is lost.

Cross-Process Data Sharing – Desktop, TUI, and CLI clients all read from and write to the same on-disk database, guaranteeing a single source of truth regardless of interface.

Summary

• The storage package provides the SQLite-backed persistence layer for Apache Maka, consolidating all disk operations into type-safe TypeScript modules.
• Key files include stable-storage.ts as the central façade, operational-state-store.ts for immutable event logs, and artifact-stores.ts for file management.
• All stores expose async APIs that enable durable logging, deterministic crash recovery, and cross-process data sharing across Maka's various client interfaces.
• The package manages five core domains: operational state, configuration, artifacts, sessions, and auxiliary data like memory and secrets.

Frequently Asked Questions

What database technology does the Apache Maka storage package use?

The storage package uses SQLite as its underlying database engine. All stores—including operational-state-store.ts, settings-store.ts, and artifact-stores.ts—read from and write to SQLite databases such as runtime.sqlite, providing ACID-compliant persistence without external dependencies.

How does the storage package enable crash recovery?

The package implements deterministic recovery through immutable snapshots and append-only event logs stored in operational-state-store.ts. When a turn crashes, the runtime host reads the last committed state from runtime.sqlite and reconstructs the conversation context exactly as it existed before the failure.

Can multiple Maka clients access storage simultaneously?

Yes. The storage package architecture supports cross-process sharing where desktop, TUI, and CLI clients all interact with the same on-disk SQLite database. This design guarantees a single source of truth and prevents data fragmentation across different interface implementations.

Where are runtime events persisted in the storage package?

Runtime events are persisted in runtime.sqlite via the operational-state-store.ts module. This store maintains an immutable, append-only log of every turn, model message, tool call, and permission check, enabling replay and debugging capabilities.

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