Configuration

This page documents MobKit v0.8.34 (mirrored from v0.8.34). MobKit is configured through Rust types passed at startup. This page documents every configuration surface.

MobKitConfig

Top-level configuration for the module runtime.

MobKitConfig {
    modules: Vec<ModuleConfig>,
    discovery: DiscoverySpec,
    pre_spawn: Vec<PreSpawnData>,
}

Field	Type	Description
`modules`	`Vec<ModuleConfig>`	Module definitions to load
`discovery`	`DiscoverySpec`	Namespace and expected module list
`pre_spawn`	`Vec<PreSpawnData>`	Environment variables to inject before spawning

ModuleConfig

ModuleConfig {
    id: String,
    command: String,
    args: Vec<String>,
    restart_policy: RestartPolicy,
}

Field	Type	Default	Description
`id`	`String`	—	Unique module identifier
`command`	`String`	—	Executable path or name
`args`	`Vec<String>`	`[]`	Command-line arguments
`restart_policy`	`RestartPolicy`	`OnFailure`	Process restart behavior

RestartPolicy

enum RestartPolicy {
    Never,
    OnFailure,
    Always,
}

DiscoverySpec

DiscoverySpec {
    namespace: String,
    modules: Vec<String>,
}

Field	Type	Description
`namespace`	`String`	Logical namespace for module grouping
`modules`	`Vec<String>`	Module IDs expected in this namespace

PreSpawnData

PreSpawnData {
    module_id: String,
    env: Vec<(String, String)>,
}

Field	Type	Description
`module_id`	`String`	Target module ID
`env`	`Vec<(String, String)>`	Environment variable key-value pairs

SDK and Gateway runtime options

The stock SDK gateway (rpc_gateway) consumes the runtime_options object of mobkit/init. The Python and TypeScript builders emit it from their setters; where a row names a setter, that is the only way the SDK reaches the key, and a key with no setter on an SDK can be sent only from a hand-built mobkit/init payload. mobkit_gateway refuses a runtime_options object rather than dropping it.

Field	Type	Gateway behavior
`memory_config`	Object	Supports `{ "backend": "local_json" }` with optional `health_check_endpoint`, deriving `state_path` as `<persistent_state>/memory-ledger-state.json` (an existing legacy state file is adopted automatically). The legacy `{ "backend": "elephant", "endpoint": "..." }` shape still works but is deprecated and logs a warning; it keeps `<persistent_state>/elephant-memory-state.json`.
`identity_bootstrap_mode`	Object	Controls roster materialization for identity-first gateways. Omitted preserves the classic gateway when no roster is configured; with a roster, omission selects synchronous eager startup. Any explicit value declares identity-first intent and requires a roster provider, including `{ "mode": "eager_materialize" }`. `{ "mode": "lazy_materialize" }` registers metadata and materializes on use. `{ "mode": "lazy_with_background_warm", "concurrency": 2 }` returns after metadata registration and warms in a tracked background task; concurrency must be `1..=16`.
`agent_memory`	Boolean or object	Enables identity-first agent memory injection for roster-backed agents. `true` uses contextual recall defaults with the bundled per-realm SQLite store under `<persistent_state>/agent-memory`. The object form controls recall, injection, trust, Distiller, Steward, and provisional operator scope. `store: "markdown"` is import-only and refused with -32014. `selector` is retired: only absence or `"off"` is accepted; every activation-shaped value is refused with -32602, and recall is always deterministic lexical recall. `hygienist` is parked: only absence, `false`, or `{enabled:false}` is accepted for migration compatibility; every activation-shaped value is refused with -32602. The internal Hygienist engine remains in the Rust crate, but the public gateway has no activation seam and this release makes no provider-proof claim. `operator_scope: "provisional"` is preserved: the SDK gateway installs the console-auth-principal resolver and composes operator scope only for authenticated principals it has observed addressing an identity. Library embedders may install a different `OperatorResolver`. `TrustTier::Operator`, operator-scope schema, and re-derivation metadata remain policy-bearing contracts.
`routing_config_path`	String	Loads JSON or TOML route config (`routes = [...]` / `[[routes]]`) and installs the routes into the unified runtime before serving RPCs.
`gating_config_path`	String	Loads JSON or TOML action policies from an `actions` object and supplies a configured `risk_tier` for `mobkit/gating/evaluate` requests that omit `risk_tier`.
`auth_config`	Object	Supports JWT shared-secret auth (`provider = "jwt"` / `shared_secret`) and wires the reference HTTP console/SSE routes to the configured trusted issuer, audience, and email allowlist.
`console_config_path`	String	Loads a TOML `ConsoleUiConfig` and projects it through `/console/experience` as `console_config`. Python `.console_config(path)`, TypeScript `.consoleConfig(path)`.
`console_require_app_auth`	Boolean	Overrides `ConsolePolicy.require_app_auth`. The default is fail-closed: without `auth_config` the gateway’s decision state trusts no signing key, so a console that still requires app auth refuses every request with 401, and the gateway logs a startup warning naming this. `false` is the explicit opt-out for a local or host-protected console. Python `.console_auth_required(False)`, TypeScript `.consoleAuthRequired(false)`; the Rust library twin is `RuntimeDecisionState::local_console`.
`console_read_only`	Boolean	Sets `ConsolePolicy.read_only` for SDK `rpc_gateway` launches; mutating console RPCs are denied and omitted from capabilities while read/stream routes stay available. Python `.console_read_only()`, TypeScript `.consoleReadOnly()`.
`console_fetch_timeout_ms`	Positive integer	Sets `RuntimeDecisionState.console.fetch_timeout_ms`, which the bundled console uses for JSON fetches after the initial 60s default.
`http_listen`	`HOST:PORT` string	Bind address of the gateway HTTP listener (console, JSON-RPC, blobs, SSE, live). Default `127.0.0.1:0`: loopback, ephemeral port, the only bind every earlier release had. IP literals only, no hostnames. A non-loopback address is refused at init (`-32602`, before any bootstrap) unless `auth_config` enforces console app auth or `allow_remote` is `true`; every non-loopback bind that passes logs one WARN line. The listener is bound right behind that gate, still before any bootstrap, so a port another process holds is a `-32603` init error naming the address with no runtime built and no schedule executor lease taken behind it. The init result’s `http_base_url` stays the same-host form (`127.0.0.1` for `0.0.0.0` and `::` binds). Python `.http_listen("0.0.0.0:8080")`, TypeScript `.httpListen("0.0.0.0:8080")`. A top-level `http_listen` (the `mobkit_gateway` init-param shape) is refused with `-32602` naming `runtime_options.http_listen`. See Deployment.
`http_public_base_url`	Absolute `http(s)://` URL	The base URL clients reach the gateway at through a proxy. Reported back in the init result as `http_public_base_url` (trailing `/` removed; `null` when undeclared); never used to bind. Python `.http_public_base_url(url)`, read back as `runtime.rust_http_public_base_url`; TypeScript `.httpPublicBaseUrl(url)`, read back as `runtime.rustHttpPublicBaseUrl`.
`allow_remote`	Boolean	Explicit acknowledgement that `http_listen` exposes the listener beyond this host; the same word and rule as `--allow-remote` on `rkat-rpc --tcp` and `rkat mob host --listen-tcp`. An exposure opt-in, not an auth mechanism: pass it only with an authenticating proxy in front of the listener. Python `.allow_remote()`, TypeScript `.allowRemote()`.
`member_comms_address`	Socket-address string	Binds each local member to a signed TCP endpoint that remote peers can dial. Wildcard addresses are refused because they cannot be advertised as a concrete route.
`contacts_toml`	TOML string	Loads the contact directory used to resolve remote mob ids to TCP/UDS control endpoints and pinned gateway public keys.
`control_grants_toml`	TOML string	Loads the closed `[control_grants]` table for `--control-listen`. Each caller public key is scoped to named control verbs and members, and the gateway binds every request signature to the local mob id as its audience. Omitting the field installs an empty deny-all table; an explicit value without `[control_grants]`, or with an unknown/invalid field, fails initialization.
`event_log`	Object	Declares the operational event log. `storage = "memory"` (with optional `batch_size`, `flush_interval_ms`) keeps a bounded queryable in-process store so `mobkit/query_events` returns events instead of `no_event_log_configured`; `storage = "null"` declares that events are dropped. Both are declared-ephemeral choices; omitting the key means no ingestion at all, and any other storage kind fails initialization. Durable event-log backends are embedder-only (`UnifiedRuntimeBuilder` accepts any `EventLogStore`).
`runtime_store`	Object	Declares the runtime store’s durability. The store (`runtime.sqlite` — session resume, archive, retire) is persistent SQLite by default; the only accepted declaration is `{ "storage": "memory" }`, after which sessions do not survive gateway restart. A failed SQLite open without this declaration is a startup error (`-32014`), never a silent in-memory fallback.
`declare_spec_update`	Object	One-shot canonical mob-definition compare-and-swap. `{ "expected_revision": N }` applies the `mob_config` supplied in the same `mobkit/init` request only when the durable definition is still at `N`. The launch must be authoritative and use persistent mob storage. Exact replay converges; stale revision or successor-content disagreement refuses initialization with typed storage error `-32014`.
`compaction`	Object	Declares the host-level session-compaction policy for every agent the gateway builds: `auto_compact_threshold` (tokens, non-zero), `recent_turn_budget`, `max_summary_tokens`, `min_turns_between_compactions`. A compactor is always installed; this declares when it fires. Omitting `auto_compact_threshold` inherits Meerkat’s model-aware default — `context_window * 4 / 5`, i.e. ~840,000 tokens on a million-token model such as `gpt-5.6-sol`, which in practice never fires and resends the full transcript every turn. Declaring the key pins it. A mob profile’s own `auto_compact_threshold` still wins per member. Unknown keys and a zero threshold fail initialization.
`meerkat_config_path`	String path	The Meerkat host `config.toml` every agent the gateway builds starts from (the live/realtime door included), loaded once at init, merged over `Config::default()` with Meerkat’s own file semantics and validated with Meerkat’s own `Config::validate` against the canonical catalog. This is the only door for the `[self_hosted]` and `[realm]` tables, which Meerkat keeps in the host config rather than in `mob.toml`; a host-config `[models]` table reaches the factory too, but does not satisfy the init model check, which reads the definition’s own `[models.<id>]`. The gateway’s own overlays (`member_comms_address`, `compaction`) are layered on top. A missing, malformed or non-validating file (a `[self_hosted.models.<id>]` alias naming an undeclared server, for one) refuses init with `-32602` naming the option and the path, never a silent `Config::default()`. Omitted, agents build from Meerkat’s default config as before. Python `.meerkat_config(path)`, TypeScript `.meerkatConfig(path)`. `mobkit_gateway` takes the same file as its top-level `meerkat_config_path` init param and adopts `<workspace>/.rkat/config.toml` when it exists, logging one INFO line naming the adopted file either way; a top-level `meerkat_config_path` sent to `rpc_gateway` is refused with `-32602` naming `runtime_options.meerkat_config_path`. See Self-hosted models and the Meerkat host config.
`workgraph`	Boolean or directory string	WorkGraph construction switch, default `true`. `false` disables the store, the member `workgraph_` tools, the attention overlays and the `mobkit/workgraph/` RPCs; a non-empty string is an explicit directory for the durable store (`workgraph.sqlite3` is created inside it); any other value fails initialization. Python `.workgraph(enabled)` and TypeScript `.workgraph(enabled)` take `true`, `false` or the directory string; an unused setter sends nothing and the gateway default applies. Store placement per launch mode, the auto-issued namespace grant and the memory-backed fallback are in WorkGraph.

