Cerebro 🧠

An AI memory layer and multi-agent swarm engine in async Rust: specialized agents share working, episodic and semantic memory.

Features

• 🚀 Async Rust: Built on Tokio, with trait-based storage, embedding and LLM components.
• 🔌 Universal Storage: Trait-based backends — swap between MemoryVectorStore, PgVectorStore, or Qdrant.
• 🧠 Pluggable Compute: Route embeddings through local models (Candle, CPU) or remote APIs (OpenAI, Voyage AI).
• 🔄 Consolidation Worker (experimental): Periodic background task that scans stored memories and can ask an LLM to summarise them into an "axiom" (printed, not stored yet). Pruning and merging are planned.
• 🔍 Hybrid Search (PgVectorStore): Reciprocal Rank Fusion (RRF) of pgvector similarity and Postgres full-text rank. The in-memory and Qdrant stores use vector search only.
• 🕸️ Graphify: LLM-powered entity extraction into an in-memory (petgraph) or Neo4j knowledge graph. Querying triplets back from Neo4j is not implemented yet.
• 🧪 Experimental: an append-only KV store you can read as of any past step; an immunology supervisor that suggests a rewritten prompt after a failed run (not applied automatically); nearest-neighbour lookup over caller-assigned 3D coordinates (spatial feature).
• 🐝 SwarmForge: Multi-agent swarming engine with sequential, fan-out/fan-in, and hierarchical orchestration patterns.
• 🤖 Universal LLM: Supports Ollama, OpenAI, Gemini, Anthropic, and any OpenAI-compatible API.
• 🌐 MCP Ready: Native Model Context Protocol server (cerebro-mcp) for AI desktop apps.
• 🦀 Bindings (scaffolding only): the python (PyO3) and wasm features expose placeholder classes; ingest and search are not wired to the engine yet.
• 📄 Complex Ingestion: PDF extraction and HTML-aware semantic chunking.

Getting Started

[dependencies]
cerebro = "1.1.9"

1. Working with the Memory Engine

Store and retrieve semantic memory. This example uses the in-memory store (vector search only); PgVectorStore adds hybrid search with Reciprocal Rank Fusion.

use cerebro::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let engine = MemoryEngine::new(
        Arc::new(RecursiveCharacterChunker::new(512, 50)),
        Arc::new(MockEmbedder::new(1536)),
        Arc::new(MemoryVectorStore::new()),
    );

    engine.ingest_document(Document::new("Rust ensures memory safety.")).await.unwrap();

    let results = engine.query("memory safety", 1).await.unwrap();
    println!("Match: {}", results[0].0.chunk.text);
}

2. Building a Multi-Agent Swarm

Orchestrate a team of agents that share Cerebro's memory layer.

use cerebro::prelude::*;
use cerebro::swarm::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let engine = Arc::new(MemoryEngine::new(
        Arc::new(RecursiveCharacterChunker::new(512, 50)),
        Arc::new(MockEmbedder::new(8)),
        Arc::new(MemoryVectorStore::new()),
    ));
    let memory = Arc::new(CerebroMemoryBus::new(engine, Arc::new(MemoryKVStore::new())));
    
    let mut swarm = SwarmOrchestrator::new(memory);

    swarm.register_agent(AgentConfig {
        id: "analyst".into(),
        name: "Security Analyst".into(),
        system_prompt: "Analyze code for vulnerabilities.".into(),
        model: LlmProvider::Ollama { model: "llama3".into(), base_url: "http://localhost:11434".into() },
        tools: vec![], handoff_targets: vec![], max_steps: 10,
    });

    let result = swarm.execute(
        SwarmPattern::Sequential { agent_order: vec!["analyst".into()] },
        "Review this code snippet",
    ).await.unwrap();
}

3. Model Context Protocol (MCP)

Cerebro acts as a native Model Context Protocol server for your local IDE (Cursor, Claude Desktop).

Compile the server:

cargo build --release --bin cerebro-mcp

Add the generated binary to your IDE's MCP config:

{
  "mcpServers": {
    "cerebro": {
      "command": "<ABSOLUTE_PATH>/target/release/cerebro-mcp",
      "args": []
    }
  }
}

Supported LLM Providers