/configuring-agent-brain

name: configuring-agent-brain
description: |
  Installation and configuration skill for Agent Brain document search system.
  Use when asked to "install agent brain", "setup agent brain", "configure agent brain",
  "setting up document search", "installing agent-brain packages", "configuring API keys",
  "initializing project for search", "troubleshooting agent brain", "pip install agent-brain",
  "agent brain not working", "agent brain setup error", "configure embeddings provider",
  "setup ollama for agent brain", "agent brain environment variables",
  "install agent brain mcp", "configure mcp server", or "connect agent brain to claude desktop".
  Covers package installation (server, CLI, MCP), provider configuration, project initialization, and server management.
license: MIT
allowed-tools:
  - Bash
  - Read
metadata:
  version: 10.4.0
  category: ai-tools
  author: Spillwave
  last_validated: 2026-06-24

Configuring Agent Brain

Installation and configuration for Agent Brain document search with pluggable providers.

Contents

• [Quick Setup](#quick-setup)
• [Setup Wizard](#setup-wizard)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [MCP Server](#mcp-server-optional)
• [Provider Configuration](#provider-configuration)
• [Project Initialization](#project-initialization)
• [Verification](#verification)
• [When Not to Use](#when-not-to-use)
• [Reference Documentation](#reference-documentation)

---

Multi-Runtime Support

Agent Brain supports multiple AI coding runtimes from a single canonical plugin source:

| Runtime | Install Command | |---------|----------------| | Claude Code | `agent-brain install-agent --agent claude` | | OpenCode | `agent-brain install-agent --agent opencode` | | Codex (+ AGENTS.md) | `agent-brain install-agent --agent codex` | | Cursor | `agent-brain install-agent --agent cursor` | | Grok Build | `agent-brain install-agent --agent grok` | | Any skill runtime | `agent-brain install-agent --agent skill-runtime --dir <path>` |

All runtimes share the same `.agent-brain/` data directory for indexes, configuration, and server state. The `install-agent` command converts the canonical plugin format into each runtime's native format automatically.

Use `--global` for user-level installation, or `--dry-run` to preview files before writing.

---

Quick Setup

Option A: Local with Ollama (FREE, No API Keys)

# 1. Install packages
pip install agent-brain-rag agent-brain-cli

# 2. Install and start Ollama
brew install ollama  # macOS
ollama serve &
ollama pull nomic-embed-text
ollama pull llama3.2

# 3. Configure for Ollama
export EMBEDDING_PROVIDER=ollama
export EMBEDDING_MODEL=nomic-embed-text
export SUMMARIZATION_PROVIDER=ollama
export SUMMARIZATION_MODEL=llama3.2

# 4. Initialize and start
agent-brain init
agent-brain start
agent-brain status

Option B: Cloud Providers (Best Quality)

# 1. Install packages
pip install agent-brain-rag agent-brain-cli

# 2. Configure API keys
export OPENAI_API_KEY="sk-proj-..."       # For embeddings
export ANTHROPIC_API_KEY="sk-ant-..."     # For summarization (optional)

# 3. Initialize and start
agent-brain init
agent-brain start
agent-brain status

**Validation**: After each step, verify success before proceeding to the next.

---

Setup Wizard

The canonical entry point for a complete guided setup is `/agent-brain-setup`. It asks all configuration questions interactively before running any CLI commands, then writes a comprehensive `config.yaml`.

Wizard Configuration Questions

The wizard asks the following questions in sequence:

| Step | Question | Config Keys Set | |------|----------|----------------| | 2 | Embedding Provider | `embedding.provider`, `embedding.model`, optionally `embedding.base_url`, `embedding.api_key` or `embedding.api_key_env` | | 3 | Summarization Provider | `summarization.provider`, `summarization.model`, optionally `summarization.base_url`, `summarization.api_key` or `summarization.api_key_env` | | 4 | Storage Backend | `storage.backend` (`chroma` or `postgres`) | | 5 | GraphRAG | `graphrag.enabled`, `graphrag.store_type`, `graphrag.use_code_metadata` | | 6 | Default Query Mode | Written as YAML comment: `# query.default_mode` |

Embedding Provider Options

| Option | Provider Key | Model | Notes | |--------|-------------|-------|-------| | Ollama (FREE, local) | `ollama` | `nomic-embed-text` | Requires Ollama running locally | | OpenAI | `openai` | `text-embedding-3-large` | Requires `OPENAI_API_KEY` | | Cohere | `cohere` | `embed-multilingual-v3.0` | Requires `COHERE_API_KEY`, multi-language support | | Google Gemini | `gemini` | `text-embedding-004` | Requires `GOOGLE_API_KEY` | | Custom | (user-specified) | (user-specified) | Specify provider, model, and base_url |

Summarization Provider Options

| Option | Provider Key | Model | Notes | |--------|-------------|-------|-------| | Ollama (FREE, local) | `ollama` | `llama3.2` | Requires Ollama running locally | | Ollama + Mistral (FREE, local) | `ollama` | `mistral-small3.2` | Better summarization quality | | Anthropic | `anthropic` | `claude-haiku-4-5-20251001` | Requires `ANTHROPIC_API_KEY` | | OpenAI | `openai` | `gpt-4o-mini` | Requires `OPENAI_API_KEY` | | Google Gemini | `gemini` | `gemini-2.0-flash` | Requires `GOOGLE_API_KEY` | | Grok (xAI) | `grok` | `grok-3-mini-fast` | Requires `XAI_API_KEY` |

Config.yaml Written by Wizard

After answering all questions, the wizard writes a comprehensive `config.yaml` covering:

• `embedding.*` — provider, model, api_key or api_key_env, optional base_url
• `summarization.*` — provider, model, api_key or api_key_env, optional base_url
• `storage.*` — backend selection and (if PostgreSQL) connection settings
• `graphrag.*` — enabled flag, store_type, use_code_metadata
• `# query.default_mode` as a YAML comment (informational)

The file is chmod 600 automatically. A security warning is shown: never commit config.yaml to git