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

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. The 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 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 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, 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 – Core logic for storage root lifecycle management, including marker file handling, lease acquisition, and repair mechanisms.
• 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 – Filesystem durability utilities ensuring atomic write operations.
• packages/storage/src/workspace-root.ts – Resolution helpers for determining client data roots and workspace paths on disk.
• packages/storage/src/artifact-stores.ts – SQLite-backed persistence for code artifacts and generated files.
• packages/storage/src/usage-stores.ts – Storage for interaction history and usage metadata.
• packages/storage/src/long-term-memory-store.ts – Persistent storage for agent memory across sessions.
• 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:

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:

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:

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, storage-writer-composition.ts, and 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 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 for workspace locking, packages/storage/src/storage-writer-composition.ts for store orchestration, and packages/storage/src/stable-storage.ts for durability utilities.

How does Maka ensure data durability?

Maka ensures durability through the 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 and tryAcquireInteractiveRootOwner from 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.

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