last_validated	2026-03-16

Agent Brain

A RAG-based (Retrieval-Augmented Generation) document indexing and semantic search system for AI agents and applications. Agent Brain enables intelligent querying of documentation and source code using natural language.

Overview

Agent Brain provides AI-first document and code search through a Claude Code plugin with skills, commands, and agents. Use slash commands to search, agents for complex research tasks, and skills for intelligent query optimization.

Component	Description
Plugin	30 slash commands, 3 agents, 2 skills for Claude Code
Skills	Intelligent search mode selection and query optimization
Agents	Research assistant, search assistant, setup assistant
Server	FastAPI backend for indexing and retrieval
CLI	Command-line tool (also used by plugin internally)

Quick Start (Claude Code Plugin)

1. Install the Plugin

# 1. Add the Agent Brain marketplace (the repo is a plugin marketplace)
claude plugins marketplace add SpillwaveSolutions/agent-brain

# 2. Install the plugin from that marketplace
claude plugins install agent-brain@agent-brain-marketplace

Installing a Claude Code plugin does not use pip. The plugin is installed through the marketplace above; the underlying Python packages (agent-brain-rag, agent-brain-cli) are installed for you by the /agent-brain-setup wizard (or manually via pip — see CLI Usage).

Other hosts

The same plugin installs into Codex, Cursor, Grok Build, and OpenCode through the CLI. Each command converts the shared payload into the host's native layout and, with --with-mcp, registers the MCP server in that host's config file.

pip install agent-brain-rag agent-brain-cli agent-brain-ag-mcp
agent-brain install-agent --agent codex --with-mcp     # .codex/skills/agent-brain + AGENTS.md; MCP in ~/.codex/config.toml
agent-brain install-agent --agent cursor --with-mcp    # .cursor/plugins/agent-brain + .cursor/rules; MCP in .cursor/mcp.json
agent-brain install-agent --agent grok --with-mcp      # .grok/plugins/agent-brain; zero-config Claude load, MCP in .mcp.json
agent-brain install-agent --agent opencode --with-mcp  # .opencode/plugins/agent-brain; MCP in opencode.json

A conforming Agent Plugins 1.0 client reads agent-brain-plugin/plugin.json, skills/, and mcp.json directly. See docs/HOSTS.md for the manifest each host reads.

2. Set Up Your Project

In Claude Code, run:

/agent-brain-setup

This interactive wizard will:

• Install the Python packages (agent-brain-rag, agent-brain-cli)
• Configure your API keys
• Initialize the project
• Start the server
• Index your documentation

3. Search with Commands

/agent-brain-search "how does authentication work"

That's it! The plugin handles everything automatically.

Plugin Commands

Search Commands

Command	Description	Use When
/agent-brain-search	Smart hybrid search (recommended)	General questions
/agent-brain-semantic	Pure semantic/vector search	Conceptual queries
/agent-brain-keyword	BM25 keyword search	Error messages, function names
/agent-brain-hybrid	Hybrid with alpha tuning	Fine-tuned searches
/agent-brain-graph	Knowledge graph search	"What calls X?", dependencies
/agent-brain-multi	All modes combined (RRF)	Maximum recall

Server Commands

Command	Description
/agent-brain-start	Start the server (auto-port)
/agent-brain-stop	Stop the server
/agent-brain-status	Check health and document count
/agent-brain-index	Index documents or code

Setup Commands

Command	Description
/agent-brain-setup	Complete guided setup wizard
/agent-brain-install	Install pip packages
/agent-brain-init	Initialize project directory
/agent-brain-verify	Verify configuration
/agent-brain-providers	Configure embedding/summarization providers

Plugin Agents

Agent Brain includes three intelligent agents for complex tasks:

Agent	Description	Triggered By
Search Assistant	Multi-step search across modes, synthesizes answers	"Find all references to...", "Research how..."
Research Assistant	Deep exploration with follow-up queries	"Investigate...", "Analyze the architecture of..."
Setup Assistant	Guided installation and troubleshooting	"Help me set up Agent Brain", configuration issues

Example Agent Interaction

You: "Research how authentication is implemented across the codebase"

Research Assistant:

1. Searches documentation for auth concepts
2. Queries code for auth-related functions
3. Uses graph mode to find dependencies
4. Synthesizes comprehensive answer with references

Plugin Skills

Skills provide intelligent context to Claude for optimal searching:

Skill	Purpose
using-agent-brain	Search mode selection, query optimization, API knowledge
configuring-agent-brain	Installation, provider configuration, troubleshooting

When you ask about documentation or code, Claude automatically uses the skill to:

• Choose the best search mode for your query
• Set appropriate parameters (top_k, threshold, alpha)
• Interpret and synthesize results

