# Where is Maka's Storage Implementation Located? Inside Apache Maka's Persistence Layer

> Discover Maka's storage implementation in the packages storage package. Explore its SQLite-backed persistence layer for root authority management and filesystem durability.

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

---

**Maka's storage implementation is located in the `packages/storage` package, featuring a SQLite-backed persistence layer built around root authority management, writer composition orchestration, and filesystem durability guarantees.**

Apache Maka is an emerging open-source AI agent framework that requires robust, transactional persistence for workspaces, artifacts, and long-term agent memory. Understanding exactly where Maka's storage implementation lives—and how its modular architecture ensures data integrity—is essential for developers extending the platform or debugging workspace state issues.

## Core Architecture: Three Pillars of Maka Storage

The storage subsystem in `packages/storage` is organized around three foundational concepts that work together to provide durable, locked workspace access.

### Storage Root Authority

The **storage root** is a directory that houses a workspace's durable data, identified by a marker file named [`.maka-storage-root.json`](https://github.com/apache/maka/blob/main/.maka-storage-root.json). The [`root-authority.ts`](https://github.com/apache/maka/blob/main/root-authority.ts) module handles creation, discovery, validation, and locking of these roots. According to the Apache Maka source code, the root authority implements capability-based access control, issuing exclusive leases to prevent concurrent write access to the same workspace.

Key functions in [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) include `tryAcquireInteractiveRootOwner()`, which attempts to obtain an exclusive write lease on a storage root, returning an owner object that must be held for the duration of the session.

### Writer Composition Orchestration

The **storage writer composition** acts as a façade that opens a group of interactive stores for write access while guaranteeing a clean, reverse-order shutdown sequence. The [`storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/storage-writer-composition.ts) file exports `openStorageWriterComposition()`, a single API entry point that returns an object exposing all writable stores—including execution state, artifacts, usage statistics, and long-term memory.

This composition pattern ensures that when a workspace closes, each SQLite-backed store releases its resources in the correct order, preventing corruption or partial writes.

### Stable Storage Guarantees

Durability is enforced by [`packages/storage/src/stable-storage.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/stable-storage.ts), which provides low-level utilities like `syncFile()` and `syncDirectoryChain()`. These helpers perform `fsync` operations on files and directories to guarantee that writes are physically flushed to disk before the composition releases its locks. This prevents data loss in the event of system crashes or power failures.

## Key Source Files in `packages/storage`

The storage implementation spans several specialized modules, each responsible for specific persistence concerns:

- **[`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts)** – Core logic for storage root lifecycle management, including marker file handling, lease acquisition, and repair mechanisms.
- **[`packages/storage/src/storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/storage-writer-composition.ts)** – Orchestration layer that coordinates opening and closing of all interactive stores for write access.
- **[`packages/storage/src/stable-storage.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/stable-storage.ts)** – Filesystem durability utilities ensuring atomic write operations.
- **[`packages/storage/src/workspace-root.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/workspace-root.ts)** – Resolution helpers for determining client data roots and workspace paths on disk.
- **[`packages/storage/src/artifact-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/artifact-stores.ts)** – SQLite-backed persistence for code artifacts and generated files.
- **[`packages/storage/src/usage-stores.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/usage-stores.ts)** – Storage for interaction history and usage metadata.
- **[`packages/storage/src/long-term-memory-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/long-term-memory-store.ts)** – Persistent storage for agent memory across sessions.
- **[`packages/storage/src/task-ledger-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/task-ledger-store.ts)** – Transactional ledger tracking task execution history.

## Working with Maka's Storage API

Developers interact with the storage layer through asynchronous composition APIs that handle root resolution, lease acquisition, and store initialization.

### Opening a Writable Storage Composition

To write data to a Maka workspace, you must resolve the workspace root, acquire an exclusive lease, and open the writer composition:

