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.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
chore(readme): updated layout
Christian70407d5c1d55
diff --git a/README.md b/README.mdindex 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&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/) |  ⚠️ Pre-release || **Node.js** | [`lumen-brain`](https://www.npmjs.com/package/@lumenlabs/lumen-brain) |  ⚠️ 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)**++---++## 🤝 Contributing1. Fork the repository2. 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.