# SQLite Store Schemas for Maka's Persistent State: Complete Technical Guide

> Explore Maka's SQLite store schemas for persistent state management. This guide details independent schema versions and automated migration within the Apache Maka repository.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: technical-guide
- Published: 2026-09-01

---

**Apache Maka persists its runtime state across eight specialized SQLite databases, each defined in `packages/storage/src/` with independent schema versions and automated migration via `migrateSqlite…Database` functions.**

Apache Maka relies on a distributed SQLite persistence layer to manage everything from agent execution traces to billing metrics. The **SQLite store schemas for Maka's persistent state** are implemented as versioned TypeScript modules that define table structures, enforce data integrity, and handle backward-compatible upgrades through built-in migration utilities.

## Core Storage Architecture

Maka splits its persistent state into isolated SQLite databases rather than a single monolithic file. This separation optimizes access patterns, reduces lock contention, and allows independent backup strategies for distinct data lifecycles. All schema definitions reside in `packages/storage/src/` and export two critical constants: a `SQLITE_*_SCHEMA_VERSION` integer and a `migrateSqlite*Database` function that executes sequential SQL migrations to bring old databases up to the current version.

Each store targets a specific domain: artifacts generated during sessions, low-level execution graphs, usage accounting, session lifecycle metadata, runtime engine state, workflow planning data, long-term memory fragments, and offloaded context blobs.

## Artifact Store Schema

The **Artifact Store** manages uploaded documents, generated images, and other file-based outputs produced during agent sessions.

- **Schema File**: [`sqlite-artifact-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-artifact-schema.ts)
- **Current Version**: `1`
- **Migration Function**: `migrateSqliteArtifactDatabase`

The primary table `artifact_records` stores metadata including `storage_key`, `artifact_id`, `session_id`, `created_at`, `status`, `relative_path`, and `record_json`. This schema remains at version 1, indicating a stable initial design for binary asset tracking.

## Core Execution Store Schema

The **Core Execution Store** records the low-level execution graph of agent runs, including turn admissions, interaction requests, and shell-run metadata.

- **Schema File**: [`sqlite-core-execution-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-core-execution-schema.ts)
- **Current Version**: `6`
- **Migration Function**: `migrateSqliteCoreExecutionDatabase`

Key tables include:
- `core_agent_runs` and `core_agent_run_events` for execution traces
- `core_root_turn_admissions` and `core_root_turn_start_rejections` for turn management
- `core_interaction_requests` and `core_interaction_outcomes` for request/response tracking
- `core_client_capability_session_grants` for permission management
- `core_shell_runs` for shell command execution metadata

## Usage Store Schema

The **Usage Store** tracks LLM consumption, tool invocations, and pricing data for cost accounting and billing.

- **Schema File**: [`sqlite-usage-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-usage-schema.ts)
- **Current Version**: `5`
- **Migration Function**: `migrateSqliteUsageDatabase`

Critical tables include `usage_llm_calls`, `usage_tool_invocations`, `usage_model_call_attempts`, and `usage_model_call_projection_checkpoints`. Pricing authority and overrides are managed through `usage_pricing_authority` and `usage_pricing_overrides`, allowing dynamic cost configuration without schema changes.

## Session-Metadata Store Schema

The **Session-Metadata Store** maintains the richest schema at version 36, handling chat session lifecycles, message hierarchies, and the Agent Graph subsystem.

- **Schema File**: [`sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-session-metadata-schema.ts)
- **Current Version**: `36`
- **Migration Function**: `migrateSqliteSessionMetadataDatabase`

Primary tables include `session_metadata`, `session_metadata_labels`, and `session_metadata_tombstones` for soft deletes. Message storage spans `session_messages`, `session_message_payloads`, and `session_message_chunks` for large content segmentation. The Agent Graph subsystem uses tables such as `agent_graph_epochs`, `agent_graph_intents`, `agent_graph_schedules`, and `agent_graph_supervisor_wakes` to manage hierarchical task execution.

## Runtime Store Schema

The **Runtime Store** captures the execution engine's volatile state, including tool events, workspace versioning, and continuation claims.

- **Schema File**: [`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts)
- **Current Version**: `15`
- **Migration Function**: `migrateSqliteRuntimeDatabase`

Notable tables include:
- `runtime_events` and `tool_journal_events` for event sourcing
- `tool_operations` for operation tracking
- `runtime_partial_snapshots` and `runtime_partial_segments` for streaming large outputs
- `runtime_workspace_versions`, `runtime_workspace_heads`, and `runtime_workspace_epochs` for git-like workspace management
- `runtime_continuation_claims` for async operation resumption
- `runtime_capabilities` and `runtime_managed_mutation_reservations` for capability-based security

## Workflow Store Schema

The **Workflow Store** manages higher-level planning artifacts, task scheduling, and goal-oriented work tracking.

- **Schema File**: [`sqlite-workflow-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-workflow-schema.ts)
- **Current Version**: `12`
- **Migration Function**: `migrateSqliteWorkflowDatabase`

Key tables include `workflow_session_todo_documents` for task lists, `workflow_scheduled_tasks` and `workflow_scheduled_task_fires` for cron-like scheduling, `workflow_daily_review_state` for session summaries, and `workflow_goal_authority` for objective hierarchies. Projection tables such as `workflow_task_ledger_projections` and `workflow_plan_projections` support materialized views of workflow state.

