# klieo

Open-source Rust agent framework — typed agents, durable inter-agent comms, local-first.

[![crates.io](https://img.shields.io/crates/v/klieo)](https://crates.io/crates/klieo)
[![docs.rs](https://img.shields.io/docsrs/klieo)](https://docs.rs/klieo)
[![MIT](https://img.shields.io/crates/l/klieo)](https://github.com/mohrimic/klieo/blob/main/LICENSE)

## What it is

klieo is a Rust agent framework that wires LLM clients, tools, memory,
and inter-agent messaging behind a clean trait surface. Build agents that
call local or remote LLMs, persist memory to SQLite/Qdrant/Neo4j,
communicate over NATS or in-process bus, and expose themselves as MCP
servers or A2A endpoints.

## Feature flags

| Flag | Adds | Default |
|---|---|---|
| `local` | `tools`, `macros`, `llm-ollama`, `memory-sqlite`, `bus-memory` | **on** |
| `all-foundation` | `tools`, `macros`, `llm-ollama`, `memory-sqlite`, `bus-memory`, `bus-nats`, `mcp`, `auth-common`, `ops`, `ops-api` | off |
| `all-llm` | `llm-openai`, `llm-anthropic`, `llm-gemini` (+ `llm-ollama`) | off |
| `all-memory` | `memory-sqlite`, `memory-neo4j`, `memory-qdrant`, `embed-common` | off |
| `all-observability` | `runlog`, `otel`, `provenance` | off |
| `full` | All flags above | off |

## Quickstart

```toml
[dependencies]
klieo = { version = "1", features = ["full"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1"
```

```rust
use klieo::prelude::*;

#[klieo::tool(description = "Returns a greeting.")]
async fn greet(_ctx: &ToolCtx, name: String) -> Result<String, ToolError> {
    Ok(format!("Hello, {name}!"))
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = App::local_at("klieo.db")
        .tool(GreetTool)
        .build()
        .await?;
    let agent = SimpleAgent::new("greeter", "Be helpful.", app.tools_catalogue().to_vec());
    let reply = app.run(&agent, "say hi to Alex".into()).await?;
    println!("{reply}");
    Ok(())
}
```

## Crate catalogue

Versions reflect the current published majors; minor bumps are not
called out per row. See each crate's `CHANGELOG.md` for fine-grained
history.

| Sub-crate | Purpose | Stability |
|---|---|---|
| [`klieo-core`](https://docs.rs/klieo-core) | Trait surface (`LlmClient`, `Tool`, `MemoryLongTerm`, …) | 1.0 |
| [`klieo-llm-ollama`](https://docs.rs/klieo-llm-ollama) | Ollama LLM provider | 1.0 |
| [`klieo-llm-openai`](https://docs.rs/klieo-llm-openai) | OpenAI Chat Completions | 1.0 |
| [`klieo-llm-anthropic`](https://docs.rs/klieo-llm-anthropic) | Anthropic Messages API | 1.0 |
| [`klieo-llm-gemini`](https://docs.rs/klieo-llm-gemini) | Google Gemini | 1.0 |
| [`klieo-llm-common`](https://docs.rs/klieo-llm-common) | Shared HTTP / retry helpers for LLM providers | 1.0 |
| [`klieo-memory-sqlite`](https://docs.rs/klieo-memory-sqlite) | SQLite short-term + long-term memory | 1.1 |
| [`klieo-memory-neo4j`](https://docs.rs/klieo-memory-neo4j) | Neo4j-backed long-term memory | 1.2 |
| [`klieo-memory-qdrant`](https://docs.rs/klieo-memory-qdrant) | Qdrant vector store for long-term memory | 1.2 |
| [`klieo-memory-graph`](https://docs.rs/klieo-memory-graph) | Knowledge-graph traits (GraphRAG cluster) | 1.0 |
| [`klieo-memory-graph-neo4j`](https://docs.rs/klieo-memory-graph-neo4j) | Neo4j implementation of `KnowledgeGraph` | 1.0 |
| [`klieo-memory-graph-rag`](https://docs.rs/klieo-memory-graph-rag) | Retrieval orchestration over graph + vector | 1.0 |
| [`klieo-graph-projector`](https://docs.rs/klieo-graph-projector) | Episode → knowledge-graph projector | 1.0 |
| [`klieo-embed-common`](https://docs.rs/klieo-embed-common) | `Embedder` trait + `DummyEmbedder` | 1.0 |
| [`klieo-bus-memory`](https://docs.rs/klieo-bus-memory) | In-process durable bus | 1.1 |
| [`klieo-bus-nats`](https://docs.rs/klieo-bus-nats) | NATS-backed durable bus | 1.1 |
| [`klieo-tools`](https://docs.rs/klieo-tools) | `ChainedInvoker` + tool dispatch | 1.1 |
| [`klieo-tools-mcp`](https://docs.rs/klieo-tools-mcp) | Client adapter — consume remote MCP servers' tools | 1.0 |
| [`klieo-mcp-server`](https://docs.rs/klieo-mcp-server) | Server adapter — expose a klieo agent as an MCP server | 1.1 |
| [`klieo-macros`](https://docs.rs/klieo-macros) | `#[tool]` + `derive(KlieoResponse)` macros | 1.0 |
| [`klieo-flows`](https://docs.rs/klieo-flows) | Sequential / Parallel / Loop / Graph / TypedSequential flows | 1.0 |
| [`klieo-a2a`](https://docs.rs/klieo-a2a) | Agent-to-agent dispatch + conformance | 1.1 |
| [`klieo-auth-common`](https://docs.rs/klieo-auth-common) | `Authenticator` trait + `BearerTokenAuthenticator` | 1.0 |
| [`klieo-auth-oauth`](https://docs.rs/klieo-auth-oauth) | OAuth / OIDC authenticator | 1.1 |
| [`klieo-ops`](https://docs.rs/klieo-ops) | Multi-tenant runtime — gates, escalation, four-eyes, worklog, handoff, encryption | 1.1 |
| [`klieo-ops-api`](https://docs.rs/klieo-ops-api) | HTTP routes for the ops layer | 1.1 |
| [`klieo-ops-evidence-verify`](https://docs.rs/klieo-ops-evidence-verify) | CLI to verify signed evidence bundles | 1.0 |
| [`klieo-ops-redispatcher`](https://docs.rs/klieo-ops-redispatcher) | Cron-driven redispatch CLI | 1.0 |
| [`klieo-otel`](https://docs.rs/klieo-otel) | OpenTelemetry integration (`install`) | 1.0 |
| [`klieo-runlog`](https://docs.rs/klieo-runlog) | Run-log store + projection | 1.0 |
| [`klieo-pii-patterns`](https://docs.rs/klieo-pii-patterns) | PII pattern table for redactors | 1.0 |
| [`klieo-provenance`](https://docs.rs/klieo-provenance) | Signed evidence bundles (DORA / AI-Act) | 2.0 |
| [`klieo-spec`](https://docs.rs/klieo-spec) | Spec / critic / refiner flow primitives | 1.0 |
| [`klieo-eval`](https://docs.rs/klieo-eval) | Recall-quality metrics for memory pipelines | 1.0 |
| [`cargo-klieo`](https://crates.io/crates/cargo-klieo) | `cargo klieo` CLI (replay, a2a-conformance) | 1.0 |

## Resources

- [API docs](https://docs.rs/klieo)
- [User guide](https://github.com/mohrimic/klieo/tree/main/docs/book)
- [SEMVER policy](https://github.com/mohrimic/klieo/blob/main/docs/SEMVER.md)

## Status

`2.x` — stable. Minor releases may add public items. See
[`docs/SEMVER.md`](https://github.com/mohrimic/klieo/blob/main/docs/SEMVER.md).

## License

MIT — see [`LICENSE`](https://github.com/mohrimic/klieo/blob/main/LICENSE).
