Skip to main content
Meerkat is modular. Every feature is opt-in. This matrix shows what works in each build profile.

​
Build profiles

ProfileCargo FeaturesUse Case
Minimal--no-default-featuresEphemeral agent, no persistence, no compaction
Persistentsession-storeSessions survive restart, redb-backed storage
Compactingsession-compactionAuto-compact long conversations
Fullsession-store,session-compactionPersistent + compacting

​
Capability behavior

OperationMinimalPersistentCompactingFull
create_sessionWorksWorksWorksWorks
start_turnWorksWorks + snapshot savedWorksWorks + snapshot saved
interruptWorksWorksWorksWorks
read (live session)WorksWorksWorksWorks
read (archived)SESSION_NOT_FOUNDFalls back to storeSESSION_NOT_FOUNDFalls back to store
listLive sessions onlyLive + stored sessionsLive sessions onlyLive + stored sessions
archiveRemoves from memoryRemoves from memory, snapshot keptRemoves from memoryRemoves + snapshot kept
Auto-compactionNo-opNo-opTriggers at thresholdTriggers at threshold

​
Error codes

Deterministic error codes across all surfaces. Every SessionError variant maps to a stable string code and a transport-specific representation:
SessionErrorCodeJSON-RPCRESTMCPCLI
NotFoundSESSION_NOT_FOUND-32001404tool errorexit 1
BusySESSION_BUSY-32002409tool errorexit 1
PersistenceDisabledSESSION_PERSISTENCE_DISABLED-32003501tool errorstderr
CompactionDisabledSESSION_COMPACTION_DISABLED-32004501tool errorstderr
NotRunningSESSION_NOT_RUNNING-32005409tool errorexit 1
StoreSESSION_STORE_ERROR-32000500tool errorexit 1
AgentAGENT_ERROR-32000500tool errorexit 1

​
Transport error mapping summary

  • JSON-RPC: Custom error codes in the -32000..-32099 range. The code field of the JSON-RPC error object carries the string code (e.g. SESSION_NOT_FOUND).
  • REST: HTTP status codes (404, 409, 500, 501). Error body includes { "code": "...", "message": "..." }.
  • MCP Server: Tool calls return is_error: true with the error message and code in the content.
  • CLI: Non-zero exit codes. exit 1 for errors, exit 2 for budget exhaustion. Error details printed to stderr.

​
Pick only what you need

# Minimal: just the agent loop
[dependencies]
meerkat = { version = "0.1", default-features = false, features = ["anthropic"] }

# Add persistence
meerkat = { version = "0.1", default-features = false, features = ["anthropic", "session-store"] }

# Add compaction
meerkat = { version = "0.1", default-features = false, features = ["anthropic", "session-store", "session-compaction"] }

# Kitchen sink
meerkat = { version = "0.1", features = ["all-providers", "session-store", "session-compaction", "comms", "mcp"] }

​
Compaction behavior

When session-compaction is enabled:
  • Trigger: last_input_tokens >= threshold OR estimated_history_tokens >= threshold
  • Guards: Never on first turn. Minimum 3 turns between compactions.
  • Failure: Non-fatal. CompactionFailed event emitted, agent continues with uncompacted history.
  • Budget: Compaction LLM call draws from the same token budget as regular turns.
Events emitted: CompactionStarted, CompactionCompleted, CompactionFailed.

​
Concurrency

  • At most one turn runs per session at a time.
  • Second start_turn while one is in-flight returns SESSION_BUSY.
  • interrupt() cancels the in-flight turn.
  • read() and list() are non-blocking.
  • No queueing: callers retry on Busy.

​
Durability

  • Ephemeral: Process death loses all state.
  • Persistent: Snapshot saved AFTER turn completes. Crash mid-turn loses the in-flight turn.
  • .rkat/sessions/ files are derived (projected) output, not canonical source. Deleting them and replaying from the event store produces identical content.

​
See also