## Long-Term Memory Store Schema

The **Long-Term Memory Store** persists knowledge fragments that survive across individual chat sessions, enabling context retention for future interactions.

- **Schema File**: [`sqlite-long-term-memory-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-long-term-memory-schema.ts)
- **Current Version**: `1`
- **Migration Function**: `migrateSqliteLongTermMemoryDatabase`

The simplified schema centers on `ltm_documents`, containing `id`, `session_id`, `created_at`, and `record_json` fields for flexible document storage with provenance tracking.

## Context-Offload Store Schema

The **Context-Offload Store** provides overflow capacity for large contextual blobs that would bloat the main runtime database.

- **Schema File**: [`sqlite-context-offload-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-context-offload-schema.ts)
- **Current Version**: `1`
- **Migration Function**: `migrateSqliteContextOffloadDatabase`

The single table `context_offload` stores `session_id`, `key`, and `payload_json`, typically housing vector embeddings or large intermediate computations that are fetched on demand rather than kept in working memory.

## Schema Versioning and Migration System

Each schema module exports a `MIGRATIONS` map containing sequential SQL snippets that evolve the database from version 1 to the current target. When opening a database, the corresponding `migrateSqlite…Database` function checks the current `user_version` pragma and applies only the necessary migration steps, ensuring zero-downtime upgrades and backward compatibility.

The migration system supports idempotent upgrades; running the migrator multiple times on an up-to-date database results in no changes. This design allows Maka deployments to upgrade seamlessly without manual schema management or data export/import cycles.

## How to Query Schema Versions Programmatically

You can inspect the current schema version at runtime using the exported helper functions. The Runtime and Session-Metadata stores expose specific readers, while other stores typically rely on the standard `user_version` pragma.

```typescript
import { readUserVersion } from 'packages/storage/src/sqlite-runtime-schema.js';
import { readSqliteSessionMetadataSchemaVersion } from 'packages/storage/src/sqlite-session-metadata-schema.js';
import { DatabaseSync } from 'node:sqlite';

// Check Runtime DB version (schema version 15 as of main)
const runtimeDb = new DatabaseSync('runtime.sqlite');
const runtimeVersion = readUserVersion(runtimeDb);
console.log(`Runtime DB schema version = ${runtimeVersion}`);

// Check Session-Metadata DB version (schema version 36 as of main)
const metaDb = new DatabaseSync('session-metadata.sqlite');
const metaVersion = readSqliteSessionMetadataSchemaVersion(metaDb);
console.log(`Session-metadata DB schema version = ${metaVersion}`);

```

If the returned integer is lower than the `SQLITE_*_SCHEMA_VERSION` constant defined in the corresponding schema file, calling the migration function will automatically execute the required SQL deltas to bring the database current.

## Summary

- Apache Maka distributes persistent state across **eight specialized SQLite stores** located in `packages/storage/src/`.
- Schema versions range from **1** (Artifact, Long-Term Memory, Context-Offload) to **36** (Session-Metadata), with Runtime at **15**, Workflow at **12**, Core Execution at **6**, and Usage at **5**.
- Each store exports a `migrateSqlite…Database` function that auto-upgrades schemas using internal `MIGRATIONS` maps.
- The **Session-Metadata Store** contains the most complex schema, managing Agent Graph tables alongside traditional message storage.
- **Context-Offload** and **Long-Term Memory** stores use minimal version-1 schemas for flexible document and blob storage.
- Runtime inspection functions like `readUserVersion` and `readSqliteSessionMetadataSchemaVersion` enable programmatic version validation.

## Frequently Asked Questions

### How does Maka handle database schema migrations?

Each schema module exports a `migrateSqlite…Database` function that reads the current `user_version` pragma and applies sequential SQL migrations from an internal `MIGRATIONS` map. This automated process upgrades databases from any previous version to the latest schema without manual intervention or data loss.

### Where are the SQLite database files created in a Maka deployment?

Maka creates separate `.sqlite` files for each store domain (e.g., `runtime.sqlite`, `session-metadata.sqlite`, `artifact.sqlite`) as configured by the deployment environment. The schema definitions in `packages/storage/src/sqlite-*-schema.ts` determine the table structures within these files, but the actual file paths are determined by the storage configuration passed to the database constructors.

### What is the difference between the Runtime Store and the Core Execution Store?

The **Runtime Store** ([`sqlite-runtime-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-runtime-schema.ts), version 15) manages the execution engine's immediate operational state—tool journals, workspace versions, and continuation claims for active sessions. The **Core Execution Store** ([`sqlite-core-execution-schema.ts`](https://github.com/apache/maka/blob/main/sqlite-core-execution-schema.ts), version 6) persists the structural graph of agent runs, turn admissions, and interaction outcomes for historical analysis and debugging. Runtime handles "how the engine is running now," while Core Execution records "what the agent did."

### Why does the Session-Metadata Store have such a high schema version (36)?

The Session-Metadata Store evolves rapidly because it manages Maka's complex Agent Graph subsystem—including intents, schedules, supervisor wakes, and hierarchical task structures—alongside traditional message storage and catalog projections. The high version number reflects iterative refinements to the `session_metadata`, `agent_graph_*`, and `session_catalog_*` tables to support advanced orchestration features without breaking existing session data.