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.
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 | 24 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) |
claude plugins install github:SpillwaveSolutions/agent-brainIn 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
/agent-brain-search "how does authentication work"
That's it! The plugin handles everything automatically.
| 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 |
| 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 |
| 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 |
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 |
You: "Research how authentication is implemented across the codebase"
Research Assistant:
- Searches documentation for auth concepts
- Queries code for auth-related functions
- Uses graph mode to find dependencies
- Synthesizes comprehensive answer with references
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
| 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" |
Agent Brain supports multiple providers for embeddings and summarization:
| 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 |
| 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 |
Run completely offline with Ollama:
/agent-brain-providers
# Select Ollama for both embeddings and summarization
- 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
- Entity and relationship extraction
- Dependency-aware queries ("What calls X?")
- Code structure visualization
- Per-project isolated servers
- Automatic port allocation
- Work on multiple projects simultaneously
agent-brain/
├── agent-brain-plugin/ # Claude Code plugin (primary interface)
│ ├── commands/ # 24 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
- Quick Start - Get running in minutes
- Plugin Guide - Complete plugin documentation
- User Guide - Detailed usage guide
- API Reference - REST API documentation
- Configuration - All configuration options
- Provider Configuration - Provider setup
- Architecture Overview - System design
- GraphRAG Guide - Knowledge graph features
- Code Indexing - AST-aware chunking
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
agent-brain start --daemon
# Index and query
agent-brain index /path/to/docs --include-code
agent-brain query "authentication" --mode hybrid- Python 3.10+
- Poetry (dependency management)
- Task (task runner)
git clone https://github.com/SpillwaveSolutions/agent-brain.git
cd agent-brain
task installtask test # All tests
task before-push # Full quality check- 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
See the Developer Guide for setup instructions.
Before pushing changes, always run:
task before-pushMIT License - see LICENSE file for details.