Sessions

This page documents MobKit v0.8.34 (mirrored from v0.8.34). Meerkat owns the canonical session and runtime lifecycle: input acceptance, turn execution, deduplication, retire/reset semantics, and durable recovery. MobKit adds session-store adapters that support MobKit’s operational workflows, console views, and integration surfaces.

This page describes MobKit-specific storage adapters. It does not replace Meerkat’s own runtime-backed session durability model.

MobKit storage backends

Backend	Use case	Description
`JsonFileSessionStore`	Local development	JSON files on disk with lock-based concurrency
`BigQuerySessionStoreAdapter`	Production	Cloud persistence via BigQuery

JSON file store

The default adapter writes session state snapshots as JSON files to a local directory. Each session gets its own file, and concurrent access is managed through lock files.

JsonFileSessionStore {
    base_dir: "/var/mobkit/sessions",
}

Lock-based concurrency. Before writing, the store acquires a lock file ({session_id}.lock). The lock contains a JsonStoreLockRecord with the process ID and acquisition timestamp. Stale lock recovery. If a process crashes while holding a lock, the lock becomes stale. On the next access attempt, the store checks whether the PID in the lock record is still alive. Dead PIDs trigger automatic lock recovery — the stale lock is removed and a new one is acquired.

BigQuery adapter

For production-oriented deployments, the BigQuery adapter writes session rows to a configured dataset and table:

BigQuerySessionStoreAdapter {
    dataset: "mobkit_sessions",
    table: "session_rows",
}

BigQuery naming is validated:

Dataset and table names must be non-empty
Only alphanumeric characters, underscores, and hyphens are allowed

BigQuery naming validation rejects special characters to prevent injection. Names like my.dataset or table;DROP are rejected.

Session persistence rows

Session state is serialized as SessionPersistenceRow records:

Field	Type	Description
`session_id`	`String`	Unique session identifier
`turn_number`	`u64`	Current turn count
`state`	`Value`	Serialized session state (messages, tool results, context)
`created_at_ms`	`u64`	Creation timestamp
`updated_at_ms`	`u64`	Last update timestamp

Session store contracts

The SessionStoreContract defines the operations every backend must implement:

Operation	Description
`write`	Persist a session row (create or update)
`read`	Load a session row by ID
`list`	List all session IDs
`delete`	Remove a session row

Contracts are verified by integration tests that run the same test suite against every backend implementation.

Materialization

MobKit provides two materialization functions for session inspection:

materialize_latest_session_rows — returns the most recent row per session
materialize_live_session_rows — returns rows for currently active sessions

These power MobKit’s operational session inspection features and adapter-specific APIs.

On-disk layout and durability

On persistent gateway launches (persistent_state), session state lives in the state directory under names owned by MobKitStorageLayout, MobKit’s single path authority: the canonical session database is sessions.sqlite3 (Meerkat’s realm spelling), and the runtime store — session resume, archive, retire — is runtime.sqlite. Legacy spellings (sessions.db, sessions.sqlite) remain readable through canonical-name-first probing: a single existing spelling is used where it lies, but two spellings of the same store refuse startup (error -32014, “file-name twins”) and point at mobkit/storage/doctor — renames happen only through the storage migrate verb. Durability is fail-closed: a runtime store that cannot open is a startup error, never a silent in-memory fallback. Running sessions in-memory on a persistent launch requires the explicit declaration runtime_options.runtime_store = {"storage": "memory"} (runtime_store.memory() / runtimeStore.memory() in the SDKs), and the choice is visible in the storage census on mobkit/status → storage.slots. See Configuration → Storage layout and durability.

Runtime correlation

When MobKit accepts a mobkit/send_message request, the response includes the Meerkat session_id that accepted the message. Treat that value as the canonical correlation handle for follow-up inspection, debugging, and resume-aware flows.

Getting started

Core concepts

Guides

MobKit storage backends

JSON file store

BigQuery adapter

Session persistence rows

Session store contracts

Materialization

On-disk layout and durability

Runtime correlation

See also

​MobKit storage backends

​JSON file store

​BigQuery adapter

​Session persistence rows

​Session store contracts

​Materialization

​On-disk layout and durability

​Runtime correlation

​See also

MobKit storage backends

JSON file store

BigQuery adapter

Session persistence rows

Session store contracts

Materialization

On-disk layout and durability

Runtime correlation

See also