Skip to content

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.

chore(readme): updated layout

Christian70407d5c1d55
diff --git a/README.md b/README.md
index e5029fc..5a21c8e 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,14 @@
<h1 align="center">🧠 BrainAPI</h1>
<p align="center">
- <strong>A cognitive reasoning memory layer for modern applications</strong>
- <br/>
- <em>Transform unstructured data into actionable knowledge with human-inspired retrieval</em>
+ <strong>Your AI doesn't have memory. It has a database. There's a difference.</strong>
+ <br/><br/>
+ <em>BrainAPI turns raw text, documents and events into a living knowledge graph —<br/>one that reasons, connects dots, and grows smarter with every ingestion.</em>
+</p>
+
+<p align="center">
+ <!-- <a href="https://brainapi.lumen-labs.ai/docs/quickstart"><img src="https://img.shields.io/badge/⚡%20Try%20it%20in%2030%20seconds-Get%20Started-FF6B35?style=for-the-badge" alt="Get Started"/></a> -->
+ <a href="https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC"><img src="https://img.shields.io/badge/▶%20Watch%20Demo-YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch Demo"/></a>
</p>
<p align="center">
@@ -27,250 +32,153 @@
</a>
<p align="center">
- <img src="https://pbs.twimg.com/media/G6jXa2HXsAAJhDO?format=jpg&amp;name=4096x4096" alt="BrainAPI Concept Art" width="1000" style="border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
+ <img src="https://pbs.twimg.com/media/G6jXa2HXsAAJhDO?format=jpg&name=4096x4096" alt="BrainAPI Concept Art" width="1000" style="border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
</p>
-## 🏃‍♂️ Local Development & Running BrainAPI2
-
-You can run **BrainAPI2 locally** in two main ways:
-
-### 1. Clone or Download the Project
-
-- **Clone via Git:**
- ```sh
- git clone https://github.com/lumen-labs/brainapi2.git
- cd brainapi2
- ```
-- **Or Download ZIP:**
- [Download ZIP from GitHub](https://github.com/lumen-labs/brainapi2/archive/refs/heads/main.zip), then unzip and `cd` into the project folder.
-
-- **Install dependencies (recommended with Python 3.11+):**
-
- ```sh
- poetry install
- ```
-
-- **Use the Makefile commands to start the API & Workers:**
-
- ```sh
- make start-all
- ```
+---
-#### Connecting Claude Desktop to the MCP server
+## ⚡ See It in 30 Seconds
-The MCP server runs as a **separate process** on port **8001** (Streamable HTTP at `http://localhost:8001/mcp`) to avoid ASGI nesting issues. Use the stdio adapter so Claude Desktop can connect by URL.
+Feed BrainAPI one sentence:
-1. Start the MCP server (in addition to the API if you need it): `make start-mcp`. Keep it running.
-2. Open Claude Desktop **Settings → Developer → Edit Config** (edit `claude_desktop_config.json`).
-3. For the **brainapi-local** (or your chosen name) server, add it under `mcpServers`. Example:
+```
+"Emily organized the AI Ethics Meetup in London on March 8, 2024."
+```
- ```json
- "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"
- }
- }
- ```
+Ask it a question it was never explicitly told the answer to:
-4. Ensure the MCP server is running (`make start-mcp`) and that URL-based MCP servers are enabled in Claude Desktop.
+```python
+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.retrieveContext shows the full graph path used to derive this
+```
-### 2. Run Using the Container Image
+That 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.
-- **Pull the prebuilt container:**
+> **[▶ Watch the full demo →](https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC)**
- ```sh
- docker pull ghcr.io/lumen-labs/brainapi:latest
- ```
+---
-- **Start all required services and the BrainAPI container:**
- Use the included `example-docker-compose.yaml` to start up BrainAPI and all dependencies together:
+## 🏃 Try It Now
- ```sh
- docker compose -f example-docker-compose.yaml up -d
- ```
+```sh
+# Clone and run in under 2 minutes
+git clone https://github.com/lumen-labs/brainapi2.git && cd brainapi2
+poetry install && make start-all
+```
----
+Or with Docker (recommended):
-> This will bring up all necessary databases and services so data ingestion, querying, and API access all work out-of-the-box.
+```sh
+docker compose -f example-docker-compose.yaml up -d
+```
-See the [`example-docker-compose.yaml`](./example-docker-compose.yaml) file for configuration details, ports, and volumes.
-For step-by-step instructions, visit the [Quick Start Guide](https://brainapi.lumen-labs.ai/docs/quickstart).
+Then ingest your first data point:
----
+```sh
+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."}'
+```
-<p align="center">
- <a href="https://www.youtube.com/watch?v=wWwTFU5-qeA">
- <img src="https://img.youtube.com/vi/wWwTFU5-qeA/0.jpg" alt="BrainAPI Overview Video" width="100%" style="aspect-ratio: 16/9;object-fit: cover;border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
- <br/>
- <strong>▶ Watch: BrainAPI (non-technical) Overview Video</strong>
- </a>
-</p>
+Full walkthrough → [Quick Start Guide](https://brainapi.lumen-labs.ai/docs/quickstart)
---
-## 📖 Use Cases
+## 📖 What is BrainAPI?
-### 🚀 Example Use Cases
+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.
-BrainAPI enables advanced knowledge representation and semantic retrieval for a wide range of AI-powered applications. Here are a few core use cases:
+**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_.
-#### 1. **Recommendation Systems**
-
-Leverage BrainAPI's graph of actions, relationships, and temporal contexts to produce precise recommendations for users, whether for content, products, collaborators, or actions.
-
-- **How:** By tracing _events_ such as purchases, likes, shares, or user journeys, BrainAPI can recommend similar or complementary items considering social influence, context, and personalized behavioural paths.
-- **Example:**
- - _Text Input:_
- `"Alice bought a book called 'Neural Networks 101' during the Spring AI Symposium."`
- - _Ingested JSON:_
- ```json
- {
- "actor": "Alice",
- "event": "purchased",
- "target": "Neural Networks 101",
- "context": "Spring AI Symposium"
- }
- ```
- - _Constructed Graph:_
- ```
- (Alice)-[:MADE {date: "2024-04-12"}]->(Purchase Event)-[:TARGETED]->(Neural Networks 101)
- \
- \-[:OCCURRED_WITHIN]->(Spring AI Symposium)
- ```
- - _Recommendation Example:_
- _Bob also attended the Spring AI Symposium and might be interested in the same books as Alice._
+### When to use BrainAPI
----
+✅ **BrainAPI excels when you need:**
-#### 2. **Search Engines**
-
-Move beyond keyword search and retrieve information via deep semantic connections, matching intent, events, and multi-hop reasoning.
-
-- **How:** The event-centric model lets you ask nuanced questions that traditional full-text search can't answer—enabling contextual, temporal, and relational queries.
-- **Example:**
- - _Text Input:_
- `"Tesla presented their latest battery at the 2023 Battery Expo in Berlin."`
- - _Ingested JSON:_
- ```json
- {
- "actor": "Tesla",
- "event": "presented",
- "target": "latest battery",
- "context": {
- "event": "2023 Battery Expo",
- "location": "Berlin"
- }
- }
- ```
- - _Constructed Graph:_
- ```
- (Tesla)-[:MADE]->(Presentation Event)-[:TARGETED]->(Latest Battery)
- \
- \-[:OCCURRED_WITHIN]->(2023 Battery Expo)-[:HELD_IN]->(Berlin)
- ```
- - _Retrieval Example:_
- _query: "What products did Tesla present in Berlin in 2023?"_<br>
- _result: "The latest battery was presented at the 2023 Battery Expo in Berlin."_
+- 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
----
+⚠️ **It may be overkill if:**
-#### 3. **AI Memory for AI-Apps & Agents**
-
-Equip your agents and apps with persistent, structured memory, allowing nuanced contextual understanding, continuity, and knowledge grounding.
-
-- **How:** Store, retrieve, and update multi-turn conversations, observations, and learned facts as an evolving graph, empowering agents to reason, plan, and act over long time horizons.
-- **Example:**
- - _Text Input Sequence:_
- 1. `"The user's favorite tool is VSCode."`
- 2. `"She also uses GitHub Copilot for code suggestions."`
- - _Ingested JSON:_
- ```json
- [
- {
- "actor": "User",
- "event": "prefers",
- "target": "VSCode"
- },
- {
- "actor": "User",
- "event": "uses",
- "target": "GitHub Copilot",
- "context": "code suggestions"
- }
- ]
- ```
- - _Constructed Graph:_
- ```
- (User)-[:MADE]->(Preference Event)-[:TARGETED]->(VSCode)
- (User)-[:MADE]->(Usage Event)-[:TARGETED]->(GitHub Copilot)
- \
- \-[:OCCURRED_WITHIN]->(Code Suggestions)
- ```
- - _Retrieval + Recommendation Query:_
- - _"Which productivity tools does the user rely on for coding?"_
- - _"Recommend AI tools that integrate with VSCode."_
+- 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
---
-### 🧩 **Sample: From Unstructured Data to Graph, Then Query & Recommend**
+## ⚙️ How It Works: The Ingestion Pipeline
-#### **Step 1: Ingest Text & JSON**
-
-```json
-{
- "actor": "Emily",
- "event": "organized",
- "target": "AI Ethics Meetup",
- "context": "London",
- "date": "2024-03-08"
-}
-```
-
-#### **Step 2: BrainAPI Graph Representation**
+Every piece of data you feed BrainAPI flows through a five-step pipeline before it becomes queryable knowledge:
```
-(Emily)-[:MADE {date: "2024-03-08"}]->(Organizing Event)-[:TARGETED]->(AI Ethics Meetup)
- \
- \-[:OCCURRED_WITHIN]->(London)
+ 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 │
+ └───────────────────────────────────────────────────┘
```
-#### **Step 3: Retrieve Information**
-
-- _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: Generate Recommendations**
-
-- _Query_: `"What other events has Emily organized, or what similar events are happening in London?"`
-- _Result_:
- - List of past/future meetups in London, relevant organizers, or AI-themed events.
-
----
-
-BrainAPI makes it easy to convert unstructured information into actionable, queryable, and recommendable knowledge — powering the next generation of memory-augmented AI applications.
-
----
-
-## 📖 What is BrainAPI?
-
-BrainAPI is an advanced **Knowledge Graph Ecosystem** designed for high-precision semantic reasoning and relational analysis across multi-domain datasets. Unlike traditional graphs that rely on static entity-to-entity links, BrainAPI uses a dynamic **Event-Centric architecture** — treating actions, interactions, and state changes as central nodes to capture multi-dimensional context, temporal tracking, and complex multi-hop reasoning.
-
-> **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_.
+You bring the data. BrainAPI handles the rest — no custom extraction pipeline required.
---
## 🔺 Core Philosophy: The Triangle of Attribution
-Every action in the graph is modeled as a central hub connecting three critical points through directed energy vectors:
+Every action in the graph is modeled as a central **Event Hub** connecting three critical points through directed energy vectors:
```
┌─────────────────┐
@@ -294,19 +202,23 @@ Every action in the graph is modeled as a central hub connecting three critical
| **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.
+
---
## 🤖 The Agentic Swarm
-BrainAPI transforms unstructured text into rigorous graph schemas through a specialized multi-agent pipeline:
+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 |
+| 🔍 **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.
+
---
## 🔎 Retrieval & Intelligence Layer
@@ -335,32 +247,296 @@ Uses **Personalized PageRank** to navigate large, disparate data clusters. By tr
<details>
<summary><strong>Quantitative Synergy Scoring</strong></summary>
-Ranks results using a multi-factor formula balancing semantic similarity, temporal recency, and quantitative alignment:
+Ranks results using a multi-factor formula balancing semantic similarity, temporal recency and quantitative alignment:
$$Score = (Similarity \times W_1) + (Recency \times W_2) + (PropertyAlignment)$$
-Retrieval based not just on _what_ an entity is, but on the _scale_ and _timing_ of their recorded actions.
+Retrieval is based not just on _what_ an entity is, but on the _scale_ and _timing_ of their recorded actions.
</details>
---
+## 🚀 Use Cases
+
+### 1. AI Memory for Agents & Apps
+
+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:**
+
+1. `"The user's favorite tool is VSCode."`
+2. `"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."_
+
+---
+
+### 2. Relationship-Driven Recommendation Systems
+
+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._
+
+---
+
+### 3. Semantic Knowledge Search
+
+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."`
+
+---
+
+### 4. Community & Expert Mapping
+
+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?"_
+
+### 5. Business Intelligence from Qualitative Data
+
+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.
+
+### 6. Investigation & Compliance Workflows
+
+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.
+
+---
+
+### End-to-End Example: From Text to Graph to Answer
+
+**Step 1 — Ingest**
+
+```json
+{
+ "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.
+
+---
+
+## 🔌 Connecting Claude Desktop via MCP
+
+The MCP server runs as a separate process on port **8001** (`http://localhost:8001/mcp`) to avoid ASGI nesting issues.
+
+1. Start the MCP server: `make start-mcp` — keep it running.
+2. Open Claude Desktop → **Settings → Developer → Edit Config** (`claude_desktop_config.json`).
+3. Add the following under `mcpServers`:
+
+```json
+"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"
+ }
+}
+```
+
+4. Ensure URL-based MCP servers are enabled in Claude Desktop settings.
+
+---
+
## 📦 SDKs & Packages
-Integrate BrainAPI into your applications using our official client libraries:
+Integrate BrainAPI into your stack using our official client libraries:
| Platform | Package | Status |
| ----------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Python** | [`lumen_brain`](https://pypi.org/project/lumen_brain/) | ![PyPI](https://img.shields.io/pypi/v/lumen_brain?label=v0.x&color=orange) ⚠️ Pre-release |
| **Node.js** | [`lumen-brain`](https://www.npmjs.com/package/@lumenlabs/lumen-brain) | ![npm](https://img.shields.io/npm/v/lumen-brain?label=v0.x&color=orange) ⚠️ Pre-release |
-> **Note:** Both SDKs are currently at version 0.x and under active development. For production use cases, we recommend using the [REST API](https://brainapi.lumen-labs.ai/docs/rest) directly until v1.0 releases.
+> **Note:** Both SDKs are at version 0.x and under active development. For production use cases, we recommend the [REST API](https://brainapi.lumen-labs.ai/docs/rest) 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.
---
-## 🤝 Contributing
+## 🧩 Plugin Registry & Extensibility
-<!-- Add contributing guidelines -->
+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.
+
+### Install a plugin
+
+```sh
+brainapi plugins install @community/crm-entities
+brainapi plugins list
+```
+
+### Publish your own
+
+```sh
+brainapi plugins login # authenticate as a publisher
+brainapi plugins publish ./my-plugin
+brainapi plugins depublish @myorg/[email protected]
+```
+
+Plugins 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 →](https://registry.brain-api.dev/app)
+
+---
+
+## 💻 SDK Quick Examples
+
+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:**
+
+```sh
+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:**
+
+```python
+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 answer
+```
+
+**Ingest with the Node.js SDK:**
+
+```typescript
+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);
+```
+
+---
+
+## ⚖️ BrainAPI vs. Memory Vaults
+
+> **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.
+
+---
+
+<p align="center">
+ <a href="https://www.youtube.com/watch?v=wWwTFU5-qeA">
+ <img src="https://img.youtube.com/vi/wWwTFU5-qeA/0.jpg" alt="BrainAPI Overview Video" width="100%" style="aspect-ratio: 16/9;object-fit: cover;border-radius:4px;box-shadow:0 2px 12px rgba(0,0,0,0.09);margin-bottom:16px;"/>
+ <br/>
+ <strong>▶ Watch: BrainAPI (non-technical) Overview Video</strong>
+ </a>
+</p>
+
+---
+
+## 📚 Resources
+
+| Resource | Link |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| 📖 Documentation | [brainapi.lumen-labs.ai/docs/v2](https://brainapi.lumen-labs.ai/docs/v2) |
+| ⚡ Quick Start Guide | [brainapi.lumen-labs.ai/docs/quickstart](https://brainapi.lumen-labs.ai/docs/quickstart) |
+| 🔌 Plugin Registry | [registry.brain-api.dev/app](https://registry.brain-api.dev/app) |
+| 🛠️ REST API Reference | [brainapi.lumen-labs.ai/docs/rest](https://brainapi.lumen-labs.ai/docs/rest) |
+| 🐍 Python SDK (PyPI) | [pypi.org/project/lumen_brain](https://pypi.org/project/lumen_brain/) |
+| 📦 Node.js SDK (npm) | [npmjs.com/package/@lumenlabs/lumen-brain](https://www.npmjs.com/package/@lumenlabs/lumen-brain) |
+| 💬 Community & Support | [Discord](https://discord.gg/VTngQTaeDf) |
+
+---
+
+> BrainAPI isn't memory. It's understanding at scale — queryable, explainable, and built to grow.
+> **[Start building →](https://brainapi.lumen-labs.ai/docs/quickstart)**
+
+---
+
+## 🤝 Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
@@ -372,7 +548,7 @@ Integrate BrainAPI into your applications using our official client libraries:
## 📄 License
-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](mailto:[email protected]) from Lumen Platforms Inc.
+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](mailto:[email protected]) from Lumen Platforms Inc.
See the [LICENSE](LICENSE) file for full details.