/agent-brain-config

name: agent-brain-config
description: 12-step wizard to configure all Agent Brain settings — providers, storage, GraphRAG, reranking, caching, file watcher, chunking, and server deployment
parameters: []
context: fork
agent: setup-assistant
skills:
  - configuring-agent-brain
last_validated: 2026-03-16

Configure Agent Brain

Purpose

Guides users through configuring all aspects of Agent Brain across 12 wizard steps: 1. **Providers** - Ollama (local/free) or cloud providers (OpenAI, Anthropic, Gemini) 2. **Storage backend** - ChromaDB (local-first) or PostgreSQL + pgvector 3. **Indexing excludes** - Detect and exclude large directories (node_modules, .venv, etc.) 4. **GraphRAG** - Knowledge graph extraction and indexing (AST, LangExtract, or Kuzu) 5. **Caching** - Embedding cache and query result cache configuration 6. **File watcher** - Automatic re-indexing when files change 7. **Reranking** - Two-stage search quality with cross-encoder reranking 8. **Chunking and search tuning** - Chunk size, overlap, top-k, and similarity threshold 9. **Server and deployment** - Host, port, instance mode, and multi-project setup

Usage

/agent-brain:agent-brain-config

Execution

Step 1: Detect Config File Location

**IMPORTANT: Check BOTH locations and edit the correct one.**

Config file search order (highest to lowest): 1. **AGENT_BRAIN_CONFIG** environment variable 2. **State directory**: `AGENT_BRAIN_STATE_DIR/config.yaml` 3. **Current directory**: `./config.yaml` 4. **Project-level** (walk up from CWD): `.agent-brain/config.yaml` or `.claude/agent-brain/config.yaml` 5. **XDG config** (preferred user-level): `~/.config/agent-brain/config.yaml` 6. **Legacy user-level** (deprecated): `~/.agent-brain/config.yaml`

Use `agent-brain config path` to see which file is active.

# Check which config file is active
agent-brain config path

# Show the full active configuration
agent-brain config show

**When editing config: Use the file reported by `agent-brain config path`. Project-level takes precedence over user-level.**

Step 2: Run Pre-Flight Detection

Run the environment detection script once. It consolidates Ollama check, Docker check, large-dir scan, and config detection into a single call:

# Find the script — adjust path if plugin is installed to ~/.claude/plugins/
SCRIPT=$(find ~/.claude/plugins/agent-brain/scripts ~/.claude/skills/agent-brain/scripts agent-brain-plugin/scripts -name "ab-setup-check.sh" 2>/dev/null | head -1)
if [ -n "$SCRIPT" ]; then
  SETUP_STATE=$("$SCRIPT")
  echo "$SETUP_STATE"
else
  echo "ab-setup-check.sh not found — run detection manually (see fallback below)"
  SETUP_STATE="{}"
fi

Parse the JSON output into local variables for use in subsequent steps:

OLLAMA_RUNNING=$(echo "$SETUP_STATE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('ollama_running','false'))" 2>/dev/null || echo "false")
CONFIG_FILE=$(echo "$SETUP_STATE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('config_file_path',''))" 2>/dev/null || echo "")
DOCKER_AVAILABLE=$(echo "$SETUP_STATE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('docker_available','false'))" 2>/dev/null || echo "false")
AVAILABLE_PORT=$(echo "$SETUP_STATE" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('available_postgres_port','5432'))" 2>/dev/null || echo "5432")

**Interpreting results:**

• `ollama_running: true` → Ollama IS running; proceed with configuration
• `ollama_running: false` → Tell user to start Ollama: `ollama serve`
• `docker_available: true` → Docker is installed; PostgreSQL setup is possible
• `config_file_path: "..."` → Edit THAT config file (project-level takes priority)

**Fallback (if ab-setup-check.sh not found):** Use the manual methods below — but `ab-setup-check.sh` should always be present if the plugin is installed.

<details> <summary>Manual fallback (not needed when plugin is installed)</summary>

# Manual Ollama check
curl -s --connect-timeout 3 http://localhost:11434/ 2>/dev/null
lsof -i :11434 2>/dev/null | head -3
ollama list 2>/dev/null | head -10

</details>

Step 3: Use AskUserQuestion for Provider Selection

Which provider setup would you like for Agent Brain?

Options:
1. Ollama (Local) - FREE, no API keys required. Uses nomic-embed-text + llama3.2
2. OpenAI + Anthropic - Best quality cloud providers. Requires OPENAI_API_KEY and ANTHROPIC_API_KEY
3. Google Gemini - Google's models. Requires GOOGLE_API_KEY
4. Custom Mix - Choose different providers for embedding vs summarization
5. Ollama + Mistral - FREE, uses nomic-embed-text + mistral-small3.2 (better summarization)

Step 4: Based on Selection

**For Ollama (Option 1):**

=== Ollama Setup (Local, Free) ===

Ollama runs locally - no API keys or cloud costs!

1. Install Ollama (if not installed):

   macOS:   brew install ollama
   Linux:   curl -fsSL https://ollama.com/install.sh | sh
   Windows: Download from https://ollama.com/download

2. Start Ollama server:
   ollama serve

3. Pull required models:
   ollama pull nomic-embed-text      # For embeddings (8192 token context)
   ollama pull llama3.2              # For summarization

   IMPORTANT: Use nomic-embed-text (NOT mxbai-embed-large)
   - nomic-embed-text: 8192 token context - handles large documents
   - mxbai-embed-large: only 512 token context - causes indexing errors

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

   mkdir -p ~/.agent-brain
   cat > ~/.agent-brain/config.yaml << 'EOF'
   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"
   EOF

   OR use environment variables:
   export EMBEDDING_PROVIDER=ollama
   export EMBEDDING_MODEL=nomic-embed-text
   export SUMMARIZATION_PROVIDER=ollama
   export SUMMARIZATION_MODEL=ll