{"id":35678290,"url":"https://github.com/lumen-labs/brainapi2","last_synced_at":"2026-04-26T22:01:12.956Z","repository":{"id":327121184,"uuid":"1079155251","full_name":"Lumen-Labs/brainapi2","owner":"Lumen-Labs","description":"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.","archived":false,"fork":false,"pushed_at":"2026-04-26T09:52:04.000Z","size":8078,"stargazers_count":103,"open_issues_count":3,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-26T11:20:50.194Z","etag":null,"topics":["ai-agents","ai-memory","knowledge-graph","knowledge-management","knowledge-representation","reccomendation-system"],"latest_commit_sha":null,"homepage":"https://brainapi.lumen-labs.ai/docs/v2","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Lumen-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-19T08:13:08.000Z","updated_at":"2026-04-26T09:26:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Lumen-Labs/brainapi2","commit_stats":null,"previous_names":["lumen-labs/brainapi2"],"tags_count":108,"template":false,"template_full_name":null,"purl":"pkg:github/Lumen-Labs/brainapi2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lumen-Labs%2Fbrainapi2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lumen-Labs%2Fbrainapi2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lumen-Labs%2Fbrainapi2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lumen-Labs%2Fbrainapi2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Lumen-Labs","download_url":"https://codeload.github.com/Lumen-Labs/brainapi2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Lumen-Labs%2Fbrainapi2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32314116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T21:09:39.134Z","status":"ssl_error","status_checked_at":"2026-04-26T21:09:21.240Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-memory","knowledge-graph","knowledge-management","knowledge-representation","reccomendation-system"],"created_at":"2026-01-05T20:04:54.326Z","updated_at":"2026-04-26T22:01:12.948Z","avatar_url":"https://github.com/Lumen-Labs.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/VTngQTaeDf\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join%20Lumen%20Brain-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"/\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-2.11.12--dev-blue?style=for-the-badge\" alt=\"Version\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.11+-green?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-AGPLv3%20%2B%20Commons%20Clause-purple?style=for-the-badge\" alt=\"License\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🧠 BrainAPI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour AI doesn't have memory. It has a database. There's a difference.\u003c/strong\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cem\u003eBrainAPI turns raw text, documents and events into a living knowledge graph —\u003cbr/\u003eone that reasons, connects dots, and grows smarter with every ingestion.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003c!-- \u003ca href=\"https://brainapi.lumen-labs.ai/docs/quickstart\"\u003e\u003cimg src=\"https://img.shields.io/badge/⚡%20Try%20it%20in%2030%20seconds-Get%20Started-FF6B35?style=for-the-badge\" alt=\"Get Started\"/\u003e\u003c/a\u003e --\u003e\n  \u003ca href=\"https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC\"\u003e\u003cimg src=\"https://img.shields.io/badge/▶%20Watch%20Demo-YouTube-FF0000?style=for-the-badge\u0026logo=youtube\u0026logoColor=white\" alt=\"Watch Demo\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://brainapi.lumen-labs.ai/\"\u003eBrainAPI Cloud\u003c/a\u003e •\n  \u003ca href=\"#-what-is-brainapi\"\u003eOverview\u003c/a\u003e •\n  \u003ca href=\"#-core-philosophy-the-triangle-of-attribution\"\u003eCore Philosophy\u003c/a\u003e •\n  \u003ca href=\"#-the-agentic-swarm\"\u003eAgents\u003c/a\u003e •\n  \u003ca href=\"https://brainapi.lumen-labs.ai/docs/v2/installation\"\u003eSDKs\u003c/a\u003e •\n  \u003ca href=\"https://brainapi.lumen-labs.ai/docs/v2\"\u003eAPI Docs ↗\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ca href=\"https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC\"\u003e\n  \u003cimg src=\".github/assets/screen-video.png\" width=\"100%\" alt=\"Watch the video\" /\u003e\n\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://pbs.twimg.com/media/G6jXa2HXsAAJhDO?format=jpg\u0026name=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;\"/\u003e\n\u003c/p\u003e\n\n---\n\n## ⚡ See It in 30 Seconds\n\nFeed BrainAPI one sentence:\n\n```\n\"Emily organized the AI Ethics Meetup in London on March 8, 2024.\"\n```\n\nAsk it a question it was never explicitly told the answer to:\n\n```python\nresult = client.retrieveContext(\"Who organized AI events in London in Q1 2024?\")\n# → \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"\n# → result.triples shows the full graph path used to derive this\n```\n\nThat 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.\n\n\u003e **[▶ Watch the full demo →](https://youtu.be/ECOleTRjl64?si=fBUALoYvsiUl-BPC)**\n\n---\n\n## 🏃 Try It Now\n\n```sh\n# Clone and run in under 2 minutes\ngit clone https://github.com/lumen-labs/brainapi2.git \u0026\u0026 cd brainapi2\npoetry install \u0026\u0026 make start-all\n```\n\nOr with Docker (recommended):\n\n```sh\ndocker compose -f example-docker-compose.yaml up -d\n```\n\nThen ingest your first data point:\n\n```sh\ncurl -X POST http://localhost:3000/ingest \\\n  -H \"Authorization: Bearer $BRAIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\": \"text\", \"content\": \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"}'\n```\n\nFull walkthrough → [Quick Start Guide](https://brainapi.lumen-labs.ai/docs/quickstart)\n\n---\n\n## 📖 What is BrainAPI?\n\nBrainAPI 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.\n\n**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.\n\n\u003e **Why Event-Centric?**  \n\u003e 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_.\n\n### When to use BrainAPI\n\n✅ **BrainAPI excels when you need:**\n\n- Structured knowledge extracted from messy, constantly-changing data sources\n- Long-term AI memory that persists across sessions, users and documents\n- Explainable relationships behind recommendations — not just similarity scores\n- Multi-hop queries over temporal data with traceable provenance\n\n⚠️ **It may be overkill if:**\n\n- Your data fits a fixed schema you fully control\n- A single SQL query or simple CRUD operations solve the problem\n- You need purely local, offline-only storage with zero extraction\n\n---\n\n## ⚙️ How It Works: The Ingestion Pipeline\n\nEvery piece of data you feed BrainAPI flows through a five-step pipeline before it becomes queryable knowledge:\n\n```\n  Raw data (files, text, APIs, event streams)\n          │\n          ▼\n  ┌───────────────────────────────────────────────────┐\n  │  1. INGEST                                        │\n  │     Accept documents, plain text, structured      │\n  │     events                                        │\n  └──────┬────────────────────────────────────────────┘\n         │\n         ▼\n  ┌───────────────────────────────────────────────────┐\n  │  2. ANNOTATE                                      │\n  │     Save observations, notes and annotations on   │\n  │     the new data — informed by existing knowledge │\n  │     already in the graph                          │\n  └──────┬────────────────────────────────────────────┘\n         │\n         ▼\n  ┌───────────────────────────────────────────────────┐\n  │  3. PROCESS                                       │\n  │                                                   │\n  │  3a. EXTRACT                                      │\n  │      Identify entities, events, adjectives and    │\n  │      properties in the new data                   │\n  │                 │                                 │\n  │                 ▼                                 │\n  │  3b. LINK                                         │\n  │      Connect extracted nodes with relationships   │\n  │      — to each other and to existing KG nodes     │\n  │                 │                                 │\n  │                 ▼                                 │\n  │  3c. DEDUPLICATE                                  │\n  │      Entity resolution — merge duplicates,        │\n  │      reconcile conflicts, unify references        │\n  │                 │                                 │\n  │                 ▼                                 │\n  │  3d. CONSOLIDATE  (optional)                      │\n  │      High-level graph reasoning to inject or      │\n  │      edit inferred knowledge from the current     │\n  │      state of the graph                           │\n  └──────┬────────────────────────────────────────────┘\n         │\n         ▼\n  ┌───────────────────────────────────────────────────┐\n  │  4. STORE                                         │\n  │     Persist as a connected, time-aware graph      │\n  └──────┬────────────────────────────────────────────┘\n         │\n         ▼\n  ┌───────────────────────────────────────────────────┐\n  │  5. QUERY                                         │\n  │     REST · Python SDK · Node SDK · MCP            │\n  └───────────────────────────────────────────────────┘\n```\n\nYou bring the data. BrainAPI handles the rest — no custom extraction pipeline required.\n\n---\n\n## 🔺 Core Philosophy: The Triangle of Attribution\n\nEvery action in the graph is modeled as a central **Event Hub** connecting three critical points through directed energy vectors:\n\n```\n                    ┌─────────────────┐\n                    │   EVENT HUB     │\n                    │  (Action Node)  │\n                    └────────┬────────┘\n                             │\n           ┌─────────────────┼─────────────────┐\n           │                 │                 │\n           ▼                 ▼                 ▼\n    ┌──────────────┐  ┌──────────────┐  ┌──────────────┐\n    │    ACTOR     │  │    TARGET    │  │   CONTEXT    │\n    │   (Source)   │  │ (Recipient)  │  │  (Anchor)    │\n    └──────────────┘  └──────────────┘  └──────────────┘\n         :MADE            :TARGETED       :OCCURRED_WITHIN\n```\n\n| Vector         | Relationship                 | Description                                                                       |\n| -------------- | ---------------------------- | --------------------------------------------------------------------------------- |\n| **Initiation** | `:MADE` / `:INITIATED`       | Connects the **Actor** to the **Event Hub**. Carries quantitative `amount` data.  |\n| **Targeting**  | `:TARGETED` / `:DIRECTED_AT` | Connects the **Event Hub** to the **Target** (recipient/destination).             |\n| **Context**    | `:OCCURRED_WITHIN`           | Connects the **Event Hub** to a **Persistent Anchor** (org, location, timeframe). |\n\nThis 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.\n\n---\n\n## 🤖 The Agentic Swarm\n\nBrainAPI transforms unstructured text into rigorous graph schemas through a specialized **multi-agent ingestion pipeline**. Each agent has a single, clearly-defined responsibility:\n\n| Agent               | Role                  | Responsibility                                                                       |\n| :------------------ | :-------------------- | :----------------------------------------------------------------------------------- |\n| 🔍 **Scout**        | Semantic Fact-Finding | Identifies raw entities; distinguishes static properties from dynamic shared anchors |\n| 🏛️ **Architect**    | Structural Mapping    | Translates facts into the Triangle of Attribution, enforcing vector directionality   |\n| 🧹 **Janitor**      | Directional Police    | Audits graph units, resolves UUIDs, flips inverted relationships violating ontology  |\n| 🔄 **Consolidator** | Micro-Swarm Auditor   | Performs deduplication and hub merging via collaborative voting (MAKGED)             |\n\nThis 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.\n\n---\n\n## 🔎 Retrieval \u0026 Intelligence Layer\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eKGLA — Knowledge Graph Enhanced Language Agents\u003c/strong\u003e\u003c/summary\u003e\n\nBridges 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRGP — Relational Graph Perceiver with Temporal Sampling\u003c/strong\u003e\u003c/summary\u003e\n\nApplies **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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHippoRAG2 — Subgraph Localization\u003c/strong\u003e\u003c/summary\u003e\n\nUses **Personalized PageRank** to navigate large, disparate data clusters. By traversing abstract \"Concept Nodes,\" bridges disconnected subgraphs to discover structurally distant but semantically related information.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQuantitative Synergy Scoring\u003c/strong\u003e\u003c/summary\u003e\n\nRanks results using a multi-factor formula balancing semantic similarity, temporal recency and quantitative alignment:\n\n$$Score = (Similarity \\times W_1) + (Recency \\times W_2) + (PropertyAlignment)$$\n\nRetrieval is based not just on _what_ an entity is, but on the _scale_ and _timing_ of their recorded actions.\n\n\u003c/details\u003e\n\n---\n\n## 🚀 Use Cases\n\n### 1. AI Memory for Agents \u0026 Apps\n\nEquip your agents and applications with persistent, structured memory — enabling nuanced contextual understanding, continuity across sessions and knowledge grounding over long time horizons.\n\n**Example input sequence:**\n\n1. `\"The user's favorite tool is VSCode.\"`\n2. `\"She also uses GitHub Copilot for code suggestions.\"`\n\n**Constructed graph:**\n\n```\n(User)-[:MADE]-\u003e(Preference Event)-[:TARGETED]-\u003e(VSCode)\n(User)-[:MADE]-\u003e(Usage Event)-[:TARGETED]-\u003e(GitHub Copilot)\n                                  \\\n                                   \\-[:OCCURRED_WITHIN]-\u003e(Code Suggestions)\n```\n\n**Queries this unlocks:**\n\n- _\"Which productivity tools does the user rely on for coding?\"_\n- _\"Recommend AI tools that integrate with VSCode.\"_\n\n---\n\n### 2. Relationship-Driven Recommendation Systems\n\nLeverage 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.\n\n**Example input:** `\"Alice bought 'Neural Networks 101' during the Spring AI Symposium.\"`\n\n**Constructed graph:**\n\n```\n(Alice)-[:MADE {date: \"2024-04-12\"}]-\u003e(Purchase Event)-[:TARGETED]-\u003e(Neural Networks 101)\n                                      \\\n                                       \\-[:OCCURRED_WITHIN]-\u003e(Spring AI Symposium)\n```\n\n**Recommendation unlocked:**  \n_Bob also attended the Spring AI Symposium — he may be interested in the same books as Alice._\n\n---\n\n### 3. Semantic Knowledge Search\n\nMove beyond keyword search and retrieve information via deep semantic connections, matching intent, events and multi-hop reasoning across documents, tickets and chat history.\n\n**Example input:** `\"Tesla presented their latest battery at the 2023 Battery Expo in Berlin.\"`\n\n**Constructed graph:**\n\n```\n(Tesla)-[:MADE]-\u003e(Presentation Event)-[:TARGETED]-\u003e(Latest Battery)\n                                    \\\n                                     \\-[:OCCURRED_WITHIN]-\u003e(2023 Battery Expo)-[:HELD_IN]-\u003e(Berlin)\n```\n\n**Query:** `\"What products did Tesla present in Berlin in 2023?\"`  \n**Result:** `\"The latest battery was presented at the 2023 Battery Expo in Berlin.\"`\n\n---\n\n### 4. Community \u0026 Expert Mapping\n\nIdentify 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?\"_\n\n### 5. Business Intelligence from Qualitative Data\n\nFeed 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.\n\n### 6. Investigation \u0026 Compliance Workflows\n\nConnect 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.\n\n---\n\n### End-to-End Example: From Text to Graph to Answer\n\n**Step 1 — Ingest**\n\n```json\n{\n  \"actor\": \"Emily\",\n  \"event\": \"organized\",\n  \"target\": \"AI Ethics Meetup\",\n  \"context\": \"London\",\n  \"date\": \"2024-03-08\"\n}\n```\n\n**Step 2 — Graph representation**\n\n```\n(Emily)-[:MADE {date: \"2024-03-08\"}]-\u003e(Organizing Event)-[:TARGETED]-\u003e(AI Ethics Meetup)\n                                        \\\n                                         \\-[:OCCURRED_WITHIN]-\u003e(London)\n```\n\n**Step 3 — Retrieve**\n\n- Query: `\"Who organized AI events in London in March 2024?\"`\n- Result: `\"Emily organized the 'AI Ethics Meetup' in London on 2024-03-08.\"`\n\n**Step 4 — Recommend**\n\n- Query: `\"What other events has Emily organized, or what similar events are happening in London?\"`\n- Result: Past and upcoming meetups in London, related organizers, AI-themed events.\n\n---\n\n## 🔌 Connecting Claude Desktop via MCP\n\nThe MCP server runs as a separate process on port **8001** (`http://localhost:8001/mcp`) to avoid ASGI nesting issues.\n\n1. Start the MCP server: `make start-mcp` — keep it running.\n2. Open Claude Desktop → **Settings → Developer → Edit Config** (`claude_desktop_config.json`).\n3. Add the following under `mcpServers`:\n\n```json\n\"brainapi-local\": {\n  \"command\": \"/path/to/your/node/version/v22.19.0/bin/npx\",\n  \"args\": [\"-y\", \"@pyroprompts/mcp-stdio-to-streamable-http-adapter\"],\n  \"env\": {\n    \"URI\": \"http://localhost:8001/mcp\",\n    \"MCP_NAME\": \"brainapi-local\",\n    \"PATH\": \"/path/to/your/node/version/v22.19.0/bin:/usr/local/bin:/usr/bin:/bin\",\n    \"BEARER_TOKEN\": \"your-pat-here\"\n  }\n}\n```\n\n4. Ensure URL-based MCP servers are enabled in Claude Desktop settings.\n\n---\n\n## 📦 SDKs \u0026 Packages\n\nIntegrate BrainAPI into your stack using our official client libraries:\n\n| Platform    | Package                                                               | Status                                                                                    |\n| ----------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |\n| **Python**  | [`lumen_brain`](https://pypi.org/project/lumen_brain/)                | ![PyPI](https://img.shields.io/pypi/v/lumen_brain?label=v0.x\u0026color=orange) ⚠️ Pre-release |\n| **Node.js** | [`lumen-brain`](https://www.npmjs.com/package/@lumenlabs/lumen-brain) | ![npm](https://img.shields.io/npm/v/lumen-brain?label=v0.x\u0026color=orange) ⚠️ Pre-release   |\n\n\u003e **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.\n\nYou can mix interaction modes freely — for example, ingest data via REST on a schedule and retrieve context via MCP for agent runtimes.\n\n---\n\n## 🧩 Plugin Registry \u0026 Extensibility\n\nBrainAPI 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.\n\n### Install a plugin\n\n```sh\nbrainapi plugins install @community/crm-entities\nbrainapi plugins list\n```\n\n### Publish your own\n\n```sh\nbrainapi plugins login          # authenticate as a publisher\nbrainapi plugins publish ./my-plugin\nbrainapi plugins depublish @myorg/my-plugin@1.0.0\n```\n\nPlugins can:\n\n- Extend the graph ontology with new entity and relation types\n- Add custom REST routes to the BrainAPI server\n- Customize agent prompts for domain-specific extraction\n- Register new MCP tools for agent runtimes\n\nBrowse and publish at the [Plugin Registry →](https://registry.brain-api.dev/app)\n\n---\n\n## 💻 SDK Quick Examples\n\nYou can mix interaction modes freely — ingest over REST on a schedule, retrieve via MCP inside an agent runtime, or use the SDKs for everything.\n\n**Ingest via REST:**\n\n```sh\ncurl -X POST https://localhost:3000/ingest \\\n  -H \"Authorization: Bearer $BRAIN_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"type\": \"text\", \"content\": \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"}'\n```\n\n**Ingest \u0026 query with the Python SDK:**\n\n```python\nfrom lumen_brain import BrainAPI\n\nclient = BrainAPI(api_key=\"your-key\")\n\n# Ingest\nclient.ingest.text(\"Emily organized the AI Ethics Meetup in London on 2024-03-08.\")\n\n# Query\nresult = client.query(\"Who organized AI events in London in March 2024?\")\nprint(result.answer)   # \"Emily organized the AI Ethics Meetup on 2024-03-08.\"\nprint(result.trace)    # Full graph path used to derive the answer\n```\n\n**Ingest with the Node.js SDK:**\n\n```typescript\nimport { BrainAPI } from \"@lumenlabs/lumen-brain\";\n\nconst client = new BrainAPI({ apiKey: process.env.BRAIN_API_KEY });\nawait client.ingest.text(\n  \"Emily organized the AI Ethics Meetup in London on 2024-03-08.\"\n);\nconst result = await client.query(\n  \"Who organized AI events in London in March 2024?\"\n);\nconsole.log(result.answer);\n```\n\n---\n\n## ⚖️ BrainAPI vs. Memory Vaults\n\n\u003e **Other tools store your words. BrainAPI builds understanding.**\n\nMost 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.\n\nBrainAPI 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.\n\n|                   | BrainAPI                                   | Memory Vault (e.g. MemPalace)      |\n| ----------------- | ------------------------------------------ | ---------------------------------- |\n| **Storage model** | Structured knowledge graph                 | Verbatim transcripts               |\n| **Extraction**    | Multi-agent pipeline                       | None — stores raw text             |\n| **Reasoning**     | Multi-hop, time-aware queries              | Semantic similarity search         |\n| **Answers**       | Traceable graph paths                      | Nearest-neighbour scores           |\n| **Grows smarter** | ✅ Yes — each ingestion enriches the graph | ❌ No — each doc sits in isolation |\n| **Deployment**    | Cloud or self-hosted                       | Local only                         |\n\nIf 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.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.youtube.com/watch?v=wWwTFU5-qeA\"\u003e\n    \u003cimg 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;\"/\u003e\n    \u003cbr/\u003e\n    \u003cstrong\u003e▶ Watch: BrainAPI (non-technical) Overview Video\u003c/strong\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 📚 Resources\n\n| Resource               | Link                                                                                             |\n| ---------------------- | ------------------------------------------------------------------------------------------------ |\n| 📖 Documentation       | [brainapi.lumen-labs.ai/docs/v2](https://brainapi.lumen-labs.ai/docs/v2)                         |\n| ⚡ Quick Start Guide   | [brainapi.lumen-labs.ai/docs/quickstart](https://brainapi.lumen-labs.ai/docs/quickstart)         |\n| 🔌 Plugin Registry     | [registry.brain-api.dev/app](https://registry.brain-api.dev/app)                                 |\n| 🛠️ REST API Reference  | [brainapi.lumen-labs.ai/docs/rest](https://brainapi.lumen-labs.ai/docs/rest)                     |\n| 🐍 Python SDK (PyPI)   | [pypi.org/project/lumen_brain](https://pypi.org/project/lumen_brain/)                            |\n| 📦 Node.js SDK (npm)   | [npmjs.com/package/@lumenlabs/lumen-brain](https://www.npmjs.com/package/@lumenlabs/lumen-brain) |\n| 💬 Community \u0026 Support | [Discord](https://discord.gg/VTngQTaeDf)                                                         |\n\n---\n\n\u003e BrainAPI isn't memory. It's understanding at scale — queryable, explainable, and built to grow.  \n\u003e **[Start building →](https://brainapi.lumen-labs.ai/docs/quickstart)**\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis 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.\n\nSee the [LICENSE](LICENSE) file for full details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/lumen-labs\"\u003eLumen Labs\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumen-labs%2Fbrainapi2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flumen-labs%2Fbrainapi2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flumen-labs%2Fbrainapi2/lists"}