README.md
Persistent semantic memory backed by PostgreSQL and pgvector
brain-mcp
An MCP (Model Context Protocol) server that provides persistent semantic memory backed by PostgreSQL + pgvector. Store "thoughts" with vector embeddings and organize them via a flexible dimensional model.
Two Servers
This repo provides two MCP servers with a shared codebase:
- brain-mcp (
dist/index.js) — General-purpose knowledge store with ADR support. Use this for non-code contexts. - brain-code-mcp (
dist/code.js) — Superset of brain-mcp with code-aware tools. Use this for software projects.
You only need to configure one — brain-code-mcp includes all brain-mcp tools.
Features
- Semantic search — find thoughts by meaning using cosine similarity over vector embeddings
- Dimensional organization — tag thoughts with typed dimensions (person, project, topic, tag, file, symbol, etc.)
- Thought temporality — thoughts have types (
fact,decision,observation,question) and can be superseded while preserving history - Multi-brain support — isolated knowledge spaces via the
BRAIN_NAMEenvironment variable - Conflict detection — automatically surfaces similar existing thoughts when capturing new ones
- Architecture Decision Records — structured ADR capture with auto-numbering, alternatives, and consequences
- Code-linked knowledge — link thoughts to repositories, files, and symbols (brain-code-mcp)
- Knowledge freshness — detect stale knowledge when referenced code changes (brain-code-mcp)
Tools
Core tools (both servers)
| Tool | Description |
|---|---|
capture_thought |
Store a thought with type, dimensions, metadata, and embedding. Surfaces conflicts with similar active thoughts. |
search |
Semantic vector search with optional filters (dimension, thought type, etc.) |
list_recent |
Chronological listing with optional filters |
explore_dimension |
All thoughts linked to a given dimension |
list_dimensions |
All dimensions with thought counts |
list_brains |
List all brains with optional thought counts. Respects BRAIN_ACCESSIBLE. |
supersede_thought |
Replace an existing thought, preserving history. Auto-preserves ADR metadata. |
capture_adr |
Record an Architecture Decision Record with context, alternatives, and consequences |
list_adrs |
List and filter ADRs by status or dimension |
Code tools (brain-code-mcp only)
| Tool | Description |
|---|---|
capture_code_context |
Capture knowledge linked to specific files, symbols, or repositories |
search_code |
Semantic search filtered to code-linked knowledge |
check_freshness |
Check if code-linked knowledge is stale by comparing git state |
refresh_stale_knowledge |
Find stale thoughts with git diffs for review |
Core prompts (both servers)
| Prompt | Description |
|---|---|
brain_overview |
Comprehensive orientation: thought counts, dimensions, recent thoughts, ADR summary, open questions |
deep_dive |
Deep dive into a dimension with all linked thoughts, co-occurring dimensions, and ADRs |
decision_review |
Review active decisions and ADRs, flagging overdue revisit dates |
capture_session |
Set up a knowledge capture session with existing taxonomy and related knowledge |
Code prompts (brain-code-mcp only)
| Prompt | Description |
|---|---|
codebase_knowledge |
All knowledge about a repo grouped by file/symbol, with optional freshness checks |
file_context |
All knowledge about a specific file with freshness and semantically related unlinked knowledge |
Setup
Prerequisites
- Node.js
- PostgreSQL with pgvector extension
- An OpenRouter API key (for generating embeddings)
Quick start (Claude Code)
Set OPENROUTER_API_KEY in your shell environment (e.g. in ~/.bashrc or ~/.zshrc):
export OPENROUTER_API_KEY="your-key-here"
Then add to your project's .mcp.json:
{
"mcpServers": {
"brain": {
"command": "npx",
"args": ["-y", "github:markschaake/brain-mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host:5432/brain",
"BRAIN_NAME": "personal"
}
}
}
}
For brain-code-mcp (includes code-aware tools):
{
"mcpServers": {
"brain": {
"command": "npx",
"args": ["-y", "-p", "github:markschaake/brain-mcp", "brain-code-mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@host:5432/brain",
"BRAIN_NAME": "my-project"
}
}
}
}
Note: Do not put
OPENROUTER_API_KEYin.mcp.json— it is often checked into version control. The server reads it from the environment automatically.
The database schema is automatically created on first run.
Database options
Option 1: Use the included docker-compose (easiest for local development)
git clone https://github.com/markschaake/brain-mcp.git
cd brain-mcp
do
Tools (9)
capture_thoughtStore a thought with type, dimensions, metadata, and embedding.searchSemantic vector search with optional filters.list_recentChronological listing with optional filters.explore_dimensionAll thoughts linked to a given dimension.list_dimensionsAll dimensions with thought counts.list_brainsList all brains with optional thought counts.supersede_thoughtReplace an existing thought, preserving history.capture_adrRecord an Architecture Decision Record with context, alternatives, and consequences.list_adrsList and filter ADRs by status or dimension.Environment Variables
DATABASE_URLrequiredPostgreSQL connection stringOPENROUTER_API_KEYrequiredAPI key for generating embeddingsBRAIN_NAMEIdentifier for isolated knowledge spacesConfiguration
claude_desktop_config.json
{"mcpServers": {"brain": {"command": "npx", "args": ["-y", "github:markschaake/brain-mcp"], "env": {"DATABASE_URL": "postgresql://user:pass@host:5432/brain", "BRAIN_NAME": "personal"}}}}Try it
→Give me a brain_overview of my current knowledge base.
→Search for thoughts related to 'database migration' and list them.
→Capture a new ADR regarding the decision to use PostgreSQL for this project.
→Deep dive into the 'project-x' dimension to see all related thoughts and decisions.
→List all recent observations I've recorded in the last week.