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
);

Provenance Helpers v0.7.0+

Migration 003-add-provenance-helpers.sql adds two generated columns projected from metadata->'provenance' (the Hallmark v1 envelope written by Plan Forge), two partial indexes, and a sibling RPC for source-hash lookups. Existing rows are untouched — provenance stays optional.

New sibling RPC — match_thoughts() is unchanged:

SELECT * FROM match_thoughts_by_source(
    source_hash      := 'sha256:abcd...',
    max_count        := 25,
    project_filter   := NULL,
    include_archived := false
);

MCP Server

Open Brain's MCP server exposes 7 tools via the Model Context Protocol, an 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

Plan Forge is an agentic project execution system. In Plan Forge's unified memory architecture, Open Brain is the L3 layer — permanent, cross-project, semantic memory. Skills run search_thoughts before acting, and capture_thought after, so architecture decisions, patterns, and postmortems are preserved across runs and tools.

Memory layers (Plan Forge's view)

Hallmark provenance envelope

Plan Forge wraps every L3 write in a Hallmark v1 envelope under metadata.provenance. Open Brain projects two fields out as generated columns (source_file_hash, code_hash) with partial indexes, plus a sibling RPC (match_thoughts_by_source) and a REST endpoint (GET /memories/by-source) for exact-source deduplication.

{
  "content": "Decision: pgvector over pinecone for OSS-friendliness",
  "metadata": {
    "provenance": {
      "schemaVersion": "hallmark-provenance.v1",
      "contentHash":   "sha256:abcd...",
      "codeHash":      "sha256:ef01...",
      "phase":         "Phase-3-Slice-2",
      "tool":          "forge_step3_execute_slice"
    }
  }
}

Capability negotiation

Before stamping provenance, Plan Forge checks Open Brain's /health response. The presence of "by-source" in capabilities[] means the server understands the Hallmark envelope and the by-source lookup path. Older servers get bare thoughts (no Hallmark) — everything degrades transparently.

curl https://openbrain.example.com/health
# {
#   "status": "healthy",
#   "service": "open-brain-api",
#   "capabilities": ["capture","search","list","batch","update","delete","stats","by-source"]
# }

Resilience: the OpenBrain queue

When Open Brain is unreachable, Plan Forge does not drop the thought. It writes it to .forge/openbrain-queue.jsonl (L2) and drains the queue back to Open Brain later via forge_anvil_dlq_drain. Failed writes that Open Brain rejects (e.g. a malformed Hallmark envelope) land in the Slag-Heap DLQ for inspection. This means Plan Forge can keep working offline, on a flight, or during a brief outage — no thought is lost.

Recommended Plan Forge tools

Full integration spec in Plan Forge · MEMORY-ARCHITECTURE.md and UNIFIED-SYSTEM-ARCHITECTURE.md.

Deployment — pick a path

Open Brain runs anywhere PostgreSQL + Node can run. There are five canonical paths, all using the same MCP tools and AI clients. Pick the one that matches how you want to use it.

🖥️ Docker Desktop dev box

The friendliest path for Windows / macOS laptops. ~10 minutes, $0, fully private. Recommended starting point for most people.

git clone https://github.com/srnichols/OpenBrain.git
cd OpenBrain

# Wizard (PowerShell on Windows, bash on Mac)
.\setup.ps1   # or:  ./setup.sh

# Verify
.\scripts\verify.ps1 http://localhost:8000

Ollama runs natively on your host; everything else lives in Docker. Full walkthrough in 11-DOCKER-DESKTOP-DEVBOX.md.

☁️ Cheap hosted (Supabase / Neon + Fly.io)

Always-on, accessible from any device, ~$0–5/month. The closest match to Nate B Jones' original Open Brain spirit — hosted Postgres + a tiny serverless MCP runtime.

Pick Postgres

Pick MCP runtime

Recommended: Fly.io with the ready-made deploy/hosted/fly/fly.toml. Free tier covers a personal install with ~1 sec wake from suspend.

cd deploy/hosted/fly
fly launch --copy-config --no-deploy --name openbrain-<handle>
fly secrets set \
  DATABASE_URL='postgresql://...' \
  MCP_ACCESS_KEY="$(openssl rand -hex 32)" \
  EMBEDDER_PROVIDER=openrouter \
  OPENROUTER_API_KEY='sk-or-...' \
  EMBEDDING_DIMENSIONS=1536
fly deploy

Render and Railway templates are also included. Full walkthrough in 12-HOSTED-CHEAP.md.

🐳 Docker Compose (Linux servers)

For headless Linux hosts — a NAS, Raspberry Pi, VPS, or any always-on server. Same compose stack the dev box uses, just without Docker Desktop's host helpers.

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

# Configure
cp .env.example .env
# Edit .env with your settings (MCP_ACCESS_KEY, embedder, etc.)

# Start everything
docker compose up -d

# Verify (universal smoke test)
./scripts/verify.sh http://localhost:8000

The Docker Compose stack includes PostgreSQL with pgvector pre-configured, the Open Brain API + MCP server, and reaches Ollama either on the host or via OpenRouter / Azure OpenAI based on your .env.

☸️ 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 docs/09-SELF-HOSTED-K8S.md.

🚀 Azure (managed)

One-command Bicep deploy: Azure Container Apps + Azure PostgreSQL Flexible Server + Azure OpenAI + Key Vault. Fully managed, scale-to-zero, ~$15–20/month for personal use.

git clone https://github.com/srnichols/OpenBrain.git
cd OpenBrain

.\deploy\azure\deploy.ps1 -ResourceGroup rg-openbrain -Location eastus2

The script generates secrets, deploys Bicep, seeds the database, and prints the MCP endpoint + key. Embeddings via Azure OpenAI text-embedding-3-small (1536 dim).

AWS & GCP equivalents

Open Brain itself is provider-agnostic; only the Bicep is Azure-specific. The same architecture maps to:

Full mapping & cost-parity table in 10-AZURE-DEPLOYMENT.md → Equivalents. PRs welcome for AWS / GCP IaC.

Full guide in docs/10-AZURE-DEPLOYMENT.md.

🤖 AI-prompted setup (EASY-SETUP.md)

Don't want to run the commands yourself? Paste a prompt into any AI agent (VS Code Copilot, Claude Code, Cursor, Claude Desktop with terminal) and it'll do the install for you.

EASY-SETUP.md has one prompt per deployment path, plus a "Help me decide" prompt that asks 3 questions and routes you to the right one:

• • 🖥️ Docker Desktop dev box prompt
• • 🐳 Docker Compose (Linux) prompt
• • ☁️ Cheap hosted (Fly + Supabase) prompt
• • ☸️ Kubernetes prompt
• • 🚀 Azure prompt
• • 🤔 Help me decide prompt

Full prompts in EASY-SETUP.md. The repo also ships an AGENTS.md so any AI agent helping a user follows the canonical install procedure.

✅ verify script — universal smoke test

A single script that confirms any Open Brain deployment is healthy. Captures a marker thought, semantically searches for it, then deletes it. Exit 0 = all good.

# Linux / macOS
./scripts/verify.sh http://localhost:8000

# Windows
.\scripts\verify.ps1 http://localhost:8000

# Hosted
./scripts/verify.sh https://openbrain-<handle>.fly.dev

If anything fails, see docs/TROUBLESHOOTING.md — a cross-cutting troubleshooting guide organized by symptom (API won't start, capture / embedder failures, search returns nothing, client config, Azure-specific, hosted-specific).

⏱️ Your first hour

Server's running. Now what? 13-FIRST-HOUR.md walks through the first 60 minutes of actually using Open Brain:

• • Minutes 0–5 — confirm it works with the verify script + a thought_stats probe
• • Minutes 5–20 — your first 5 captures (small, varied, real)
• • Minutes 20–40 — search the way you'd actually think; semantic recall in practice
• • Minutes 40–60 — bake it into your real workflow (after-bug captures, project-start captures, cross-tool handoffs)

The piece that turns "it's running" into "I'm using it."

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}'

Example: Capability Probe v0.7.0+

Single round trip — clients learn which optional features the server speaks:

curl http://localhost:8000/health
# { "status": "healthy", "service": "open-brain-api",
#   "capabilities": ["provenance"] }

Example: Capture with Provenance v0.7.0+

curl -X POST http://localhost:8000/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Phase-PROVENANCE Slice 3 shipped: by-source RPC live",
    "metadata": {
      "provenance": {
        "schemaVersion": "hallmark/v1",
        "toolName": "forge_memory_capture",
        "capturedAt": "2026-05-16T20:00:00Z",
        "contentHash": "sha256:abcd...",
        "codeHash":    "sha256:efgh..."
      }
    }
  }'

Example: Look up by Source Hash v0.7.0+

curl 'http://localhost:8000/memories/by-source?hash=sha256:abcd...&limit=10'
# Returns thoughts whose metadata.provenance.contentHash matches,
# ordered by created_at DESC. limit defaults to 25, max 100.

Troubleshooting

Common gotchas