Cerebro

<div align="center"> <img src="https://readme-typing-svg.demolab.com?font=Orbitron&weight=900&size=60&duration=3000&pause=1000&color=8B5CF6&center=true&vCenter=true&width=600&height=80&lines=CEREBRO" alt="Cerebro" /> <br/> <em>The Brain Behind the Code</em> <br/><br/> <strong>A cognitive memory system that plugs into Claude Code (or any MCP client) and gives your AI persistent memory, learning, causal reasoning, and predictive intelligence — across every session, every project, forever.</strong> <br/><br/> <img src="docs/images/neural-banner.svg" width="900" alt="Neural Network"/> <br/><br/> _{49 MCP tools. 3-tier memory. Local-first. Install in under 3 minutes.} </div>

<br/>

<div align="center">

     

</div>

---

Why Cerebro?

<table> <tr> <td align="center" width="33%">

:brain: Remember Everything

Your AI gets total recall. Conversations, facts, and context carry across sessions — nothing is ever forgotten.

• Episodic memory for events, semantic for facts, working for active reasoning
• Hybrid semantic + keyword search across all memories
• Session continuity — pick up exactly where you left off

</td> <td align="center" width="33%">

:gear: Learn and Adapt

Your AI gets smarter with every interaction. Solutions, failures, and patterns are tracked automatically.

• Auto-detects solutions, failures, and antipatterns
• Patterns auto-promote to trusted knowledge after 3+ confirmations
• Tracks past mistakes and avoids repeating them

</td> <td align="center" width="33%">

:crystal_ball: Reason and Predict

Go beyond retrieval into genuine reasoning. Cerebro builds causal models and catches problems before they happen.

• Causal models with "what-if" simulation
• Predictive failure anticipation from historical patterns
• Hallucination detection and confidence scoring

</td> </tr> </table>

---

See It In Action

<div align="center"> <img src="docs/images/demo.gif" width="900" alt="Cerebro MCP tools in Claude Code"/> <br/> _{<a href="https://github.com/Professor-Low/Cerebro/releases/download/v2.0.0/demo.mp4">Watch full demo (1:49)</a>} </div>

Note: In the demo, Claude Code calls tools prefixed with ai-memory — that's just the MCP server name in the config. The server is Cerebro. Name it anything you like in your mcp.json (we recommend "cerebro").

---

Quick Start

Prerequisites

• Python 3.10+
• Claude Code or any MCP-compatible client

1. Install

pip install cerebro-ai

For semantic search (recommended — uses FAISS + sentence-transformers):

pip install cerebro-ai[embeddings]

Without [embeddings], Cerebro falls back to keyword-only search. Still functional, but semantic search is significantly more powerful.

2. Initialize

cerebro init

This creates your local memory store at ~/.cerebro/data.

3. Add to Claude Code

Add this to your MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "cerebro": {
      "command": "cerebro",
      "args": ["serve"]
    }
  }
}

4. Verify

Restart Claude Code and run /mcp — you should see 49 Cerebro tools. Start a conversation and Cerebro will automatically begin building your memory.

5. Tell Claude How to Use Memory (Recommended)

Add this to your ~/.claude/CLAUDE.md:

## AI Memory (Cerebro)
- At session start, call `check_session_continuation` to resume previous work
- Before answering questions, call `search` to check if relevant memory exists
- When you solve a problem, call `record_learning` to save the solution
- Call `get_corrections` to avoid repeating known mistakes
- Use `update_active_work` before ending a session with pending work

This tells Claude how to use the 49 memory tools proactively, instead of waiting for you to ask.

6. Install Hooks (Optional)

cerebro hooks install

Hooks automate memory at lifecycle events — saving conversations on exit, injecting context on each message, restoring continuity on start. Run cerebro hooks status to see what's installed.

Health Check

cerebro doctor

Note: If you installed with [embeddings], the first run downloads a ~438 MB sentence-transformer model. Subsequent starts are instant.

