{
  "markdown": "# Open Brain\n\n**Graph-structured MCP memory. [37.2% on LongMemEval baseline](BENCHMARK.md) — a benchmark most memory systems don't publish.**\n\nA 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.\n\n## How It Works\n\n```mermaid\nflowchart LR\n    TG[Telegram Message] --> TGBot[telegram-bot\\nEdge Function]\n    MCP[AI Client\\nClaude/ChatGPT] --> MCPServer[open-brain-mcp\\nEdge Function]\n    Pipeline[RSS/HF Papers/\\nEmergent Mind] --> RunPipeline[run-pipeline\\nEdge Function]\n    TGBot --> OR1[OpenRouter\\nEmbedding + Metadata]\n    MCPServer --> OR2[OpenRouter\\nEmbedding + Search]\n    RunPipeline --> OR3[OpenRouter\\nTriage + Embed]\n    OR1 --> DB[(Postgres\\n+ pgvector)]\n    OR2 --> DB\n    OR3 --> DB\n    MCPServer --> DB\n    TGBot --> TGReply[Telegram Reply\\nwith Metadata]\n```\n\n### Capture Path\n\nWhen 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.\n\n### Pipeline Path\n\nThe **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).\n\n### Retrieval Path\n\nAny 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.\n\n### Knowledge Graph\n\nEvery 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.\n\n### Storage\n\nEverything 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.\n\n## Deployment Options\n\nChoose how you want to run Open Brain:\n\n| | **Supabase (hosted)** | **Docker Compose (self-hosted)** |\n|---|---|---|\n| **Setup** | Link project + run scripts | `cp .env.example .env` + `./start.sh` |\n| **Infrastructure** | Managed by Supabase | Runs on your machine/server |\n| **Scheduling** | GitHub Actions | Built-in cron container |\n| **Cost** | Supabase free tier + OpenRouter | Just OpenRouter |\n| **Guide** | [Continue below](#supabase-deployment) | [Docker guide](docker/README.md) |\n\n## Supabase Deployment\n\n### Prerequisites\n\n1. **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](https://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).\n\n2. **Supabase CLI** -- The command-line tool for managing your Supabase project (applying database migrations, deploying functions, setting secrets).\n   ```\n   npm install -g supabase\n   ```\n3. **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](https://openrouter.ai) and generate an API key from the dashboard.\n\n4. **Telegram bot** (recommended) -- The primary way to capture thoughts on the go. Create a bot via [@BotFather](https://t.me/BotFather) on Telegram and run the setup script (see below). If you only want MCP access, you can skip this.\n\n### Quick Start\n\n#### 1. Clone the repository\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/open_brain.git\ncd open_brain\n```\n\n#### 2. Link your Supabase project\n\n```bash\ncd supabase\nsupabase link --project-ref YOUR_PROJECT_REF\ncd ..\n```\n\n> **Tip:** Your project ref is the subdomain in your Supabase URL. If your URL is `https://abcdef.supabase.co`, your project ref is `abcdef`.\n\n#### 3. Run bootstrap\n\n```bash\n./scripts/bootstrap.sh\n```\n\nBootstrap 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.\n\n#### 4. Run deploy\n\n```bash\n./scripts/deploy.sh\n```\n\nDeploy 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.\n\n#### 5. Run validate\n\n```bash\n./scripts/validate.sh\n```\n\nValidate 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.\n\n### Set up Telegram bot (optional)\n\nCreate a bot via [@BotFather](https://t.me/BotFather) on Telegram, then run the setup script:\n\n```bash\n./scripts/setup-telegram.sh YOUR_BOT_TOKEN\n```\n\nThe 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.\n\n## Connect Your AI Client\n\nOnce deployed, connect your AI client to start using Open Brain. You need two values:\n\n- **MCP endpoint URL:** `https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp` (Supabase) or `http://localhost:80/functions/v1/open-brain-mcp` (Docker)\n- **MCP access key:** The key generated during setup (stored in `.env.local` or Docker `.env`)\n\n> **Tip:** The deploy script (Supabase) or start script (Docker) prints the exact connection command with your values filled in.\n\n### Claude Code (CLI -- recommended)\n\n```bash\nclaude mcp add --transport http --header \"x-brain-key: YOUR_MCP_KEY\" open-brain https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp\n```\n\nThis 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.\n\n### Claude Code (project .mcp.json)\n\nAdd this to a `.mcp.json` file in your project root to share the connection with your team:\n\n```json\n{\n  \"mcpServers\": {\n    \"open-brain\": {\n      \"type\": \"http\",\n      \"url\": \"https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp\",\n      \"headers\": {\n        \"x-brain-key\": \"${MCP_ACCESS_KEY}\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** The `${MCP_ACCESS_KEY}` syntax uses environment variable expansion so your key stays out of version control. Set the `MCP_ACCESS_KEY` environment variable on each machine that uses this config.\n\n### Claude Desktop\n\nClaude Desktop does not support remote MCP servers via configuration files. Instead:\n\n1. Open **Claude Desktop** > **Settings** > **Connectors**\n2. Click **Add a new connector**\n3. Enter the MCP endpoint URL: `https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp`\n4. Configure the `x-brain-key` authentication header with your MCP access key\n\n### ChatGPT (Pro/Team/Enterprise/Edu)\n\n1. Go to **Settings** > **Connectors** > **Advanced** > **Developer Mode**\n2. Add the MCP server URL: `https://YOUR_REF.supabase.co/functions/v1/open-brain-mcp/mcp`\n3. Configure the `x-brain-key` authentication header with your MCP access key\n\n## Usage Examples\n\n### Telegram Capture\n\nSend any message to your bot and Open Brain automatically processes it:\n\n```\nYou: Just had a great meeting with Sarah about the Q3 product roadmap.\n     She wants to prioritize the mobile app redesign.\n\nBot: Captured!\n  Type: meeting_note\n  Theme: personal\n  Topics: q3-roadmap, mobile-app-redesign\n  Quality: 0.7\n  People: Sarah\n  Action items: Prioritize mobile app redesign\n  Why: Records a product strategy decision with clear ownership\n  Related: \"Product planning session notes...\" (82% similar)\n```\n\nEvery 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.\n\n### Semantic Search\n\nAsk any connected AI client to search your brain:\n\n```\nYou: Search my brain for anything about product roadmap discussions\n\nClaude: I found 3 relevant thoughts:\n  1. (0.89 similarity) Meeting with Sarah about Q3 product roadmap...\n  2. (0.82 similarity) Product planning session notes...\n  3. (0.76 similarity) Quarterly goals discussion...\n```\n\nSemantic 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.\n\n### Weekly Review\n\nGet an AI-generated summary of your recent thinking:\n\n```\nYou: Give me a weekly review of my recent thoughts\n\nClaude: Here's your weekly review:\n  Themes: Product planning, team meetings, technical architecture\n  Open loops: Mobile redesign decision pending, API migration timeline\n  Connections: Sarah mentioned in 3 meetings this week, all about mobile\n```\n\nThe weekly review analyzes the past 7 days of thoughts and synthesizes themes, open loops, connections between ideas, and gaps in your thinking.\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_thoughts` | Semantic search with optional graph expansion (1-hop traversal) |\n| `list_thoughts` | Browse thoughts filtered by type, topic, person, theme, quality, time |\n| `thought_stats` | Aggregate statistics: counts, type/theme breakdown, top topics/people |\n| `capture_thought` | Save a new thought from any AI client (with auto-embedding) |\n| `get_connections` | Graph traversal from a thought (typed links: extends, contradicts, etc.) |\n| `list_entities` | Browse extracted entities (people, tools, projects, orgs) by frequency |\n| `weekly_review` | AI-generated summary of themes, open loops, and next steps |\n| `analyze` | Graph analysis: hubs, density, sources, co-occurrence, themes |\n| `dedup_review` | Duplicate candidates with similarity zone histogram |\n| `refresh_salience` | Recompute all salience scores |\n| `update_thought` | Rewrite content (re-embeds, re-extracts metadata) |\n| `delete_thought` | Permanent delete (cascades connections) |\n| `serendipity_digest` | Resurface forgotten high-quality thoughts |\n| `pipeline` | Pipeline monitoring: health status, run history, merge audit |\n| `review_stale` | Review and act on stale thought candidates |\n| `migration_guide` | Instructions for importing memories from other platforms |\n\nSee `docs/cookbook.md` for detailed usage patterns, tool compositions, and non-obvious behaviors.\n\n## Skills (Claude Code Workflows)\n\nOpen Brain includes [Claude Code](https://docs.anthropic.com/en/docs/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.\n\n| Skill | What it does |\n|-------|-------------|\n| `/discover` | Incremental pattern discovery across recent thoughts. Builds on previous reports (EVOLVED/NEW/STALE classification), dispatches parallel research agents, correlates with project priorities. |\n| `/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. |\n| `/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. |\n\nSee `docs/skills/README.md` for detailed descriptions and usage.\n\n## Automated Maintenance\n\nOpen 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).\n\n| Job | Frequency | Purpose |\n|-----|-----------|---------|\n| **RSS/HF Papers/Emergent Mind ingestion** | 2x daily | Ingest ideas from configured sources |\n| **Pipeline monitoring** | 2x daily | Health checks with Telegram alerting on failures |\n| **Dream dedup** | 2x daily | Merge near-duplicate thoughts (>0.92 similarity auto-merged, 0.85-0.92 LLM-confirmed) |\n| **Graph analysis cache** | Daily | Pre-compute hub, density, and co-occurrence analysis |\n| **Dream themes** | Weekly | Track theme velocity, lifecycle transitions (emerging/active/declining), centroid drift |\n| **Dream decay** | Weekly | Archive stale thoughts via tiered scoring + LLM confirmation |\n| **Dream synthesis** | Weekly | Generate cross-cutting insights from thought clusters |\n| **Co-occurrence decay** | Weekly | Decay unused co-occurrence edges |\n\nGitHub Actions workflow files are included in `docs/workflows/` as reference for customizing schedules.\n\n## Project Structure\n\n```\nopen-brain-server/\n  supabase/\n    migrations/                   # Database migrations (applied with supabase db push)\n    functions/\n      _shared/                    # Shared modules (supabase-client, openrouter, types, errors, auto-link, entities, dream-*)\n      telegram-bot/               # Telegram capture (primary capture path)\n      open-brain-mcp/             # MCP server (17 tools)\n        tools/                    # Individual tool implementations\n      run-pipeline/               # Automated RSS/HF Papers/Emergent Mind ingestion\n      monitor-pipeline/           # Pipeline health monitoring with Telegram alerts\n      refresh-graph-analysis/     # Graph analysis cache computation\n  docker/                         # Docker Compose self-hosting (6 services)\n  pipeline/                       # Python-based local pipeline (Reddit, RSS, briefing)\n  scripts/                        # Setup and deployment automation\n  tests/                          # Integration tests\n  docs/\n    cookbook.md                    # MCP tool usage patterns and compositions\n    skills/                       # Skill documentation\n    workflows/                    # GitHub Actions reference (scheduling)\n    writing-a-source.md           # Guide for adding pipeline sources\n  .claude/\n    skills/                       # Claude Code skills (auto-discovered)\n      discover/                   # Incremental pattern discovery\n      pulse/                      # Pipeline health report\n      brain-health/               # Knowledge graph health report\n```\n\n## License\n\nMIT\n",
  "bytes": 15850,
  "sha": "be1da51f6bf384d1399c3f2ced3f80eb15fd02cad5253635a97a98c2acac68ec",
  "repo_slug": "bobby-cell-commits/open-brain-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bobby_cell_commits_open_brain_22daee0c/readme"
}