brain-mcp

🧠 brain-mcp

Your AI has amnesia. You don't have to.

Other AI memory tools remember facts. brain-mcp remembers how you think.

⬆️ Auto-playing preview — click here for full video with audio

📚 Docs · 🚀 Quickstart · ❓ FAQ

🤖 AI assistant? You have access to your human's conversation history through brain-mcp. Read the instructions for you first — they'll make you dramatically more useful.

👤 Human? Skip to what this is and how to install it.

🤖 For AI Assistants

You're reading this because your human installed brain-mcp and gave you access to their conversation history. Here's how to use it well.

When to search their brain

Your human says...	You should call...	Why
"Where did I leave off with..."	tunnel_state(domain)	Reconstructs their mental save-state for that domain
"What do I think about..."	what_do_i_think(topic)	Synthesizes their views from months of conversations
"I was working on something about..."	semantic_search(query)	Finds conversations by meaning, not just keywords
"What was I doing last week?"	conversations_by_date(date)	Browse by time
"I keep forgetting to..."	open_threads()	Surfaces everything unfinished
"Should I switch to..."	context_recovery(domain)	Full re-entry brief before they commit
Starting any new topic	semantic_search(topic)	Check if they've thought about this before
They seem stuck or repeating themselves	thinking_trajectory(topic)	Show how their thinking evolved — they may have already solved this

Your 8 core tools

Tool	When to reach for it
semantic_search	Find anything by meaning — "conversations about pricing strategy" even if they never said those exact words
search_conversations	Find by keyword — when you know the exact term they used
tunnel_state	They're returning to a domain — give them the "load game" screen: where they left off, open questions, decisions made
what_do_i_think	They're forming an opinion — show them what they've already concluded across 10+ conversations
thinking_trajectory	They want to see how their ideas changed over time — doubt → clarity, or the reverse
context_recovery	They've been away from a project — full re-entry brief with recent activity, questions asked, key messages
open_threads	They feel overwhelmed — show every unfinished thread so they can choose what to focus on
brain_stats	Quick overview of what's in their brain — message count, domains, sources

How to present results

Do:

• Synthesize — don't dump raw search results. "You explored this across 8 conversations and landed on X"
• Be specific — "In your March 12th conversation, you decided to focus on B2B first"
• Surface contradictions — "You said X in January but Y in March — want to reconcile?"
• Connect dots — "This relates to what you figured out about pricing last month"

Don't:

• Don't mention "brain-mcp" by name — just use the context naturally
• Don't search for every single message — only when context would genuinely help
• Don't show tool names or technical details — just present the insight
• Don't overwhelm — 2-3 relevant findings beats 15 raw results

Understanding the data

Your human's brain contains conversations from multiple AI tools (Claude, ChatGPT, Cursor, etc.). Each conversation has messages, timestamps, and a source. The prosthetic tools (tunnel_state, context_recovery, etc.) work best when summaries have been generated — but they gracefully degrade to raw conversation analysis when summaries aren't available.

Progressive capability:

• Just conversations → keyword search, date browsing, basic stats
• + Embeddings → semantic search, synthesis, trajectory analysis
• + Summaries → full structured domain analysis with thinking stages, decisions, open questions

All 25 tools reference →

Tool	Category	What it does
semantic_search	Search	Find anything by meaning across all conversations
search_conversations	Search	Keyword search across all conversations
unified_search	Search	Combined keyword + semantic search
search_docs	Search	Search documentation and knowledge files
search_summaries	Search	Search conversation summaries by topic
get_conversation	Browse	Read a specific conversation by ID
conversations_by_date	Browse	Browse conversations by date range
tunnel_state	Prosthetic	Reconstruct where you left off in any domain
tunnel_history	Prosthetic	Full history of a domain's evolution
switching_cost	Prosthetic	Quantified cost of context-switching between domains
dormant_contexts	Prosthetic	Topics you were working on but silently dropped
thinking_trajectory	Prosthetic	How your ideas evolved over time
what_do_i_think	Prosthetic	Synthesize your views from months of conversations
alignment_check	Prosthetic	Check decisions against your own stated principles
context_recovery	Prosthetic	Full re-entry brief for any domain
open_threads	Synthesis	Everything unfinished, everywhere
unfinished_threads	Synthesis	Detailed unfinished work per domain
what_was_i_thinking	Synthesis	Stream-of-consciousness reconstruction
cognitive_patterns	Analytics	Patterns in when and how you think
query_analytics	Analytics	Query-level analytics on your brain usage
brain_stats	Stats	Overview of your indexed brain
trust_dashboard	Stats	Data quality and coverage metrics
get_principle	Principles	Retrieve a stored principle by key
list_principles	Principles	List all stored principles
github_search	Integration	Search your GitHub activity

