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.

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:

/a0/agents/developer/prompts/agent.system.main.role.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: <FactType> | Entity: <Entity> | Attribute: <Attribute> | Value: <Value> | Context: <Why it matters>`
- **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

{
  "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