Your AI doesn't have memory. It has a database. There's a difference.
BrainAPI turns raw text, documents and events into a living knowledge graph —
one that reasons, connects dots, and grows smarter with every ingestion.
BrainAPI Cloud • Overview • Core Philosophy • Agents • SDKs • API Docs ↗
Feed BrainAPI one sentence:
"Emily organized the AI Ethics Meetup in London on March 8, 2024."
Ask it a question it was never explicitly told the answer to:
result = client.retrieveContext("Who organized AI events in London in Q1 2024?")
# → "Emily organized the AI Ethics Meetup in London on 2024-03-08."
# → result.triples shows the full graph path used to derive thisThat trace is the difference. Not a similarity score. Not a nearest-neighbour guess. A reasoned, walkable path through a knowledge graph — built automatically from your raw text.
# Clone and run in under 2 minutes
git clone https://github.com/lumen-labs/brainapi2.git && cd brainapi2
poetry install && make start-allOr with Docker (recommended):
docker compose -f example-docker-compose.yaml up -dThen ingest your first data point:
curl -X POST http://localhost:3000/ingest \
-H "Authorization: Bearer $BRAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "text", "content": "Emily organized the AI Ethics Meetup in London on 2024-03-08."}'Full walkthrough → Quick Start Guide
BrainAPI is an advanced knowledge graph ecosystem designed for high-precision semantic reasoning and relational analysis across multi-domain datasets. Unlike traditional databases that store static snapshots, BrainAPI uses a dynamic Event-Centric architecture — treating actions, interactions and state changes as first-class nodes that capture multi-dimensional context, temporal history and complex multi-hop reasoning.
The core idea: raw documents, plain text and event streams go in. A queryable, time-aware knowledge graph comes out — powering long-term memory, recommendations and natural-language retrieval for AI agents without you needing to build an extraction pipeline yourself.
Why Event-Centric?
Move beyond simple keyword retrieval toward "Action-Path Reasoning." BrainAPI identifies not just that two entities are connected, but how they interacted, at what magnitude, and within what environment.
✅ BrainAPI excels when you need:
- Structured knowledge extracted from messy, constantly-changing data sources
- Long-term AI memory that persists across sessions, users and documents
- Explainable relationships behind recommendations — not just similarity scores
- Multi-hop queries over temporal data with traceable provenance
- Your data fits a fixed schema you fully control
- A single SQL query or simple CRUD operations solve the problem
- You need purely local, offline-only storage with zero extraction
Every piece of data you feed BrainAPI flows through a five-step pipeline before it becomes queryable knowledge:
Raw data (files, text, APIs, event streams)
│
▼
┌───────────────────────────────────────────────────┐
│ 1. INGEST │
│ Accept documents, plain text, structured │
│ events │
└──────┬────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────┐
│ 2. ANNOTATE │
│ Save observations, notes and annotations on │
│ the new data — informed by existing knowledge │
│ already in the graph │
└──────┬────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────┐
│ 3. PROCESS │
│ │
│ 3a. EXTRACT │
│ Identify entities, events, adjectives and │
│ properties in the new data │
│ │ │
│ ▼ │
│ 3b. LINK │
│ Connect extracted nodes with relationships │
│ — to each other and to existing KG nodes │
│ │ │
│ ▼ │
│ 3c. DEDUPLICATE │
│ Entity resolution — merge duplicates, │
│ reconcile conflicts, unify references │
│ │ │
│ ▼ │
│ 3d. CONSOLIDATE (optional) │
│ High-level graph reasoning to inject or │
│ edit inferred knowledge from the current │
│ state of the graph │
└──────┬────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────┐
│ 4. STORE │
│ Persist as a connected, time-aware graph │
└──────┬────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────┐
│ 5. QUERY │
│ REST · Python SDK · Node SDK · MCP │
└───────────────────────────────────────────────────┘
You bring the data. BrainAPI handles the rest — no custom extraction pipeline required.
Every action in the graph is modeled as a central Event Hub connecting three critical points through directed energy vectors:
┌─────────────────┐
│ EVENT HUB │
│ (Action Node) │
└────────┬────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ACTOR │ │ TARGET │ │ CONTEXT │
│ (Source) │ │ (Recipient) │ │ (Anchor) │
└──────────────┘ └──────────────┘ └──────────────┘
:MADE :TARGETED :OCCURRED_WITHIN
| Vector | Relationship | Description |
|---|---|---|
| Initiation | :MADE / :INITIATED |
Connects the Actor to the Event Hub. Carries quantitative amount data. |
| Targeting | :TARGETED / :DIRECTED_AT |
Connects the Event Hub to the Target (recipient/destination). |
| Context | :OCCURRED_WITHIN |
Connects the Event Hub to a Persistent Anchor (org, location, timeframe). |
This model is what enables BrainAPI to answer questions like "Who organized AI events in London in March 2024?" and return a traceable graph path — not just a similarity score.
BrainAPI transforms unstructured text into rigorous graph schemas through a specialized multi-agent ingestion pipeline. Each agent has a single, clearly-defined responsibility:
| Agent | Role | Responsibility |
|---|---|---|
| 🔍 Scout | Semantic Fact-Finding | Identifies raw entities; distinguishes static properties from dynamic shared anchors |
| 🏛️ Architect | Structural Mapping | Translates facts into the Triangle of Attribution, enforcing vector directionality |
| 🧹 Janitor | Directional Police | Audits graph units, resolves UUIDs, flips inverted relationships violating ontology |
| 🔄 Consolidator | Micro-Swarm Auditor | Performs deduplication and hub merging via collaborative voting (MAKGED) |
This modular design keeps ingestion reliable while maintaining a consistent, conflict-free graph over time. Because each agent has a narrow role, failures are isolated and the pipeline stays auditable end-to-end.
KGLA — Knowledge Graph Enhanced Language Agents
Bridges structured facts and natural language. Extracts multi-hop paths and translates them into human-readable explanations using rich description properties stored in nodes and relationships.
RGP — Relational Graph Perceiver with Temporal Sampling
Applies Temporal Subgraph Sampling to prioritize contextually recent events while enabling "Non-Local Temporal Matching" — finding entities that shared similar challenges during the same chronological windows.
HippoRAG2 — Subgraph Localization
Uses Personalized PageRank to navigate large, disparate data clusters. By traversing abstract "Concept Nodes," bridges disconnected subgraphs to discover structurally distant but semantically related information.
Quantitative Synergy Scoring
Ranks results using a multi-factor formula balancing semantic similarity, temporal recency and quantitative alignment:
Retrieval is based not just on what an entity is, but on the scale and timing of their recorded actions.
Equip your agents and applications with persistent, structured memory — enabling nuanced contextual understanding, continuity across sessions and knowledge grounding over long time horizons.
Example input sequence:
"The user's favorite tool is VSCode.""She also uses GitHub Copilot for code suggestions."
Constructed graph:
(User)-[:MADE]->(Preference Event)-[:TARGETED]->(VSCode)
(User)-[:MADE]->(Usage Event)-[:TARGETED]->(GitHub Copilot)
\
\-[:OCCURRED_WITHIN]->(Code Suggestions)
Queries this unlocks:
- "Which productivity tools does the user rely on for coding?"
- "Recommend AI tools that integrate with VSCode."
Leverage BrainAPI's graph of actions, relationships and temporal contexts to produce precise recommendations — for content, products, collaborators or actions — grounded in real behavioural paths rather than click co-occurrence.
Example input: "Alice bought 'Neural Networks 101' during the Spring AI Symposium."
Constructed graph:
(Alice)-[:MADE {date: "2024-04-12"}]->(Purchase Event)-[:TARGETED]->(Neural Networks 101)
\
\-[:OCCURRED_WITHIN]->(Spring AI Symposium)
Recommendation unlocked:
Bob also attended the Spring AI Symposium — he may be interested in the same books as Alice.
Move beyond keyword search and retrieve information via deep semantic connections, matching intent, events and multi-hop reasoning across documents, tickets and chat history.
Example input: "Tesla presented their latest battery at the 2023 Battery Expo in Berlin."
Constructed graph:
(Tesla)-[:MADE]->(Presentation Event)-[:TARGETED]->(Latest Battery)
\
\-[:OCCURRED_WITHIN]->(2023 Battery Expo)-[:HELD_IN]->(Berlin)
Query: "What products did Tesla present in Berlin in 2023?"
Result: "The latest battery was presented at the 2023 Battery Expo in Berlin."
Identify domain experts, map collaboration paths and surface emerging topics within an organization or community. Answer questions like "Who in our org has worked on Kubernetes and ML pipelines together?"
Feed in customer feedback, usage events and support conversations. BrainAPI extracts patterns, sentiment signals and recurring themes — turning free-form qualitative data into structured, queryable business intelligence.
Connect people, events, documents and timestamps into a coherent investigative graph. Ideal for compliance teams, journalists and researchers who need to trace relationships across large, heterogeneous source corpora.
Step 1 — Ingest
{
"actor": "Emily",
"event": "organized",
"target": "AI Ethics Meetup",
"context": "London",
"date": "2024-03-08"
}Step 2 — Graph representation
(Emily)-[:MADE {date: "2024-03-08"}]->(Organizing Event)-[:TARGETED]->(AI Ethics Meetup)
\
\-[:OCCURRED_WITHIN]->(London)
Step 3 — Retrieve
- Query:
"Who organized AI events in London in March 2024?" - Result:
"Emily organized the 'AI Ethics Meetup' in London on 2024-03-08."
Step 4 — Recommend
- Query:
"What other events has Emily organized, or what similar events are happening in London?" - Result: Past and upcoming meetups in London, related organizers, AI-themed events.
The MCP server runs as a separate process on port 8001 (http://localhost:8001/mcp) to avoid ASGI nesting issues.
- Start the MCP server:
make start-mcp— keep it running. - Open Claude Desktop → Settings → Developer → Edit Config (
claude_desktop_config.json). - Add the following under
mcpServers:
"brainapi-local": {
"command": "/path/to/your/node/version/v22.19.0/bin/npx",
"args": ["-y", "@pyroprompts/mcp-stdio-to-streamable-http-adapter"],
"env": {
"URI": "http://localhost:8001/mcp",
"MCP_NAME": "brainapi-local",
"PATH": "/path/to/your/node/version/v22.19.0/bin:/usr/local/bin:/usr/bin:/bin",
"BEARER_TOKEN": "your-pat-here"
}
}- Ensure URL-based MCP servers are enabled in Claude Desktop settings.
Integrate BrainAPI into your stack using our official client libraries:
| Platform | Package | Status |
|---|---|---|
| Python | lumen_brain |
 |
| Node.js | lumen-brain |
 |
Note: Both SDKs are at version 0.x and under active development. For production use cases, we recommend the REST API directly until v1.0 releases.
You can mix interaction modes freely — for example, ingest data via REST on a schedule and retrieve context via MCP for agent runtimes.
BrainAPI is designed to be extended without forking the core. Teams can publish and install plugins through the BrainAPI CLI to modify ontology, add custom routes, tune agent prompts, or register new MCP tools.
brainapi plugins install @community/crm-entities
brainapi plugins listbrainapi plugins login # authenticate as a publisher
brainapi plugins publish ./my-plugin
brainapi plugins depublish @myorg/my-plugin@1.0.0Plugins can:
- Extend the graph ontology with new entity and relation types
- Add custom REST routes to the BrainAPI server
- Customize agent prompts for domain-specific extraction
- Register new MCP tools for agent runtimes
Browse and publish at the Plugin Registry →
You can mix interaction modes freely — ingest over REST on a schedule, retrieve via MCP inside an agent runtime, or use the SDKs for everything.
Ingest via REST:
curl -X POST https://localhost:3000/ingest \
-H "Authorization: Bearer $BRAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "text", "content": "Emily organized the AI Ethics Meetup in London on 2024-03-08."}'Ingest & query with the Python SDK:
from lumen_brain import BrainAPI
client = BrainAPI(api_key="your-key")
# Ingest
client.ingest.text("Emily organized the AI Ethics Meetup in London on 2024-03-08.")
# Query
result = client.query("Who organized AI events in London in March 2024?")
print(result.answer) # "Emily organized the AI Ethics Meetup on 2024-03-08."
print(result.trace) # Full graph path used to derive the answerIngest with the Node.js SDK:
import { BrainAPI } from "@lumenlabs/lumen-brain";
const client = new BrainAPI({ apiKey: process.env.BRAIN_API_KEY });
await client.ingest.text(
"Emily organized the AI Ethics Meetup in London on 2024-03-08."
);
const result = await client.query(
"Who organized AI events in London in March 2024?"
);
console.log(result.answer);Other tools store your words. BrainAPI builds understanding.
Most AI memory tools store conversation transcripts verbatim. No extraction, no reasoning, no connections. Just text in, text out, closest match returned. That's a search engine dressed up as memory.
BrainAPI extracts what happened, who was involved, when, and how it connects to everything else — then stores that as a traversable, time-aware graph. The result isn't a retrieved chunk. It's a reasoned answer with a provenance trail.
| BrainAPI | Memory Vault (e.g. MemPalace) | |
|---|---|---|
| Storage model | Structured knowledge graph | Verbatim transcripts |
| Extraction | Multi-agent pipeline | None — stores raw text |
| Reasoning | Multi-hop, time-aware queries | Semantic similarity search |
| Answers | Traceable graph paths | Nearest-neighbour scores |
| Grows smarter | ✅ Yes — each ingestion enriches the graph | ❌ No — each doc sits in isolation |
| Deployment | Cloud or self-hosted | Local only |
If you just need to find a sentence you wrote before, use a memory vault. If you need your system to understand what happened and why it matters — use BrainAPI.
▶ Watch: BrainAPI (non-technical) Overview Video
| Resource | Link |
|---|---|
| 📖 Documentation | brainapi.lumen-labs.ai/docs/v2 |
| ⚡ Quick Start Guide | brainapi.lumen-labs.ai/docs/quickstart |
| 🔌 Plugin Registry | registry.brain-api.dev/app |
| 🛠️ REST API Reference | brainapi.lumen-labs.ai/docs/rest |
| 🐍 Python SDK (PyPI) | pypi.org/project/lumen_brain |
| 📦 Node.js SDK (npm) | npmjs.com/package/@lumenlabs/lumen-brain |
| 💬 Community & Support | Discord |
BrainAPI isn't memory. It's understanding at scale — queryable, explainable, and built to grow.
Start building →
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under AGPLv3 + Commons Clause — free for personal, research and non-commercial use. Commercial usage (SaaS, embedding, redistribution) requires an Enterprise License from Lumen Platforms Inc.
See the LICENSE file for full details.
Built with ❤️ by Lumen Labs