Search Modes

Mode	Best For	Example Query
HYBRID	General questions (default)	"How does caching work?"
VECTOR	Conceptual understanding	"Explain the architecture"
BM25	Exact terms, error codes	"NullPointerException", "getUserById"
GRAPH	Relationships, dependencies	"What classes use AuthService?"
MULTI	Comprehensive search	"Everything about data validation"

Pluggable Providers

Agent Brain supports multiple providers for embeddings and summarization:

Embedding Providers

Provider	Models	Local
OpenAI	text-embedding-3-large, text-embedding-3-small	No
Ollama	nomic-embed-text, mxbai-embed-large	Yes
Cohere	embed-english-v3.0, embed-multilingual-v3.0	No

Summarization Providers

Provider	Models	Local
Anthropic	claude-haiku-4-5-20251001, claude-sonnet-4-5-20250514	No
OpenAI	gpt-5, gpt-5-mini	No
Gemini	gemini-3-flash, gemini-3-pro	No
Grok	grok-4, grok-4-fast	No
Ollama	llama4:scout, mistral-small3.2, qwen3-coder	Yes

Fully Local Mode

Run completely offline with Ollama:

/agent-brain-providers
# Select Ollama for both embeddings and summarization

Features

Code Search

• 10 Programming Languages: Python, TypeScript, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift
• AST-Aware Chunking: Tree-sitter parsing preserves code structure
• LLM Summaries: AI-generated descriptions improve semantic search
• Language Filtering: Filter results by programming language

GraphRAG (Knowledge Graph)

• Entity and relationship extraction
• Dependency-aware queries ("What calls X?")
• Code structure visualization

Multi-Instance Architecture

• Per-project isolated servers
• Automatic port allocation
• Work on multiple projects simultaneously

Project Structure

agent-brain/
├── agent-brain-plugin/        # Claude Code plugin (primary interface)
│   ├── commands/              # 30 slash commands
│   ├── agents/                # 3 intelligent agents
│   └── skills/                # 2 context skills
├── agent-brain-server/        # FastAPI backend
├── agent-brain-cli/           # CLI tool (used by plugin)
└── docs/                      # Documentation

Documentation

Getting Started

• Quick Start - Get running in minutes
• Plugin Guide - Complete plugin documentation
• User Guide - Detailed usage guide
• MCP Quickstart - Use Agent Brain over MCP in ~5 minutes
• Project Setup: Plugin + Skills + MCP - Wire all three into one project

Reference

• API Reference - REST API documentation
• MCP User Guide - MCP server: 16 tools, resources, prompts, OAuth
• Configuration - All configuration options
• Provider Configuration - Provider setup
• Integrations - Connect agent-brain-mcp to LLM frameworks + editors

Architecture

• Architecture Overview - System design
• GraphRAG Guide - Knowledge graph features
• Code Indexing - AST-aware chunking

CLI Usage (Alternative)

While the plugin is the recommended interface, you can also use the CLI directly:

# Install
pip install agent-brain-rag agent-brain-cli

# Initialize and start
agent-brain init                     # auto-generates a per-project API key
agent-brain start --daemon

# Index and query
agent-brain index /path/to/docs --include-code
agent-brain query "authentication" --mode hybrid

Note on authentication. As of the next release, every data endpoint requires X-API-Key. agent-brain init writes a 32-byte urlsafe key into .agent-brain/config.json (mode 0o600); the CLI and agent-brain-mcp pick it up automatically. Pass --no-api-key to agent-brain init for the legacy no-auth experience on 127.0.0.1. The server refuses to start on any non-loopback bind without a key set. See docs/CHANGELOG.md under the unreleased entry for the full design (Issue #179).

Development

Prerequisites

• Python 3.10+
• Poetry (dependency management)
• Task (task runner)

Setup

git clone https://github.com/SpillwaveSolutions/agent-brain.git
cd agent-brain
task install

Running Tests

task test           # All tests
task before-push    # Full quality check

Technology Stack

• Plugin: Claude Code slash commands, agents, skills
• Server: FastAPI + Uvicorn
• Vector Store: ChromaDB (HNSW, cosine similarity)
• BM25 Index: LlamaIndex BM25Retriever
• Graph Store: SimplePropertyGraphStore / Kuzu
• Embeddings: OpenAI or Ollama
• Summarization: Claude, GPT-5, Gemini, Grok, or Ollama
• AST Parsing: tree-sitter (10 languages)
• CLI: Click + Rich
• Build System: Poetry

Contributing

See the Developer Guide for setup instructions.

Before pushing changes, always run:

task before-push

License

MIT License - see LICENSE file for details.

Links

• GitHub Wiki
• Plugin Marketplace
• Issue Tracker