# OpenBrain — Agent Guidelines

> **Purpose**: Self-hosted semantic brain — pgvector + MCP server for any AI agent
> **SSOT**: https://git.mosaicstack.dev/mosaic/openbrain
> **Status**: Alpha (0.0.1)

---

## Stack

| Layer | Tech |
|-------|------|
| Language | Python 3.12 |
| API | FastAPI + uvicorn |
| MCP | `mcp[cli]` Python SDK (streamable HTTP transport) |
| Database | PostgreSQL 17 + pgvector |
| Embeddings | Ollama (`bge-m3:latest`, 1024-dim) |
| CI/CD | Woodpecker → Gitea registry |
| Deployment | Docker Swarm via Portainer |

## Structure

```
src/
  config.py     — env-based settings (pydantic-settings)
  db.py         — asyncpg connection pool
  embeddings.py — Ollama embedding client
  models.py     — Pydantic request/response models
  brain.py      — core operations (capture, search, recent, stats)
  main.py       — FastAPI app + MCP server mount
docker/
  postgres/init.sql — schema + pgvector setup
.woodpecker/
  build.yml     — lint → kaniko build → push
```

## Key Rules

1. **Never hardcode secrets, IPs, or internal hostnames.** All config via env vars.
2. **Public repo.** `.env` is gitignored. `.env.example` has placeholders only.
3. **MCP transport is Streamable HTTP** mounted at `/mcp`. Not stdio.
4. **REST + MCP live in one process** (`src/main.py`). No separate MCP container.
5. **Schema is append-only** in alpha. Migrations via new SQL files in `docker/postgres/`.
6. **Embeddings are best-effort**: if Ollama is unreachable, thought is stored without embedding.

## Auth

All REST endpoints require: `Authorization: Bearer <API_KEY>`

MCP server at `/mcp` uses the same key via MCP client config headers.

## Local Dev

```bash
cp .env.example .env
# Fill in DATABASE_URL, API_KEY, OLLAMA_URL

uv pip install -e ".[dev]"
uvicorn src.main:app --reload
```

## CI/CD

Push to `main` → Woodpecker lints + builds image → pushes `sha-<hash>` + `latest` tags.
Tag a release → pushes `v0.0.x` + `sha-<hash>` tags.

## Deployment

Use `docker-compose.portainer.yml` as a Portainer stack.
Required env vars: `POSTGRES_PASSWORD`, `API_KEY`, `OLLAMA_URL`, `IMAGE_TAG`.
Init SQL must be copied to host at `/opt/openbrain/init.sql` before first deploy.

## MCP Client Config (Claude Code)

```json
{
  "mcpServers": {
    "openbrain": {
      "type": "http",
      "url": "https://brain.woltje.com/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```