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> · <a href="https://cerebro.life"><strong>Cerebro Pro</strong></a> · <a href="docs/ARCHITECTURE.md">Architecture</a> · <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>