diff --git a/README.md b/README.md
index e5029fc..5a21c8e 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,14 @@
π§ BrainAPI
- A cognitive reasoning memory layer for modern applications
-
- Transform unstructured data into actionable knowledge with human-inspired retrieval
+ 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.
+
+
+
+
+ 
@@ -27,250 +32,153 @@
- 
+
-## πββοΈ 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."}'
+```
-
-
- 
-
- βΆ Watch: BrainAPI (non-technical) Overview Video
-
-
+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?"_
- _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
Quantitative Synergy Scoring
-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.
---
+## π 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
-
+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/my-plugin@1.0.0
+```
+
+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.
+
+---
+
+
+
+
+
+ βΆ Watch: BrainAPI (non-technical) Overview Video
+
+
+
+---
+
+## π 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:hello@lumen-labs.ai) 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:hello@lumen-labs.ai) from Lumen Platforms Inc.
See the [LICENSE](LICENSE) file for full details.