# 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 | | `batch_store` | Store 1-50 memories atomically in a single call | | `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 ```sql 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 ```bash cp .env.example .env # Edit .env with your database credentials ``` ### Build & Run ```bash 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: ```bash ./target/release/openbrain-mcp migrate ``` If you use the deploy script or CI workflow in [`.gitea/deploy.sh`](/Users/bobbytables/ai/openbrain-mcp/.gitea/deploy.sh) and [`.gitea/workflows/ci-cd.yaml`](/Users/bobbytables/ai/openbrain-mcp/.gitea/workflows/ci-cd.yaml), they already run this for you. ## Agent Zero Developer Prompt For Agent Zero / A0, add the following section to the Developer agent role prompt so the agent treats OpenBrain as external MCP memory rather than its internal conversation context. Recommended target file in A0: ```text /a0/agents/developer/prompts/agent.system.main.role.md ``` ```md ### External Memory System - **Memory Boundary**: Treat OpenBrain as an external MCP long-term memory system, never as internal context, reasoning scratchpad, or built-in memory - **Tool Contract**: Use the exact MCP tools `openbrain.store`, `openbrain.query`, and `openbrain.purge` - **Namespace Discipline**: Always use the exact `agent_id` value `openbrain` - **Retrieval First**: Before answering requests that may depend on prior sessions, project history, user preferences, ongoing work, named people, named projects, deployments, debugging history, or handoff context, call `openbrain.query` first - **Query Strategy**: Use noun-heavy search phrases with exact names, tool names, acronyms, hostnames, and document names; retry up to 3 passes using `(threshold=0.25, limit=5)`, then `(threshold=0.10, limit=8)`, then `(threshold=0.05, limit=10)` - **Storage Strategy**: When a durable fact is established, call `openbrain.store` without asking permission and store one atomic fact whenever possible - **Storage Content Rules**: Store durable, high-value facts such as preferences, project status, project decisions, environment details, recurring workflows, handoff notes, stable constraints, and correction facts - **Noise Rejection**: Do not store filler conversation, temporary speculation, casual chatter, or transient brainstorming unless it becomes a real decision - **Storage Format**: Prefer retrieval-friendly content using explicit nouns and exact names in the form `Type: | Entity: | Attribute: | Value: | Context: ` - **Metadata Usage**: Use metadata when helpful for tags such as `category`, `project`, `source`, `status`, `aliases`, and `confidence` - **Miss Handling**: If `openbrain.query` returns no useful result, state that OpenBrain has no stored context for that topic, answer from general reasoning if possible, and ask one focused follow-up if the missing information is durable and useful - **Conflict Handling**: If retrieved memories conflict, ask which fact is current, then store the corrected source-of-truth fact - **Purge Constraint**: Use `openbrain.purge` cautiously because it is coarse-grained; it deletes by `agent_id` and optionally before a timestamp, not by individual memory ID - **Correction Policy**: For ordinary corrections, prefer storing the new source-of-truth fact instead of purging unless the user explicitly asks for cleanup or reset ``` ## 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 ```json { "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 ```json { "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 } } } ``` ### Example: Batch Store Memories ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "batch_store", "arguments": { "agent_id": "assistant-1", "entries": [ { "content": "The user prefers dark mode", "metadata": {"category": "preference"} }, { "content": "The user uses vim keybindings", "metadata": {"category": "preference"} } ] } } } ``` ## 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