What Data Is Stored in `runtime.sqlite` in Apache Maka

runtime.sqlite stores Apache Maka’s operational state as a central SQLite database containing six core entities: Sessions, User Messages, Plan Reminders, Durable Cron Automations, Graph States, and Artifact Bytes.

Apache Maka persists its runtime operational state in runtime.sqlite, a file created automatically when a workspace instantiates the public storage APIs. This database serves as the single source of truth for conversation contexts, scheduled automations, knowledge graphs, and binary artifacts across user sessions.

The Six Core Data Entities in runtime.sqlite

According to the Apache Maka source code, the database schema defined in packages/storage/src/operational-state-store.ts and related files encapsulates the following entities:

Session

The Session represents the top-level execution context for a user-initiated conversation. Each record stores the session’s unique identifier, creation timestamp, and lifecycle status. This entity is defined and managed within packages/storage/src/operational-state-store.ts.

User Message

User Messages capture the initial message sent by the user that triggered a session, stored together with metadata such as timestamp and source origin. The bundling logic resides in packages/storage/src/session-bundle-policy.ts, which handles how these messages are persisted to runtime.sqlite.

Plan Reminder

A Plan Reminder is a scheduled notification that a specific Plan (a set of actions) should be revisited. Records include the plan ID, next-run timestamp, and repeat interval. Like Sessions, this entity is implemented in packages/storage/src/operational-state-store.ts.

Durable Cron Automation

Long-running, repeatable automations that survive workspace restarts are stored as Durable Cron Automations. These records contain the automation definition, cron-style schedule, and the last execution checkpoint. This persistence mechanism is also defined in packages/storage/src/operational-state-store.ts, ensuring automations resume correctly after system restarts.

Graph State

The Graph State represents the mutable knowledge-base and execution graph for each session. Stored via packages/storage/src/agent-graph-control-store.ts, this entity shares the same SQLite file as session data to ensure transactional consistency. The graph represents the agent’s current reasoning state and is updated in real-time during conversations.

Artifact Bytes

Binary blobs—including uploaded files and generated artifacts—are stored as Artifact Bytes in dedicated BLOB columns. Backup and restore operations for these artifacts are handled in packages/storage/src/operational-state-backup.ts, which manages the lifecycle of large binary data alongside the operational state.

Programmatic Access to runtime.sqlite

The constant OPERATIONAL_STATE_DATABASE_NAME = 'runtime.sqlite' in packages/storage/src/operational-state-store.ts defines the default filename. Developers interact with this database through the public storage APIs rather than raw SQL, ensuring schema integrity and proper indexing.

import { createSqliteRuntimeStore } from '@apache/maka/packages/storage';
import { join } from 'path';

// 1️⃣ Open the runtime database (creates the file if it doesn't exist)
const runtimePath = join(process.cwd(), 'runtime.sqlite');
const runtimeStore = createSqliteRuntimeStore(runtimePath);

// 2️⃣ Create a new session
const session = await runtimeStore.sessionStore.create({
  userId: 'user-123',
  createdAt: new Date(),
});

// 3️⃣ Add a user message to the session
await runtimeStore.sessionMessageStore.create({
  sessionId: session.id,
  role: 'user',
  content: 'What is the weather tomorrow?',
  timestamp: new Date(),
});

// 4️⃣ Schedule a Plan Reminder (cron-style)
await runtimeStore.planReminderStore.create({
  sessionId: session.id,
  planId: 'plan-456',
  nextRun: new Date(Date.now() + 60_000), // run in 1 minute
  repeatIntervalMs: 24 * 60 * 60 * 1000, // daily
});

// 5️⃣ Register a durable automation
await runtimeStore.automationStore.create({
  sessionId: session.id,
  name: 'daily-summary',
  cronExpression: '0 8 * * *', // every day at 08:00
  lastRun: null,
});

// 6️⃣ Query the current graph state
const graph = await runtimeStore.graphControlStore.getGraph(session.id);
console.log('Current graph nodes:', graph.nodes.length);

These methods ultimately read from and write to the same runtime.sqlite file, providing a unified interface for operational state management.

Schema Validation and Test Fixtures

The Apache Maka repository includes a concrete test fixture for version v0.1.6 (SHA-256 634d514c07df704b7f30794e5fd5aa53221b20e2833e036cdb166dfe663221e5) that validates the runtime.sqlite schema. This fixture contains a minimal but representative operational state: one Session with a user message, one Plan Reminder, and one durable cron Automation. Test suites in packages/storage/src/__tests__/ (such as operational-state-store.test.ts) use this fixture to verify schema migrations and data integrity across releases.

Summary

• runtime.sqlite is the central SQLite database for Apache Maka’s operational state, created automatically when the storage APIs initialize.
• The database stores six primary entities: Sessions, User Messages, Plan Reminders, Durable Cron Automations, Graph States, and Artifact Bytes.
• Graph State shares the same SQLite file as session data to ensure transactional consistency, implemented in packages/storage/src/agent-graph-control-store.ts.
• The OPERATIONAL_STATE_DATABASE_NAME constant defines the filename and is located in packages/storage/src/operational-state-store.ts.
• Artifact Bytes are backed up via packages/storage/src/operational-state-backup.ts, which handles binary blob persistence alongside the database.
• Version v0.1.6 test fixtures provide a validated reference schema for development and testing.

Frequently Asked Questions

Where is the runtime.sqlite file located?

By default, runtime.sqlite is created in the current working directory when you instantiate the runtime store via createSqliteRuntimeStore(). The exact path is determined by the runtimePath argument passed to the factory function, as defined by the OPERATIONAL_STATE_DATABASE_NAME constant in the operational state store implementation.

How does Apache Maka handle backups of runtime.sqlite?

The packages/storage/src/operational-state-backup.ts module provides dedicated logic for backing up and restoring runtime.sqlite along with its associated Artifact Bytes. This ensures that binary blobs and database state remain synchronized during archival or migration operations.

What is the difference between Plan Reminders and Durable Cron Automations?

Plan Reminders are lightweight, scheduled callbacks tied to specific Plan IDs that prompt the system to revisit a set of actions, storing only the plan reference and timing data. Durable Cron Automations are full automation definitions with cron expressions and execution checkpoints that survive workspace restarts, maintaining state across system lifecycles in runtime.sqlite.

Can I query runtime.sqlite directly with standard SQL tools?

Yes, runtime.sqlite is a standard SQLite file accessible via the sqlite3 CLI or any SQLite browser. However, direct manipulation is discouraged in production environments as it bypasses the validation logic in packages/storage/src/operational-state-store.ts and may corrupt the Graph State or automation checkpoints.

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