# Cerebro 🧠

[![Crates.io](https://img.shields.io/crates/v/cerebro.svg)](https://crates.io/crates/cerebro)
[![Docs.rs](https://docs.rs/cerebro/badge.svg)](https://docs.rs/cerebro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Cerebro** is a blazing-fast, universal, and storage-agnostic "Memory Layer" for AI Agents and LLM Applications, written in pure Rust.

## Why Cerebro?

While typical vector database wrappers just push raw vectors into a database, `Cerebro` functions as the **Hippocampus** for autonomous AI. It natively understands Agentic Memory structures:

- **Short-Term Episodic Memory** (Conversations)
- **Working Memory** (KV State)
- **Long-Term Semantic Memory** (Vector Search with Temporal Decay)

It bridges the gap between raw document parsing and multi-agent frameworks (like LangChain, Auto-GPT, Cursor).

## Key Features

- 🚀 **Zero-Cost Abstractions**: Powered by Rust, designed for massive async parsing and embedding workloads.
- 🔌 **Universal Storage**: Trait-based backends — swap between `MemoryVectorStore`, `PgVectorStore`, or `Qdrant`.
- 🧠 **Pluggable Compute**: Route embeddings through local models (`Candle`) or remote APIs (`OpenAI`, `Anthropic`).
- 🔄 **Active Consolidation**: Background "Sleep Cycle" worker for autonomous memory pruning and semantic organization.
- 🔍 **Hybrid Search**: Native RRF (Reciprocal Rank Fusion) combining keyword and vector retrieval for highest precision.
- 🌐 **MCP Ready**: Native Model Context Protocol server (`cerebro-mcp`) for AI desktop apps.
- 🦀 **Multi-Language**: Native Python (`PyO3`) and WASM bindings.
- 📄 **Complex Ingestion**: PDF extraction and HTML-aware semantic chunking.

## Getting Started

```toml
[dependencies]
cerebro = "0.1.1"
```

### Basic Example

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

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

    let engine = MemoryEngine::new(chunker, embedder, store);

    let doc = Document::new("The Rust programming language ensures memory safety.");
    engine.ingest_document(doc).await.unwrap();

    let memories = engine.query("What language is safe?", 5).await.unwrap();
    
    for (node, score) in memories {
        println!("Match: {} (Score: {})", node.chunk.text, score);
    }
}
```


---
*Author: Suraj Kumar Nanda* | [www.SurajKumarNanda.com](https://www.surajkumarnanda.com)

