BrainAPI builds a knowledge graph out of your text and shows the path it used

Events, not pairs: the modelling choice behind the answers

The README's description of what BrainAPI is reads like a definition and a differentiator at once. You feed it documents, notes, messages or events, and behind the scenes a group of AI agents reads everything, understands what happened, writes down the facts and connects them into a queryable graph. You then ask questions in plain language and get answers grounded in the actual connections it found.

The design decision the README calls out is that BrainAPI is event-centric. Instead of storing a generic relation like A is related to B, it captures who did what, to whom, when, and in what context. That is what lets it answer multi-step questions and always show the path it used to get there.

The example makes the difference concrete. You feed it one sentence, that Emily organized the AI Ethics Meetup in London on March 8, 2024. Then you ask something it was never explicitly told, who organized AI events in London in Q1 2024, and the answer comes back as a sentence with a date, with the graph path available in result.triples.

The README states the contrast directly: not a nearest-neighbour guess, but a reasoned, walkable path through a graph it built for you. For a team that has to justify a model's answer, that path is the product.

The TUI does the setup, and the wizard is the product

The quickstart is the quickest way to understand the project, because it explains how much of the system is automated for you.

The brainapi TUI is a CLI that clones the project, sets up a Python environment, configures services, starts backing services and launches everything. The commands are short:

npm install -g brainapi-tui
brainapi init     # clone, install deps, setup wizard (or pass flags to skip prompts)
brainapi start    # backing services + API + MCP + worker + console

Once it is up there are three endpoints to know: the API on port 8000, the web console on port 8000 under /console, and the MCP server on port 8001 under /mcp. You log in to the console with the BRAINPAT_TOKEN generated during setup.

The TUI command table covers the lifecycle. brainapi init clones into ~/.brainapi/source/, creates a venv and runs setup, with flags skipping individual prompts. brainapi start brings up the backing services and runs the API, MCP server and Celery worker, and Ctrl-C stops all of them. brainapi config re-opens the setup wizard for one area such as databases, models, pipeline or plugins. brainapi doctor checks Python, Docker, Ollama, cloud credentials and configured services. brainapi update does a git pull and reinstalls the Python dependencies. Running any command except help before init runs init first automatically.

The TUI installs into ~/.brainapi/ with the source, venv, .env and state.json, separate from any git clone, and you can override the location with BRAINAPI_HOME, BRAINAPI_REPO_URL or BRAINAPI_BRANCH.

Running from source, and the two deploy profiles

If you are contributing, the README points you at make and the repository rather than the TUI:

git clone https://github.com/lumen-labs/brainapi2.git && cd brainapi2
poetry install
make start-all      # backing services + API (:8000) + MCP (:8001) + Celery worker

The console can be built and served separately, with make build-console and make start-api serving it on port 8000, or the console UI hot-reloaded on port 5173 while the API runs in a separate terminal. Other targets include start-api, start-mcp, stop-all, and install-extras, which auto-installs heavy machine learning extras such as local OCR based on your .env.

The Docker path is where the real weight is, and the README offers two deploy profiles. The light profile is Postgres with DeepSeek and OpenAI embeddings, and the heavy profile is Neo4j, Milvus, Mongo plus GCP and Azure:

# light - Postgres + DeepSeek + OpenAI embeddings
cp deploy/env.light.example .env   # fill in secrets, then:
docker compose -f deploy/docker-compose.light.yaml up -d

The Makefile at the repository root shows how the services are actually managed, with separate start, stop and delete-volumes targets for Milvus, RabbitMQ, Redis, Neo4j and Mongo, each pointing at a compose file under src/lib. The Neo4j extension is built and packaged with a Maven container, and the API is started with poetry run python -m uvicorn src.services.api.app.

That list of databases is the honest summary of what this project is. A knowledge graph layer needs a graph store, a vector store, a document store and a queue, and the light profile is the one that removes the heaviest of them.

Ingesting data, and the provider matrix behind it

Once the stack is up, the first data point goes in over the ingest endpoint:

curl -X POST http://localhost:8000/ingest/ \
  -H "Authorization: Bearer $BRAINPAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"data_type": "text", "text_data": "Emily organized the AI Ethics Meetup in London on 2024-03-08."}, "brain_id": "default"}'

The .env.example file shows how wide the provider surface is. The LLM implementation variables cover Azure with small and large models and an API version, GCP Vertex with Claude models for extra small, small and large, Bedrock with Haiku and Sonnet model identifiers and a Titan embedding model, and OpenAI with small, large and embedding models. DeepSeek is included as an OpenAI-compatible chat provider, and the comment in the file notes it has no embeddings, so the embeddings provider stays on azure, openai or gcp_vertex.

The library dependencies in pyproject.toml tell the same story from a different angle. Alongside fastapi and uvicorn for the API, celery with kombu and rabbitmq for the worker, and mcp for the Model Context Protocol server, there is langgraph-sdk, langchain and langchain-core, langchain-openai, langchain-google-vertexai and langchain-aws, the openai, google-genai, anthropic and boto3 clients, tiktoken, and a set of document processing libraries: spacy with spacy_langdetect and langid, cpp-chunker, pillow, sympy, numpy, levenshtein and tenacity. Storage is neo4j for the graph, pymilvus and pgvector for vectors, psycopg2-binary for Postgres, pymongo for Mongo, redis for the cache, and langid and networkx as smaller helpers.

The library is BUSL-1.1, Python 3.11 or newer and under 4.0, and the project metadata shows a licence field GitHub cannot classify, so read the LICENSE file and the licences/ directory before you build a product on it.

The Console, and what the docs do not settle

The Console section describes the web UI as a way to explore everything inside your brain: the graph, text chunks, vectors, observations, tasks, and an ingest page to push new data. The README also links a BrainAPI Cloud service and a documentation site for version 2 at brainapi.lumen-labs.ai/docs/v2, plus a wiki, an llms.txt file in the repository, and a Discord community.

What the documentation does not settle is worth naming, because it shapes what you can evaluate. The pipeline has an accurate and a lightweight mode, selected with the --pipeline flag on brainapi start, but the README does not say what each one does, only that the choice exists. The vector database and the model providers are likewise a matter of flags rather than a documented recommendation, and the light and heavy deploy profiles differ in which stores are present, not in what the agent swarm does.

The plugin system is mentioned in the init flags with --no-plugins and in the plugins/ directory, and the repository carries benchmarks/, tests/, an mcp-stdio-http-bridge/ directory and an example-docker-compose.yaml, so there is more here than the readme shows.

The release record is the other thing to check. The listed versions are v2.18.0-dev, v2.19.0-dev and v2.19.0-dev.0, all from August 2026, and the package version in pyproject.toml is 2.19.1.dev1, so what is published is development builds rather than a stable release line.

Editorial conclusion

Adopt BrainAPI if your product needs an agent memory that can explain its answers, since the event-centric graph and the traceable retrieval path are the reason to pick it over plain vector search. Do not adopt it for a prototype that needs one API and a few documents, because the default deployment profile pulls in Postgres, Neo4j, Milvus, Mongo, Redis and RabbitMQ alongside the agent pipeline. Before you commit, read the two deploy profiles and pick light or heavy deliberately, check the licence yourself, since the project metadata declares BUSL-1.1 and GitHub shows a licence it cannot classify, and note the release picture, where the listed tags are 2.18 and 2.19 development builds and the last push was on 2026-10-17.

Frequently asked questions

Official sources

1. Issues
2. Lumen-Labs/brainapi2 on GitHub
3. Project website
4. README
5. Releases