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

> Explore Apache Maka's storage package, the SQLite-backed persistence layer for managing state, config, artifacts, and session data. Learn how Maka ensures data reliability.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/settings-store.ts) module persists user preferences, API keys, and JSON-based configuration files (such as [`settings.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

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

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

```typescript
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`](https://github.com/apache/maka/blob/main/stable-storage.ts) as the central façade, [`operational-state-store.ts`](https://github.com/apache/maka/blob/main/operational-state-store.ts) for immutable event logs, and [`artifact-stores.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/operational-state-store.ts), [`settings-store.ts`](https://github.com/apache/maka/blob/main/settings-store.ts), and [`artifact-stores.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.