Unsupported nested fields fail initialization with -32602 instead of being silently ignored.

Model fallback

Automatic model fallback is off by default. An enabled policy requires an explicit, non-empty chain; an empty chain never walks the model catalog. Meerkat owns retry eligibility, target admission, credentials, and committed model routing. MobKit forwards that policy without adding its own retry loop. The host file selected by meerkat_config_path accepts [model_fallback]. Rust embedders can pass the same meerkat::Config to UnifiedRuntimeBuilder::meerkat_config. In mob.toml, use [runtime.model_fallback] for a mob default or [profiles.<name>.model_fallback] on an inline profile:

[runtime.model_fallback]
enabled = true
chain = [{ model = "gpt-5.5", provider = "openai" }]

[runtime.model_fallback.policy]
cross_provider = false
min_context_headroom = 0.10
require_tool_parity = true
trigger_after_attempts = 3
triggers = ["provider_unavailable", "capacity"]

# A profile can explicitly disable an inherited policy.
[profiles.coordinator.model_fallback]
enabled = false

The first present whole table wins: profile, then mob runtime, then host configuration. Omission inherits; an explicit enabled = false wins over an enabled parent. Tables are not merged field by field, so a profile does not silently borrow its parent’s chain. A realm-profile reference cannot carry a sibling fallback override; put it on the referenced profile or the mob runtime. Unknown fallback keys, use_catalog_default_chain, invalid policy values, and enabled = true without a chain are errors. There is no separate runtime_options.model_fallback gateway option. Cross-provider fallback requires explicit cross_provider = true and a usable authorized credential binding; omission does not authorize switching accounts. Targets must pass Meerkat’s context, output-budget, tool and modality admission. Transport failures and empty output are not default fallback triggers. New fallback provenance can cause an unsafe restored route to be held with a typed error. Historical sessions without that provenance are not inferred to be fallback sessions, automatically reverted, or migrated. Existing explicit operator model/provider resume masks retain their authority. The host config setter affects builder-created member session services, not an already-built .mob_spec() service. Native background memory engines currently use their own default config (also fallback-off); this table does not configure those engines. This release does not add fallback overlays, automatic reversion, or a routing-repair CLI.

One-shot mob definition update

Python hosts use the supported builder ceremony on the single activation authorized to change the durable definition:

runtime = await (
    MobKit.builder()
    .mob("config/mob.toml")  # complete replacement definition
    .persistent_state("/var/lib/homecore")
    .declare_spec_update(expected_revision=1)
    .gateway("/path/to/rpc_gateway")
    .build()
)

The builder sends the replacement TOML as top-level mob_config and emits:

{
  "runtime_options": {
    "mob_composition": {"authority": "authoritative"},
    "declare_spec_update": {"expected_revision": 1}
  }
}

The gateway delegates the mutation to Meerkat’s canonical definition CAS. It does not append raw events, rewrite a projection independently, or treat the creation manifest as mutable authority. Remove declare_spec_update(...) from later ordinary restarts. A stale revision or different successor definition raises Python StorageResolutionError; an exact retry returns the already committed successor revision and converges its checked projection. This is a cold-activation ceremony, not a hot reload. Fully shut down the prior runtime before issuing the update: an already-running MobHandle keeps the definition it was constructed with. The CAS and verified-resume fence serialize the update with the next bootstrap, but they do not reconfigure an older live process.

runtime_options.scheduling_files was removed in contract 0.5.0 and is an unsupported field. Move definitions to the durable schedule store through schedule tools or ScheduleService.

Self-hosted models and the Meerkat host config

Meerkat keeps three tables out of the mob definition and in the host config.toml: [self_hosted] (serving endpoints and model aliases), [realm] (backend, auth and binding profiles, including the credential binding every provider = "self_hosted" member resolves through) and [models] (custom model rows). A mob.toml profile refers to them by name only:

mob.toml

[profiles.worker]
model = "gemma-4-31b"
provider = "self_hosted"
self_hosted_server_id = "local"

config.toml

[self_hosted]
default_model = "gemma-4-31b"

[self_hosted.servers.local]
transport = "openai_compatible"
base_url = "http://127.0.0.1:11434"
api_style = "chat_completions"

[self_hosted.models.gemma-4-31b]
server = "local"
remote_model = "gemma4:31b"

[realm.global]
default_binding = "local"

[realm.global.backend.local]
provider = "self_hosted"
backend_kind = "self_hosted"
server = "local"

[realm.global.auth.local_auth]
provider = "self_hosted"
auth_method = "none"
source = { kind = "platform_default" }

[realm.global.binding.local]
backend_profile = "local"
auth_profile = "local_auth"

The alias shape, the realm binding rules and the Gemma 4 worked example are Meerkat’s contract, documented in the Meerkat self-hosting guide; MobKit adds nothing to them. Note that [models.<id>] provider = "self_hosted" is refused by Meerkat’s model registry: self-hosted aliases live under [self_hosted.models] only. [self_hosted] and [realm] belong in the host config, never in mob.toml. MobDefinition::from_toml deserializes without deny_unknown_fields, so a top-level [self_hosted] or [realm] table written into mob.toml used to vanish without a diagnostic and resurface two layers later as a member that could not build. Both binaries now refuse it at init, on the raw TOML text, with one message:

mob.toml declares a top-level [self_hosted] table, which is meerkat host configuration
that the mob definition parser ignores; move it into the meerkat config.toml and point the
gateway at that file: runtime_options.meerkat_config_path on rpc_gateway, or the
meerkat_config_path init param (default <workspace>/.rkat/config.toml) on mobkit_gateway

Both binaries answer it as -32602 on the mobkit/init request id (mobkit_gateway when it loads config/mob.toml). [models.<id>] is different from the two tables above. A profile’s model must be catalogued, provider-annotated, or defined under the mob definition’s own [models.<id>] to pass the model check: the check (meerkat_mob::validate_definition, run at init on rpc_gateway and by Meerkat at create time on both binaries) reads only the definition’s tables. So a custom model a profile names by id belongs in mob.toml. A [models] table in the host config still reaches the factory through meerkat_config_path (a provider-annotated profile can use such a row), but it does not satisfy the check, and a profile whose model exists only there and carries no provider is refused at init as UnknownModel.

How the host config reaches each surface

Surface	Ingress	When nothing is declared
`rpc_gateway`	`runtime_options.meerkat_config_path`; Python `.meerkat_config(path)`, TypeScript `.meerkatConfig(path)`	`Config::default()`, as in every earlier release
`mobkit_gateway`	Top-level `meerkat_config_path` init param (a relative path resolves against the launch directory); the file’s content joins the resume fingerprint, so a changed host config does not resume a runtime built without it	`<workspace>/.rkat/config.toml` when that file exists (`ConventionalPaths::with_meerkat_config_from_workspace`), else `Config::default()`
Rust library	`UnifiedRuntimeBuilder::meerkat_config(config)`; `gateway_composition::load_gateway_host_config(path)` is the loader both binaries use and `refuse_host_config_tables_in_mob_toml(text)` the `mob.toml` check	`Config::default()`

The loader reads exactly the named file and merges it over Config::default() with Config::merge_toml_str, the step Meerkat applies to a discovered .rkat/config.toml: no directory walk and no home-directory fallback, so what the gateway loads is what the operator named. Adoption is never silent: mobkit_gateway logs one INFO line naming the adopted file and whether the init param or the workspace convention produced it. A file that cannot be read or does not parse or does not validate refuses init (rpc_gateway: -32602, runtime_options.meerkat_config_path: failed to read meerkat config <path>: ..., meerkat config <path> is invalid: ... or meerkat config <path> does not validate: ...; mobkit_gateway: -32602 on the request id, init params: meerkat_config_path: ...), because an operator who pointed the gateway at a file expects that file in force. Validation is Meerkat’s own Config::validate against the canonical catalog, the step rkat and rkat-rpc run after every load: a [self_hosted.models.<id>] alias whose server is not declared, a [models.<id>] row colliding with a catalog id, or a zero compaction threshold is refused at init instead of killing the first member build. The gateway’s own declarations stay layered on top: member_comms_address and compaction on rpc_gateway, compaction on mobkit_gateway, and a profile’s own auto_compact_threshold still wins per member.

The init model check

rpc_gateway checks every inline profile’s model before the mob exists, by Meerkat’s own rule (meerkat_mob::validate_definition, narrowed to its UnknownModel diagnostic): a model is acceptable when it is catalogued, or defined under this definition’s [models.<id>], or provider-annotated (provider = "self_hosted" with a self_hosted_server_id, for one). This is the rule rkat mob validate documents and MobBuilder::create applies at bootstrap. A refused model is -32602 with the profile named and, when a catalog id is close, a Did you mean one of: ...? hint (the common cause is a dated id such as claude-sonnet-4-5-20250514 for claude-sonnet-4-5). Only that one diagnostic is adopted at init on purpose: the rest of the set (missing skill refs, wiring, flows) is Meerkat’s to refuse at create time. mobkit_gateway has no pre-check; Meerkat runs the same validation when it creates the mob. Provider-annotated profiles bypass the refusal. By Meerkat’s rule a profile that sets provider = "..." is resolvable whatever its model string says, so a dated or misspelled id on such a profile (every HomeCore profile carries provider = "openai") passes init and surfaces at the first LLM call. rpc_gateway does not add a second refusal authority for that case; it logs one WARN per such profile at init naming the profile, the model and the closest catalog ids (profiles.<p> model '<m>' is provider-annotated ... a typo surfaces at the first LLM call. Did you mean one of: ...?). A provider = "self_hosted" alias is checked against the host config’s [self_hosted.models] instead and warned about only when it is not registered there. Catalogued and [models.<id>]-defined models warn about nothing. Earlier releases compared the model string against the static catalog alone, so a [models.<id>] custom model and every self-hosted alias were refused at init on rpc_gateway while mobkit_gateway accepted them and then failed at the first member build with “self-hosted model ’..’ is not registered in config”; both binaries now agree, and with meerkat_config_path the member builds.