---

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0a0a1a,50:4c1d95,100:7c3aed&height=80&section=header&reversal=true" width="100%"/>

<div align="center">

The Full Experience

The MCP tools give your AI persistent memory. Cerebro Pro wraps it in a complete cognitive desktop — where your AI thinks, acts, and evolves autonomously.

</div>

<div align="center"> <br/> <a href="https://cerebro.life"> <img src="https://img.shields.io/badge/Explore_Cerebro_Pro-%E2%86%92_cerebro.life-A855F7?style=for-the-badge&labelColor=1a1a2e" alt="Cerebro Pro"/> </a> <br/><br/> </div>

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:7c3aed,50:4c1d95,100:0a0a1a&height=80&section=footer" width="100%"/>

---

What You Get

These are the tools you'll use daily. Cerebro has 49 total — here are the highlights:

| Tool | What it does | |------|-------------| | search | Find anything in memory — hybrid semantic + keyword search across all conversations, facts, and learnings | | record_learning | Save a solution, failure, or antipattern. Next time you hit the same problem, Cerebro surfaces it | | get_corrections | Check what your AI got wrong before — so it doesn't repeat the same mistakes | | check_session_continuation | Pick up where you left off. Detects in-progress work and restores full context | | working_memory | Active reasoning state: hypotheses, evidence chains, scratch notes that persist across compactions | | causal | Build cause-effect models. Ask "what causes X?" or simulate "what if I do Y?" | | predict | Anticipate failures before they happen based on patterns from your history | | get_user_profile | Your AI knows your preferences, projects, environment, and goals — no re-explaining |

See all 49 tools below or browse the full MCP Tools Reference.

<p align="center"> <br/> <img src="docs/images/cerebro-flow.svg" width="800" alt="Cerebro Pipeline"/> <br/><br/> </p>

Your First Conversation

Once Cerebro is connected, try this:

You: "Search my memory for anything about Docker networking"
Claude: calls search("Docker networking") → finds nothing yet

You: "I just learned that Docker containers on the same network
       can reach each other by container name, not IP."
Claude: calls record_learning(solution, ...)
        → Saved! Next time you ask about Docker networking, this surfaces automatically.

You: "What mistakes have I made before?"
Claude: calls get_corrections() → shows past corrections so it doesn't repeat them

Every session builds on the last. After a few conversations, Claude knows your projects, preferences, and environment without re-explaining.

---

All 49 MCP Tools

Cerebro exposes 49 tools through the Model Context Protocol, organized into 10 categories. Every tool works with any MCP-compatible AI client.

<details> <summary><strong>Memory Core</strong> (5 tools) — Store, search, and retrieve memories</summary>

| Tool | Description | |------|-------------| | save_conversation_ultimate | Save conversations with comprehensive extraction of facts, entities, actions, and code snippets | | search | Hybrid semantic + keyword search across all memories (recommended default) | | search_knowledge_base | Search the central knowledge base for facts, learnings, and discoveries | | search_by_device | Filter memory searches by device origin (e.g., only laptop conversations) | | get_chunk | Retrieve specific memory chunks by ID for context injection |

</details>

<details> <summary><strong>Knowledge Graph</strong> (5 tools) — Entities, timelines, and user context</summary>

| Tool | Description | |------|-------------| | get_entity_info | Get information about any entity (tool, person, server, etc.) with conversation history | | get_timeline | Chronological timeline of actions and decisions for a given month | | find_file_paths | Find all file paths mentioned in conversations with purpose and context | | get_user_context | Comprehensive user context: goals, preferences, technical environment | | get_user_profile | Full personal profile: identity, relationships, projects, preferences |

</details>

<details> <summary><strong>3-Tier Memory</strong> (6 tools) — Episodic, semantic, and working memory</summary>

| Tool | Description | |------|-------------| | memory_type: query_episodic | Query event memories by date, actor, or emotional state | | memory_type: query_semantic | Query general facts by domain or keyword | | memory_type: save_episodic | Save event memories with emotional state and outcome | | memory_type: save_semantic | Save factual knowledge with domain classification | | working_memory | Active reasoning state: hypotheses, evidence chains, scratch notes | | consolidate | Cluster episodes, create abstractions, strengthen connections, prune redundancies |

