Crate openheim 

openheim

A fast, multi-provider LLM agent runtime written in Rust.

Quick start

use openheim::{OpenheimClient, Result};

// `current_thread`: the library itself only needs `tokio`'s `rt` feature,
// not `rt-multi-thread` (that's what the `cli` feature adds for the
// `openheim` binary's own `#[tokio::main]`).
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<()> {
    let client = OpenheimClient::builder()
        .provider("openai")
        .api_key("sk-...")
        .model("gpt-4o")
        .build()
        .await?;

    let session = client.new_session().start().await?;
    session
        .prompt_events("List the files in the current directory.", |_event| {})
        .await?;

    Ok(())
}

Providers

Provider	Value	Default model
OpenAI	"openai"	gpt-4o
Anthropic	"anthropic"	claude-sonnet-4-6
Google	"gemini"	gemini-2.0-flash
Compatible	any string	set via .model()

Configuration file

By default openheim loads ~/.openheim/config.toml. Use OpenheimClient::from_config to load from a custom path, or set individual fields via the builder for fully programmatic configuration.

MCP servers

External tools are registered as MCP servers and namespaced as {server_name}__{tool_name}. They are automatically available in every agent session.

Feature flags

Feature	Default	Enables
cli	✓	The openheim binary (CLI, TUI, serve). Implies tui + server + acp.
tui	via cli	The tui module (ratatui/crossterm terminal UI). Doesn’t need acp.
acp	via cli	The acp and transport modules (Agent Client Protocol: serve, stdio, run, ws).
server	via cli	The transport::ws WebSocket/REST server (axum). Implies acp.
rag	via cli	The rag module and remember/search_memory/forget tools (rusqlite with FTS5 + sqlite-vec).

Everything else — the client facade, agent loop, providers, tools, MCP, and config — is always available. Embedders that don’t need ACP, the terminal UI, or the built-in server should depend on openheim with default-features = false (optionally adding back "acp", "tui", or "server") to skip the clap, ratatui, crossterm, axum, tower-http, notify, walkdir, tracing-subscriber, and agent-client-protocol{,-tokio} dependency trees. futures is not behind any feature — the agent loop uses it directly.

Key types

• OpenheimClient / OpenheimBuilder — main entry point
• SessionHandle — send prompts and receive streaming events (StreamEvent, or ACP’s SessionUpdate with feature acp)
• LlmClient — implement to add a custom provider
• MemoryContext — conversation history, skills, and system identity
• rag::LongTermMemory — tool-driven long-term memory: FTS5 keyword search, optionally sqlite-vec semantic search (feature rag)
• Error / Result — unified error type

Re-exports

pub use config::AgentConfig;

pub use config::AppConfig;

pub use config::McpServerConfig;

pub use config::ModelsInfo;

pub use core::agent;

pub use core::llm;

pub use core::models;

pub use error::Error;

pub use error::Result;

pub use llm::AnthropicClient;

pub use llm::GeminiClient;

pub use llm::LlmClient;

pub use llm::OpenAiClient;

pub use llm::OpenAiCompatibleClient;

pub use memory::Conversation;

pub use memory::ConversationMeta;

pub use memory::HistoryManager;

pub use memory::MemoryContext;

pub use memory::PromptBuilder;

pub use models::AgentResult;

pub use models::Choice;

pub use models::ContentBlock;

pub use models::FinishReason;

pub use models::FunctionDefinition;

pub use models::Message;

pub use models::Role;

pub use models::StopReason;

pub use models::StreamEvent;

pub use models::Tool;

pub use models::ToolResultBlock;

pub use models::ToolUseBlock;

pub use rag::LongTermMemory;

pub use client::OpenheimBuilder;

pub use client::OpenheimClient;

pub use client::SessionBuilder;

pub use client::SessionHandle;

Modules

acp

Agent Client Protocol (ACP) integration.

client

config

core

error

mcp

memory

Agent memory: persisted conversation history, skill files, the system identity, and the prompt assembly that stitches them into an LLM request.

rag

Long-term memory driven by tool calls, with retrieval that is keyword search by default and semantic search when an embeddings provider is configured.

subagents

Subagent profiles: named, user-defined agent personas that the orchestrating agent can delegate self-contained tasks to via the delegate_task tool (see crate::tools::delegate).

tools

Tool abstraction layer: trait definitions, built-in tools, and the runtime executor that routes LLM tool calls to the correct handler.

transport

Server transport implementations for the Openheim agent runtime.

tui