Member role migrations

role_migrations is a top-level mobkit/init param, a sibling of runtime_options rather than a field inside it. On rpc_gateway, runtime_options is a closed allowlist and unknown keys are a hard error, so nesting the declaration there fails initialization with unsupported runtime_options fields: role_migrations. A durable member whose role changed refuses to resume: Meerkat returns MobError::MemberRoleMigrationRequired rather than silently restamping the member’s durable role, comms name and binding together. The host clears that refusal by declaring, for one boot, which exact identity is migrating and which role it is migrating from.

{
  "role_migrations": [
    { "identity": "domain:home-automation", "from_role": "domain" }
  ]
}

Python hosts declare the same thing through the builder:

from meerkat_mobkit import MobKit, RoleMigrationDeclaration

runtime = await (
    MobKit.builder()
    .gateway("./target/debug/rpc_gateway")
    .roster(roster_provider)
    .role_migrations(
        [
            RoleMigrationDeclaration(
                identity="domain:home-automation", from_role="domain"
            )
        ]
    )
    .build()
)

.role_migrations([...]) accepts RoleMigrationDeclaration dataclasses or plain dicts and validates both; a conflicting pair raises ValueError; leaving the setter unused emits no role_migrations key at all. The TypeScript builder exposes no equivalent setter.

Property	Behavior
Lifetime	Boot-scoped. The list is installed on the session bridge, which lives for exactly one boot, and is never written to the continuity store. Dropping it from the next boot payload is how the authority goes away.
Matching	Exact `AgentIdentity` match. No prefix, suffix, or case variant of a declared identity inherits authority.
Authority	MobKit only carries the declared predecessor role into the resume request. Meerkat re-verifies it against durable state and refuses with `MobError::MemberRoleMigrationRejected` on mismatch; MobKit never infers a declaration and never retries a resume Meerkat refused.
Leftovers	Once the durable and requested roles agree, Meerkat returns before reading the declaration, so a declaration left in place after the migration landed is inert. An identical repeated declaration is therefore accepted on purpose.
Bad payloads	A payload that does not deserialize refuses the boot rather than arming nothing. One identity declared twice with conflicting predecessor roles is refused too, because nothing but map order could pick which predecessor becomes authority.

The two gateway binaries, whose names differ by one word, refuse bad payloads differently and install accepted ones under different conditions.

Binary	Refusals	Install condition
`rpc_gateway` (untyped init params; what SDK hosts run)	Parses and conflict-checks at init scope, answering both the malformed and the conflicting case with `-32602` on the request id	Inside the roster-provider branch
`mobkit_gateway` (typed `InitParams`)	Malformed params fail typed deserialization and answer `-32602` with a null `id`; the conflict check sits inside the identity-first block and fails the boot out as `-32603`, also with a null `id`. Under `identity_first: false` that block never runs, so a self-contradicting payload is not refused at all; `identity_first` defaults to true	Inside the identity-first block

Declarations that reach neither identity plane arm nothing, because there is no identity plane to migrate on. See roster and member lifecycle for the operator view of the refusal.

Mob profile tools (`[profiles.*.tools]`)

The mob definition (.mob("config/mob.toml"), or the mob_config string of mobkit/init) is Meerkat’s MobDefinition. Each [profiles.<name>.tools] table is meerkat-mob’s ToolConfig, and every boolean in it defaults to false. The table has no unknown-key check, so a misspelled key (comm = true) is dropped and the flag it meant to set stays false.

[profiles.assistant.tools]
comms = true
builtins = true
workgraph = true
schedule = true

Key	Default	Effect
`comms`	`false`	Must be `true` for every profile a member spawns from. A member’s durable identity, roster occupancy check, wiring, peer messaging and supervisor bridge are all keyed on its comms name, and the peer-messaging tools are composed whenever a member has one, so there is no honest member without comms: Meerkat refuses `comms = false`, and an omitted key, at build time with `MobError::WiringError`: `profile '<name>' has tools.comms=false; mob meerkats require comms=true`. On the worker plane `mobkit/ensure_member` answers `-32602` with `ensure_member failed: wiring error: ...` and creates no roster entry; on the identity plane the identity reconciles to outcome `broken` (`EmbodimentFailed`, the message as its detail), `mobkit/status_identity_bootstrap` carries it as `error`, and the continuity repair task retries what is a static configuration error. To keep a member from messaging peers, leave `comms = true` and set `read_only = true` (`send_message` is denied, `peers` stays permitted) or deny the tools through a per-spawn tool access policy. Mobpack validation does not flag this; it fails at spawn.
`builtins`	`false`	Meerkat’s built-in tools (task, blob, patch, datetime, web search and similar). When `workgraph` is `false` and `builtins` is `true`, the `task-workflow` skill is preloaded.
`shell`	`false`	The shell execution tool. Never read-only: nothing classifies a command line, so `read_only = true` denies it outright.
`memory`	`false`	Memory and semantic-search tools.
`workgraph`	`false`	The realm-scoped `workgraph_*` tools; preloads the `workgraph-workflow` skill. The namespace grant the tools need is issued by the gateway, not the host (see WorkGraph).
`mob`	`false`	Mob management tools (spawn, retire, wire, unwire, list). Without a host-supplied authority context the member is granted spawn authority over every profile in the definition.
`schedule`	`false`	Durable schedule tools (create, list, update, pause, resume, delete).
`image_generation`	`false`	Image generation tools; the profile’s `image_generation_provider` names the backend.
`read_only`	`false`	An enforcement declaration, not prompt guidance: a tool call executes only when its owning dispatcher declares it read-only, and the declaration wins over any per-spawn tool access policy. The category booleans above still decide what the model sees; this decides what may run. Provider-native tools, MCP tools and `shell` are outside the guarantee.
`mcp`	`[]`	MCP server names this profile may use from the mob-wide default external-tools provider; an empty list means the full host surface.
`mcp_servers`	`[]`	Declarative MCP server configs durable on the profile, so a revived member recomposes the same MCP tools that built it.
`rust_bundles`	`[]`	Names of Rust tool bundles registered at mob construction. Not serializable; re-register them on resume.

The mob-communication skill is preloaded for every member regardless of these flags. Agent-side spawns that inherit the parent’s tool filter open every category, including comms, before the inherited allow-list is applied, so the comms refusal is a host-spawn (mobkit/ensure_member) behaviour; an agent spawn of a comms = false profile silently runs with comms on.

