🧠 BrainAPI

A cognitive memory layer for AI applications
Transform unstructured data into actionable knowledge with human-inspired retrieval

Use Cases • Overview • Core Philosophy • Agents • SDKs • Quick Start ↗ • API Docs ↗

🏃‍♂️ Local Development & Running BrainAPI2

You can run BrainAPI2 locally in two main ways:

1. Clone or Download the Project

• Clone via Git:

  git clone https://github.com/lumen-labs/brainapi2.git
  cd brainapi2

• Or Download ZIP:
  Download ZIP from GitHub, then unzip and cd into the project folder.

• Install dependencies (recommended with Python 3.11+):

  poetry install

• Use the Makefile commands to start the API & Workers:

  make start-all

---

2. Run Using the Container Image

• Pull the prebuilt container:

  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:

  docker compose -f example-docker-compose.yaml up -d

---

This will bring up all necessary databases and services so data ingestion, querying, and API access all work out-of-the-box.

See the example-docker-compose.yaml file for configuration details, ports, and volumes. For step-by-step instructions, visit the Quick Start Guide.

---

▶ Watch: BrainAPI (non-technical) Overview Video

---

📖 Use Cases

🚀 Example Use Cases

BrainAPI enables advanced knowledge representation and semantic retrieval for a wide range of AI-powered applications. Here are a few core use cases:

---

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:

    {
      "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.

---

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:

    {
      "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."

---

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:

    [
      {
        "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."

---

🧩 Sample: From Unstructured Data to Graph, Then Query & Recommend

Step 1: Ingest Text & JSON

{
  "actor": "Emily",
  "event": "organized",
  "target": "AI Ethics Meetup",
  "context": "London",
  "date": "2024-03-08"
}

Step 2: BrainAPI Graph Representation

(Emily)-[:MADE {date: "2024-03-08"}]->(Organizing Event)-[:TARGETED]->(AI Ethics Meetup)
                                        \
                                         \-[:OCCURRED_WITHIN]->(London)

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.

---

🔺 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:

                    ┌─────────────────┐
                    │   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).

---

🤖 The Agentic Swarm

BrainAPI transforms unstructured text into rigorous graph schemas through a specialized multi-agent pipeline:

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)

---

🔎 Retrieval & Intelligence Layer

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:

$$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.

---

📦 SDKs & Packages

Integrate BrainAPI into your applications using our official client libraries:

Platform	Package	Status
Python	lumen_brain	⚠️ Pre-release
Node.js	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 directly until v1.0 releases.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 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 from Lumen Platforms Inc.

See the LICENSE file for full details.

---

_{Built with ❤️ by Lumen Labs}