</details>

<details> <summary><strong>Reasoning</strong> (5 tools) — Causal models, prediction, and self-awareness</summary>

| Tool | Description | |------|-------------| | reason | Active reasoning over memories: analyze, find insights, validate hypotheses | | causal | Causal models: add cause-effect links, find causes/effects, simulate "what-if" interventions | | predict | Predictive simulation: anticipate failures, check patterns, suggest preventive actions | | self_model | Continuous self-modeling: confidence tracking, uncertainty, hallucination checks | | analyze | Pattern analysis, knowledge gap detection, skill development tracking |

</details>

<details> <summary><strong>Learning</strong> (4 tools) — Solutions, corrections, and antipatterns</summary>

| Tool | Description | |------|-------------| | record_learning | Record solutions, failures, or antipatterns with tags and context | | find_learning | Search for proven solutions or known antipatterns by problem description | | analyze_conversation_learnings | Extract learnings from a past conversation automatically | | get_corrections | Retrieve corrections Claude learned from the user to avoid repeating mistakes |

</details>

<details> <summary><strong>Session Continuity</strong> (6 tools) — Never lose your place</summary>

| Tool | Description | |------|-------------| | check_session_continuation | Check for recent work-in-progress to continue | | get_continuation_context | Get full context for resuming a previous session | | update_active_work | Track current project state for session handoff | | session_handoff | Save and restore working memory across sessions | | working_memory: export/import | Export active reasoning state for handoff, import to restore | | session | Session info: thread history, active sessions, summaries, continuation detection |

</details>

<details> <summary><strong>User Intelligence</strong> (5 tools) — Preferences, goals, and proactive suggestions</summary>

| Tool | Description | |------|-------------| | preferences | Track and evolve user preferences with confidence weighting and contradiction detection | | personality | Personality evolution: traits, consistency checks, feedback-driven adaptation | | goals | Detect, track, and reason about user goals with blocker identification | | suggest_questions | Generate questions to fill knowledge gaps in the user profile | | get_suggestions | Proactive context-aware suggestions based on current situation and history |

</details>

<details> <summary><strong>Projects</strong> (2 tools) — Project tracking and version evolution</summary>

| Tool | Description | |------|-------------| | projects | Project lifecycle: state, active list, stale detection, auto-update, activity summaries | | project_evolution | Version tracking: record releases, view timeline, manage superseded versions |

</details>

<details> <summary><strong>Quality</strong> (5 tools) — Maintenance, health, and self-improvement</summary>

| Tool | Description | |------|-------------| | rebuild_vector_index | Rebuild the FAISS vector search index after bulk updates | | decay | Storage decay management: run decay cycles, preview, manage golden (protected) items | | self_report | Self-improvement reports: performance metrics, before/after tracking | | system_health_check | Health check across all components: storage, embeddings, indexes, database | | quality | Memory quality: deduplication, merge, fact linking, quality scoring |

</details>

<details> <summary><strong>Meta</strong> (6 tools) — Retrieval optimization, privacy, and exploration</summary>

| Tool | Description | |------|-------------| | meta_learn | Retrieval strategy optimization: A/B testing, parameter tuning, performance tracking | | memory_type | Query and manage episodic vs semantic memory types with stats and migration | | privacy | Secret detection, redaction statistics, sensitive conversation identification | | device | Device registration and identification for multi-device memory isolation | | branch | Exploration branches: create divergent reasoning paths, mark chosen/abandoned | | conversation | Conversation management: tagging, notes, relevance scoring |

</details>

---

How It Works

graph LR
  A[Your AI Client] <-->|MCP Protocol| B[Cerebro Server]
  B --> C[FAISS Vector Search]
  B --> D[Knowledge Base]
  B --> E[File Storage]

All data stays on your machine. No cloud, no API keys, no telemetry.

