OpenBrain

Open Brain

[](https://github.com/srnichols/OpenBrain/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://srnichols.github.io/OpenBrain/)

Persistent, searchable memory for every AI tool you use — solo or as a small team.

> 📖 Read the full documentation →

The Problem

Every AI conversation starts from zero. You explained your architecture to Claude last week, made a caching decision in ChatGPT yesterday, captured a pattern in GitHub Copilot this morning, and now Cursor has no idea about any of it. Your knowledge is scattered across platforms, locked inside sessions that expire.

The Solution

Open Brain is a shared memory backend that any MCP-compatible AI tool can read from and write to. Capture a thought from GitHub Copilot, search for it from Claude, review it from ChatGPT — all hitting the same database of your decisions, patterns, and context.

You: "Remember that we chose Redis for session caching."
     → GitHub Copilot calls capture_thought → stored with embedding + auto-extracted metadata

Later, from any tool:
You: "What did we decide about caching?"
     → Claude calls search_thoughts → finds it by meaning, not keywords
     → "Decision: Redis for session caching. Reason: ..."

Why Set It Up?

• Your AI gets smarter over time — every captured thought compounds into a richer knowledge base
• Switch AI tools freely — your context travels with you, not locked to one vendor
• Small teams (1-3 devs) share context — tag thoughts with created_by so the whole team's decisions are searchable, filterable by person
• Decisions survive — months later, ask "why did we choose PostgreSQL over MongoDB?" and get the exact reasoning
• Works with what you already use — GitHub Copilot, VS Code, Claude, ChatGPT, Gemini, Cursor, Windsurf, and any MCP client

Works Great With Plan Forge

If you use Plan Forge for agentic project execution, Open Brain is the memory layer. Plan Forge's agents can capture architecture decisions, patterns, and postmortems during execution, then retrieve that context in future projects. See Plan Forge's Unified System Architecture for how the two systems integrate.

> Based on Nate B Jones' Open Brain architecture. This is a significantly extended self-hosted implementation — see [Differences from Nate's Original](#differences-from-nates-original) below.

---

How It Works

flowchart TD
    A[Any AI Tool\nCopilot · Claude · ChatGPT · Cursor · Windsurf · Gemini] -->|MCP Protocol| B[Open Brain Server\nREST :8000 · MCP :8080]
    B -->|Generate embedding\n+ extract metadata| C[Ollama or Azure OpenAI]
    B -->|Store & search| D[(PostgreSQL + pgvector\nVector similarity search)]
    D -->|Ranked results| B
    B -->|Thoughts + metadata| A

You capture a thought from any AI client. Open Brain generates a vector embedding, extracts metadata (type, topics, people mentioned), and stores it. Later, any AI client can semantically search your memories by meaning, not keywords.

flowchart LR
    subgraph Capture
        A[You say:\nRemember this decision] --> B[AI calls capture_thought]
        B --> C{Parallel}
        C --> D[Embedding\n768 or 1536 dims]
        C --> E[Metadata\ntype · topics · people]
        D --> F[(Stored)]
        E --> F
    end
    subgraph Search
        G[You ask:\nWhat did we decide?] --> H[AI calls search_thoughts]
        H --> I[Query embedding]
        I --> J{Cosine similarity}
        F --> J
        J --> K[Ranked results\nwith metadata]
    end

---

Features

• Semantic Search — Find thoughts by meaning, not keywords. Ask "what did we decide about caching?" and get results even if you never used the word "caching" in the original thought.
• Auto-Metadata Extraction — Every thought is automatically classified: type (decision, pattern, bug, etc.), topics, people mentioned, action items, dates. No manual tagging.
• Provenance Helpers — Generated columns and partial indexes for exact-source deduplication via match_thoughts_by_source RPC, plus a GET /memories/by-source REST endpoint.
• 9 AI Clients Supported — VS Code Copilot, Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT, Gemini, Grok, and any MCP-compatible client.
• REST API — Direct HTTP access for scripts, webhooks, CI/CD integrations, and non-MCP tools. Every MCP tool has a REST equivalent.
• Multi-Developer Teams — Optional created_by field lets 1-3 devs share one instance with per-user filtering.
• Project Scoping — Isolate thoughts per project. Search within "ecommerce-api" without noise from "internal-tools".
• 5 Deployment Options — Docker Desktop dev box (free, ~10 min), Docker Compose Linux ($0–5), cheap hosted (Supabase + Fly, ~$0–5/mo), Kubernetes (homelab), or Azure (managed, ~$15–20/mo).
• Self-Hosted & Private — Your data stays on your infrastructure. No vendor lock-in.
• 27-Test Integration Suite — Run npm run test:integration against any deployment to verify everything works.

---

Choose Your Deployment Path

Open Brain runs anywhere Postgres + Node can run. Pick the path that matches how you want to use it, not how big your wallet is — every option below works end-to-end with the same MCP tools and AI clients.

| Path | Best For | Time | Monthly Cost | Skill Level | Guide | |------|----------|------|--------------|-------------|-------| | 🖥️ Docker Desktop dev box | Solo dev on a Win/Mac laptop, fully local & private | ~10 min | $0 | Beginner | [11-DOCKER-DESKTOP-DEVBOX.md](docs/11-DOCKER-DESKTOP-DEVBOX.md) | | 🐳 Docker Compose (any Linux box) | Headless server, NAS, Raspberry Pi, VPS | ~10 min | $0–5 | Beginner | [Quick Start](#quick-start-docker-compose) below | | ☁️ Cheap hosted (Supabase / Neon / Fly) | Always-on, accessible anywhere, no hardware | ~30 min | $0–5 | Beginner | [12-HOSTED-CHEAP.md](docs/12-HOSTED-CHEAP.md) | | ☸️ Kubernetes (homelab / on-prem) | Homelab, on-prem cluster, multi-user privacy | ~1 hour | $0 (own hw) | Intermediate | [09-SELF-HOSTED-K8S.md](docs/09-SELF-HOSTED-K8S.md) | | 🚀 Azure (managed cloud) | Teams, production, fully managed | ~20 min | ~$15–20 | Intermediate | [10-AZURE-DEPLOYMENT.md](docs/10-AZURE-DEPLOYMENT.md) |

> Using AWS or GCP instead? Open Brain is provider-agnostic — only the Azure path ships ready-made IaC. See [10-AZURE-DEPLOYMENT.md → Equivalents on AWS & GCP](docs/10-AZURE-DEPLOYMENT.md#equivalents-on-aws--gcp) for a service-by-service mapping (Container Apps → ECS / Cloud Run, Azure PostgreSQL Flex → RDS / Cloud SQL, Azure OpenAI → Bedrock / Vertex AI). PRs welcome for AWS/GCP IaC.

Not sure? If you have a laptop and want to try it today, start with the Docker Desktop dev box guide. If you want it reachable from every device with zero hardware, go Cheap hosted.

Bootstrap helpers (work with every path)

• 🤖 [EASY-SETUP.md](EASY-SETUP.md) — paste-into-your-AI prompts that automate the install for each path (including a "help me decide" prompt that picks for you).
• ✅ [scripts/verify.{ps1,sh}](scripts/) — 60-second smoke test you can point at any deployment URL. Captures a test thought, searches for it, cleans up. Use it to confirm a fresh install or to debug a sick one.
• 🚑 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — cross-cutting fixes: embedder unreachable, dimension mismatch, multi-replica SSE drops, Supabase pooler quirks, etc.
• ⏱️ [docs/13-FIRST-HOUR.md](docs/13-FIRST-HOUR.md) — what to actually do once it's running: first captures, search patterns, building the habit.
• 🧠 [AGENTS.md](AGENTS.md) — drop this file in your fork so any AI agent helping a user follows the canonical install procedure (read automatically by Copilot, Claude Code, Cursor, Aider, Devin).

> Note on docs 02-08: The numbered documentation (02-DATABASE-SCHEMA through 08-IMPLEMENTATION-ROADMAP) was originally written for the Supabase/OpenRouter path with 1536-dim vectors. The actual codebase and Docker/K8s deployment use 768-dim Ollama vectors. Both paths are fully functional — just match your EMBEDDING_DIMENSIONS env var to your embedder.

---

Quick Start (Docker Compose)

Prerequisites

• Docker and Docker Compose
• Ollama running locally (or an OpenRouter API key)

Option A: Easy Button — Paste One Prompt

Open Copilot Chat (Agent Mode), Claude Code, or Cursor and paste the prompt from [EASY-SETUP.md](EASY-SETUP.md). Your AI will check prerequisites, ask a few questions, generate .env, start Docker, configure your client, and verify — zero manual steps.

Option B: Setup Wizard Script

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

# PowerShell (Windows)
.\setup.ps1

# Bash (macOS / Linux)
chmod +x setup.sh && ./setup.sh

The wizard checks Docker/Ollama, asks which embedder and AI client, generates .env with secure random keys, starts Docker Compose, waits for health, and configures your MCP client.

Option C: Manual Setup

1. Clone and configure

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

cp .env.example .env
# Edit .env — set your MCP_ACCESS_KEY and embedder settings

2. Pull the embedding model (if using Ollama)

ollama pull nomic-embed-text
ollama pull llama3.2

3. Start services

docker compose up -d

This starts:

• PostgreSQL 17 + pgvector on port 5432
• Open Brain API on port 8000 (REST) and port 8080 (MCP SSE)

4. Verify

For a 60-second smoke test (works against any deployment URL):

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

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

Or do it by hand:

# REST API health
curl http://localhost:8000/health
# {"status":"healthy","service":"open-brain-api"}

# MCP server health
curl http://localhost:8080/health
# {"status":"healthy","service":"open-brain-mcp"}

# Run the full 27-test integration suite
OPENBRAIN_API_URL=http://localhost:8000 npm run test:integration

The integration test suite runs 27 tests covering every endpoint — capture, batch, search, list, stats, update, delete — including created_by filtering, validation errors, and a full lifecycle test. All test data is auto-cleaned after the run.

If anything fails, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md). For what to do once it's working, see [docs/13-FIRST-HOUR.md](docs/13-FIRST-HOUR.md).

5. Connect an AI client

Add to your Claude Code settings (~/.claude/settings.json):

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

Restart Claude Code. You now have persistent memory across all sessions.

---

MCP Tools

Open Brain exposes seven tools via the Model Context Protocol.

> Prompting tip: Metadata (type, topics, people, action items) is extracted automatically — just write naturally. Optional parameters like project, created_by, and source require you to mention them in your prompt. See the [Prompt Kit](docs/06-PROMPT-KIT.md) for full guidance on prompting your AI to use all features.

capture_thought

Save a new thought with auto-generated embedding and metadata extraction. Supports project scoping and provenance tracking.

"Save this thought: We decided to use PostgreSQL with pgvector
instead of Pinecone. Reason: self-hosted, lower cost, simpler stack."

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | content | string | required | The thought to capture | | project | string | — | Scope to a project/workspace | | source | string | "mcp" | Provenance tracking (which session/tool) | | supersedes | string | — | UUID of a prior thought this replaces | | created_by | string | — | User who created this thought (optional, for multi-developer teams) |

search_thoughts

Semantic vector search — find thoughts by meaning, not exact keywords. Supports project scoping and metadata filters.

"Search my brain for database migration decisions"

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | query | string | required | Natural language search query | | limit | integer | 10 | Maximum results | | threshold | float | 0.5 | Minimum similarity score (0-1) | | project | string | — | Scope to a specific project | | type | string | — | Filter by thought type | | topic | string | — | Filter by topic tag | | include_archived | boolean | false | Include archived thoughts | | created_by | string | — | Filter to thoughts by a specific user |

list_thoughts

Browse and filter thoughts by type, topic, person, project, or time range.

| Parameter | Type | Description | |-----------|------|-------------| | type | string | Filter: observation, task, idea, reference, person_note, decision, meeting, architecture, pattern, postmortem, requirement, bug, convention | | topic | string | Filter by topic tag | | person | string | Filter by person mentioned | | days | integer | Only thoughts from the last N days | | project | string | Scope to a specific project | | include_archived | boolean | Include archived thoughts (default: false) | | created_by | string | Filter to thoughts by a specific user |

thought_stats

Aggregate statistics: total thoughts, type distribution, top topics, top people. Optionally scoped to a project or user.

| Parameter | Type | Description | |-----------|------|-------------| | project | string | Scope stats to a specific project | | created_by | string | Scope stats to a specific user |

update_thought

Update an existing thought's content. Re-generates embedding and re-extracts metadata automatically.

| Parameter | Type | Description | |-----------|------|-------------| | id | string | required — UUID of the thought to update | | content | string | required — New content |

delete_thought

Permanently delete a thought by ID.

| Parameter | Type | Description | |-----------|------|-------------| | id | string | required — UUID of the thought to delete |

capture_thoughts (batch)

Batch capture multiple thoughts in one call. Each thought gets independent embedding and metadata extraction.

| Parameter | Type | Description | |-----------|------|-------------| | thoughts | array | required — Array of { content: string } objects | | project | string | Scope all thoughts to a project | | source | string | Provenance tracking (default: "mcp") | | created_by | string | User who created these thoughts (optional) |

---

REST API

The REST API provides direct HTTP access (no MCP protocol needed).

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | POST | /memories | Capture a thought (supports project, supersedes, created_by) | | POST | /memories/batch | Batch capture multiple thoughts | | POST | /memories/search | Semantic search (supports project, type, topic, created_by, include_archived) | | POST | /memories/list | Filtered listing (supports project, created_by, include_archived) | | PUT | /memories/:id | Update a thought (re-embeds + re-extracts metadata) | | DELETE | /memories/:id | Delete a thought permanently | | GET | /stats | Brain statistics (supports ?project= and ?created_by= query params) | | GET | /memories/by-source | Retrieve thoughts by source hash (supp

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: srnichols
• Source: srnichols/OpenBrain
• License: MIT

Install and usage instructions live in the source repository linked above.