Open Brain Documentation

Persistent, searchable memory for every AI tool you use.

What is Open Brain?

Open Brain is a personal, database-backed AI knowledge system that gives every AI tool persistent memory. Based on Nate B Jones' architecture, it turns your scattered conversations across Copilot, Claude, ChatGPT, Cursor, and other tools into a single, searchable knowledge base.

Philosophy

• → One row = one retrievable idea — Zettelkasten-style atomic notes
• → Vector search = associative retrieval — search by meaning, not keywords
• → Metadata extraction is automatic — LLM classifies and tags on ingest
• → Backend, not frontend — use with any UI or AI tool you prefer
• → Your memory is portable — self-hosted, open protocol, compounding

Cost

Architecture

Open Brain has a simple, layered architecture — AI clients talk to the MCP server via SSE, which handles tool dispatch, embedding generation, metadata extraction, and database operations.

AI Client (Copilot, Claude, ChatGPT, Cursor, etc.)
    ↓ MCP Protocol (SSE transport)
    ↓ Auth: x-brain-key header or ?key= param
    ↓
MCP Server (Node.js + Hono / Deno Edge Function)
    ├─ Tool dispatch (7 MCP tools)
    ├─ Embedding generation (OpenRouter or Ollama)
    ├─ Metadata extraction (LLM)
    └─ Database client
    ↓
PostgreSQL + pgvector
    ├─ thoughts table (content + embedding + metadata)
    ├─ HNSW index (vector search)
    ├─ GIN index (metadata filtering)
    └─ match_thoughts() RPC function

Data Flows

Scaling

Database Schema

Single table design on PostgreSQL with pgvector extension. Rich JSONB metadata enables flexible filtering without schema migrations.

The thoughts Table

Metadata Fields

Extracted automatically by the LLM on capture:

Indexes

match_thoughts() Function

The core search RPC — combines vector similarity with a configurable threshold:

SELECT * FROM match_thoughts(
    query_embedding := '[0.1, 0.2, ...]'::vector,
    match_count := 10,
    match_threshold := 0.5
);

MCP Server

Open Brain's MCP server exposes 7 tools via the Model Context Protocol, Anthropic's open standard for AI-to-tool integration. Uses SSE transport over HTTP.

Tools

Authentication

API key sent via x-brain-key header (preferred) or ?key= URL parameter.

# Auth is enforced on /sse connection only.
# /messages endpoint uses sessionId for implicit auth.
GET /sse?key=YOUR_64_CHAR_HEX_KEY     → SSE stream
POST /messages?sessionId=xxx           → JSON-RPC calls (no key needed)

Capture Pipeline

Multiple ways to feed thoughts into Open Brain — from AI tool conversations to Slack messages to bulk imports.

Capture Methods

Quick Capture Templates

Prompt Kit

Five core prompts covering the full lifecycle — from migration to daily capture to weekly review.

Daily Rhythm

Supabase Deployment

Deploy to Supabase's free tier with Edge Functions. ~45 minutes, ~$0.10-$0.30/month.

Full step-by-step guide in 07-DEPLOYMENT.md.

1. 1. Create Supabase project
2. 2. Set up database (pgvector extension, thoughts table, indexes, match_thoughts function)
3. 3. Get OpenRouter API key
4. 4. Generate MCP access key (openssl rand -hex 32)
5. 5. Set Supabase secrets
6. 6. Deploy Edge Functions
7. 7. Configure AI clients
8. 8. Slack integration (optional)
9. 9. Verify everything works

Docker Compose

The fastest path — PostgreSQL + pgvector + Ollama + API server in one command.

# Clone the repo
git clone https://github.com/srnichols/OpenBrain.git
cd OpenBrain

# Configure
cp .env.example .env
# Edit .env with your settings

# Start everything
docker compose up -d

# Verify
curl http://localhost:8000/health
curl http://localhost:8080/health

The Docker Compose stack includes PostgreSQL with pgvector pre-configured, Ollama for local embeddings (nomic-embed-text), and the Open Brain API + MCP server.

Kubernetes Deployment

Full homelab deployment with Tailscale networking, MetalLB, Ollama GPU, and monitoring integration.

Stack

Networking Options

Important Notes

• • Session Affinity — Required for multi-replica SSE. Set sessionAffinity: ClientIP on the ClusterIP service.
• • Tailscale Funnel — The K8s Operator (v1.92.4) doesn't auto-configure Funnel serve. Manual tailscale funnel command needed inside the proxy pod.
• • Auth — API key is checked on /sse only. /messages uses sessionId for implicit auth.

Full guide in 09-SELF-HOSTED-K8S.md.

Implementation Roadmap

Four phases, each independently functional. Total time: 2-4 hours.

Success Criteria

Client Configuration

Copy-paste configs for every supported AI client.

Claude Desktop

Requires mcp-remote bridge (Claude Desktop doesn't support SSE natively).

File: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "openbrain": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR_HOST/sse?key=YOUR_KEY"]
    }
  }
}

Claude Code / VS Code Copilot

File: ~/.claude/settings.json

{
  "mcpServers": {
    "openbrain": {
      "type": "sse",
      "url": "http://YOUR_HOST:8080/sse?key=YOUR_KEY"
    }
  }
}

Cursor

File: .cursor/mcp.json

{
  "mcpServers": {
    "openbrain": {
      "url": "http://YOUR_HOST:8080/sse?key=YOUR_KEY",
      "transport": "sse"
    }
  }
}

ChatGPT

Enable Developer Mode → Add MCP connector with your Funnel/public URL. Set auth to "none" (key in URL).

REST API

Every MCP tool has a REST equivalent on port 8000. Useful for scripts, testing, and non-MCP integrations.

Example: Capture

curl -X POST http://localhost:8000/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "Decision: Using pgvector for embeddings"}'

Example: Search

curl -X POST http://localhost:8000/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "database decisions", "limit": 5}'

Troubleshooting