WorkGraph

rpc_gateway constructs a realm-scoped WorkGraphService on every launch unless runtime_options.workgraph is false (the default is true, so a launch that never mentions the key has one). The service backs the member workgraph_* tools, the mob-executor attention overlays and the mobkit/workgraph/* RPCs.

Launch	`workgraph: true` (default)	`workgraph: "<dir>"`
With `persistent_state`	Durable `SqliteWorkGraphStore` at `<persistent_state>/workgraph.sqlite3`, the `workgraph` storage slot. If the store fails to open, the slot reports `degraded` and WorkGraph is disabled for that launch; nothing falls back to memory.	Durable store at `<dir>/workgraph.sqlite3`, created if needed, same open-failure posture.
Without `persistent_state`	Memory-backed `MemoryWorkGraphStore`, reported as a declared-ephemeral slot: goals, work items and attention bindings do not survive a gateway restart. On an identity-first launch that persists through an SDK-hosted continuity store the gateway logs one WARN line naming this, because everything else about that launch is durable.	Durable store at `<dir>/workgraph.sqlite3`; the directory form exists for exactly this case.

mobkit_gateway has no switch: its persistent mode attaches the durable store from the workspace state dir (same degraded posture on open failure) and its default ephemeral launch is memory-backed. The namespace grant is issued by the gateway, not the host. Meerkat refuses to build an agent that has WorkGraph tools and no host-issued WorkGraphNamespaceGrant. Whenever MobKit installs the tools it takes the grant from the service it just built, so the grant names the same scope the tools are pinned to: realm mob.<mob definition id> (Meerkat’s canonical mob realm, the one every other realm-scoped store for the mob uses; if it cannot be formed the raw id is used and Meerkat’s own validation names both realms) and namespace default. Every workgraph_* tool call has its realm_id and namespace arguments overwritten with that scope and all_namespaces removed, so a member cannot wander into another mob’s graph. The meerkat WorkGraph guide’s “embedding hosts must issue the grant in the agent build” is a Rust-embedder instruction; SDK hosts have nothing to issue. The tools stay per-profile: a member sees them only when its profile sets tools.workgraph = true, while the mobkit/workgraph/* RPCs are available whenever the service exists.

Storage layout and durability

MobKitStorageLayout is the single path authority for storage roots and the canonical top-level database locators; no gateway or builder surface derives state-dir file names or resolves ambient roots ($XDG_STATE_HOME, $HOME) on its own, and a CI gate (tests/storage_gate.rs) keeps it that way. Feature code owns relative names beneath the layout’s roots (the blob directory’s internal sharding, per-realm agent-memory files). Canonical spellings (decided once; stores shared with Meerkat keep Meerkat’s names, MobKit-owned files converge on *.sqlite3):

Slot	Canonical name	Legacy spellings (still readable)
sessions	`sessions.sqlite3`	`sessions.db`, `sessions.sqlite`
runtime	`runtime.sqlite`	—
schedule	`schedule.sqlite`	—
workgraph	`workgraph.sqlite3`	—
continuity	`continuity.sqlite3`	`continuity.db`, `identity_continuity.sqlite`
metadata	`mobkit_metadata.sqlite3`	`mobkit_metadata.sqlite`
console	`mobkit_console.sqlite3`	`mobkit_console.sqlite`
agent-memory root	`agent-memory/`	`agent-memory-sqlite/`
event log	`event_log.sqlite3` (reserved)	—
blob root	`blobs/`	—

Canonical-name-first probing. Opening a slot resolves the canonical name first, then probes the known legacy spellings in the same directory. Exactly one spelling → it is used where it lies (no rename at open). Two spellings of the same store → the gateway refuses to start (error -32014, “file-name twins”) and points at mobkit/storage/doctor; physical renames happen only through the storage migrate verb, under the maintenance fence. Durability classes and the declaration requirement. Every composed slot resolves to a durability class (durable / scratch) and a resolution (persistent / declared_ephemeral / non_persistent). A durable-class slot may run non-persistent only as an explicit declaration (runtime_options.runtime_store, runtime_options.event_log, the Rust builder’s ephemeral_runtime_store(true) / ephemeral_blobs(true)) — never as a silent fallback; undeclared gaps are startup errors that SDKs surface as the typed StorageResolutionError (-32014). The sanctioned boot-without degradations (schedule or workgraph store open failure) disable the feature and appear as degraded slots. Storage census surfaces. The resolved picture rides the storage object on mobkit/status, mobkit/capabilities, and mobkit/storage/doctor: blob_durability / blob_store_persistent (H1), session_store_incremental (H2), and the per-slot slots array (domain, class, resolution, backend, degraded, optional detail).

Changelog policy. Any storage file rename or table move gets the binary-rename treatment: an explicit, loud changelog entry naming the old and new spellings — operators read these files directly.

Identity bootstrap

Rust
Python

use meerkat_mobkit::{IdentityBootstrapMode, UnifiedRuntime};

let runtime = UnifiedRuntime::builder()
    .definition(definition)
    .continuity_store(continuity_store)
    .lease_provider(lease_provider)
    .scratch_dir("state/identity-scratch")
    .roster_provider(roster_provider)
    .identity_bootstrap_mode(
        IdentityBootstrapMode::LazyWithBackgroundWarm { concurrency: 2 },
    )
    .build()
    .await?;

let status = runtime
    .identity_runtime()
    .expect("identity-first runtime")
    .identity_bootstrap_status();

from meerkat_mobkit import IdentityBootstrapMode, MobKit

runtime = await (
    MobKit.builder()
    .gateway("./target/debug/rpc_gateway")
    .mob("config/mob.toml")
    .persistent_state("state/mobkit")
    .roster(roster_provider)
    .identity_bootstrap_mode(
        IdentityBootstrapMode.lazy_with_background_warm(concurrency=2)
    )
    .build()
)

status = await runtime.wait_identity_bootstrap(
    target="startup_ready",
    timeout=120,
)
if not status.ready or status.startup_ready is not True:
    raise RuntimeError(status)

Calling a Rust or Python identity_bootstrap_mode setter is an explicit identity-first configuration and therefore requires a roster provider for all three modes. Leave the setter unused to retain a classic non-identity gateway; a configured roster with no mode continues to use eager materialization. mobkit/status_identity_bootstrap returns a non-blocking typed snapshot. mobkit/wait_identity_bootstrap accepts target = "materialized" or "startup_ready"; terminal broken identities return with ready = false rather than leaving the barrier pending indefinitely. Provider or restore failures that apply to the whole pass are reported in the snapshot’s optional error field. The stock persistent gateway also advertises a private shutdown handshake and its bounded stdio_shutdown_horizon_ms in the mobkit/init result. SDK hosts keep stdin and provider callbacks open until that handshake completes, then close the process. The current 335-second horizon covers an already-admitted provider callback, runtime event and mob drains, the final lease-release callback, and bounded response-delivery/reaping margin. Provider operations must resolve or reject within their public 120-second contract. The Python host allows 125 seconds for event-loop completion before cancelling that callback; the TypeScript host exposes the same cancellation as an optional ProviderCallbackContext and suppresses late callback responses; the gateway enforces a final 130-second hard wire deadline. Provider rejection, timeout, or cancellation is pre-commit: an implementation must not commit a replacement grant or other external authority after cancellation is observed. Older and custom gateways that do not advertise the handshake retain the EOF shutdown protocol. If the gateway exhausts its runtime deadline, it reports incomplete cleanup; the SDK still reaps the bounded child process and then surfaces the failure. Rust hosts that dispatch JSON-RPC from an Arc<UnifiedRuntime> should call handle_unified_rpc_json_arc (or the corresponding with_live_arc entrypoint). That transfers runtime ownership to supervised identity mutations, so a disconnected request cannot cancel a cross-mob operation between its commit and rollback points. The borrowed dispatcher fails identity-owned cross-mob mutations closed because it cannot provide that ownership guarantee.

`mobkit_gateway` identity roster

identity_roster is a top-level mobkit/init param of mobkit_gateway (typed InitParams), the standalone counterpart of the SDK roster provider that rpc_gateway reaches through .roster(...) callbacks; rpc_gateway has no identity_roster key. It is an array of DurableAgentSpec objects and seeds the desired identity roster for identity_first: true (the default):

{
  "identity_roster": [
    { "identity": "personal:alice", "profile": "alpha" },
    {
      "identity": "domain:security",
      "profile": "security",
      "display_name": "Security",
      "labels": { "console_group": "Internal" },
      "runtime_mode_override": "turn_driven"
    }
  ]
}

Field	Required	Meaning
`identity`	yes	`AgentIdentity` (`<kind>:<name>`), the durable identity key.
`profile`	yes	A `[profiles.<name>]` of the mob definition.
`addressability`	no	`addressable` (default; accepts `send`) or `internal_only` (`dispatch` only).
`display_name`, `labels`, `context`, `additional_instructions`	no	Console name, string labels, opaque JSON app context, extra prompt instructions.
`initial_message`, `runtime_mode_override`	no	The kickoff turn and the per-identity `autonomous_host` / `turn_driven` override, as on the SDK `DurableAgentSpec`.
`backend`, `binding`, `placement`	no	Backend kind, runtime binding and exact Meerkat host placement; a placement never degrades to local.

At boot the seed becomes the MutableRosterProvider and restore_flow runs over it: the roster is validated, continuity is resolved for every listed identity, and each non-Broken identity is created or resumed. Omitting the param is an empty seed, so the gateway starts with no identities and mobkit/ensure_member adds them at runtime (it upserts the same provider). The seed is boot-scoped like role_migrations: it is never persisted, and an identity missing from the next boot’s seed is not restored on that boot (its continuity record is untouched). Under identity_first: false the param is parsed and ignored, not refused.

ConsoleUiConfig

View-level configuration for the stock console. mobkit_gateway discovers config/console.toml in the conventional workspace layout; rpc_gateway accepts the same file via runtime_options.console_config_path, and the TypeScript builder exposes .consoleConfig("config/console.toml"). The config is normalized and projected through GET /console/experience as console_config.

title = "OB3"

[brand]
label = "Open Brain"
logo_url = "/assets/ob3.svg"
logo_alt = "OB3"

[appearance]
default_theme = "dark"
default_variant = "graphite"

[environment]
label = "prod"

[layout]
initial_preset = "two_columns"
initial_control = "roster"
initial_agent = "identity:ops-lead"
sidebar_collapsed = false

[rail]
visible = true
collapsed = false
active_preset_id = "critical"
empty_text = "No meaningful signals yet."

[[rail.filter_presets]]
id = "critical"
label = "Critical"
watched_only = true
alert_levels = ["critical"]

[sidebar]
visible_controls = ["topology", "roster", "logs", "health"]
hidden_controls = []

[[sidebar.buttons]]
id = "ob3-board"
label = "OB3 Board"
href = "https://example.test/ob3"
target = "_blank"
icon_name = "external-link"

[agent_list]
group_by = ["labels.console_group", "labels.group", "role"]
subgroup_by = ["labels.org", "labels.realm"]
section_order = ["Personal", "Initiatives", "Internal"]
fallback_group = "Agents"
fallback_subgroup = "Other"
default_pinned_agent_ids = ["identity:ops-lead"]
collapse_single_subgroup = true

[[agent_list.badges]]
id = "org"
label = "Org"
field = "labels.org"
tone = "info"

[[agent_list.sections]]
name = "Initiatives"
collapsed = false
empty_title = "No initiatives"
empty_text = "Create one in Linear."

[actions]
inspect_label = "Profile"
chat_label = "Open chat"
send_label = "Send to agent"
respawn_label = "Respawn"
retire_label = "Retire"
reset_label = "Reset"
show_reset = false

[realms.ob3]
title = "OB3"

[realms.ob3.agent_list]
subgroup_by = ["labels.org"]

Section	Description
`brand`	Label and logo metadata.
`appearance`	Default theme and variant.
`environment`	Short environment label shown in the topbar.
`layout`	Initial preset/control/agent and sidebar collapsed default.
`rail`	Signals rail visibility, collapsed state, empty text, and filter presets.
`sidebar`	Stock control visibility and custom buttons.
`agent_list`	Grouping selectors, section order, default pins, badges, and empty states.
`actions`	Operator-facing action labels and visibility toggles.
`realms.<id>`	Partial overlay applied when the gateway is launched for a realm.

Agent grouping selectors and badge fields support labels.<key>, label:<key>, raw label keys, and direct fields such as group, subgroup, role, kind, identity, member_id, and agent_id.

ConsoleUiConfig is intentionally view-level. It controls presentation, ordering, labels, default pins, and links; it does not decide runtime authorization, routing, or whether an agent exists.

AuthPolicy

AuthPolicy {
    default_provider: AuthProvider,
    email_allowlist: Vec<String>,
}

Field	Type	Default	Description
`default_provider`	`AuthProvider`	`GoogleOAuth`	Expected identity provider
`email_allowlist`	`Vec<String>`	`[]`	Allowed email addresses and service identities

AuthProvider

enum AuthProvider {
    GoogleOAuth,
    GitHubOAuth,
    GenericOidc,
    ServiceIdentity,
    TestProvider,
}

ConsolePolicy

ConsolePolicy {
    require_app_auth: bool,
    read_only: bool,
    fetch_timeout_ms: Option<u64>,
}

Field	Type	Default	Description
`require_app_auth`	`bool`	`true`	Whether console routes require JWT authentication
`read_only`	`bool`	`false`	Whether the console is view-only; when enabled, send/upload/lifecycle/gating-write RPCs return a read-only error
`fetch_timeout_ms`	`Option<u64>`	`None`	Optional bundled-console JSON fetch timeout override, projected through `/console/experience`

For standalone mobkit_gateway launches, pass console_read_only: true in the mobkit/init params or set MOBKIT_CONSOLE_READ_ONLY=true. This setting is part of the gateway resume fingerprint, so toggling it creates or resumes the matching runtime instead of reusing a runtime launched with the opposite policy. mobkit_gateway takes the HTTP exposure knobs as top-level mobkit/init params rather than runtime_options: http_listen (HOST:PORT, default 127.0.0.1:0; also --http-listen or MOBKIT_HTTP_LISTEN_ADDR, the init param winning), allow_remote (also --allow-remote or MOBKIT_HTTP_ALLOW_REMOTE=1) and http_public_base_url. Its console is always open, so a non-loopback http_listen is refused unless allow_remote is set. Every init-param refusal on this binary (http_listen parse, the exposure gate, http_public_base_url, meerkat_config_path, compaction, a [self_hosted] table in mob.toml) answers -32602 on the request id, and a listener bind failure -32603 on the request id. The listen address and the advertised base both join the resume fingerprint like --control-listen, so a relaunch that changes either creates a runtime with the declared values instead of reporting the previous launch’s. The mirror rule holds on rpc_gateway: the same four keys sent top-level there are refused with -32602 naming their runtime_options.* home. See Deployment.

Console auth by surface

require_app_auth defaults to true, and the SDK gateway’s decision state without auth_config trusts no signing key, so the default console is closed to every caller (each request answers 401 missing_credentials or a token failure). Opening it is an explicit, per-surface choice:

Surface	Explicit opt-out
Raw `mobkit/init`	`runtime_options.console_require_app_auth: false`
Python	`MobKit.builder().console_auth_required(False)`
TypeScript	`MobKit.builder().consoleAuthRequired(false)`
Rust library	`RuntimeDecisionState::local_console(ConsolePolicy { require_app_auth: false, ..ConsolePolicy::default() }, None)`
`mobkit_gateway`	Always open: it has no auth ingress and binds loopback by default, so the host is the protection; a non-loopback `http_listen` is refused unless `allow_remote` acknowledges the exposure

An open console is a deployment decision. Use it only behind a loopback bind or a reverse proxy that authenticates; for anything shared, configure auth_config (Python .auth(...), TypeScript .auth(...)) instead.

RuntimeOpsPolicy

RuntimeOpsPolicy {
    replica_count: u16,
    metrics: MetricsPolicy,
}

Field	Type	Default	Description
`replica_count`	`u16`	`1`	Number of runtime replicas (must be 1 in v0.1)
`metrics`	`MetricsPolicy`	`{ enforce_slo_targets: false }`	Metrics enforcement settings

v0.1 enforces single-replica deployments. Setting replica_count to any value other than 1 produces DecisionPolicyError::ReplicaCountMustBeOne.

LocalJsonMemoryBackendConfig

LocalJsonMemoryBackendConfig {
    state_path: String,
    health_check_endpoint: Option<String>,
}

Field	Type	Description
`state_path`	`String`	Local JSON file holding the operational assertion ledger (`mobkit/memory/*`). Runtime-owned: read once at bootstrap into memory, and rewritten wholesale (the whole state to `<state_path>.tmp`, then renamed over the file) on every `mobkit/memory/index`. Not a shared append log; see below.
`health_check_endpoint`	`Option<String>`	Optional HTTP base URL probed with `GET /v1/health` at the bootstrap load and before every persist; a failed probe refuses that load or persist. No ledger data is ever sent to it

For SDK builds that boot through rpc_gateway, state_path is derived from .persistent_state(path) as <path>/memory-ledger-state.json; callers provide only backend: "local_json" (and optionally health_check_endpoint). The legacy ElephantMemoryBackendConfig / backend: "elephant" shape is deprecated: it was always local JSON persistence plus a health check — no data ever reached Elephant — and it converts to this config on load. Real Elephant integration is the wire-boundary provider described in docs/design/memory-hub-roadmap.md. Ownership of the assertion ledger. The file is a snapshot of runtime state, not a log that other writers may append to. MobkitRuntimeHandle loads it exactly once at bootstrap and keeps assertions and conflicts in memory as the authority; every mobkit/memory/index (host calls, and the Steward’s conflict signals when agent_memory.steward is enabled) serializes the entire in-memory state and atomically replaces the file, with no re-read, lock or modification check. A direct edit is therefore invisible until the next boot and overwritten by the next flush; single-writer is a convention MobKit does not enforce with a lock. Retention is capped at 4,096 assertions, oldest evicted first, at index time and at load. At load, a structurally malformed file (an entry missing assertion_id, entity, topic, store, fact or indexed_at_ms) refuses the boot with MobkitRuntimeError::MemoryBackend, while a well-formed entry whose entity, topic or store is not canonical, or whose fact is empty, is dropped without a diagnostic. Append through mobkit/memory/index, Python MobHandle.memory_index(...), TypeScript handle.memoryIndex(...), or Rust MobkitRuntimeHandle::memory_index / UnifiedRuntime::memory_index; there is no agent-facing tool, so a host that wants members to write exposes one over the handle. This ledger is distinct from the agent_memory injection and turn-surface ledgers below.

Agent memory injection

agent_memory is separate from mobkit/memory/*. It is hot identity-scoped memory plus prompt injection: during create/resume/materialize and ordinary identity-first turns, MobKit asks an AgentMemoryProvider for memories keyed by AgentIdentity and injects a bounded, quoted observation summary. With the current Meerkat 0.8.32 pairing, ambient per-turn memory requires runtime_mode = "turn_driven"; remove this restriction after the Meerkat 0.8.33 carrier change lands. The bundled gateway provider is one SQLite database per realm under <persistent_state>/agent-memory (store: "sqlite", the only live gateway store). The earlier per-identity markdown files are import-only: store: "markdown" is refused at init with a migration verdict, and pointing SQLite at the same directory imports a realm’s un-imported markdown files when that realm is first accessed and its SQLite connection is opened, preserving ids, tag content and timestamps and renaming each original <file>.imported rather than deleting it (tags are collated on insert, so tag ORDER is not preserved - assert on the set, not the sequence). The path is server-owned and cannot be overridden from SDK init input. Elephant remains an optional deeper knowledge backend for graph/document/truth/provenance use cases and is not required for this hot path. With the SQLite store, build-time injection also composes a metadata index (record ids, kinds, titles, descriptions, human-phrased age) over the identity’s readable scopes, budgeted at ~8 KiB, ahead of the selected record bodies. Every injected record is logged to an injection ledger inside the realm database and counted in per-record usage statistics; explicit mobkit/agent_memory/recall reads are counted separately from ambient injection. Inbound anti-spoofing is on by default (defang_inbound: true): every non-steer identity-first send is scanned for reserved memory-envelope markers (the injection header pattern, <mobkit_memory_observation> tags, [mem-token: prefixes) and matches are visibly neutralized before delivery, so a peer message or echoed web content cannot impersonate remembered context. A warning with a hit count is logged whenever defanging fires. Steer sends bypass injection and defanging entirely. Rust builders can use .persistent_agent_memory_stack(config, engines) with .persistent_state(path) to install the full SQLite stack (store plus taint firewall plus the enabled judgment-plane engines). Callers that need a different authority use .agent_memory(provider, config). The former .persistent_agent_memory(...) markdown constructor is removed; legacy markdown is accepted only by the one-shot SQLite importer. Gateway callers can write records with mobkit/agent_memory/remember, read them with mobkit/agent_memory/recall, and delete individual records with mobkit/agent_memory/forget. TypeScript callers can use handle.rememberAgentMemory(identity, { title, body, tags, realm }), handle.recallAgentMemory(identity, { realm, selection, queryText, queryTerms, maxEntries }), and handle.forgetAgentMemory(identity, memoryId, { realm }); Python callers can use handle.remember_agent_memory(identity, title=..., body=..., tags=..., realm=...), handle.recall_agent_memory(identity, realm=..., selection=..., query_text=..., query_terms=..., max_entries=...), and handle.forget_agent_memory(identity, memory_id, realm=...). Writes and deletes are identity-scoped, require the identity to be registered in the identity runtime, and writes become turn context on the next identity-first send, plus build context on materialization/resume/respawn/reset for that identity. A successful write means the configured hot provider accepted the record; it does not mean optional Elephant extraction/enrichment has completed. Bundled SQLite writes enforce the staged-memory validator’s record limits. The retired markdown parser is used only while importing existing files. When selection = "always", the latest memories for the identity are injected. When selection = "contextual" (the default), build-time injection sends synthesized identity/profile/label query text and deterministic terms; per-turn injection sends the raw current identity-first message plus normalized terms. Common stopwords are ignored by the bundled provider and records below the relevance threshold are not injected. MobKit does not send app context or customizer-added instructions to the memory provider. Semantic/vector retrieval remains a provider concern rather than a MobKit runtime authority. Per-turn injection is governed by per_turn_injection. When omitted, the gateway derives the effective policy from the selected memory backend’s library default: "budgeted" for the bundled SQLite store and "off" for the legacy, import-only markdown kind. Set "off" explicitly to disable ambient push. Selected memories travel as typed injected context immediately before the conversational input, rather than being fused into the user message, and Meerkat excludes that role from semantic-memory indexing. Budgeted injection applies an injection ladder: at most ~4 KiB rendered per record, 20 KiB per assembly, and 60 KiB cumulative per delivered session, with records offered at most once per session (cross-turn dedup). The turn-surface ledger records that preparation-time offer; the transcript’s typed injected-context append records delivery at activation. Build-time injection always applies the per-record and per-assembly caps. Automatic build/turn injection uses recall_timeout_ms (default 500, max 30000) and recall_failure_policy (default "skip", or "fail"). With the default skip policy, provider errors and timeouts omit the memory block and allow delivery to continue. Explicit mobkit/agent_memory/recall requests still return provider errors. Agent memory is identity-scoped and is not automatically cleared by session respawn or identity reset. Apps that require privacy reset semantics can call mobkit/agent_memory/forget for specific records or use an AgentMemoryProvider whose lifecycle policy clears memory alongside the app’s identity lifecycle. forget removes records from future recall and injection; it does not erase text already delivered into an active model context, so reset or respawn the identity after deletion when immediate context revocation matters.

BigQueryNaming

BigQueryNaming {
    dataset: String,
    table: String,
}

Field	Type	Validation
`dataset`	`String`	Non-empty, alphanumeric + underscore + hyphen only
`table`	`String`	Non-empty, alphanumeric + underscore + hyphen only

ReleaseMetadata

ReleaseMetadata {
    targets: Vec<String>,
    support_matrix: String,
}

Field	Type	Description
`targets`	`Vec<String>`	Release targets (must include: `crates.io`, `npm`, `pypi`, `github-releases`)
`support_matrix`	`String`	Must be `"same-as-meerkat"`

build_runtime_decision_state parses and validates this document on every build, with or without console auth; nothing reads it at serve time, so the check is release governance, not runtime policy. RuntimeDecisionState::local_console fills the canonical value. A malformed document is a DecisionPolicyError::TomlParse whose message names the release metadata JSON.

Trust manifest (mobkit.toml)

[[modules]]
id = "router"
command = "meerkat-router"
args = ["--port", "9001"]
restart_policy = "on_failure"

[[modules]]
id = "delivery"
command = "meerkat-delivery"

Field	Type	Required	Default
`id`	`string`	yes	—
`command`	`string`	yes	—
`args`	`string[]`	no	`[]`
`restart_policy`	`string`	no	`"on_failure"`

Constants

Constant	Value	Description
`MOBKIT_CONTRACT_VERSION`	`"0.5.0"`	JSON-RPC contract version
`DEFAULT_KEEP_ALIVE_INTERVAL`	`15s`	SSE keep-alive interval
`GATING_AUDIT_MAX_RETAINED`	implementation-defined	Max gating audit entries
`GATING_PENDING_MAX_RETAINED`	implementation-defined	Max pending gating entries

Architecture

Governance

MobKitConfig

ModuleConfig

RestartPolicy

DiscoverySpec

PreSpawnData

SDK and Gateway runtime options

Model fallback

One-shot mob definition update

Self-hosted models and the Meerkat host config

How the host config reaches each surface

The init model check

Member role migrations

Mob profile tools (`[profiles.*.tools]`)

WorkGraph

Storage layout and durability

Identity bootstrap

`mobkit_gateway` identity roster

ConsoleUiConfig

AuthPolicy

AuthProvider

ConsolePolicy

Console auth by surface

RuntimeOpsPolicy

LocalJsonMemoryBackendConfig

Agent memory injection

BigQueryNaming

ReleaseMetadata

Trust manifest (mobkit.toml)

Constants

See also

​MobKitConfig

​ModuleConfig

​RestartPolicy

​DiscoverySpec

​PreSpawnData

​SDK and Gateway runtime options

​Model fallback

​One-shot mob definition update

​Self-hosted models and the Meerkat host config

​How the host config reaches each surface

​The init model check

​Member role migrations

​Mob profile tools ([profiles.*.tools])

​WorkGraph

​Storage layout and durability

​Identity bootstrap

​mobkit_gateway identity roster

​ConsoleUiConfig

​AuthPolicy

​AuthProvider

​ConsolePolicy

​Console auth by surface

​RuntimeOpsPolicy

​LocalJsonMemoryBackendConfig

​Agent memory injection

​BigQueryNaming

​ReleaseMetadata

​Trust manifest (mobkit.toml)

​Constants

​See also

MobKitConfig

ModuleConfig

RestartPolicy

DiscoverySpec

PreSpawnData

SDK and Gateway runtime options

Model fallback

One-shot mob definition update

Self-hosted models and the Meerkat host config

How the host config reaches each surface

The init model check

Member role migrations

Mob profile tools (`[profiles.*.tools]`)

WorkGraph

Storage layout and durability

Identity bootstrap

`mobkit_gateway` identity roster

ConsoleUiConfig

AuthPolicy

AuthProvider

ConsolePolicy

Console auth by surface

RuntimeOpsPolicy

LocalJsonMemoryBackendConfig

Agent memory injection

BigQueryNaming

ReleaseMetadata

Trust manifest (mobkit.toml)

Constants

See also