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 the live runtime handle and hide the session from normal listing while preserving committed history for later reads

​
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. Archived sessions still keep their committed transcript history on the normal runtime-backed path. Archiving retires the live runtime handle, blocks further mutation, and can still leave committed state readable depending on the surface/service implementation. It is a lifecycle visibility change, not a history wipe.

​
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
jsonlFile-based, inspectable, useful for debugging
A realm created as sqlite stays sqlite; a realm created as jsonl stays jsonl.

​
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