hrafn

Lightweight, modular AI agent runtime. Hrafn thinks. MuninnDB remembers.

Quickstart · Architecture · Contributing · Discussions

Hrafn is an autonomous AI agent runtime written in Rust. It connects to the messaging platforms you already use (Telegram, Discord, WhatsApp, Signal, Matrix, and more), runs on hardware as small as a Raspberry Pi, and keeps your data local.

Unlike monolithic agent frameworks, Hrafn is modular by design. You compile only what you need. Runtime extensibility comes through MCP -- every MCP server is a plugin.

Modular, not monolithic. Channels, tools, providers, and memory backends are Cargo features. The default build is small. You opt in to what you need.

MCP as the plugin protocol. No custom plugin API. Any MCP server works as a Hrafn plugin, in any language. The OpenClaw Bridge lets you test OC plugins via MCP before porting them to native Rust.

MuninnDB. Cognitive memory with Ebbinghaus-curve decay and Hebbian association learning. The Dream Engine consolidates memories via local LLM inference (Ollama), so your data never leaves your machine.

A2A protocol. Native Agent-to-Agent communication. Discover, delegate, and receive tasks from other agents over HTTP using the open A2A standard.

Community-first governance. Every PR gets a response within 48 hours. No silent closes. Public roadmap. Weekly community calls. See CONTRIBUTING.md for our promises.

# Install from source
git clone https://github.com/5queezer/hrafn.git
cd hrafn
cargo build --release --locked
cargo install --path . --force --locked

# Guided setup
hrafn onboard

# Or quick start
hrafn onboard --api-key "sk-..." --provider openrouter

# Start the gateway (web dashboard + webhook server)
hrafn gateway

# Chat directly
hrafn agent -m "Hello, Hrafn!"

# Interactive mode
hrafn agent

# Full autonomous runtime
hrafn daemon

# Diagnostics
hrafn status
hrafn doctor

# Full default build (all channels, tools, gateway, metrics)
cargo build --release --locked

# Selective channels: only Telegram + shell, no Matrix/Nostr/WhatsApp
cargo build --no-default-features --features "desktop,channel-telegram,tool-shell"

# Stripped-down ESP32 build (no CLI, no gateway, no optional channels)
cargo build --bin hrafn-esp32 --no-default-features --features target-esp32

Hrafn's architecture is trait-based. Every subsystem is a Rust trait. Swap implementations through configuration, not code changes.

src/
├── agent/         # Orchestration loop
├── config/        # TOML configuration
├── providers/     # LLM backends          → Provider trait
├── channels/      # Messaging platforms    → Channel trait
├── tools/         # Agent capabilities     → Tool trait
├── memory/        # Persistence            → Memory trait
├── gateway/       # HTTP/WS control plane
├── security/      # Policy, secrets, audit
├── hardware/      # Device discovery, I2C/SPI/GPIO
├── peripherals/   # Peripheral management  → Peripheral trait
├── runtime/       # Runtime adapters       → RuntimeAdapter trait
├── observability/ # Metrics, tracing
├── plugins/       # WASM plugin runtime
├── daemon/        # Background service
├── skills/        # Skill management
├── rag/           # Retrieval-augmented generation
├── hooks/         # Lifecycle hooks
├── cron/          # Scheduled tasks
├── identity/      # Identity management
├── tunnel/        # Tunnel/relay support
└── ...            # approval, auth, commands, cost, doctor, hands, health,
                   # heartbeat, integrations, nodes, onboard, routines,
                   # service, skillforge, sop, trust, verifiable_intent

Every channel, tool, and subsystem is gated behind a Cargo feature. The desktop feature bundles everything needed for a full CLI build; opt-in features add extra backends.

Use --no-default-features and opt in to individual features for minimal builds. Configuring a disabled module logs a warning at startup.

Any MCP server is a plugin. Configure in config.toml:

[mcp]
servers = [
  { name = "my-tool", command = "npx", args = ["-y", "my-mcp-server"] },
]

No recompilation needed. MCP plugins can be written in any language.

The OC Bridge lets Hrafn users run OpenClaw plugins via MCP without a native Rust port. It serves as a validation funnel: plugins that see sustained community usage get queued for native porting.

OC Plugin → MCP Adapter (Node.js) → Hrafn tests it → Community validates
  → Port Queue → Native Rust implementation → Review & merge

OC Bridge is planned for a future release (M3).

Cognitive memory backend with Ebbinghaus-curve decay (memories fade naturally) and Hebbian learning (co-activated memories strengthen each other). The Dream Engine runs periodic consolidation via local LLM inference.

[memory]
backend = "muninndb"

[memory.muninndb]
url = "http://127.0.0.1:8475"   # optional; falls back to MUNINNDB_URL env var
vault = "default"               # optional; falls back to MUNINNDB_VAULT env var
# api_key = "your-api-key"     # optional; falls back to MUNINNDB_API_KEY env var

Native Agent-to-Agent communication per the open A2A standard.

[a2a]
enabled = true
bearer_token = "your-secret"
# agent_name = "my-agent"        # defaults to config agent name
# public_url = "https://my-agent.example.com"  # auto-derived from gateway if omitted
# capabilities = ["research", "coding"]

Inbound tasks route through the gateway server and the existing agent pipeline (A2A uses the same gateway port; no separate bind). The agent card is auto-generated from your configuration.

See the GitHub Projects board for current status.

We believe open-source communities deserve transparent governance and respect for contributors' work. Read CONTRIBUTING.md for our promises and workflow.

The short version:

• Every PR gets a response within 48 hours.
• No silent closes. Rejections come with explanations.
• Your code stays your code. Maintainers never re-submit contributor work under their own name.

• GitHub Discussions -- questions, RFCs, show & tell
• Weekly community calls (schedule in Discussions)

Hrafn originated as a fork of ZeroClaw (Apache-2.0). We thank the ZeroClaw contributors for the foundation.

MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE. You retain copyright of your contributions.

memory-muninndb feature gate: Enabling this feature pulls in MuninnDB, which is licensed under BSL 1.1 (not open source) and patent pending (U.S. Provisional Application No. 63/991,402). Commercial use of MuninnDB requires a separate license. See muninndb.com for details.