The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Open Brain listing page.
Graph-structured MCP memory. 37.2% on LongMemEval baseline — a benchmark most memory systems don't publish.
A self-hostable memory server for MCP clients (Claude, ChatGPT, any assistant that speaks MCP). Thoughts flow in from Telegram, pipelines, or direct capture, and land in a Newman-IDF weighted entity graph — not a flat document store. An automated Dream cycle runs in the background: deduplicating near-duplicates, tracking theme drift, synthesizing insights across clusters, and archiving stale content. 17 MCP tools. PostgreSQL + pgvector. You own your data.
When you send a message to the Telegram bot, the telegram-bot Edge Function picks it up via webhook. It sends the message to OpenRouter in parallel for two things: generating a vector embedding (a numerical representation of meaning) and extracting metadata like topics, people mentioned, action items, theme, quality score, and named entities. The thought is checked for semantic duplicates, stored in your database with auto-linked connections to related thoughts, and the bot replies with a summary of what it captured.
The run-pipeline Edge Function automatically ingests ideas from RSS feeds (AI newsletters), Hugging Face daily papers, and Emergent Mind (trending arXiv papers). Each item is triaged for relevance, embedded, deduplicated, and stored. Runs on a schedule via GitHub Actions (Supabase deployment) or a built-in cron container (Docker deployment).
Any AI client connected via MCP (Model Context Protocol) can search your thoughts by meaning using semantic search, browse by filters (type, topic, person, time), get aggregate statistics, or request a weekly review of themes. The open-brain-mcp Edge Function handles these requests, authenticated with your personal access key.
Every thought is automatically linked to related thoughts via vector similarity. Connections above 0.80 similarity are classified by an LLM into typed relationships (extends, contradicts, is-evidence-for, supersedes). Named entities (people, tools, projects, organizations) are extracted and resolved into a shared entity graph. Co-occurrence edges track which thoughts are retrieved together over time, strengthening connections based on actual usage patterns.
Everything lives in Postgres with pgvector for fast similarity search. Thoughts are stored with their embeddings (1536-dimensional vectors), metadata, typed connections, and entity references. You can deploy on Supabase (managed hosting) or self-host with Docker Compose.
Choose how you want to run Open Brain:
| Supabase (hosted) | Docker Compose (self-hosted) | |
|---|---|---|
| Setup | Link project + run scripts | cp .env.example .env + ./start.sh |
| Infrastructure | Managed by Supabase | Runs on your machine/server |
| Scheduling | GitHub Actions | Built-in cron container |
| Cost | Supabase free tier + OpenRouter | Just OpenRouter |
| Guide | Continue below | Docker guide |
Supabase account -- Supabase is a hosted Postgres database with built-in APIs, authentication, and Edge Functions (serverless code). Create a free account at supabase.com. Create a new project -- you will need the project URL (looks like https://abcdef.supabase.co) and the service role key (a long string found under Settings > API).
Supabase CLI -- The command-line tool for managing your Supabase project (applying database migrations, deploying functions, setting secrets).
OpenRouter account -- OpenRouter routes requests to AI models. It is used here for generating embeddings (vector representations of your thoughts) and extracting metadata. Create an account at openrouter.ai and generate an API key from the dashboard.
Telegram bot (recommended) -- The primary way to capture thoughts on the go. Create a bot via @BotFather on Telegram and run the setup script (see below). If you only want MCP access, you can skip this.
Tip: Your project ref is the subdomain in your Supabase URL. If your URL is
https://abcdef.supabase.co, your project ref isabcdef.
Bootstrap walks you through setting up your environment. It prompts for each secret (Supabase URL, service role key, OpenRouter API key, Telegram tokens, etc.), generates a cryptographic MCP access key automatically, and writes everything to .env.local. If you already have a .env.local, it will show your existing values and let you update specific ones.
Deploy applies the database schema (creates the thoughts table with vector search indexes), uploads your secrets to Supabase, and deploys all Edge Functions. It shows a step-by-step checklist as each operation completes. At the end, it prints your MCP connection URL and a ready-to-paste Claude Code command.
Validate runs 8 checks against your live deployment to confirm everything works: database access, RPC functions, Edge Function reachability, authentication, thought capture, semantic search, and thought listing. It prints a checklist with pass/fail for each check and a final summary.
Create a bot via @BotFather on Telegram, then run the setup script:
The script verifies your token, registers the webhook, sets up command autocomplete, and prints the env vars and secrets to configure. Follow the printed instructions to complete setup.
Once deployed, connect your AI client to start using Open Brain. You need two values:
https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp (Supabase) or http://localhost:80/functions/v1/open-brain-mcp (Docker).env.local or Docker .env)Tip: The deploy script (Supabase) or start script (Docker) prints the exact connection command with your values filled in.
This registers Open Brain as an MCP server that Claude Code can use in any conversation. Replace YOUR_MCP_KEY and YOUR_REF with your actual values.
Add this to a .mcp.json file in your project root to share the connection with your team:
Note: The
${MCP_ACCESS_KEY}syntax uses environment variable expansion so your key stays out of version control. Set theMCP_ACCESS_KEYenvironment variable on each machine that uses this config.
Claude Desktop does not support remote MCP servers via configuration files. Instead:
https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcpx-brain-key authentication header with your MCP access keyhttps://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcpx-brain-key authentication header with your MCP access keySend any message to your bot and Open Brain automatically processes it:
Every message is embedded as a vector, enriched with extracted metadata, checked for duplicates, auto-linked to related thoughts, and entities are resolved into a knowledge graph.
Ask any connected AI client to search your brain:
Semantic search finds thoughts by meaning -- even if you used different words. Asking about "product planning" will find thoughts about "roadmap discussions" because the meanings are similar.
Get an AI-generated summary of your recent thinking:
The weekly review analyzes the past 7 days of thoughts and synthesizes themes, open loops, connections between ideas, and gaps in your thinking.
| Tool | Description |
|---|---|
search_thoughts | Semantic search with optional graph expansion (1-hop traversal) |
list_thoughts | Browse thoughts filtered by type, topic, person, theme, quality, time |
thought_stats | Aggregate statistics: counts, type/theme breakdown, top topics/people |
capture_thought | Save a new thought from any AI client (with auto-embedding) |
get_connections | Graph traversal from a thought (typed links: extends, contradicts, etc.) |
list_entities | Browse extracted entities (people, tools, projects, orgs) by frequency |
weekly_review | AI-generated summary of themes, open loops, and next steps |
analyze | Graph analysis: hubs, density, sources, co-occurrence, themes |
dedup_review | Duplicate candidates with similarity zone histogram |
refresh_salience | Recompute all salience scores |
update_thought | Rewrite content (re-embeds, re-extracts metadata) |
delete_thought | Permanent delete (cascades connections) |
serendipity_digest | Resurface forgotten high-quality thoughts |
pipeline | Pipeline monitoring: health status, run history, merge audit |
review_stale | Review and act on stale thought candidates |
migration_guide | Instructions for importing memories from other platforms |
See docs/cookbook.md for detailed usage patterns, tool compositions, and non-obvious behaviors.
Open Brain includes Claude Code skills -- structured multi-phase workflows that compose the MCP tools above into higher-level analysis. Skills are auto-discovered from .claude/skills/ and invoked as slash commands.
| Skill | What it does |
|---|---|
/discover | Incremental pattern discovery across recent thoughts. Builds on previous reports (EVOLVED/NEW/STALE classification), dispatches parallel research agents, correlates with project priorities. |
/pulse | Pipeline and data health report. 9 parallel MCP calls, rubric-scored (GREEN/YELLOW/RED), cross-run memory for tracking findings over time, 6 cross-metric pattern detectors. |
/brain-health | Knowledge graph health report. 12 parallel MCP calls covering theme attention, graph density, hub health, co-occurrence alignment, dedup pressure, synthesis output, and entity landscape. |
See docs/skills/README.md for detailed descriptions and usage.
Open Brain runs background maintenance to keep the knowledge graph healthy. These jobs run automatically -- via GitHub Actions (Supabase deployment) or the built-in cron container (Docker deployment).
| Job | Frequency | Purpose |
|---|---|---|
| RSS/HF Papers/Emergent Mind ingestion | 2x daily | Ingest ideas from configured sources |
| Pipeline monitoring | 2x daily | Health checks with Telegram alerting on failures |
| Dream dedup | 2x daily | Merge near-duplicate thoughts (>0.92 similarity auto-merged, 0.85-0.92 LLM-confirmed) |
| Graph analysis cache | Daily | Pre-compute hub, density, and co-occurrence analysis |
| Dream themes | Weekly | Track theme velocity, lifecycle transitions (emerging/active/declining), centroid drift |
| Dream decay | Weekly | Archive stale thoughts via tiered scoring + LLM confirmation |
| Dream synthesis | Weekly | Generate cross-cutting insights from thought clusters |
| Co-occurrence decay | Weekly | Decay unused co-occurrence edges |
GitHub Actions workflow files are included in docs/workflows/ as reference for customizing schedules.
MIT