Plugins overview

For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.

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	API endpoint	You need model inference, streaming, and optional MCP tools.
Chatbot memory	Chat memory	Conversations need isolated messages, summaries, and preferences.
Search Rerank	Search second stage	Candidate recall is good but subtle top-result ordering is weak.
Search SPLADE	Search first stage	Learned sparse expansion may fix vocabulary mismatch.
Search ColBERT	Search first stage	Token-level term relationships matter.
Features Rec	Preference writes	You need train-free interaction and attribute preferences.
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:

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

./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 for the manifest, registration lifecycle, runtime boundaries, and Search callable contracts. Use Search levels before adding a retrieval plugin and Search recipes to compare behavior on real query shapes.