---

Free vs Pro

| Capability | Free (This Repo) | Pro (cerebro.life) | |---|---|---| | Memory | 49-tool MCP server. Full cognitive architecture. | Everything in Free + dashboard visualization of your memory graph and health stats. | | Interface | Claude Code CLI or any MCP client. | Native desktop app with Mind Chat, 3D neural constellation, real-time activity. | | Agents | Single Claude session with persistent memory. | Agent swarms — multiple Claudes collaborating on complex tasks autonomously. | | Browser | Not included. | Autonomous browser agents: research, navigate, extract — with live video preview. | | Automations | Not included. | Calendar-driven recurring tasks, scheduled research, automated workflows. | | Cognitive Loop | Not included. | OODA cycle: Observe-Orient-Decide-Act. Your AI thinks and acts continuously. |

<div align="center"> <br/> <a href="https://cerebro.life"> <img src="https://img.shields.io/badge/See_Cerebro_Pro_in_Action-%E2%86%92_cerebro.life-A855F7?style=for-the-badge&labelColor=1a1a2e" alt="Cerebro Pro"/> </a> <br/><br/> </div>

---

Configuration

Cerebro works out of the box with zero configuration. All settings are optional and controlled via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | CEREBRO_DATA_DIR | ~/.cerebro/data | Base directory for all Cerebro data | | CEREBRO_EMBEDDING_MODEL | all-mpnet-base-v2 | Sentence transformer model for semantic search | | CEREBRO_EMBEDDING_DIM | 768 | Embedding vector dimensions | | CEREBRO_LOG_LEVEL | INFO | Logging level | | CEREBRO_LLM_URL | (none) | Optional local LLM endpoint for deeper reasoning | | CEREBRO_LLM_MODEL | (none) | Optional local LLM model name |

Set them in your MCP config:

{
  "mcpServers": {
    "cerebro": {
      "command": "cerebro",
      "args": ["serve"],
      "env": {
        "CEREBRO_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}

---

Troubleshooting

| Problem | Solution | |---------|----------| | First start is slow | If you installed [embeddings], the sentence-transformer model (~438 MB) downloads on first run. This is a one-time download. | | "No module named 'src'" | Install via pip install cerebro-ai, not by running the source directly. | | MCP tools not showing up | Check ~/.claude/mcp.json is valid JSON, restart Claude Code, and run /mcp to verify. | | Hook errors blocking Claude | Hooks should never block — they always output {"continue": true}. Check stderr output with cerebro hooks status. If a hook is broken, run cerebro hooks uninstall to remove all hooks. | | "cerebro: command not found" | Ensure the pip scripts directory is in your PATH. Try python -m src.cli serve as a fallback. |

---

Contributing

Contributions are welcome — bug fixes, new MCP tools, documentation improvements, or feature ideas.

Please read the Contributing Guide before submitting a pull request. All contributions must be compatible with the AGPL-3.0 license.

---

License & Attribution

Copyright (C) 2026 Michael Lopez (Professor-Low)

Cerebro is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
See LICENSE for details.

What AGPL-3.0 means: If you use Cerebro's code in your own product — including as a network service — you must release your modified source code under the same license and give proper attribution. This protects the project from being taken proprietary.

Created and maintained by Michael Lopez (Professor-Low)

<div align="center"> <br/>

<p> <a href="#quick-start">Get Started</a> &middot; <a href="https://cerebro.life"><strong>Cerebro Pro</strong></a> &middot; <a href="docs/ARCHITECTURE.md">Architecture</a> &middot; <a href="https://github.com/Professor-Low/Cerebro/issues">Issues</a> </p>

_{If Cerebro helps you, consider giving it a star — it helps others find the project.} <br/><br/> <a href="https://github.com/Professor-Low/Cerebro"> <img src="https://img.shields.io/github/stars/Professor-Low/Cerebro?style=social" alt="GitHub stars" /> </a> <br/><br/> <a href="https://cerebro.life"><strong>cerebro.life</strong></a> </div>