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
Interactive installer and runtime CLI for BrainAPI.
Install
npm install -g brainapi-tui
This puts a brainapi binary on your $PATH.
Quick start
brainapi init # clone the project, set up a Python venv, configure services
brainapi start # start docker compose services + run the API
brainapi doctor # check Python, Docker, Ollama, and configured services
Non-interactive / hybrid init
Any value you pass as a flag skips that wizard prompt; everything else is still asked.
brainapi init \
--vector-db=postgresql \
--data-db=postgresql \
--graph-db=networkx \
--models-mode=remote \
--llm-small-provider=openai \
--llm-large-provider=openai \
--embeddings-provider=openai \
--openai-api-key=sk-... \
--llm-small=gpt-4o-mini \
--llm-large=gpt-4o \
--brainpat-token=brainpat_... \
--no-plugins \
--no-start-services
brainapi --init ... is an alias for brainapi init ....
| Flag group | Examples |
|---|---|
| Defaults / DBs | --defaults, --vector-db, --data-db, --graph-db |
| Pipeline / runtime | --ocr-mode, --services-runtime, --start-services, --no-start-services |
| Models | --models-mode, --llm-small-provider, --llm-large-provider, --embeddings-provider, --llm-small, --llm-large, --embedding-model, --embedding-dimensions |
| Ollama | --ollama-host, --ollama-port, --ollama-small, --ollama-large, --ollama-embeddings |
| GCP | --gcp-credentials, --gcp-project, --gcp-small, --gcp-large, --gcp-embedding |
| Azure | --azure-endpoint, --azure-api-version, --azure-key, --azure-small, --azure-large, --azure-embedding-endpoint, --azure-embedding-key, --azure-embedding |
| OpenAI / Anthropic / DeepSeek | --openai-api-key, --openai-base-url, --openai-small, --openai-large, --openai-embedding, --anthropic-api-key, --anthropic-small, --anthropic-large, --deepseek-api-key, --deepseek-small, --deepseek-large |
| Bedrock | --aws-region, --aws-access-key-id, --aws-secret-access-key, --aws-session-token, --bedrock-small, --bedrock-large, --bedrock-embedding |
| Connections | --redis-host, --redis-port, --postgres-*, --neo4j-*, --milvus-*, --mongo-* |
| Auth / plugins | --brainpat-token, --plugin <name[@version]> (repeatable), --no-plugins |
If any config flag is present (or --defaults), the “Use default settings?” question is skipped.
Commands
| Command | Description |
|---|---|
brainapi init |
Full bootstrap: clone the repo, create a venv, install deps, and run setup (flags skip prompts). |
brainapi start |
Start docker compose containers for the chosen services and launch the API. |
brainapi config |
Re-run the interactive flow and rewrite .env. |
brainapi doctor |
Check that Python, Docker, Ollama, GCP credentials, and configured services are reachable. |
brainapi update |
git pull the project and pip install -e . again. |
brainapi plugins install <name> |
Install a plugin from the registry (e.g. brainapi plugins install chatbot). |
brainapi plugins list |
List installed plugins (--remote to browse the registry). |
brainapi plugins uninstall <name> |
Remove an installed plugin. |
brainapi reset |
Purge Celery queues and/or wipe Redis + Postgres brain state (interactive). |
brainapi reset --brain <id> -y |
Wipe one brain's Redis keys and DROP its brain_* Postgres database. |
brainapi reset --all -y |
Redis FLUSHDB + DROP all brain_* databases + clear data_brains. |
brainapi reset --queues-only -y |
Purge Celery queue keys only. |
brainapi start options
| Option | Description |
|---|---|
--pipeline accurate|lightweight |
Set PIPELINE_MODE in ~/.brainapi/source/.env before start (accurate = full pipeline; lightweight = faster ingestion). |
Where things live
- Source:
~/.brainapi/source/ - Python venv:
~/.brainapi/source/.venv/ - Env file:
~/.brainapi/source/.env - Install state:
~/.brainapi/state.json
Configuration
The interactive flow asks (any matching CLI flag skips that prompt):
- Use default settings? (NetworkX + Postgres + pgvector + remote GCP Vertex)
- Otherwise: Vector DB → Data DB → Graph DB → Models mode
- For
remotemodels mode: pick provider, then provide GCP credentials, project, and model names - For
localmodels mode: probe Ollama, wait for it to start, then verify pulled models - Search: enable
/retrieve/search? If yes, retrieval = both fused (default) / dense only / BM25 only. RequiresDATA_DB=postgresql. Search p50 SLO is < 200 ms excluding embed RTT. - Connection details for only the services you actually selected
BRAINPAT_TOKEN(generate or paste)- Optionally start the docker compose containers now
If Python (>=3.11) or Docker is missing, the TUI walks you through installing them with platform-aware commands and retries detection automatically.
Development
cd tui
npm install
npm run dev # builds in watch mode
node dist/index.js init # try it
Publishing
npm version <patch|minor|major>
npm publish
prepublishOnly runs the build automatically so the published tarball always contains dist/. Only the dist/, README.md, and LICENSE files are included (see the files field in package.json).
If someone runs any command before brainapi init (e.g. brainapi doctor or brainapi start), the CLI prints a notice and runs init first.
Environment overrides
| Variable | Default | Description |
|---|---|---|
BRAINAPI_REPO_URL |
https://github.com/Lumen-Labs/brainapi2.git |
The git repo cloned on init. |
BRAINAPI_HOME |
$HOME/.brainapi |
Where the source and state live. |
BRAINAPI_BRANCH |
main |
Branch to checkout after cloning. |