Agent Brain

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.

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

Server Commands

Setup Commands

Plugin Agents

Agent Brain includes three intelligent agents for complex tasks:

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:

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

Pluggable Providers

Agent Brain supports multiple providers for embeddings and summarization:

Embedding Providers

Summarization Providers

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