Brainwires Framework

Brainwires Framework

[](https://github.com/Brainwires/brainwires-framework/actions/workflows/ci.yml) [](https://crates.io/crates/brainwires) [](https://docs.rs/brainwires) [](#testing) [](#) [](https://github.com/Brainwires/brainwires-framework/blob/main/LICENSE-MIT) [](https://www.rust-lang.org/)

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.

Overview

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](FEATURES.md) | Key capabilities:

• Multi-provider AI — Anthropic, OpenAI, Google, Ollama, and local LLMs behind a unified Provider trait
• 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

Crate Map

  ┌─────────────────────────────────────────────────────────────────┐
  │                          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│   │
  │  └────────────┘ └─────────────┘ └──────────┘ └──────────────┘   │
  └─────────────────────────────────────────────────────────────────┘

Framework Crates

| Crate | Description | |-------|-------------| | [brainwires](crates/brainwires/README.md) | Facade crate — re-exports every other framework crate behind feature flags | | [brainwires-core](crates/brainwires-core/README.md) | Core types, traits, and error handling shared by all crates | | [brainwires-provider](crates/brainwires-provider/README.md) | Multi-provider LLM interface (Anthropic, OpenAI, Google, Ollama, Bedrock, Vertex AI, local llama.cpp / Candle) | | [brainwires-provider-speech](crates/brainwires-provider-speech/README.md) | Speech (TTS / STT) providers (Azure, Cartesia, Deepgram, ElevenLabs, Fish, Google, Murf, browser web-speech) | | [brainwires-tool-runtime](crates/brainwires-tool-runtime/README.md) | Tool framework — ToolExecutor, ToolRegistry, validation, smart router, sandbox/orchestrator/sessions/oauth/openapi | | [brainwires-tool-builtins](crates/brainwires-tool-builtins/README.md) | Built-in tool implementations: bash, fileops, git, web, search, codeexec, browser, email, calendar, system, semantic_search | | [brainwires-agent](crates/brainwires-agent/README.md) | Agent coordination primitives + multi-agent patterns — communication, locks, queues, git coordination, contract net, saga, optimistic concurrency, market allocation, workflow graph | | [brainwires-inference](crates/brainwires-inference/README.md) | LLM-driven workhorses — ChatAgent, TaskAgent, planner / judge / validator helpers, cycle orchestrator, validation loop, summarization, system-prompt registry | | [brainwires-mdap](crates/brainwires-mdap/README.md) | Multi-Dimensional Adaptive Planning (MAKER voting framework) | | [brainwires-seal](crates/brainwires-seal/README.md) | Self-Evolving Agentic Learning — coreference, query-core extraction, learned-pattern store, reflection | | [brainwires-skills](crates/brainwires-skills/README.md) | SKILL.md skills system — manifest parsing, registry, smart routing, sandboxed execution | | [brainwires-eval](crates/brainwires-eval/README.md) | Evaluation harness — fixtures, regression suites, stability tests, adversarial cases, NDCG / MRR / precision@k | | [brainwires-knowledge](crates/brainwires-knowledge/README.md) | Knowledge layer — BKS / PKS, BrainClient, entity graph | | [brainwires-rag](crates/brainwires-rag/README.md) | Codebase indexing + hybrid retrieval (vector + BM25), AST-aware chunking via tree-sitter, Git history search | | [brainwires-prompting](crates/brainwires-prompting/README.md) | Adaptive prompting — technique library, K-means task clustering, BKS/PKS-aware generator, SEAL feedback hook | | [brainwires-storage](crates/brainwires-storage/README.md) | Substrate — StorageBackend trait, 9 backends, embeddings, BM25 keyword search, file-context primitives | | [brainwires-stores](crates/brainwires-stores/README.md) | Schema + CRUD for the opinionated minimum store set: sessions, conversations, tasks, plans, locks, images, templates + tier schema stores | | [brainwires-memory](crates/brainwires-memory/README.md) | Tiered memory orchestration — TieredMemory multi-factor adaptive search + offline dream consolidation engine. Built on brainwires-stores. | | [brainwires-permission](crates/brainwires-permission/README.md) | Permission policies (auto, ask, reject) for tool execution | | [brainwires-mcp-client](crates/brainwires-mcp-client/README.md) | MCP client — connect to external MCP servers and use their tools | | [brainwires-mcp-server](crates/brainwires-mcp-server/README.md) | 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](crates/brainwires-network/README.md) | Agent networking — IPC, remote bridge, mesh, WebRTC, LAN discovery | | [brainwires-reasoning](crates/brainwires-reasoning/README.md) | Reasoning scorers — complexity, entity enhancer, relevance, retrieval classifier, router, strategy selector, summarizer, validator | | [brainwires-call-policy](crates/brainwires-call-policy/README.md) | Policies on outbound provider calls — retry with backoff, circuit breaker, budget caps, response cache, error classification | | [brainwires-hardware](crates/brainwires-hardware/README.md) | Hardware I/O — audio (STT/TTS), GPIO, Bluetooth, camera/webcam, raw USB | | [brainwires-finetune](crates/brainwires-finetune/README.md) | 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](crates/brainwires-telemetry/README.md) | OutcomeMetrics, Prometheus export, anomaly detection, billing-hook trait | | [brainwires-a2a](crates/brainwires-a2a/README.md) | Agent-to-Agent protocol — JSON-RPC 2.0, HTTP/REST, and gRPC bindings | | [brainwires-sandbox](crates/brainwires-sandbox/README.md) | Container-backed sandbox executor for untrusted tool code | | [brainwires-sandbox-proxy](crates/brainwires-sandbox-proxy/README.md) | Out-of-process sandbox-executor proxy for isolating untrusted code |