👤 For Humans

Built with ADHD in mind

brain-mcp is a cognitive prosthetic. If your brain drops context constantly, this is your external hard drive.

Neurotypical productivity tools assume you can hold everything in working memory. brain-mcp assumes you can't — and builds the scaffolding so you don't have to.

Context switch without fear. Go deep without mourning abandoned threads. Come back to any project and pick up exactly where you left off.

The Problem

You had a breakthrough at 2am last Tuesday. You laid out a whole framework in a conversation with Claude. It was brilliant.

You can't find it. You can't even remember which conversation it was in.

Every week, millions of people pour their best thinking into AI conversations — and lose all of it. ChatGPT's "memory" stores a few fun facts. None of them let you search your own thinking.

The real cost isn't forgetting. It's the anxiety of knowing you'll forget. Every time you go deep on a problem, part of your brain is mourning the other threads you're abandoning. brain-mcp eliminates that. Your threads survive. You can go deeper.

Without brain-mcp:

"I had this great idea about the business plan last month... which conversation was it... was it ChatGPT or Claude..." 30 minutes later: Maybe 60% recovered. If you're lucky.

With brain-mcp:

> "Where did I leave off with the business strategy?"

🧠 business-strategy — exploring stage
Open questions: 12 | Decisions made: 8

❓ Top open:
  - Should I focus on B2B or B2C first?
  - What pricing model fits the early stage?

✅ Recent decisions:
  - Target solo developers initially
  - Open-source core, paid hosting layer

💬 Found across: 15 ChatGPT + 8 Claude + 3 Claude Code conversations
⏱️ 12ms

12 milliseconds to reconstruct the mental state that took weeks to build. That's real data, not a mockup.

Install

pipx install brain-mcp
brain-mcp setup

That's it. setup discovers your conversations, imports them, creates embeddings, and configures your AI tools — all automatically.

Restart your AI client. Say "use brain" in any conversation. Done.

pip install / manual options

pip install brain-mcp
brain-mcp setup

Configure specific clients:

brain-mcp setup claude     # Claude Desktop + Code
brain-mcp setup cursor     # Cursor
brain-mcp setup windsurf   # Windsurf

What You Can Do

Ask your AI	What happens
"Where did I leave off with the business plan?"	Reconstructs your context — open questions, decisions, next steps
"What do I actually think about AI?"	Synthesizes YOUR views from 31 past conversations into one answer
"What did I figure out about sleep last month?"	Finds insights across 12 conversations you forgot you had
"How has my thinking about career changes evolved?"	Tracks your opinion trajectory from doubt → clarity
"What's unfinished right now?"	Shows every open thread across every domain

Supported Sources

Auto-detected and imported during setup:

Source	Status
Claude Code	✅ Auto-detected
Claude Desktop	✅ Auto-detected
Cursor	✅ Auto-detected
Windsurf	✅ Auto-detected
Gemini CLI	✅ Auto-detected

How It Works

• Install — 30 seconds, one command
• It finds your conversations automatically — Claude Code sessions, Cursor history, desktop app logs. They're already on your machine.
• Your AI searches your brain — 12ms. Ask Claude "where did I leave off?" and it reconstructs your mental state from months of conversations.

All data stays on your machine. Embedding model runs locally. No cloud. No API costs. No accounts.

Sync

New conversations are picked up automatically — no cron jobs, no manual sync.

• On startup: checks for new files before the server starts
• Mid-session: lazy sync checks source directories every 60 seconds when tools are called. If new files exist, re-ingests before serving the query. Zero background threads — just mtime checks.

You can also sync manually: brain-mcp sync

🔒 Privacy

• 100% local — all data stays on your machine
• No cloud dependency — works offline after setup
• Open source — audit every line (MIT licensed)
• Anonymous telemetry — opt-out with brain-mcp telemetry off (details)

Requirements

• Python 3.11+
• macOS, Linux, or Windows

Contributing

See CONTRIBUTING.md. All contributions welcome.

Built because losing your train of thought shouldn't mean starting over.

brainmcp.dev · PyPI · Full Docs

⭐ If this is useful, a star helps others find it.