Skip to main content
Sessions are realm-scoped. A session is visible across surfaces only when they use the same realm_id.

​
Lifecycle

OperationWhat it does
create_sessionBuild an agent, run first turn, persist session metadata
start_turnContinue existing session; returns SESSION_BUSY if a turn is already running
interruptCancel in-flight turn
readReturn session state + usage
read_historyReturn committed transcript messages with optional pagination
listList sessions in the active realm
archiveRemove from runtime (and persistent store when supported)

​
Realm visibility rules

ScenarioResult
CLI + RPC with same realm_idShared session visibility
CLI + RPC with different realm_idStrict isolation
100 RPC servers, no realm providedEach gets its own isolated realm by default
100 agents, same explicit realm_idShared state and consistent visibility
See realms for default surface behavior.

​
Session metadata

Session metadata now carries realm context:
  • realm_id
  • instance_id
  • backend
  • config_generation
This allows deterministic resume behavior and cross-surface observability.

​
Session history

Public surfaces now expose full transcript history separately from lightweight metadata reads.
  • REST: GET /sessions/{id}/history
  • RPC: session/history
  • MCP: meerkat_history
  • Python SDK: read_session_history(), Session.history(), DeferredSession.history()
  • TypeScript SDK: readSessionHistory(), Session.history(), DeferredSession.history()
History responses return committed messages oldest-to-newest and support offset / limit pagination. They do not expose in-flight partial output.

​
Persistence and backend pinning

Backends are selected once per realm and pinned in realm_manifest.json.
BackendNotes
sqliteDurable embedded database; default for new persistent realms when compiled
redbDurable embedded database
jsonlFile-based, inspectable, useful for debugging
A realm created as sqlite stays sqlite; a realm created as jsonl stays jsonl; a realm created as redb stays redb.

​
Concurrency guarantees

  • One turn per session at a time.
  • No implicit queueing for concurrent turns.
  • interrupt() is explicit cancellation.
  • Config writes can be synchronized with generation CAS (expected_generation) to avoid lost updates during concurrent operations.
  • SQLite-backed realms support the standard same-realm multi-process workflow across CLI, REST, RPC, MCP, and SDK surfaces.

​
See also