Extras

| Crate | Description | |-------|-------------| | [brainwires-proxy](extras/brainwires-proxy/README.md) | HTTP proxy for AI API request routing | | [brainwires-brain-server](extras/brainwires-brain-server/README.md) | MCP server binary exposing the brainwires-knowledge::knowledge subsystem (BKS/PKS, thoughts, entity graphs) | | [brainwires-rag-server](extras/brainwires-rag-server/README.md) | MCP server binary exposing the brainwires-knowledge::rag subsystem (codebase indexing + hybrid search) | | [agent-chat](extras/agent-chat/README.md) | Simplified AI chat client with TUI and plain modes | | [reload-daemon](extras/reload-daemon/README.md) | MCP server for killing and restarting AI coding clients | | [audio-demo-ffi](extras/audio-demo-ffi/README.md) | UniFFI bindings (cdylib) exposing brainwires-hardware (audio) to C#, Kotlin, Swift, Python | | [audio-demo](extras/audio-demo/README.md) | Cross-platform Avalonia GUI for TTS/STT demo across all audio providers | | [brainclaw](extras/brainclaw/daemon/README.md) | Self-hosted personal AI assistant daemon — multi-provider, per-user sessions, secure gateway | | [brainwires-gateway](extras/brainclaw/gateway/README.md) | WebSocket/HTTP channel hub — routes channel adapters to AI agent sessions | | [brainwires-discord-channel](extras/brainclaw/mcp-discord/README.md) | Discord channel adapter — reference Channel trait implementation, optional MCP server mode | | [brainwires-telegram-channel](extras/brainclaw/mcp-telegram/README.md) | Telegram channel adapter — teloxide-based, optional MCP server mode | | [brainwires-slack-channel](extras/brainclaw/mcp-slack/README.md) | Slack channel adapter — Socket Mode (no public URL), optional MCP server mode | | [brainwires-skill-registry](extras/brainclaw/mcp-skill-registry/README.md) | Skill registry HTTP server — SQLite FTS5, publish/search/download endpoints | | [brainclaw-mcp-github](extras/brainclaw/mcp-github/README.md) | GitHub channel adapter — webhook receiver, REST API, MCP server mode | | [brainwires-memory-server](extras/brainwires-memory-server/README.md) | Mem0-compatible memory REST API backed by Brainwires knowledge | | [claude-brain](extras/claude-brain/README.md) | Brainwires context management for Claude Code — persistent context across compaction | | [brainwires-cli](extras/brainwires-cli/README.md) | AI-powered agentic CLI tool for autonomous coding assistance | | [brainwires-issues](extras/brainwires-issues/README.md) | MCP-native issue tracking server | | [brainwires-scheduler](extras/brainwires-scheduler/README.md) | MCP server for cron scheduling | | [brainwires-autonomy](extras/brainwires-autonomy/README.md) | Autonomous agent operations | | [brainwires-wasm](extras/brainwires-wasm/README.md) | WASM browser bindings | | [brainwires-billing](extras/brainwires-billing/README.md) | Billing and cost accounting hooks for agent telemetry | | [brainwires-docs](extras/brainwires-docs/README.md) | Documentation tooling and reference site generation | | [voice-assistant](extras/voice-assistant/README.md) | End-to-end voice assistant binary using the brainwires-hardware pipeline |

Workspace layout

• 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](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.

Getting Started

Requirements

• 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 with rustc --version and update with rustup update stable if needed.

Using the Facade Crate

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 + agents

Enable only what you need:

[dependencies]
brainwires = { version = "0.11", features = ["provider", "rag"] }

Using Individual Crates

Each crate is independently publishable and usable:

[dependencies]
brainwires-core = "0.11"
brainwires-provider = "0.11"
brainwires-agent = "0.11"

Minimal Example

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(())
}

Feature Flags

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 expo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Brainwires
• Source: Brainwires/brainwires-framework
• License: Apache-2.0
• Homepage: https://brainwires.dev/

Install and usage instructions live in the source repository linked above.