A modular Rust framework for building AI agents with multi-provider support, tool orchestration, MCP integration, and pluggable agent networking.
Warning: This is an early-stage project under active development. Expect breaking changes and rapid iteration as we build towards a 1.0 release.
The Brainwires Framework is a workspace of 32 framework crates plus 18 extras (including the 7-crate brainclaw set) that provide everything needed to build, train, deploy, and coordinate AI agents. Each framework crate is independently publishable to crates.io and usable standalone, but they compose together through the brainwires facade crate for a batteries-included experience.
Full feature list | Key capabilities:
- Multi-provider AI — Anthropic, OpenAI, Google, Ollama, and local LLMs behind a unified
Providertrait - Agent orchestration — hierarchical task decomposition, multi-agent coordination with file locks, MDAP voting
- MCP protocol — full client and server support via
rmcp, exposing agents as MCP tools - Agent networking — 5-layer protocol stack (IPC, TCP, A2A, Pub/Sub) with pluggable transports, routing, and discovery
- Training pipelines — cloud fine-tuning (6 providers) and local LoRA/QLoRA/DoRA via Burn
- RAG & code search — AST-aware chunking, hybrid vector + keyword search, Git-aware indexing
- Audio — speech-to-text, text-to-speech, hardware capture/playback
- Security — encrypted storage (ChaCha20-Poly1305), permission policies, content trust tagging
┌─────────────────────────────────────────────────────────────────┐
│ brainwires │
│ (facade crate) │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌────────────┐ ┌─────────────┐ │
│ │ agent │ │ provider │ │ storage │ │ mcp-client │ │
│ │ tool-runtime│ │ speech │ │ stores │ │ mcp-server │ │
│ │tool-builtins│ │ │ │ memory │ │ network │ │
│ └─────┬──────┘ └──────┬──────┘ └──────┬─────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └───────────────┴───────────────┴──────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ core │ │
│ │ permission │ │
│ │ call-policy │ │
│ └─────────────┘ │
│ │
│ ┌────────────┐ ┌─────────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ knowledge │ │ reasoning │ │telemetry │ │ hardware │ │
│ │ rag │ │ sandbox │ │ a2a │ │ finetune │ │
│ │ prompting │ │ │ │ │ │finetune-local│ │
│ └────────────┘ └─────────────┘ └──────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Crate | Description |
|---|---|
| brainwires | Facade crate — re-exports every other framework crate behind feature flags |
| brainwires-core | Core types, traits, and error handling shared by all crates |
| brainwires-provider | Multi-provider LLM interface (Anthropic, OpenAI, Google, Ollama, Bedrock, Vertex AI, local llama.cpp / Candle) |
| brainwires-provider-speech | Speech (TTS / STT) providers (Azure, Cartesia, Deepgram, ElevenLabs, Fish, Google, Murf, browser web-speech) |
| brainwires-tool-runtime | Tool framework — ToolExecutor, ToolRegistry, validation, smart router, sandbox/orchestrator/sessions/oauth/openapi |
| brainwires-tool-builtins | Built-in tool implementations: bash, file_ops, git, web, search, code_exec, browser, email, calendar, system, semantic_search |
| brainwires-agent | Agent coordination primitives + multi-agent patterns — communication, locks, queues, git coordination, contract net, saga, optimistic concurrency, market allocation, workflow graph |
| brainwires-inference | LLM-driven workhorses — ChatAgent, TaskAgent, planner / judge / validator helpers, cycle orchestrator, validation loop, summarization, system-prompt registry |
| brainwires-mdap | Multi-Dimensional Adaptive Planning (MAKER voting framework) |
| brainwires-seal | Self-Evolving Agentic Learning — coreference, query-core extraction, learned-pattern store, reflection |
| brainwires-skills | SKILL.md skills system — manifest parsing, registry, smart routing, sandboxed execution |
| brainwires-eval | Evaluation harness — fixtures, regression suites, stability tests, adversarial cases, NDCG / MRR / precision@k |
| brainwires-knowledge | Knowledge layer — BKS / PKS, BrainClient, entity graph |
| brainwires-rag | Codebase indexing + hybrid retrieval (vector + BM25), AST-aware chunking via tree-sitter, Git history search |
| brainwires-prompting | Adaptive prompting — technique library, K-means task clustering, BKS/PKS-aware generator, SEAL feedback hook |
| brainwires-storage | Substrate — StorageBackend trait, 9 backends, embeddings, BM25 keyword search, file-context primitives |
| brainwires-stores | Schema + CRUD for the opinionated minimum store set: sessions, conversations, tasks, plans, locks, images, templates + tier schema stores |
| brainwires-memory | Tiered memory orchestration — TieredMemory multi-factor adaptive search + offline dream consolidation engine. Built on brainwires-stores. |
| brainwires-permission | Permission policies (auto, ask, reject) for tool execution |
| brainwires-mcp-client | MCP client — connect to external MCP servers and use their tools |
| brainwires-mcp-server | MCP server framework with composable middleware; http feature adds stateless HTTP+SSE transport, Server Cards (SEP-1649), RFC9728, and Tasks (SEP-1686); oauth feature adds JWT validation middleware |
| brainwires-network | Agent networking — IPC, remote bridge, mesh, WebRTC, LAN discovery |
| brainwires-reasoning | Reasoning scorers — complexity, entity enhancer, relevance, retrieval classifier, router, strategy selector, summarizer, validator |
| brainwires-call-policy | Policies on outbound provider calls — retry with backoff, circuit breaker, budget caps, response cache, error classification |
| brainwires-hardware | Hardware I/O — audio (STT/TTS), GPIO, Bluetooth, camera/webcam, raw USB |
| brainwires-finetune | Cloud fine-tune APIs (OpenAI, Anthropic, Together, Fireworks, Anyscale, Bedrock, Vertex AI) + dataset pipelines. Local PEFT (LoRA / QLoRA / DoRA), training-from-scratch, and the pure-wgpu Gemma 4 inference engine all live in the sibling rullama workspace. |
| brainwires-telemetry | OutcomeMetrics, Prometheus export, anomaly detection, billing-hook trait |
| brainwires-a2a | Agent-to-Agent protocol — JSON-RPC 2.0, HTTP/REST, and gRPC bindings |
| brainwires-sandbox | Container-backed sandbox executor for untrusted tool code |
| brainwires-sandbox-proxy | Out-of-process sandbox-executor proxy for isolating untrusted code |
| Crate | Description |
|---|---|
| brainwires-proxy | HTTP proxy for AI API request routing |
| brainwires-brain-server | MCP server binary exposing the brainwires-knowledge::knowledge subsystem (BKS/PKS, thoughts, entity graphs) |
| brainwires-rag-server | MCP server binary exposing the brainwires-knowledge::rag subsystem (codebase indexing + hybrid search) |
| agent-chat | Simplified AI chat client with TUI and plain modes |
| reload-daemon | MCP server for killing and restarting AI coding clients |
| audio-demo-ffi | UniFFI bindings (cdylib) exposing brainwires-hardware (audio) to C#, Kotlin, Swift, Python |
| audio-demo | Cross-platform Avalonia GUI for TTS/STT demo across all audio providers |
| brainclaw | Self-hosted personal AI assistant daemon — multi-provider, per-user sessions, secure gateway |
| brainwires-gateway | WebSocket/HTTP channel hub — routes channel adapters to AI agent sessions |
| brainwires-discord-channel | Discord channel adapter — reference Channel trait implementation, optional MCP server mode |
| brainwires-telegram-channel | Telegram channel adapter — teloxide-based, optional MCP server mode |
| brainwires-slack-channel | Slack channel adapter — Socket Mode (no public URL), optional MCP server mode |
| brainwires-skill-registry | Skill registry HTTP server — SQLite FTS5, publish/search/download endpoints |
| brainclaw-mcp-github | GitHub channel adapter — webhook receiver, REST API, MCP server mode |
| brainwires-memory-server | Mem0-compatible memory REST API backed by Brainwires knowledge |
| claude-brain | Brainwires context management for Claude Code — persistent context across compaction |
| brainwires-cli | AI-powered agentic CLI tool for autonomous coding assistance |
| brainwires-issues | MCP-native issue tracking server |
| brainwires-scheduler | MCP server for cron scheduling |
| brainwires-autonomy | Autonomous agent operations |
| brainwires-wasm | WASM browser bindings |
| brainwires-billing | Billing and cost accounting hooks for agent telemetry |
| brainwires-docs | Documentation tooling and reference site generation |
| voice-assistant | End-to-end voice assistant binary using the brainwires-hardware pipeline |
crates/— the framework. Cohesive, independently-publishable libraries.extras/— applications and libraries that consume the framework: binaries, demos, MCP servers, and integration helpers.
Allowed dependency arrows: crates/ → crates/ and extras/ → crates/.
Forbidden: crates/ → extras/ (the framework cannot depend on its consumers) and extras/ → extras/ (extras are siblings of equal standing, not a hierarchy). If an extras/ library starts being depended on by another extras/ entry, that's a signal it belongs in crates/.
Enforcement: cargo xtask lint-deps walks every Cargo.toml and rejects forbidden arrows. See docs/adr/ADR-0004-framework-extras-boundary.md for the rationale.
The deprecated/ directory holds historical crates that have been merged or retired; nothing in the active workspace depends on it.
- Rust 1.91+ (edition 2024)
- Cargo (comes with Rust)
Note: This framework uses
edition = "2024"which requires Rust 1.91 or newer. Check your version withrustc --versionand update withrustup update stableif needed.
The simplest way to use the framework is through the brainwires facade crate, which re-exports everything behind feature flags:
[dependencies]
brainwires = "0.11" # defaults: tools + agentsEnable only what you need:
[dependencies]
brainwires = { version = "0.11", features = ["provider", "rag"] }Each crate is independently publishable and usable:
[dependencies]
brainwires-core = "0.11"
brainwires-provider = "0.11"
brainwires-agent = "0.11"use brainwires::prelude::*;
use brainwires::providers::{ChatProviderFactory, ProviderConfig, ProviderType};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Create a provider via the factory
let config = ProviderConfig {
provider: ProviderType::Anthropic,
model: "claude-sonnet-4-6".into(),
api_key: Some("your-api-key".into()),
base_url: None,
};
let provider = ChatProviderFactory::create(&config)?;
// Send a message
let messages = vec![Message::user("Hello, what can you do?")];
let options = ChatOptions::default();
let response = provider.chat(&messages, None, &options).await?;
println!("{}", response.message.content);
Ok(())
}The brainwires facade crate exposes feature flags corresponding to each sub-crate:
| Feature | Default | What it enables |
|---|---|---|
core |
Always | Core types and traits (not feature-gated) |
tools |
Yes | Tool definitions, execution, and interpreters (brainwires-tool-runtime + brainwires-tool-builtins) |
agents |
Yes | Multi-agent orchestration, communication hub, file/resource locks (brainwires-agent) |
inference |
Yes | LLM-driven workhorses — ChatAgent, PlannerAgent, JudgeAgent, TaskAgent, CycleOrchestrator (brainwires-inference) |
providers |
No | AI provider integrations |
storage |
No | Vector storage and semantic search |
mcp |
No | MCP client support |
agent-network |
No | Agent networking — IPC, remote bridge, channels, 5-layer protocol stack (brainwires-network) |
mcp-server-framework |
No | MCP server building blocks (McpServer, McpHandler, middleware pipeline) |
rag |
No | RAG engine with code search |
audio |
No | Audio capture, STT, TTS |
training |
No | Cloud fine-tuning (local PEFT lives in rullama-finetune) |
datasets |
No | Training data pipelines (delegates to brainwires-finetune) |
telemetry |
No | OutcomeMetrics, Prometheus export, billing hooks |
reasoning |
No | Reasoning strategies (re-exports from core) |
mesh |
No | Mesh networking (via agent-network mesh feature) |
a2a |
No | Agent-to-Agent protocol |
wasm |
No | WASM core bindings |
researcher |
No | Bundle: providers + agents + storage + rag + training + datasets |
# Build all crates (debug)
cargo build
# Build all crates (release)
cargo build --release
# Build a specific crate
cargo build -p brainwires-agent
# Run all tests
cargo test
# Run tests for a specific crate
cargo test -p brainwires-core brainwires (facade)
├── brainwires-agent
│ ├── brainwires-core
│ ├── brainwires-call-policy
│ ├── brainwires-tool-runtime
│ ├── brainwires-tool-builtins
│ ├── brainwires-storage (seal feature — for PatternStore)
│ ├── brainwires-knowledge (seal-knowledge feature)
│ └── brainwires-permission (seal-feedback feature)
├── brainwires-knowledge
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-rag
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-prompting
│ ├── brainwires-core
│ └── brainwires-knowledge (knowledge feature)
├── brainwires-storage
│ └── brainwires-core
├── brainwires-stores
│ ├── brainwires-core
│ └── brainwires-storage
├── brainwires-memory
│ ├── brainwires-core
│ ├── brainwires-storage
│ └── brainwires-stores (memory feature)
├── brainwires-tool-runtime
│ ├── brainwires-core
│ ├── brainwires-stores (sessions feature — SessionBroker)
│ ├── brainwires-rag (rag feature)
│ └── brainwires-sandbox (sandbox feature)
├── brainwires-tool-builtins
│ ├── brainwires-tool-runtime
│ └── brainwires-rag (rag feature)
├── brainwires-mcp-client
│ └── brainwires-core
├── brainwires-mcp-server
│ ├── brainwires-core
│ └── brainwires-mcp-client
├── brainwires-network
│ ├── brainwires-core
│ ├── brainwires-mcp-client
│ └── brainwires-a2a (a2a-transport feature)
├── brainwires-finetune (cloud only — local PEFT + wgpu Gemma 4 live in rullama)
│ ├── brainwires-core
│ └── brainwires-provider (cloud feature)
├── brainwires-telemetry
│ └── brainwires-core
└── brainwires-hardware
├── brainwires-provider (audio feature)
└── brainwires-provider-speech (audio feature)
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.