cerebro-memory 0.1.4
Give your AI agents human-like memory. The pluggable memory layer for AI applications.
License: Apache-2.0
Requires Python: >=3.10
Keywords: ai, memory, llm, agents, rag

![Cerebro Logo](https://55tcr0vpgiqmtoym.public.blob.vercel-storage.com/banner.png)

# Cerebro

**Memory infrastructure for AI applications.**

Cerebro is the memory layer for AI systems. Extract facts, persist context, and retrieve relevant memories — with pluggable infrastructure that fits your stack.

```python
from cerebro import Memory

memory = Memory()

# Extract and store facts
memory.add("I'm John, I work at Google as a software engineer.", user_id="john")

# Semantic retrieval
results = memory.search("What is John's profession?", user_id="john")
# → ["Works as a software engineer at Google"]
```

## Why Cerebro

AI applications without persistent memory accumulate technical debt: lost context, repeated user friction, degraded personalization. Cerebro addresses this at the infrastructure layer.

**Core capabilities:**

- **Automatic fact extraction** — LLM-powered extraction from conversations
- **Hybrid retrieval** — Vector similarity + temporal decay + importance weighting
- **Deduplication** — Similarity-based duplicate prevention
- **Pluggable architecture** — Swap storage, vectors, embeddings, and LLM providers independently

## Installation

```bash
pip install cerebro-memory
```

Provider extras: `openai`, `anthropic`, `gemini`, `pinecone`, `qdrant`, `chroma`, `postgres`, `mongodb`, `redis`.

## Quick Start

```python
from cerebro import Memory

# Defaults: OpenAI embeddings + Chroma vectors + SQLite storage
memory = Memory()

# Extract facts from conversation
memory.add(
    messages=[
        {"role": "user", "content": "I just moved to Seattle"},
        {"role": "assistant", "content": "How do you like it?"},
        {"role": "user", "content": "Great city, but the rain takes adjustment"}
    ],
    user_id="user_123"
)
# Extracts: ["Lives in Seattle", "Likes Seattle", "Rain requires adjustment"]

# Semantic search
results = memory.search("Where does the user live?", user_id="user_123")

# Retrieve all
all_memories = memory.get_all(user_id="user_123")

# Cleanup
memory.close()
```

## Async API

```python
from cerebro import AsyncMemory
import asyncio

async def main():
    memory = AsyncMemory()
    await memory.add("I prefer dark mode", user_id="user_123")
    results = await memory.search("user preferences", user_id="user_123")
    await memory.close()

asyncio.run(main())
```

## Configuration

```python
from cerebro import Memory

config = {
    "llm": {
        "provider": "openai",  # or "anthropic", "gemini", "ollama"
        "config": {"model": "gpt-4o-mini"}
    },
    "embedder": {
        "provider": "openai",
        "config": {"model": "text-embedding-3-small"}
    },
    "vector_store": {
        "provider": "qdrant",  # or "pinecone", "chroma", "pgvector"
        "config": {"url": "http://localhost:6333"}
    },
    "storage": {
        "provider": "postgres",  # or "mongodb", "sqlite"
        "config": {
            "host": "localhost",
            "database": "cerebro",
            "user": "postgres",
            "password": "password"
        }
    },
    "cache": {
        "redis_url": "redis://localhost:6379",
        "enabled": True
    }
}

memory = Memory(config)
```

## Supported Providers

| Category | Providers |
|----------|-----------|
| LLMs | OpenAI, Anthropic, Gemini, Ollama |
| Embeddings | OpenAI, Gemini, Cohere, Ollama, HuggingFace |
| Vector Stores | Pinecone, Qdrant, Chroma, pgvector |
| Storage | PostgreSQL, MongoDB, SQLite |
| Cache | Redis |

## Roadmap

### v0.2 — Extraction & Intelligence
- [ ] Conversation ingestion pipeline
- [ ] Contradiction detection
- [ ] Memory consolidation

### v0.3 — Graph & Relationships
- [ ] Memory graph with relationship linking
- [ ] Graph-enhanced retrieval
- [ ] Adaptive decay rates

### v0.4 — Provider Expansion
- [ ] Weaviate, Milvus vector stores
- [ ] DynamoDB, Supabase storage
- [ ] Voyage, HuggingFace embeddings
- [ ] vLLM local inference

### v1.0 — Production Hardening
- [ ] TypeScript SDK
- [ ] REST API wrapper
- [ ] Prometheus metrics
- [ ] Distributed tracing

## Contributing

```bash
git clone https://github.com/bikidsx/cerebro-memory
cd cerebro-memory
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

Apache 2.0