Skip to main content
Configuration is realm-scoped. The active realm_id determines which config file is read and written.

​
Realm-scoped config

Every realm has its own config file and runtime state:
  • config.toml (user settings)
  • config_state.json (generation counter for CAS)
  • realm_manifest.json (pinned backend + metadata)
The canonical location is under the platform data directory:
  • macOS: ~/Library/Application Support/meerkat/realms/<realm>/
  • Linux: ~/.local/share/meerkat/realms/<realm>/
  • Windows: %APPDATA%\meerkat\realms\<realm>\
Use realms to choose whether state is shared or isolated.

​
Effective precedence

For a given realm, effective settings are:
  1. Built-in defaults
  2. Realm config.toml
  3. Environment overrides (secrets and supported runtime env overrides)
  4. Per-request runtime parameters (for example model/system prompt/tool toggles on create/resume calls)

​
Config APIs and CAS

RPC, REST, and MCP all expose the same config envelope:
  • config
  • generation
  • realm_id
  • instance_id
  • backend
  • resolved_paths
Writes support optimistic concurrency:
  • config/set and config/patch accept optional expected_generation
  • stale writes return generation conflict
This gives deterministic behavior when multiple clients or processes update config concurrently.

​
Merge semantics

Meerkat uses two distinct update models:
  1. Layered config loading (defaults -> file -> env -> runtime) uses field-wise merge:
  • scalar/option values: last non-default wins
  • section values (for example providers, store, comms, compaction): replace whole section
  • hook entries: append/extend
  1. Runtime patch APIs (config/patch, PATCH /config) use RFC 7396 JSON merge-patch semantics.
Use config/set when replacing the whole config intentionally, and config/patch for surgical updates.

​
CLI behavior

CLI config commands operate on the selected realm: 
rkat --realm team-alpha config get --format json
rkat --realm team-alpha config get --format json --with-generation
rkat --realm team-alpha config patch --json '{"agent":{"model":"gpt-5.2"}}' --expected-generation 4
Without --realm, CLI uses the workspace-derived default realm (ws-...).

​
What about ~/.rkat/config.toml and .rkat/config.toml?

Those files still exist for compatibility and developer ergonomics (rkat init, legacy flows, and some layered hook loading behavior), but realm config is the canonical runtime configuration for CLI/RPC/REST/MCP surfaces.

​
Backend and storage settings

Session backend is pinned per realm in realm_manifest.json (sqlite, redb, or jsonl). --realm-backend only matters on first creation of a realm.

​
Compaction settings

Compaction runtime policy is configurable in realm config: 
[compaction]
auto_compact_threshold = 100000
recent_turn_budget = 4
max_summary_tokens = 4096
min_turns_between_compactions = 3
When session-compaction is enabled, AgentFactory maps these values into the runtime CompactionConfig.

​
See also