Getting Started

Phase 1–7 covered · ~10 min read v1.0

Introduction

xbrain is the open-source infrastructure layer behind Cortex OS — a shared cognitive memory system for agentic teams. Every AI agent on your team (coding agent, marketing agent, ops agent) reads from and writes to the same brain. Context never gets lost between them. Handoffs happen automatically.

Unlike a chatbot workspace, xbrain is a memory infrastructure layer. LibreChat, Open WebUI, and custom LangGraph agents all write to the same shared memory. Every data point carries a mandatory tagging contract: team_scope, truth_level, source, and four other fields — enforced by the API, not by convention.

Phase 7 (v1.0) adds three intelligence layers on top of the memory core, available on Team and Enterprise tiers: CRM & contact auto-extraction, task tracking with automatic generation, and Meeting Intelligence (Granola meeting notes → memory + contacts + tasks in one atomic write).

Prerequisites

VM Sizing

Phase 1 runs on a 4 GB VM (e2-medium, ~25€/mo). Phase 2 requires 8 GB. See the Deployment guide for sizing details.

Requirement Version / Notes Required for
Docker Engine 24.0+ All phases
Docker Compose v2 (plugin, not standalone) All phases
Linux VM Ubuntu 24.04 recommended, 4 GB RAM min (Phase 1), 8 GB for Phase 2+ All phases
Google OAuth credentials Client ID + Secret from Google Cloud Console SSO login
Anthropic API key ANTHROPIC_API_KEY Claude models
OpenAI API key OPENAI_API_KEY GPT models (optional)
GitHub account Optional — for GitHub Auth feature (Phase 5) GitHub Auth
Domain name Optional — for HTTPS via Cloudflare Production TLS

Quick Start

Four commands to get a running xbrain stack. All services start in Docker containers. No local dependencies to install beyond Docker.

Step 1 — Clone the repo

bashgit clone https://github.com/mrboups/xbrain.git
cd xbrain/infrastructure

Step 2 — Configure environment

bashcp .env.example .env
# Edit .env with your values:
# - POSTGRES_PASSWORD, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
# - BRIDGE_SHARED_SECRET (random 32-char hex)
# - ANTHROPIC_API_KEY, OPENAI_API_KEY

Generate a secure random secret for BRIDGE_SHARED_SECRET: 

bashopenssl rand -hex 16

Step 3 — Start the stack

bashdocker compose up -d
# Wait ~60 seconds for all healthchecks to pass
docker compose ps

First boot

On first boot, PostgreSQL runs migrations and LibreChat initialises its MongoDB collections. Allow 60–90 seconds before services are fully ready. Watch progress with docker compose logs -f memory-api.

Step 4 — Verify

bashcurl http://localhost/nginx-health
curl http://localhost:8000/v1/healthz

Open LibreChat at http://your-server and sign in with Google. Open WebUI is available at http://your-server/open-webui.

What's Included

xbrain ships as a phased stack. Each phase adds capabilities on top of the previous one. You can stop at any phase — the core memory invariant is present from Phase 1.

Phase Services What you get
Phase 1 nginx, postgres, qdrant, memory-api, librechat, open-webui Core chat + memory layer. Google OAuth. Tagging contract enforced.
Phase 2 agent-runtime, langfuse, mem0, redis, minio, clickhouse Intelligent memory (mem0) + LangGraph agents + LLM observability (Langfuse).
Phase 3 neo4j, mcp-gateway, mcp-scraper, mcp-drive-read, mcp-calendar, drive-sync Knowledge graph + integrations. Web scraping, Drive read/write, Calendar access via MCP.
Phase 4 mcp-deck, librechat bridge upgrades PPTX generation MCP tool. Full MCP toolset completed.
Phase 5 graphiti-service, chrome-extension, github-auth, projects-dashboard Temporal fact extraction, Chrome web clipper, GitHub Org auth, team project dashboard.
Phase 6 marketing-site, app-site Public marketing site and documentation. Firebase Hosting (two sites).
Phase 7 crm router, tasks router, granola-sync, librechat-bridge updates CRM & contact auto-extraction, task tracking with auto-generation, Granola meeting integration. Team & Enterprise tiers only.

Next Steps