Configuring Agent Brain

Configuring Agent Brain

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

Contents

• Quick Setup
• Setup Wizard
• Prerequisites
• Installation
• MCP Server
• Provider Configuration
• Project Initialization
• Verification
• When Not to Use
• Reference Documentation

Multi-Runtime Support

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

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:

Embedding Provider Options

Summarization Provider Options

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.

PostgreSQL + BM25: When storage.backend: "postgres" is selected, the disk-based BM25 index is replaced by PostgreSQL's built-in full-text search (tsvector + websearch_to_tsquery). The --mode bm25 command works identically from the user's perspective. Language is configurable via storage.postgres.language (default: "english").

Standalone Config Command

/agent-brain-config handles provider-specific details when called standalone (without the full wizard). It includes storage backend selection, indexing exclude patterns, and Ollama status checks.

Prerequisites

Required

• Python 3.10+: Verify with python --version
• pip: Python package manager

Provider-Dependent

• OpenAI API Key: Required for OpenAI embeddings
• Ollama: Required for local/private deployments (no API key needed)

System Requirements

• ~500MB RAM for typical document collections
• ~1GB RAM with GraphRAG enabled
• Disk space for ChromaDB vector store

Installation

Recommended installer: use pipx (isolated global) or uv to install the CLI — pipx install agent-brain-cli or uv tool install agent-brain-cli. The bare pip commands below work everywhere and are kept for simplicity, but pipx/uv avoid dependency clashes. See Installation Guide for the full comparison.

Standard Installation

pip install agent-brain-rag agent-brain-cli

Verify installation succeeded:

agent-brain --version

Expected: Version number displayed (e.g., 10.3.0 or later)

With GraphRAG Support

pip install "agent-brain-rag[graphrag]" agent-brain-cli
# Kuzu backend (optional):
pip install "agent-brain-rag[graphrag-kuzu]" agent-brain-cli

Enable GraphRAG (server)

export ENABLE_GRAPH_INDEX=true            # Master switch (default: false)
export GRAPH_STORE_TYPE=simple            # or kuzu
export GRAPH_INDEX_PATH=./graph_index
export GRAPH_USE_CODE_METADATA=true       # Extract from AST metadata
export GRAPH_USE_LLM_EXTRACTION=true      # Use LLM extractor when available
export GRAPH_MAX_TRIPLETS_PER_CHUNK=10    # Triplet cap per chunk
export GRAPH_TRAVERSAL_DEPTH=2            # Default traversal depth
export GRAPH_EXTRACTION_MODEL=claude-haiku-4-5

Add the same values to your .env if you prefer file-based config.

Virtual Environment (Recommended)

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
pip install agent-brain-rag agent-brain-cli

Installation Troubleshooting

Counter-example - Wrong approach:

# DO NOT use sudo with pip
sudo pip install agent-brain-rag  # Wrong - creates permission issues

Correct approach:

pip install --user agent-brain-rag  # Correct - user installation
# OR use virtual environment

MCP Server (Optional)

Agent Brain ships an MCP (Model Context Protocol) server that exposes the running instance to MCP-aware clients — Claude Desktop, Claude Code, Cursor, Windsurf, the Claude Agent SDK, and LangChain DeepAgents.

Install

pip install agent-brain-ag-mcp

