Initial public release

2026-03-31 14:49:06 +00:00 · 2026-03-07 13:41:36 -05:00
commit 774982dc5a
22 changed files with 3517 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,161 @@
+# 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