PersistentSessionService with MeerkatMachine; the service is the
session substrate and the machine owns runtime transitions. The direct
EphemeralSessionService path remains useful for small embedded programs and
tests that intentionally do not need runtime-backed persistence or delivery.
Method overview
Mob orchestration is layered on this facade by the separate
meerkat-mob
crate. The live feature composes meerkat-live into the runtime; direct
adapter types remain owned by meerkat-live.
Installation
1
Add the dependency
2
Choose feature flags
The default feature set enables the Anthropic, OpenAI, and Gemini clients
plus GitHub Copilot OAuth/backend support; add optional gates as needed:
Feature flag reference
Feature flag reference
Meerkat’s stores run on the SQLite that
libsqlite3-sys bundles, whose
defaults put every connection in the process behind process-wide locks.
Build your application with
LIBSQLITE3_FLAGS="-DSQLITE_DEFAULT_MEMSTATUS=0 -USQLITE_ENABLE_MEMORY_MANAGEMENT -DSQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS"
(for example in the [env] table of your workspace’s .cargo/config.toml),
and call meerkat_sqlite::disable_memory_statistics_at_process_start() from
the meerkat-sqlite crate as the first statement of main. See
SQLite Lock Profile.Quick start
Production surfaces (CLI, REST, RPC, MCP) use the runtime-backed path wherePersistentSessionService is substrate and MeerkatMachine owns keep-alive,
Queue/Steer routing, interruption, terminal publication, and archive. Start a
native host with both halves:
Use this dependency set for the persistent example. The explicit
meerkat-store dependency supplies RealmBackend and realm_paths_in;
transitive dependencies are not available as direct crate imports.
Sessions
The examples below use the directEphemeralSessionService lifecycle. The
same request and result types are used inside production hosts, but persistent
follow-up turns, interruption, and archive are machine-owned transitions and
must not call these trait methods directly.
Multi-turn conversations
Append a System message at a turn boundary
system_prompt appends one ordinary ordered System message immediately
before that turn. It may be used on any turn; prior System messages and the
rest of the transcript remain unchanged.
Error handling
Direct agent APIs
Running agents directly
Basic run
Run with event streaming
Text deltas are emitted by the model adapter, not by the run. Give one channel to both: build the adapter withbuild_llm_adapter_with_events and
pass the same sender to run_with_events. With an adapter built by
build_llm_adapter, which has no channel, the run delivers TextComplete,
TurnCompleted and the tool events, and no TextDelta.
turn_completed carries optional usage for one provider call while run_completed
carries the session-cumulative total, and their input_tokens fields use
different denominators. usage: None means no accounting exists for that
turn, not zero usage. Read
Usage accounting before aggregating either.Agent methods
Error handling
Use this dependency set for the sample. The explicitmeerkat-core
dependency supplies TurnTerminalCauseKind and TurnTerminalOutcome, which
meerkat does not re-export; transitive dependencies are not available as
direct crate imports. The meerkat_core imports under
Core types need the same dependency.
Err(AgentError::TokenBudgetExceeded { .. }); it comes from Budget::check() when you call it yourself. A token or tool-call budget spent during a run, or already spent at its start, ends as Ok(RunResult) with terminal_cause_kind == Some(TurnTerminalCauseKind::BudgetExhausted); a spent time budget ends as Err(AgentError::TerminalFailure { outcome: TimeBudgetExceeded, .. }).
The answer of the model call that takes a run past its token budget is
discarded: it is not committed to the session and not returned, although its
tokens are counted. The result’s text is then the latest assistant text
the session already held: text from an earlier step of the same run, else the
answer of an earlier turn, else empty. Check terminal_cause_kind before
using text: on BudgetExhausted the text is not this call’s answer.
A streaming caller has by then received the discarded answer’s text deltas;
no TextComplete and no TurnCompleted follow them.
Events
All event types
All event types
BoundaryAppendApplied with BoundaryAppendsDiscarded for the same
session, run, and input IDs, and with canonical transcript history. The discard
payload carries session_id, run_id, and input_ids; the applied event can
include canonical notices and the application-time transcript_start offset.
A run terminal alone does not prove discard. A discard does not terminalize
the input or invalidate its later application in another run; retained
canonical history remains authoritative.Core types
Message and ContentBlock
ContentInput
ContentInput is the prompt type accepted by CreateSessionRequest and StartTurnRequest. It supports both text-only and multimodal prompts:
ToolCall and ToolResult
RunResult
See also
- Tools and stores - tool system, session stores, MCP integration
- Advanced - expert-only direct agent construction, providers, budgets, and hooks
- API reference - quick-lookup type index