```typescript
import { resolveMakaWorkspaceRoot, resolveMakaDataRoots } from '@maka/storage/workspace-root';
import { openStorageWriterComposition } from '@maka/storage/storage-writer-composition';
import { tryAcquireInteractiveRootOwner } from '@maka/storage/root-authority';

async function getWriterComposition(workspaceName: string) {
  // 1. Resolve the workspace's root directory on disk
  const { workspaceRoot } = resolveMakaDataRoots(
    resolveMakaClientDataRoot(), { workspaceName },
  );

  // 2. Resolve (or create) the storage root marker
  const capability = await resolveMakaDataRoots(workspaceRoot);

  // 3. Acquire an exclusive write lease on the root
  const owner = await tryAcquireInteractiveRootOwner(capability);
  if (!owner) throw new Error('Workspace is already in use');

  // 4. Open the full writer composition
  const composition = await openStorageWriterComposition(owner.lease);
  return composition; // provides .execution, .artifacts, .usage, etc.
}

```

### Graceful Shutdown

The composition guarantees reverse-order closing of each store to maintain referential integrity:

```typescript
async function closeComposition(comp) {
  // Automatically closes all stores in correct order and releases the lease
  await comp.close();
}

```

### Resolving Workspace Locations

To locate where Maka stores data on disk without opening a write session:

```typescript
import { resolveMakaWorkspaceRoot } from '@maka/storage/workspace-root';

const workspacePath = resolveMakaWorkspaceRoot({
  workspaceName: 'default',
});
console.log('Workspace root on disk:', workspacePath);

```

## Summary

- **Location**: Maka's storage implementation resides in `packages/storage`, with core logic in [`root-authority.ts`](https://github.com/apache/maka/blob/main/root-authority.ts), [`storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/storage-writer-composition.ts), and [`stable-storage.ts`](https://github.com/apache/maka/blob/main/stable-storage.ts).
- **Architecture**: The system uses a three-layer design: root authority for locking, writer composition for orchestration, and stable storage for filesystem durability.
- **Persistence**: All concrete stores are SQLite-backed modules (artifacts, usage, memory, tasks) opened via `openStorageWriterComposition()`.
- **Durability**: Writes are protected by `fsync` operations through [`stable-storage.ts`](https://github.com/apache/maka/blob/main/stable-storage.ts) utilities, ensuring data survives system crashes.
- **API Entry**: Use `tryAcquireInteractiveRootOwner()` to lock a workspace, then `openStorageWriterComposition()` to access writable stores.

## Frequently Asked Questions

### Where is the Maka storage code located?

The storage implementation is located in the `packages/storage` package within the Apache Maka repository. Core files include [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) for workspace locking, [`packages/storage/src/storage-writer-composition.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/storage-writer-composition.ts) for store orchestration, and [`packages/storage/src/stable-storage.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/stable-storage.ts) for durability utilities.

### How does Maka ensure data durability?

Maka ensures durability through the [`stable-storage.ts`](https://github.com/apache/maka/blob/main/stable-storage.ts) module, which provides `syncFile()` and `syncDirectoryChain()` functions. These utilities perform `fsync` operations on both files and their parent directories, guaranteeing that data is physically written to disk before releasing locks or completing transactions.

### What database does Maka use for storage?

Maka uses **SQLite** for all persistent storage. Each domain (artifacts, usage statistics, long-term memory, task ledgers) is implemented as a separate SQLite-backed module under `packages/storage/src/`, accessed through the writer composition API.

### How do I open a Maka workspace for writing?

To open a workspace for writing, import `resolveMakaDataRoots` from [`workspace-root.ts`](https://github.com/apache/maka/blob/main/workspace-root.ts) and `tryAcquireInteractiveRootOwner` from [`root-authority.ts`](https://github.com/apache/maka/blob/main/root-authority.ts). Resolve the workspace path, acquire an exclusive lease via `tryAcquireInteractiveRootOwner()`, then pass the lease to `openStorageWriterComposition()` to receive a writable composition object containing all store interfaces.