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

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
• 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
• 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
• 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
• 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
• 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
• 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
• 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
• 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.

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, 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, 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.

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