Architecture

Overview

xbrain runs as 25 Docker containers on a single VM, connected via a private Docker network (xbrain_net). All external traffic enters through nginx on port 80/443. Internal services never expose ports to the internet.

The central invariant is memory-api: every data point from every frontend (LibreChat, Open WebUI, Chrome extension, agents) passes through memory-api before persisting. memory-api enforces the 7-field tagging contract and routes data to the right stores: PostgreSQL (event store), Qdrant (vector search), and Neo4j (knowledge graph).

Architecture Diagram

                    ┌─────────────────┐
  Browser ─────────►│  nginx (80/443)  │
                    └────────┬────────┘
                             │
              ┌────────────┼────────────┐
              │              │              │
       ┌──────▼──┐   ┌──────▼──┐   ┌─────▼──────┐
       │ LibreChat │   │Open WebUI│   │ memory-api  │
       └──────┬──┘   └──────┬──┘   └─────┬──────┘
              │              │              │
       ┌─────▼───────────▼──┐   ┌─────▼──────┐
       │  librechat-bridge        │   │ PostgreSQL  │
       │  openwebui-pipeline      │   │ Qdrant      │
       └─────────────────────────┘   │ Neo4j       │
                                      └────────────┘
       ┌──────────────┐   ┌──────────────────────────┐
       │ agent-runtime │   │ MCP Gateway               │
       │ (LangGraph)   │   │ mcp-scraper               │
       └──────┬────────┘   │ mcp-drive-read            │
              │            │ mcp-calendar              │
       ┌─────▼───────┐   │ mcp-deck                  │
       │ graphiti-svc  │   └──────────────────────────┘
       └───────────────┘

       ┌──────────────┐   ┌────────────────────────┐
       │ drive-sync   │   │ Langfuse (observability) │
       └──────────────┘   │ ClickHouse / Redis       │
                          │ MinIO (Chainguard)       │
                          └────────────────────────┘

  All containers: xbrain_net (Docker bridge network)

Container Reference

All 25 containers across Phases 1–5. The Phase column indicates when each container is first introduced. Containers from earlier phases remain active in later phases.

Network Architecture

All containers connect on xbrain_net, a Docker bridge network defined in docker-compose.yml. Container-to-container communication uses service names as hostnames (e.g., http://memory-api:8000).

Exposed ports

Internal-only ports

Data Flow — Chat Message

Here is what happens from the moment a user sends a message in LibreChat to the moment it becomes a searchable memory item:

1. User sends a message in LibreChat.
2. LibreChat saves the message to MongoDB (librechat-mongo) — its own conversation history.
3. librechat-bridge detects the new message via the LibreChat webhook/event.
4. bridge sends POST /v1/messages to memory-api with a Bearer JWT.
5. memory-api enforces the tagging contract — all 7 mandatory fields must be present or the request returns 422.
6. Message is stored in PostgreSQL (event store + audit log) and Qdrant (vector embedding for semantic search).
7. If the message payload includes an entities field, the Neo4j outbox is updated by a background worker.
8. graphiti-service enriches the knowledge graph with temporal facts — this call is fail-soft and async (a graphiti-service outage does not block the memory write).
9. Audit log entry written to PostgreSQL with timestamp, source, and team_scope.

VM Sizing

xbrain's container count grows with each phase. Plan your VM size before deploying a new phase — attempting Phase 2 on a 4 GB VM will cause OOM kills.

See the Deployment guide for detailed instructions on how to resize a GCP VM without data loss.