Open Brain

Because one brain is not enough in the age of the centaur.

Your second brain, but make it semantic. A personal knowledge base that understands meaning, not just keywords — accessible from Claude, ChatGPT, Cursor, your phone, your terminal, or anywhere that speaks MCP.

You think a thought. Your brain captures it, figures out what kind of thought it is, who you mentioned, what topics it touches, and files it away with a vector embedding. Later, you ask a question in natural language, and your brain actually understands what you meant.

No folders. No tags. No "wait, where did I put that?" Just vibes. Semantic vibes.

---

What's Inside

you → "remind me about that conversation with Alex about the API redesign"
                              ↓
                    [semantic search] ← pgvector cosine similarity
                              ↓
brain → "Found 3 thoughts: Meeting with Alex on Feb 12..."

7 tools, one brain:

Tool	What It Does
capture	Save a thought — auto-generates embedding + extracts metadata
semantic_search	Find thoughts by meaning, not keywords
search_by_person	"What do I know about Sarah?"
search_by_topic	"What have I been thinking about system design?"
list_recent	"What's been on my mind this week?"
stats	"How active has my brain been?"
delete_thought	"Forget I said that."

Every thought gets automatically classified (decision, insight, idea, reflection...), people are extracted, topics are tagged, and action items are surfaced. All of this happens invisibly — you just think, it just files.

---

The Stack

No exotic dependencies. No "run these 47 Docker containers" energy. Just:

• Neon Postgres + pgvector — your thoughts, vectorized and indexed (HNSW, cosine similarity, 1536 dimensions)
• OpenAI — text-embedding-3-small for embeddings, gpt-4o-mini for metadata extraction
• Next.js on Vercel — MCP server deployed as a serverless API route
• MCP (Model Context Protocol) — Streamable HTTP transport, works everywhere

The remote server speaks MCP's Streamable HTTP protocol, so any MCP-compatible client can connect: Claude (desktop, mobile, web), ChatGPT, Cursor, Windsurf, VS Code, or your own custom agent.

There's also a local Python MCP server in src/mcp-server/ if you prefer stdio transport for Claude Code or Claude Desktop.

---

Get Your Own Brain

Prerequisites

• A Neon Postgres database (free tier works)
• An OpenAI API key
• A Vercel account (for deployment)
• Node.js 20+

1. Clone & Install

git clone https://github.com/shawnpetros/open-brain.git
cd open-brain
pnpm install

2. Set Up Your Database

Create a Neon database and run the schema:

psql $DATABASE_URL -f src/migrations/001_schema.sql

3. Configure Environment

cp .env.example .env.local

Fill in your DATABASE_URL, OPENAI_API_KEY, and optionally a BRAIN_API_KEY (to protect your endpoint — generate one with openssl rand -base64 32).

4. Deploy

vercel deploy

Or just push to GitHub and let Vercel auto-deploy. It's 2026, we don't manually deploy anymore.

5. Connect Your Brain

Add the MCP server to your AI client. The URL is:

https://your-app.vercel.app/api/mcp

Claude Code:

claude mcp add open-brain --transport http https://your-app.vercel.app/api/mcp

Claude Desktop / ChatGPT / Cursor: Add as a remote MCP server in settings with the URL above. If you set a BRAIN_API_KEY, configure the bearer token in your client's MCP server auth settings.

---

Local Mode (Python)

If you want a local-only brain (no deployment, stdio transport):

cd src/mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # fill in your creds

claude mcp add open-brain -- $(pwd)/.venv/bin/python $(pwd)/server.py

---

How It Works

[You] "Remember: Alex suggested we switch to event-driven architecture for the notification system"
        │
        ▼
   ┌─────────┐     ┌──────────────┐     ┌──────────────────┐
   │ Capture  │────▶│  OpenAI API  │────▶│  Neon Postgres   │
   │  Tool    │     │              │     │                  │
   │         │     │ • embedding  │     │ • raw_text       │
   │         │     │ • metadata   │     │ • vector(1536)   │
   └─────────┘     └──────────────┘     │ • type: decision │
                                        │ • people: [Alex] │
                                        │ • topics: [arch, │
                                        │   notifications] │
                                        └──────────────────┘

Later:

[You] "What did we discuss about the notification system?"
        │
        ▼
   ┌──────────┐     ┌──────────────┐     ┌──────────────────┐
   │ Semantic  │────▶│  OpenAI API  │────▶│  Neon Postgres   │
   │  Search   │     │  (embed      │     │  (cosine         │
   │          │     │   query)     │     │   similarity)    │
   └──────────┘     └──────────────┘     └──────────────────┘
        │
        ▼
   "Alex suggested event-driven architecture for notifications..."

---

Why Build This

The centaur metaphor — human + AI, stronger together — only works if the AI half has access to your context, your history, your accumulated knowledge. Built-in AI memory is a black box. This is your brain, open, on your infrastructure, queryable by any AI you choose to work with.

It's not about replacing your biological brain. It's about giving it a search engine.

---

License

MIT — go build your own brain.