PyPI name vs. command: the package publishes as agent-brain-ag-mcp (renamed in v10.1.2 — the original name hit PyPI's typosquatting filter), but the installed console script is still agent-brain-mcp and the import path is still agent_brain_mcp.

Register through the plugin (recommended for Claude Code)

install-agent can register the MCP server for you while installing the plugin — no hand-editing of .mcp.json:

# Install the plugin AND register the agent-brain MCP server for Claude Code
agent-brain install-agent --agent claude --with-mcp

# ...or for OpenCode (writes the project-root opencode.json)
agent-brain install-agent --agent opencode --with-mcp

# ...or for Codex (writes ~/.codex/config.toml, TOML [mcp_servers.agent-brain])
agent-brain install-agent --agent codex --with-mcp

# ...or for Cursor (writes .cursor/mcp.json)
agent-brain install-agent --agent cursor --with-mcp

# ...or for Grok Build (writes .mcp.json — Grok loads Claude plugins)
agent-brain install-agent --agent grok --with-mcp

# Preview without writing anything
agent-brain install-agent --agent claude --with-mcp --dry-run

# Register with client-side OAuth enabled (for a remote, OAuth-protected server)
agent-brain install-agent --agent claude --with-mcp --mcp-auth oauth

What --with-mcp does:

• Writes/merges an agent-brain entry into the runtime's MCP config, preserving any other MCP servers and keys — Claude Code's .mcp.json / ~/.claude.json (mcpServers), OpenCode's project-root opencode.json / ~/.config/opencode/opencode.json (mcp), Codex's $CODEX_HOME/config.toml (default ~/.codex/config.toml, [mcp_servers.agent-brain] TOML), Cursor's .cursor/mcp.json / ~/.cursor/mcp.json, or Grok Build's Claude path.
• Pins AGENT_BRAIN_STATE_DIR to the project's absolute .agent-brain path so the server is discoverable regardless of the client's working directory.
• Is idempotent — re-running reports unchanged when the entry already matches.

Auto-registration targets Claude Code, OpenCode, Codex, Cursor, and Grok Build. For other MCP hosts, register manually with the JSON block below (the flag will print a note and skip). Codex has no project-level MCP config, so both scopes write the single user-level config.toml. Conforming Agent Plugins 1.0 clients also pick up agent-brain-plugin/mcp.json automatically.

Configure an MCP client (manual)

Add the server to your client's MCP config (Claude Desktop / Cursor / Windsurf use the same mcpServers shape):

{
  "mcpServers": {
    "agent-brain": {
      "command": "agent-brain-mcp",
      "args": ["--backend", "auto"],
      "env": { "AGENT_BRAIN_STATE_DIR": "/abs/path/.agent-brain" }
    }
  }
}

• --backend {auto,uds,http} selects how the MCP server reaches agent-brain-serve (auto prefers the Unix domain socket, falls back to HTTP). This is orthogonal to the MCP listen transport.
• stdio is the default listen transport (no flag). For IDE/framework clients that prefer HTTP, use agent-brain-mcp --transport http --host 127.0.0.1 --port 8765 (loopback only — public binds are rejected).

OAuth 2.1 for remote servers (shipped in v10.4)

For a local/loopback server you need no auth — leave the defaults. To run Agent Brain remotely (CI box, shared dev server, hosted), the MCP server supports OAuth 2.1 on the Streamable HTTP transport. Auth is off by default; opt in with env vars:

The client side persists tokens at <state_dir>/mcp-oauth-tokens.json (chmod 0o600) and refreshes silently. install-agent --with-mcp --mcp-auth oauth writes the client toggle for you. Per-tool scopes (agent-brain:read|index|admin|subscribe) enforce least privilege, with default-deny on the mutating tools.

Verify

# stdio server starts and exposes tools/resources/prompts
agent-brain-mcp --help

# Or drive it from the CLI's mcp transport
agent-brain --transport mcp resources list

The current surface is 16 tools, 5 corpus:// resources, and 6 prompts. See the MCP package README, docs/MCP_USER_GUIDE.md, and this skill's MCP Setup Guide for the full reference.

Provider Configuration

Agent Brain supports pluggable providers with two configuration methods.

Method 1: Configuration File (Recommended)

Create a config.yaml file in one of these locations:

1. Project-level: .agent-brain/config.yaml
2. User-level: ~/.agent-brain/config.yaml
3. XDG config: ~/.config/agent-brain/config.yaml
4. Current directory: ./config.yaml or ./agent-brain.yaml

# ~/.agent-brain/config.yaml
server:
  url: "http://127.0.0.1:8000"
  port: 8000

project:
  state_dir: null  # null = use default (.agent-brain)

embedding:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key: "sk-proj-..."  # Direct key, OR use api_key_env
  # api_key_env: "OPENAI_API_KEY"  # Read from env var

summarization:
  provider: "anthropic"
  model: "claude-haiku-4-5-20251001"
  api_key: "sk-ant-..."  # Direct key, OR use api_key_env
  # api_key_env: "ANTHROPIC_API_KEY"

Config file search order: AGENT_BRAIN_CONFIG env → current dir → project dir → user home

Security: If storing API keys in config file:

• Set file permissions: chmod 600 ~/.agent-brain/config.yaml
• Add to .gitignore: config.yaml
• Never commit API keys to version control

Method 2: Environment Variables

Set variables in shell or .env file:

export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large
export SUMMARIZATION_PROVIDER=anthropic
export SUMMARIZATION_MODEL=claude-haiku-4-5-20251001
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Precedence order: CLI options → environment variables → config file → defaults

Provider Profiles

Fully Local with Ollama (No API Keys)

Best for privacy, air-gapped environments:

Config file (~/.agent-brain/config.yaml):

embedding:
  provider: "ollama"
  model: "nomic-embed-text"
  base_url: "http://localhost:11434/v1"

summarization:
  provider: "ollama"
  model: "llama3.2"
  base_url: "http://localhost:11434/v1"

Or environment variables:

export EMBEDDING_PROVIDER=ollama
export EMBEDDING_MODEL=nomic-embed-text
export SUMMARIZATION_PROVIDER=ollama
export SUMMARIZATION_MODEL=llama3.2

Prerequisite: Ollama must be installed and running with models pulled.

Cloud (Best Quality)

Config file:

embedding:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key: "sk-proj-..."

summarization:
  provider: "anthropic"
  model: "claude-haiku-4-5-20251001"
  api_key: "sk-ant-..."

Or environment variables:

export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Mixed (Balance Quality and Privacy)

embedding:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key: "sk-proj-..."

summarization:
  provider: "ollama"
  model: "llama3.2"