{"slug": "show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline", "title": "Show HN: BrainAPI's event-centric graph from any data with four-stage pipeline", "summary": "Lumen Labs launched BrainAPI, an open-source tool that automatically builds event-centric knowledge graphs from raw text using a swarm of AI agents. The system extracts facts and relationships to answer multi-step questions with traceable reasoning paths, distinguishing it from similarity-based retrieval. Available via a CLI or Docker, it targets developers needing structured knowledge extraction from unstructured data.", "body_md": "**Turn raw text into a living knowledge graph — automatically.**\n\n*You send text. A swarm of agents reads it, takes notes, and draws the graph for you.\nThen you ask questions and get answers backed by a traceable path — not a similarity guess.*\n\n[BrainAPI Cloud](https://brainapi.lumen-labs.ai/) •\n[Quickstart](#-quickstart-fastest-way-to-run-it) •\n[What it is](#-what-is-brainapi) •\n[How it works](#️-how-it-works-the-agent-swarm) •\n[Use cases](#-where-you-can-use-it) •\n[Docs ↗](https://brainapi.lumen-labs.ai/docs/v2)\n\n**BrainAPI reads your text and builds a knowledge graph out of it — by itself.**\n\nYou feed it documents, notes, messages or events. 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.\n\nThe trick is that BrainAPI is **event-centric**. Instead of just storing \"A is related to B,\" it captures *who did what, to whom, when, and in what context*. That's what lets it answer multi-step questions and always show you the path it used to get there.\n\nFeed it one sentence:\n\n```\n\"Emily organized the AI Ethics Meetup in London on March 8, 2024.\"\n```\n\nAsk something it was never explicitly told:\n\n```\nresult = client.retrieveContext(\"Who organized AI events in London in Q1 2024?\")\n# → \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"\n# → result.triples shows the full graph path used to derive this\n```\n\nThat trace is the difference. Not a nearest-neighbour guess — a **reasoned, walkable path through a graph it built for you.**\n\nThe quickest way to get BrainAPI running is the ** brainapi TUI** — an interactive CLI that clones the project, sets up a Python environment, walks you through configuration, starts the backing services, and launches everything for you. Pick the defaults and you'll be up in a few minutes.\n\n```\nnpm install -g brainapi-tui\nbrainapi init     # clone, install deps, interactive setup → choose \"Use default settings\"\nbrainapi start    # backing services + API + MCP + worker + console\n```\n\nWhen it's up:\n\n**API**→`http://localhost:8000`\n\n**Console (web UI)**→`http://localhost:8000/console`\n\n**MCP server**→`http://localhost:8001/mcp`\n\nLog in to the console with the `BRAINPAT_TOKEN`\n\ngenerated during setup. That's it — you have a working brain.\n\n| Command | What it does |\n|---|---|\n`brainapi init` |\nClone the repo into `~/.brainapi/source/` , create a venv, run the setup wizard |\n`brainapi start` |\nBring up backing services and run the API, MCP server, and Celery worker (Ctrl-C stops all) |\n`brainapi config` |\nRe-open the setup wizard to change one area (databases, models, pipeline, plugins, …) |\n`brainapi doctor` |\nCheck Python, Docker, Ollama, cloud credentials, and configured services |\n`brainapi update` |\n`git pull` the install and reinstall Python dependencies |\n\nRunning any command (except `help`\n\n) before `init`\n\nwill run `init`\n\nfirst automatically.\n\n**Useful brainapi start flags:**\n\n`--pipeline accurate|lightweight`\n\n, `--no-services`\n\n, `--no-api`\n\n/ `--no-mcp`\n\n/ `--no-worker`\n\n, `--only api,mcp,worker`\n\n. Full reference → [.](/Lumen-Labs/brainapi2/blob/main/tui/README.md)\n\n`tui/README.md`\n\nThe TUI installs into\n\n`~/.brainapi/`\n\n(source, venv,`.env`\n\n, and`state.json`\n\n) — separate from any git clone. Override with`BRAINAPI_HOME`\n\n,`BRAINAPI_REPO_URL`\n\n, or`BRAINAPI_BRANCH`\n\n.\n\nIf you're contributing or hacking on BrainAPI, run it straight from the repo with `make`\n\n:\n\n```\ngit clone https://github.com/lumen-labs/brainapi2.git && cd brainapi2\npoetry install\nmake start-all      # backing services + API (:8000) + MCP (:8001) + Celery worker\n```\n\n`make start-all`\n\nruns everything from source with hot reload enabled, so code changes are picked up live.\n\n**Console in dev mode:**\n\n```\nmake build-console && make start-api   # serve console at http://localhost:8000/console\n# — or hot-reload the console UI separately —\nmake start-api          # terminal 1\nmake start-console-dev  # terminal 2 → http://localhost:5173/console/\n```\n\n**Other handy targets:** `make start-api`\n\n, `make start-mcp`\n\n, `make stop-all`\n\n, and `make install-extras`\n\n(auto-installs heavy ML extras like local OCR based on your `.env`\n\n).\n\n**Docker only:**\n\n```\ndocker compose -f example-docker-compose.yaml up -d\n```\n\nThen ingest your first data point:\n\n```\ncurl -X POST http://localhost:8000/ingest/ \\\n  -H \"Authorization: Bearer $BRAINPAT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"data\": {\"data_type\": \"text\", \"text_data\": \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"}, \"brain_id\": \"default\"}'\n```\n\nThe Console is a web UI for exploring everything inside your brain: the **graph**, **text chunks**, **vectors**, **observations**, **tasks**, and an **ingest** page to push new data. It's served on the same port as the API at `http://localhost:8000/console`\n\nand you log in with your `BRAINPAT_TOKEN`\n\n.\n\nSet\n\n`CONSOLE_ENABLED=false`\n\nto disable static serving in environments where you don't want the UI exposed.\n\nEvery piece of text you send is read and discussed by a **swarm of specialized agents**. After they understand it, they write down notes and draw the graph. Each agent has one narrow job, which keeps the pipeline reliable and auditable end to end.\n\n``` php\nflowchart TD\n    Text[\"Raw text\"] --> Scout[\"🔍 Scout<br/>extract ALL entities\"]\n    Text --> Observer[\"📝 Observations Agent<br/>write notes about facts<br/>using prior context\"]\n    Scout -->|entities| Architect[\"🏛️ Architect<br/>build event-centric<br/>relationships\"]\n    Architect -->|relationships + entities| Janitor[\"🧹 Janitor<br/>verify correctness<br/>+ check for duplicates\"]\n    Janitor -->|\"errors + instructions\"| Architect\n    Janitor -->|\"OK\"| Graph[\"📊 Knowledge Graph<br/>(append-only)\"]\n    Observer --> Graph\n```\n\n**🔍 Scout** reads the text and extracts**all** the entities it contains — people, things, events, quantities.**📝 Observations Agent** runs alongside and writes down notes about the facts in the text, taking the previously known context into account.**🏛️ Architect** takes the Scout's entities, re-reads the text, and creates the connections between them as**event-centric relationships**—`subject —rel→ event —rel→ object`\n\n. Actions become first-class event hubs rather than flat edges.**🧹 Janitor** checks the Architect's work: are the relationships correct, and do similar nodes (the same entity) or triplets (the same fact) already exist in the graph? If something is wrong, the Janitor tells the Architect exactly what to fix and expects a corrected output, then checks again — looping until it's clean.\n\nEvery action is modeled as a central **Event Hub** connecting three points, which is what makes multi-hop, traceable answers possible:\n\n```\n                    ┌─────────────────┐\n                    │   EVENT HUB     │\n                    │  (Action Node)  │\n                    └────────┬────────┘\n                             │\n           ┌─────────────────┼─────────────────┐\n           ▼                 ▼                 ▼\n    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐\n    │    ACTOR     │  │    TARGET    │  │   CONTEXT    │\n    │   (Source)   │  │ (Recipient)  │  │  (Anchor)    │\n    └──────────────┘  └──────────────┘  └──────────────┘\n         :MADE            :TARGETED       :OCCURRED_WITHIN\n```\n\nSo `\"Emily organized the AI Ethics Meetup in London\"`\n\nbecomes:\n\n``` php\n(Emily)-[:MADE]->(Organizing Event)-[:TARGETED]->(AI Ethics Meetup)\n                                     \\-[:OCCURRED_WITHIN]->(London)\n```\n\nBrainAPI follows an **append-only philosophy**: nothing is deleted from the graph. Every new action is appended as its own event node rather than overwriting what was already there. This keeps the full history intact and lets you **reconstruct how facts evolved over time** — events are never merged away, so the provenance trail always survives.\n\n(default) — the full swarm runs: Scout extracts every entity, the Observations agent writes notes, and the Janitor validates and deduplicates the Architect's relationships.`accurate`\n\n— a faster, cheaper path that extracts only the most important entities and skips the heavier validation steps. Switch with`lightweight`\n\n`--pipeline lightweight`\n\nor`PIPELINE_MODE`\n\nin`.env`\n\n.\n\nOnce your data is in, BrainAPI exposes purpose-built retrieval endpoints (REST, on port `8000`\n\n):\n\n| Endpoint | Method | What you get |\n|---|---|---|\n`/retrieve/context` |\n`POST` |\nRelevant information for a piece of text — the matching graph triples plus historical context |\n`/retrieve/entity/status` |\n`GET` |\nExistence check for a specific entity — returns whether it exists, its node, relationships, and observations |\n`/retrieve/entity/synergies` |\n`GET` |\nSimilar things related to a given one — effectively a recommendation algorithm over the graph |\n\n**Get context for a question:**\n\n```\ncurl -X POST http://localhost:8000/retrieve/context \\\n  -H \"Authorization: Bearer $BRAINPAT_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Who organized AI events in London in March 2024?\", \"brain_id\": \"default\"}'\n# → text_context + triples (the graph path) + historical_context\n```\n\n**Check if an entity exists:**\n\n```\ncurl \"http://localhost:8000/retrieve/entity/status?target=Emily\" \\\n  -H \"Authorization: Bearer $BRAINPAT_TOKEN\"\n# → { \"exists\": true, \"node\": {...}, \"relationships\": [...], \"observations\": [...] }\n```\n\n**Find synergies (recommendations):**\n\n```\ncurl \"http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101\" \\\n  -H \"Authorization: Bearer $BRAINPAT_TOKEN\"\n# → similar entities ranked by how strongly they connect to the target\n```\n\nThese three cover the most common needs, but there are more (`/retrieve/hops`\n\n, `/retrieve/entities/neighbors`\n\n, `/retrieve/text-chunks`\n\n, …). Full list → [REST API Reference](https://brainapi.lumen-labs.ai/docs/rest).\n\nOut of the box BrainAPI is a general-purpose understanding engine. **Plugins** let you reshape it into something far more specific — without forking the core. Because plugins can add routes, swap agent prompts, and register MCP tools, the same engine can become:\n\n**A cheap semantic search engine**— extract entities once, then serve fast graph-backed search instead of paying for vector queries every time.** A recommendation system**— build on`/retrieve/entity/synergies`\n\nand custom routes to surface related products, content or collaborators.**A domain-specific extractor**— override the Scout/Architect prompts so the swarm understands your ontology (CRM, legal, medical, …).** An agent toolset**— register custom MCP tools so any LLM runtime can read and write your brain.\n\nA plugin can:\n\n- Add custom REST routes to the BrainAPI server\n- Override or extend the agents' prompts for domain-specific extraction\n- Register new MCP tools for agent runtimes\n- Ship its own background (Celery) tasks\n\n```\npoetry run brainapi plugins install @community/crm-entities\npoetry run brainapi plugins list --remote\n\npoetry run brainapi plugins register         # become a publisher\npoetry run brainapi plugins publish ./my-plugin.tar.gz\n```\n\nBrowse and publish at the [Plugin Registry →](https://registry.brain-api.dev/app)\n\nBrainAPI shines wherever messy, ever-changing text needs to become structured, queryable understanding:\n\n**AI memory for agents**— persistent, structured memory across sessions and documents, with provenance.** Recommendation systems**— grounded in real behavioural paths, not click co-occurrence.** Semantic search**— retrieve by meaning and multi-hop reasoning across docs, tickets and chat.** Expert & community mapping**— \"Who in our org has worked on Kubernetes and ML pipelines together?\"** Business intelligence from qualitative data**— turn feedback and support conversations into queryable signals.** Investigation & compliance**— connect people, events, documents and timestamps into a coherent, traceable graph.\n\n✅ **Reach for BrainAPI when** you need structured knowledge from messy sources, long-term explainable memory, or multi-hop queries with a traceable answer.\n\n**Skip it when** your data already fits a fixed schema you control, or a single SQL query solves the problem.\n\nThe MCP server runs as a separate process on port **8001** (`http://localhost:8001/mcp`\n\n).\n\n- Start it:\n`make start-mcp`\n\n(or it's already running via`brainapi start`\n\n). - In Claude Desktop →\n**Settings → Developer → Edit Config**, add:\n\n```\n\"brainapi-local\": {\n  \"command\": \"/path/to/node/bin/npx\",\n  \"args\": [\"-y\", \"@pyroprompts/mcp-stdio-to-streamable-http-adapter\"],\n  \"env\": {\n    \"URI\": \"http://localhost:8001/mcp\",\n    \"MCP_NAME\": \"brainapi-local\",\n    \"PATH\": \"/path/to/node/bin:/usr/local/bin:/usr/bin:/bin\",\n    \"BEARER_TOKEN\": \"your-pat-here\"\n  }\n}\n```\n\n- Make sure URL-based MCP servers are enabled in Claude Desktop settings.\n\n| Platform | Package | Status |\n|---|---|---|\nPython |\n`lumen_brain` |\n\n**Node.js**`lumen-brain`\n\n``` python\nfrom lumen_brain import BrainAPI\n\nclient = BrainAPI(api_key=\"your-key\")\nclient.ingest.text(\"Emily organized the AI Ethics Meetup in London on 2024-03-08.\")\n\nresult = client.retrieveContext(\"Who organized AI events in London in March 2024?\")\nprint(result.text_context)   # the answer\nprint(result.triples)        # the graph path used to derive it\n```\n\nBoth SDKs are pre-1.0 and under active development. For production, use the\n\n[REST API]directly until v1.0 ships. You can mix modes freely — ingest over REST, retrieve via MCP inside an agent runtime, or use the SDKs for everything.\n\n[\n▶ Watch: BrainAPI (non-technical) Overview Video\n](https://www.youtube.com/watch?v=wWwTFU5-qeA)\n\n| Resource | Link |\n|---|---|\n| 🖥️ Local CLI (TUI) |\n`tui/README.md` |\n\n`npm install -g brainapi-tui`\n\n[brainapi.lumen-labs.ai/docs/v2](https://brainapi.lumen-labs.ai/docs/v2)[brainapi.lumen-labs.ai/docs/quickstart](https://brainapi.lumen-labs.ai/docs/quickstart)[registry.brain-api.dev/app](https://registry.brain-api.dev/app)[brainapi.lumen-labs.ai/docs/rest](https://brainapi.lumen-labs.ai/docs/rest)[pypi.org/project/lumen_brain](https://pypi.org/project/lumen_brain/)[npmjs.com/package/@lumenlabs/lumen-brain](https://www.npmjs.com/package/@lumenlabs/lumen-brain)[Discord](https://discord.gg/VTngQTaeDf)- Fork the repository\n- Create a feature branch (\n`git checkout -b feature/amazing-feature`\n\n) - Commit your changes (\n`git commit -m 'Add amazing feature'`\n\n) - Push to the branch (\n`git push origin feature/amazing-feature`\n\n) - Open a Pull Request\n\nThis project is licensed under **AGPLv3 + Commons Clause** — free for personal, research and non-commercial use. Commercial usage (SaaS, embedding, redistribution) requires an [Enterprise License](mailto:hello@lumen-labs.ai) from Lumen Platforms Inc.\n\nSee the [LICENSE](/Lumen-Labs/brainapi2/blob/main/LICENSE) file for full details.\n\nBuilt with ❤️ by Lumen Labs", "url": "https://wpnews.pro/news/show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline", "canonical_source": "https://github.com/Lumen-Labs/brainapi2", "published_at": "2026-06-25 17:29:41+00:00", "updated_at": "2026-06-25 17:43:56.309519+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "natural-language-processing", "developer-tools"], "entities": ["Lumen Labs", "BrainAPI", "BrainAPI Cloud", "GitHub", "Docker", "Ollama", "Celery", "MCP"], "alternates": {"html": "https://wpnews.pro/news/show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline", "markdown": "https://wpnews.pro/news/show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline.md", "text": "https://wpnews.pro/news/show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline.txt", "jsonld": "https://wpnews.pro/news/show-hn-brainapi-s-event-centric-graph-from-any-data-with-four-stage-pipeline.jsonld"}}