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

> Discover what data resides in Apache Maka's runtime.sqlite database. Learn about its six core entities including Sessions, User Messages, and Automations.

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

---

**`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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/operational-state-store.ts).
- **Artifact Bytes** are backed up via [`packages/storage/src/operational-state-backup.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/operational-state-store.ts) and may corrupt the **Graph State** or automation checkpoints.