openbrain-mcp/README.md

OpenBrain MCP Server

High-performance vector memory for AI agents

OpenBrain is a Model Context Protocol (MCP) server that provides AI agents with a persistent, semantic memory system. It uses local ONNX-based embeddings and PostgreSQL with pgvector for efficient similarity search.

Features

• 🧠 Semantic Memory: Store and retrieve memories using vector similarity search
• 🏠 Local Embeddings: No external API calls - uses ONNX runtime with all-MiniLM-L6-v2
• 🐘 PostgreSQL + pgvector: Production-grade vector storage with HNSW indexing
• 🔌 MCP Protocol: Standard Model Context Protocol over SSE transport
• 🔐 Multi-Agent Support: Isolated memory namespaces per agent
• ⚡ High Performance: Rust implementation with async I/O

MCP Tools

Tool	Description
store	Store a memory with automatic embedding generation and keyword extraction
query	Search memories by semantic similarity
purge	Delete memories by agent ID or time range

Quick Start

Prerequisites

• Rust 1.75+
• PostgreSQL 14+ with pgvector extension
• ONNX model files (all-MiniLM-L6-v2)

Database Setup

CREATE ROLE openbrain_svc LOGIN PASSWORD 'change-me';
CREATE DATABASE openbrain OWNER openbrain_svc;
\c openbrain
CREATE EXTENSION IF NOT EXISTS vector;

Use the same PostgreSQL role for the app and for migrations. Do not create the memories table manually as postgres or another owner and then run OpenBrain as openbrain_svc, because later ALTER TABLE migrations will fail with must be owner of table memories.

Configuration

cp .env.example .env
# Edit .env with your database credentials

Build & Run

cargo build --release
./target/release/openbrain-mcp migrate
./target/release/openbrain-mcp

Database Migrations

This project uses refinery with embedded SQL migrations in migrations/.

Run pending migrations explicitly before starting or restarting the service:

./target/release/openbrain-mcp migrate

If you use the deploy script or CI workflow in .gitea/deploy.sh and .gitea/workflows/ci-cd.yaml, they already run this for you.

MCP Integration

Connect to the server using SSE transport:

SSE Endpoint: http://localhost:3100/mcp/sse
Message Endpoint: http://localhost:3100/mcp/message
Health Check: http://localhost:3100/mcp/health

Example: Store a Memory

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "store",
    "arguments": {
      "content": "The user prefers dark mode and uses vim keybindings",
      "agent_id": "assistant-1",
      "metadata": {"source": "preferences"}
    }
  }
}

Example: Query Memories

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "query": "What are the user's editor preferences?",
      "agent_id": "assistant-1",
      "limit": 5,
      "threshold": 0.6
    }
  }
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI Agent                              │
└─────────────────────┬───────────────────────────────────┘
                      │ MCP Protocol (SSE)
┌─────────────────────▼───────────────────────────────────┐
│              OpenBrain MCP Server                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │   store     │  │   query     │  │   purge     │      │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘      │
│         │                │                │              │
│  ┌──────▼────────────────▼────────────────▼──────┐      │
│  │           Embedding Engine (ONNX)              │      │
│  │           all-MiniLM-L6-v2 (384d)              │      │
│  └──────────────────────┬────────────────────────┘      │
│                         │                                │
│  ┌──────────────────────▼────────────────────────┐      │
│  │         PostgreSQL + pgvector                  │      │
│  │         HNSW Index for fast search             │      │
│  └────────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────┘

Environment Variables

Variable	Default	Description
OPENBRAIN__SERVER__HOST	0.0.0.0	Server bind address
OPENBRAIN__SERVER__PORT	3100	Server port
OPENBRAIN__DATABASE__HOST	localhost	PostgreSQL host
OPENBRAIN__DATABASE__PORT	5432	PostgreSQL port
OPENBRAIN__DATABASE__NAME	openbrain	Database name
OPENBRAIN__DATABASE__USER	-	Database user
OPENBRAIN__DATABASE__PASSWORD	-	Database password
OPENBRAIN__EMBEDDING__MODEL_PATH	models/all-MiniLM-L6-v2	ONNX model path
OPENBRAIN__AUTH__ENABLED	false	Enable API key auth

License

MIT