# Plugins overview (https://brainapi.lumen-labs.ai/docs/v2/plugins)

> For the complete BrainAPI documentation index, see [llms.txt](https://brainapi.lumen-labs.ai/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL (e.g. https://brainapi.lumen-labs.ai/docs/v2/plugins.md).

Choose, install, inspect, and operate BrainAPI plugins

Plugins add domain behavior without forking BrainAPI core. A plugin can add API routes, lifecycle handlers, MCP tools, prompt changes, first-stage Search retrieval, or second-stage reranking. Because it executes Python inside BrainAPI, install only packages you trust.

## Choose an official plugin

| Plugin | Placement | Choose it when |
| --- | --- | --- |
| [Chatbot](https://brainapi.lumen-labs.ai/docs/v2/chatbot) | API endpoint | You need model inference, streaming, and optional MCP tools. |
| [Chatbot memory](https://brainapi.lumen-labs.ai/docs/v2/chatbot-memory) | Chat memory | Conversations need isolated messages, summaries, and preferences. |
| [Search Rerank](https://brainapi.lumen-labs.ai/docs/v2/search-rerank) | Search second stage | Candidate recall is good but subtle top-result ordering is weak. |
| [Search SPLADE](https://brainapi.lumen-labs.ai/docs/v2/search-splade) | Search first stage | Learned sparse expansion may fix vocabulary mismatch. |
| [Search ColBERT](https://brainapi.lumen-labs.ai/docs/v2/search-colbert) | Search first stage | Token-level term relationships matter. |
| [Features Rec](https://brainapi.lumen-labs.ai/docs/v2/features-rec) | Preference writes | You need train-free interaction and attribute preferences. |
| [RecSys GNN](https://brainapi.lumen-labs.ai/docs/v2/recsys-gnn) | Recommendation backend | Enough interactions exist to evaluate a trained LightGCN model. |

Search retrievers can add candidates through `plugin:<name>` channels. Search rerankers receive only a bounded candidate head and cannot recover a missing passage. Neither type changes `/retrieve/context`.

## Install and inspect

Run commands from the BrainAPI repository root:

```bash
./bin/brainapi install <name> [--version <version>]
./bin/brainapi list
./bin/brainapi info <name>
```

Restart the affected API, worker, or MCP process after installation. The loader scans `PLUGINS_DIR`, validates `plugin.yaml`, installs declared Python dependencies, imports plugins by priority, and calls `register(context)`.

## Manage plugins

```bash
./bin/brainapi update <name>
./bin/brainapi uninstall <name>
./bin/brainapi list --remote
```

The registry defaults to `https://registry.brain-api.dev`. Override it with `PLUGIN_REGISTRY_URL`. Publishing also requires `PLUGIN_PUBLISHER_ID` and `PLUGIN_PUBLISHER_API_KEY`.

## Failure behavior

- An invalid manifest, dependency failure, import error, or registration error marks that plugin failed while BrainAPI reports the loader result.
- An unavailable registry causes CLI operations to fail with exit code `1`.
- Selecting an unknown Search retriever or reranker returns HTTP `400`; BrainAPI does not silently fall back.
- Plugin-local in-memory indexes can be empty after restart; rebuild them according to the plugin's page.

## Build your own

Read [Build a plugin](https://brainapi.lumen-labs.ai/docs/v2/plugins/authoring) for the manifest, registration lifecycle, runtime boundaries, and Search callable contracts. Use [Search levels](https://brainapi.lumen-labs.ai/docs/v2/retrieval/search/levels) before adding a retrieval plugin and [Search recipes](https://brainapi.lumen-labs.ai/docs/v2/retrieval/search/recipes) to compare behavior on real query shapes.