Files

Jason Woltje 5771ec5260 feat: initial alpha scaffold — FastAPI + MCP + pgvector

Implements v0.0.1 of OpenBrain:

- FastAPI REST API (capture, search, recent, stats) with Bearer auth
- MCP server (streamable HTTP at /mcp) exposing all 4 tools
- pgvector schema (vector(1024) for bge-m3)
- asyncpg connection pool with lazy init + graceful close
- Ollama embedding client with fallback (stores thought without vector if Ollama unreachable)
- Woodpecker CI pipeline (lint + kaniko build + push to Gitea registry)
- Portainer/Swarm deployment compose
- Mosaic framework files: AGENTS.md, PRD.md, TASKS.md, scratchpad

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-02 18:25:07 -06:00

2.4 KiB

Raw Blame History

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

Never hardcode secrets, IPs, or internal hostnames. All config via env vars.
Public repo. .env is gitignored. .env.example has placeholders only.
MCP transport is Streamable HTTP mounted at /mcp. Not stdio.
REST + MCP live in one process (src/main.py). No separate MCP container.
Schema is append-only in alpha. Migrations via new SQL files in docker/postgres/.
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

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)

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

2.4 KiB Raw Blame History