Architecture

Meerkat is a library-first agent runtime with one execution pipeline and multiple host surfaces. The CLI, REST server, JSON-RPC server, MCP server, Rust facade, Python SDK, TypeScript SDK, and Web/WASM runtime all converge on the same session, provider, tool, and transcript model. The architecture is strict about ownership: runtime-backed surfaces route through MeerkatMachine, multi-agent work routes through MobMachine, auth and scheduling use their own authority machines, and the agent loop itself stays a provider-neutral library primitive.

​

System Map

​

Public Surfaces

Reduced distributions are source builds of the same crates with narrower Cargo feature sets, not separate public binaries.

​

Core Runtime Pieces

​

Architecture Snapshot

Since the 0.6.5 live-adapter release, the architecture has gained several important surfaces and runtime fixes:

• WorkGraph now owns realm-scoped durable commitments, dependencies, claims, evidence, ready-item derivation, host observability, and optional goal attention bindings through WorkAttentionLifecycleMachine. CLI and trusted hosts add narrow goal and attention controls; public REST/RPC expose observability only.
• Transcript rewrite keeps session identity stable while allowing audited transcript-head rewrites through session/rewrite_transcript, session/transcript_revision, and session/restore_transcript_revision.
• Auth/model routing now includes Azure OpenAI, project-local CLI realms, binding fallback resolution, and gemini-3.5-flash as the recommended Gemini text model.
• Output and media surfaces include standalone HTML artifacts, typed transcript notices, provider-native search/image routing, OpenAI hosted image options, and Gemini image defaults.
• Mob runtime behavior now includes batch member wiring, backpressured peer delivery, autonomous member capability validation, spawn boundary overrides, task-workflow guidance preloads, and safer retirement/respawn/session-loss handling.
• Session durability includes runtime-store checkpointing and runtime-committed projection saves, so MobKit and UnifiedRuntime consumers see checkpointed session state after the machine commit succeeds.
• Release and validation paths include docs validation, stricter version and schema freshness checks, BuildBuddy/Web SDK release hardening, and explicit release recovery lanes.

​

Machine Authority

The canonical machine and composition catalog is owned by canonical_machine_schemas() and canonical_composition_schemas() in meerkat-machine-schema/src/catalog/mod.rs. The per-machine roster, production owners, and composition list are documented in Machine Authority, which mirrors that registry; this page does not maintain its own copy. The short rule is: if a state transition has semantic meaning, it needs one owner. Generated machine artifacts, specs, and drift checks keep that ownership aligned with production Rust code.

​

Realm And Persistence Model

realm_id is the sharing key across surfaces. A realm contains sessions, config, auth bindings, schedules, blobs, and mob state. CLI commands default to a workspace-derived realm; servers and SDKs can create an opaque realm or use an explicit one. When SQLite support is compiled, new persistent realms default to SQLite. JSONL remains available as an explicit inspectable backend. WASM and tests use in-memory state unless the embedding supplies a store.

​

Provider Model

Provider selection is model-profile driven. Meerkat does not infer semantic capabilities from model name substrings. Capability flags such as realtime, structured output, compaction, web search, image generation, and media support come from the catalog and provider-owned profiles. Auth is realm/binding scoped. Environment keys are still supported as a bootstrap path, but long-lived provider access should go through auth bindings and the auth lease path.

​

Orchestration Model

Mobs are the multi-agent runtime path. A delegated helper, a forked worker, a flow step, and a reusable profile-backed member are all mob members. Stable public identity is AgentIdentity; per-runtime binding identity is AgentRuntimeId, fenced by FenceToken and generation. Agent-facing delegate and mob_* tools are separate from host control planes. Host apps use typed mob/* JSON-RPC methods, REST helper endpoints, MCP meerkat_mob_* tools, or SDK wrappers.

​

Live Channels

Live audio/text is exposed through JSON-RPC live/* methods. Start rkat-rpc with --live-ws <addr> when a channel needs WebSocket transport bootstrap. ModelCapabilities.realtime gates live/open. The current catalog realtime row is OpenAI gpt-realtime-2.

​

Reading Order