BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
BrainAPI deploy profiles
Choose heavy or light when bringing up a new deployment.
| Heavy | Light | |
|---|---|---|
| Compose | docker-compose.heavy.yaml |
docker-compose.light.yaml |
| Env template | env.heavy.example |
env.light.example |
| Graph | Neo4j | NetworkX on Postgres |
| Data | MongoDB | PostgreSQL |
| Vectors | Milvus | PostgreSQL + pgvector |
| LLMs | GCP Vertex (small) + Azure (large) | DeepSeek (small + large) |
| Embeddings | Azure | OpenAI (text-embedding-3-large) |
| Container limits | Full (current production) | Smaller footprint (mem_limit / cpus) |
| Suggested VM | ~8–16 GB RAM / 4+ vCPU | ~2 GB RAM / 1 vCPU |
Quick start
# 1. Copy a profile template outside the repository and replace every secret.
install -m 600 deploy/env.light.example /etc/brainapi/light.env
# Set BRAINAPI_ENV_FILE to the absolute file path in /etc/brainapi/light.env.
# 2. Validate first, then start and wait for health.
docker compose --env-file /etc/brainapi/light.env \
-f deploy/docker-compose.light.yaml config -q
docker compose --env-file /etc/brainapi/light.env \
-f deploy/docker-compose.light.yaml up -d --wait
# or
docker compose --env-file /etc/brainapi/heavy.env \
-f deploy/docker-compose.heavy.yaml up -d --wait
Only nginx publishes host ports (80 and 443). The API, embedded Console,
and MCP are reached through /, /console/, and /mcp. The checked-in TLS
server rejects handshakes until an operator mounts a certificate-specific
nginx server file; do not expose port 80 beyond a trusted proxy without HTTPS.
Light sizing
| Service | Heavy | Light |
|---|---|---|
| nginx | 128m / 0.2 CPU | 64m / 0.1 CPU |
| redis | 2048m / 0.5 CPU (maxmemory 1500mb) |
256m / 0.1 CPU (maxmemory 192mb) |
| postgres | — (not in heavy compose) | 768m / 0.35 CPU |
| neo4j / milvus / mongo / etcd / minio | present | omitted |
| api / worker / mcp | 2–4g / 1–2 CPU | 768m / 0.5 CPU each |
celery --concurrency |
2 | 1 |
CELERY_WORKER_CONCURRENCY |
4 | 1 |
Notes
BRAINAPI_IMAGE,BRAINAPI_ENV_FILE, Redis credentials, and profile backend credentials are required and fail during Compose interpolation when absent.- Mount cloud credentials with a private operator-owned Compose override; no host-specific credential path is present in the production profiles.
- Do not mix profiles under the same Compose project name. Their volume layouts and restore order differ.
Backup and restore
Backups default to /srv/brainapi/backups and are created with mode 0700.
They contain sensitive application data (including stored brain credentials),
so encrypt and access-control the backup directory. The generated manifest
contains only profile/version metadata, service names, restore order, and
checksums; it never contains secrets.
deploy/brainapi-backup backup --profile light \
--env-file /etc/brainapi/light.env --project-name brainapi
deploy/brainapi-backup verify --profile light \
--env-file /etc/brainapi/light.env --archive /srv/brainapi/backups/light-UTCSTAMP
deploy/brainapi-backup restore --profile light \
--env-file /etc/brainapi/light.env --archive /srv/brainapi/backups/light-UTCSTAMP
Backup stops nginx, API, MCP, and workers before capture. Restore refuses a
running stack, a profile/image mismatch, a checksum mismatch, or any non-empty
target volume. Use a documented maintenance window and retain the generated
manifest with the release artifacts. Light backups include the system registry
plus an individual custom-format dump for every brain_* PostgreSQL database.
Production validation
The CI-only Compose override supplies a deterministic OpenAI-compatible model stub; it is not a production deployment file. It lets both profiles exercise the complete storage and gateway path without external model credentials:
docker compose -f deploy/docker-compose.light.yaml \
-f deploy/docker-compose.ci.yaml up -d --wait
python scripts/production_smoke.py exercise --profile light \
--system-token "$BRAINPAT_TOKEN" --artifact-dir release-artifacts
After backup, clean-volume restore, and restart, run the same tool with
verify-restore. CI retains the profile smoke, latency, restore, backup
manifest, image audit, and SBOM evidence. The tag workflow downloads the exact
commit's successful light and heavy artifacts and runs the release-readiness
gate before any image can be published. Quality CI exports one linux/amd64
candidate archive; the heavy runner loads that same archive, and the tag
workflow publishes it unchanged after verifying its recorded image ID.
Public documentation sandbox
The anonymous sandbox is an opt-in extension of the light profile. Merge
env.public-demo.example into the deployment's
private environment, deploy the current API and worker image, and seed only the
dedicated agentdemo brain:
docker compose --env-file /etc/brainapi/light.env -f deploy/docker-compose.light.yaml up -d
docker compose --env-file /etc/brainapi/light.env -f deploy/docker-compose.light.yaml exec brainapi \
python scripts/seed_public_demo.py --api-url http://localhost:8000
The seed command downloads the published V2 documentation, records its SHA-256
marker, skips an already-current corpus, and polls the asynchronous ingestion
task. It requires the private system BRAINPAT_TOKEN inside the deployment; do
not expose that token through the gateway. After the first successful seed,
BRAIN_CREATION_ALLOWED may be returned to the operator's normal setting.
Expose the API origin as api.brain-api.dev, with TLS, and put the Cloudflare
gateway in front of root-domain /api/*. The application itself deliberately
does not implement client rate limiting; the checked-in gateway owns the
30-request/60-second demo limit.