Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 or jsonl) is pinned once per realm via realm_manifest.json.
  4. Realm IDs are user-chosen stable identifiers with syntax constraints. Reuse the same value to collaborate across surfaces.
Realm IDs must be 1-64 characters, start with an ASCII alphanumeric character, and may contain only ASCII alphanumerics, _, and -. They cannot contain whitespace or :, and UUID-like opaque values are rejected for explicit user-facing realm IDs.

​
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 jsonljsonl
No hintsqlite when compiled, otherwise jsonl
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.
  • 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 the core envelope fields config, generation, realm_id, instance_id, and backend.
  • Some surfaces may also include diagnostic fields such as resolved_paths, but those should be treated as optional.
  • config/set and config/patch accept optional expected_generation.
  • Stale writes fail deterministically with generation conflict.
resolved_paths should be treated as a diagnostic/admin field rather than a guaranteed universal field on every public config envelope.

​
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