Skip to main content
Meerkat is realm-first. A realm_id is the only identity key for sharing or isolating state across surfaces.

​
Core rules

  1. Same realm_id means shared sessions, config, and runtime metadata.
  2. Different realm_id means strict isolation, even from the same folder.
  3. Backend (sqlite, redb, or jsonl) is pinned once per realm via realm_manifest.json.
  4. Realms are opaque strings. Reuse the same value to collaborate across surfaces.

​
Surface defaults

SurfaceIf realm_id is not provided
CLI (rkat run/resume/sessions)Workspace-derived stable realm (ws-...)
RPC (rkat-rpc)New opaque realm (realm-...)
REST (rkat-rest)New opaque realm (realm-...)
MCP server (rkat-mcp)New opaque realm (realm-...)
Python/TypeScript SDKWhatever the spawned rkat-rpc process picks (new opaque realm unless realm_id is passed)
This means CLI is workspace-friendly by default, while non-CLI surfaces are isolated by default.

​
Explicit sharing

Use the same realm everywhere: 
rkat --realm team-alpha run "Draft release plan"
rkat --realm team-alpha sessions list
rkat-rpc --realm team-alpha
rkat-rest --realm team-alpha
rkat-mcp --realm team-alpha
SDKs pass the same value when connecting: 
await client.connect(realm_id="team-alpha")

await client.connect({ realmId: "team-alpha" })

​
Backend pinning

On first use, a realm writes a manifest with backend choice. Later opens must honor it.
First openManifest pins
--realm-backend sqlitesqlite
--realm-backend redbredb
--realm-backend jsonljsonl
No hintsqlite when compiled, otherwise the current build default
After pinning, all surfaces use the manifest backend for that realm.

​
Default backend and same-realm sharing

When SQLite support is compiled in, new persistent realms default to sqlite.
  • sqlite is the recommended backend for the normal Meerkat operating mode where multiple processes share one realm.
  • redb remains explicitly selectable for single-owner embedded workflows.
  • jsonl remains explicitly selectable for inspectable file-based persistence.
Existing realms stay pinned to the backend recorded in their manifest. Changing the default does not migrate old realms.

​
Config and CAS

Config is realm-scoped and generation-based.
  • config/get returns: config, generation, realm_id, instance_id, backend, resolved_paths.
  • config/set and config/patch accept optional expected_generation.
  • Stale writes fail deterministically with generation conflict.

​
Why this solves multi-surface concurrency

  1. 100 RPC servers from the same folder without realm_id do not collide.
  2. 100 agents across RPC/REST/MCP/CLI with the same realm_id see the same state.
  3. CLI workspace ergonomics remain simple without forcing filesystem identity onto non-CLI surfaces.

​
See also