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

```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.

## 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
    }
  }
}
```

## 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