Configuring Agent Brain

Configuring Agent Brain

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

Contents

• Quick Setup
• Setup Wizard
• Prerequisites
• Installation
• 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

Standard Installation

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

Verify installation succeeded:

agent-brain --version

Expected: Version number displayed (e.g., 3.0.0 or current version)

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

---

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"

GraphRAG Configuration

GraphRAG enables graph-based entity-relationship extraction for advanced query modes.

YAML config keys (config.yaml):

graphrag:
  enabled: false                    # Master switch (default: false)
  store_type: "simple"              # "simple" (in-memory) or "kuzu" (persistent disk)
  use_code_metadata: true           # Extract entities from AST metadata (imports, classes)
  langextract_provider: openai      # Optional override — see below
  langextract_model: gpt-4o-mini    # Optional override — see below

Corresponding environment variables:

Anthropic / Claude summarization users: langextract's provider registry does not recognise Claude model ids. If summarization.provider: anthropic is set and no langextract override is given, Agent Brain auto-routes langextract to openai/gpt-4o-mini (you'll see an INFO log). Set langextract_provider / langextract_model explicitly to use a different model — Agent Brain validates the choice at startup and raises a clear ConfigurationError if the model is not registered with langextract.

Note: GraphRAG requires the --include-code flag during indexing to extract code structure:

agent-brain index ./src --include-code

For Kuzu (persistent), install the optional extra first:

pip install "agent-brain-rag[graphrag-kuzu]"

Query Mode Selection

Agent Brain supports the following query modes, selectable per request with --mode:

Note: graph and multi modes are not available with PostgreSQL backend. GraphRAG uses an in-memory/Kuzu graph store that is separate from the vector store — it currently integrates only with ChromaDB.

Per-request override:

agent-brain query "authentication flow" --mode hybrid
agent-brain query "class relationships" --mode graph    # GraphRAG + ChromaDB required
agent-brain query "how do services work" --mode multi   # GraphRAG + ChromaDB required

Note: There is no global query.default_mode config key yet. Mode is per-request only. The setup wizard writes the selected default mode as a YAML comment for documentation purposes.

Verify Configuration

agent-brain verify

Counter-example - Common mistake:

# DO NOT put keys in shell command history
OPENAI_API_KEY="sk-proj-abc123" agent-brain start  # Wrong - key in history

Correct approaches:

# Use config file (keys are in file, not command line)
agent-brain start

# Or use environment from shell profile
export OPENAI_API_KEY="sk-proj-..."  # In ~/.bashrc
agent-brain start

---

Project Initialization

Initialize Project

Navigate to the project root and run:

agent-brain init

Verify initialization succeeded:

ls .agent-brain/config.json

Expected: File exists

Start Server

agent-brain start

Verify server started:

agent-brain status

Expected output:

Server Status: healthy
Port: 49321
Documents: 0
Mode: project

Index Documents

agent-brain index ./docs

Verify indexing succeeded:

agent-brain status

Expected: Documents count > 0

Test Search

agent-brain query "test query" --mode hybrid

Expected: Search results or "No results" (not an error)

---

Verification

Full Verification Checklist

Run each command and verify expected output:

• [ ] agent-brain --version shows version number (7.0.0+)
• [ ] echo ${OPENAI_API_KEY:+SET} shows "SET" (if using OpenAI)
• [ ] ls .agent-brain/config.json file exists
• [ ] agent-brain status shows "healthy"
• [ ] agent-brain status shows document count > 0
• [ ] agent-brain query "test" returns results or "no matches"
• [ ] agent-brain folders list shows indexed folders
• [ ] agent-brain types list shows file type presets
• [ ] agent-brain jobs shows job queue (empty or with history)

GraphRAG Verification (if enabled)

• [ ] echo ${ENABLE_GRAPH_INDEX} shows "true"
• [ ] agent-brain status --json | jq '.graph_index' shows graph index info
• [ ] agent-brain query "class relationships" --mode graph returns results or graceful error
• [ ] agent-brain query "how it works" --mode multi returns fused results

Automated Verification

agent-brain verify

This runs all checks and reports any issues.

Post-Indexing Verification

After indexing documents, verify the pipeline is working:

# Monitor indexing job
agent-brain jobs --watch

# Check job completed successfully
agent-brain jobs <job_id>

# Verify incremental indexing works
agent-brain index ./docs  # Should show eviction summary with unchanged files

# Validate injection scripts before use
agent-brain inject ./docs --script enrich.py --dry-run

---

When Not to Use

This skill focuses on installation and configuration. Do NOT use for:

• Searching documents - Use using-agent-brain skill instead
• Query optimization - Use using-agent-brain skill instead
• Understanding search modes - Use using-agent-brain skill instead
• GraphRAG queries - Use using-agent-brain skill instead

Scope boundary: Once Agent Brain is installed, configured, initialized, and verified healthy, switch to the using-agent-brain skill for search operations.

---

Common Setup Issues

Issue: Module Not Found

pip install --force-reinstall agent-brain-rag agent-brain-cli

Issue: API Key Not Working

# Test OpenAI key
curl -s https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 100

Expected: JSON response (not error)

Issue: Server Won't Start

# Check for stale state
rm -f .agent-brain/runtime.json
rm -f .agent-brain/lock.json
agent-brain start

Issue: Ollama Connection Failed

# Verify Ollama is running
curl http://localhost:11434/api/tags

Expected: JSON with model list

Issue: No Search Results

agent-brain status  # Check document count

If count is 0, index documents:

agent-brain index ./docs

---

Environment Variables Reference

Note: Environment variables override config file values. Config file values override defaults.

Caching

Embedding Cache

The embedding cache is automatic — no setup required. Embeddings are cached on first compute and reused on subsequent reindexes of unchanged content, significantly reducing OpenAI API costs when using file watching or frequent reindexing.

The two cache env vars allow tuning for specific environments:

• Large indexes — increase EMBEDDING_CACHE_MAX_MEM_ENTRIES (e.g., 5000) to keep more embeddings

in the fast in-memory tier and reduce SQLite lookups

• Memory-constrained environments — decrease EMBEDDING_CACHE_MAX_MEM_ENTRIES (e.g., 200) to

limit RAM usage; the disk cache still provides cost savings even with a small memory tier

• Disk space constrained — decrease EMBEDDING_CACHE_MAX_DISK_MB (e.g., 100) to cap the SQLite

cache database size; oldest entries are evicted when the limit is reached

The disk cache uses SQLite with WAL mode for safe concurrent access during indexing operations.

Query Cache

The query cache is automatic — no setup required. Identical queries within the TTL window return instantly without hitting storage.

• `graph` and `multi` modes bypass the cache — each call reaches storage

for fresh results.

• Cache is invalidated on every completed reindex job (file watcher or manual).
• Configurable via environment variables (see Configuration Guide for details):
• QUERY_CACHE_TTL — cache TTL in seconds (default: 300, i.e., 5 minutes)
• QUERY_CACHE_MAX_SIZE — max cached query results (default: 256)

---

Reference Documentation

---

Support

• Issues: https://github.com/SpillwaveSolutions/agent-brain-plugin/issues
• Documentation: Reference guides in this skill

Agent Brain Configuration Guide

Overview

Agent Brain supports multiple configuration methods with clear precedence rules. This guide covers all configuration options.

Configuration Methods

Method 1: YAML Configuration File (Recommended)

The config.yaml file provides a centralized configuration without needing to modify shell profiles.

Search locations (in order):

1. AGENT_BRAIN_CONFIG environment variable (explicit path) 2. Current directory: ./agent-brain.yaml or ./config.yaml 3. Project directory: ./.agent-brain/config.yaml 4. User home: ~/.agent-brain/config.yaml 5. XDG config: ~/.config/agent-brain/config.yaml

Complete config.yaml example:

# ~/.agent-brain/config.yaml
# Agent Brain Configuration

# Server settings (for CLI connection)
server:
  url: "http://127.0.0.1:8000"
  host: "127.0.0.1"
  port: 8000
  auto_port: true

# Project settings
project:
  state_dir: null  # null = use default (.agent-brain)
  # state_dir: "/custom/path/state"  # Custom state directory
  project_root: null  # null = auto-detect

# Embedding provider configuration
embedding:
  provider: "openai"  # openai, ollama, cohere, gemini
  model: "text-embedding-3-large"

  # API key configuration - choose ONE approach:
  api_key: "sk-proj-..."              # Direct API key in config
  # api_key_env: "OPENAI_API_KEY"     # OR read from environment variable

  # Custom endpoint (for Ollama or proxies)
  base_url: null  # null = use default, or "http://localhost:11434/v1" for Ollama

# Summarization provider configuration
summarization:
  provider: "anthropic"  # anthropic, openai, ollama, gemini, grok
  model: "claude-haiku-4-5-20251001"

  # API key configuration
  api_key: "sk-ant-..."               # Direct API key
  # api_key_env: "ANTHROPIC_API_KEY"  # OR read from environment variable

  base_url: null

# Storage backend configuration
storage:
  backend: "chroma"  # "chroma" (default) or "postgres"
  # postgres:  # Only needed when backend is "postgres"
  #   host: "localhost"
  #   port: 5432
  #   database: "agent_brain"
  #   user: "agent_brain"
  #   password: "agent_brain_dev"

# GraphRAG configuration (optional, default: disabled)
graphrag:
  enabled: false
  store_type: "simple"  # "simple" (in-memory) or "kuzu" (persistent disk)
  use_code_metadata: true

# Query mode (informational — set per-request with --mode flag)
# query:
#   default_mode: "hybrid"  # vector | bm25 | hybrid | graph | multi

Method 2: Environment Variables

Traditional approach using shell environment:

# Core settings
export AGENT_BRAIN_URL="http://127.0.0.1:8000"
export AGENT_BRAIN_STATE_DIR=".agent-brain"
export AGENT_BRAIN_CONFIG="/path/to/config.yaml"

# Provider configuration
export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large
export SUMMARIZATION_PROVIDER=anthropic
export SUMMARIZATION_MODEL=claude-haiku-4-5-20251001

# API keys
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Method 3: .env File

Create .agent-brain/.env or project root .env:

OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-large

---

Configuration Precedence

Settings are resolved in order (first wins):

1. CLI options (--url, --port, --state-dir) 2. Environment variables (AGENT_BRAIN_URL, OPENAI_API_KEY) 3. Config file (config.yaml values) 4. Built-in defaults

For API keys specifically: 1. api_key field in config.yaml 2. Environment variable specified by api_key_env 3. Default environment variable (e.g., OPENAI_API_KEY)

---

Storage Backend Configuration

Agent Brain supports two storage backends:

• chroma (default)
• postgres

Recommended YAML configuration:

storage:
  backend: "postgres"  # or "chroma"
  postgres:
    host: "localhost"
    port: 5432
    database: "agent_brain"
    user: "agent_brain"
    password: "agent_brain_dev"
    pool_size: 10
    pool_max_overflow: 10
    language: "english"
    hnsw_m: 16
    hnsw_ef_construction: 64
    debug: false

Environment overrides:

• AGENT_BRAIN_STORAGE_BACKEND overrides storage.backend
• DATABASE_URL overrides the connection string only (pool settings stay in YAML)

export AGENT_BRAIN_STORAGE_BACKEND="postgres"
export DATABASE_URL="postgresql+asyncpg://agent_brain:agent_brain_dev@localhost:5432/agent_brain"

BM25 and Full-Text Search with PostgreSQL

When using the PostgreSQL backend, the disk-based BM25 index is replaced by PostgreSQL's built-in full-text search (tsvector + websearch_to_tsquery).

• --mode bm25 queries use ts_rank scoring with websearch_to_tsquery syntax
• Scores are normalized to 0-1 to match ChromaDB BM25 output format
• The storage.postgres.language setting (default: "english") controls the

tsvector language configuration

• No BM25 configuration or index files are needed with PostgreSQL

---

API Keys

OpenAI API Key

Required for vector and hybrid search with OpenAI embeddings.

Option A: In config.yaml

embedding:
  provider: "openai"
  api_key: "sk-proj-..."

Option B: Environment variable

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

Get your key: https://platform.openai.com/account/api-keys

Verify key is set:

echo "OpenAI key: ${OPENAI_API_KEY:+CONFIGURED}"

Anthropic API Key

Required for Claude summarization.

Option A: In config.yaml

summarization:
  provider: "anthropic"
  api_key: "sk-ant-..."

Option B: Environment variable

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

Get your key: https://console.anthropic.com/

Other Provider Keys

---

Environment Variables Reference

---

GraphRAG Configuration (Feature 113)

GraphRAG enables graph-based retrieval using entity relationships extracted from documents and code.

GraphRAG Environment Variables

GraphRAG in config.yaml

# ~/.agent-brain/config.yaml
graphrag:
  enabled: true
  store_type: "simple"  # "simple" or "kuzu"
  index_path: "./graph_index"
  extraction_model: "claude-haiku-4-5"
  max_triplets_per_chunk: 10
  use_code_metadata: true
  use_llm_extraction: true
  traversal_depth: 2
  rrf_k: 60

GraphRAG via Environment Variables

# Enable GraphRAG
export ENABLE_GRAPH_INDEX=true

# Use Kuzu for persistent graph storage (optional)
export GRAPH_STORE_TYPE=kuzu
export GRAPH_INDEX_PATH=".agent-brain/graph_index"

# Entity extraction settings
export GRAPH_EXTRACTION_MODEL=claude-haiku-4-5
export GRAPH_MAX_TRIPLETS_PER_CHUNK=10

# Code relationship extraction (recommended for codebases)
export GRAPH_USE_CODE_METADATA=true
export GRAPH_USE_LLM_EXTRACTION=true

# Query settings
export GRAPH_TRAVERSAL_DEPTH=2
export GRAPH_RRF_K=60

---

Query Cache Configuration

The query cache stores identical query results for a configurable TTL window. It is auto-enabled — no setup required.

Behavior

• Identical queries within the TTL return instantly without hitting storage
• Cache is invalidated when any reindex job completes (watcher or manual)
• graph and multi query modes are never cached — each call reaches storage
• Cache is in-memory and does not persist across server restarts

Environment Variables

Example

# Extend cache TTL to 10 minutes for stable codebases
export QUERY_CACHE_TTL=600

# Increase cache size for large query workloads
export QUERY_CACHE_MAX_SIZE=512

Disable Query Cache

export QUERY_CACHE_TTL=0

---

GraphRAG Query Modes

Once enabled, you can query using graph-based retrieval:

# Graph-only retrieval (entity relationships)
agent-brain query "class relationships" --mode graph

# Multi-mode fusion (vector + BM25 + graph with RRF)
agent-brain query "how do services work" --mode multi

Store Type Comparison

Note: Kuzu requires the optional graphrag-kuzu dependency:

poetry install --extras graphrag-kuzu

Troubleshooting GraphRAG

GraphRAG disabled error:

# Check if enabled
echo $ENABLE_GRAPH_INDEX

# Enable it
export ENABLE_GRAPH_INDEX=true
agent-brain stop && agent-brain start

No graph results:

# Verify graph index was built
agent-brain status --json | jq '.graph_index'

# Re-index with graph enabled
agent-brain reset --yes
agent-brain index /path/to/docs

---

Profile Examples

Fully Local (Ollama - No API Keys)

# ~/.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"

Cloud (Best Quality)

# ~/.agent-brain/config.yaml
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-..."

Custom State Directory

# ~/.agent-brain/config.yaml
project:
  state_dir: "/data/agent-brain/my-project"

embedding:
  provider: "openai"
  api_key_env: "OPENAI_API_KEY"

GraphRAG Enabled (Code Search)

# ~/.agent-brain/config.yaml
embedding:
  provider: "openai"
  model: "text-embedding-3-large"
  api_key_env: "OPENAI_API_KEY"

summarization:
  provider: "anthropic"
  model: "claude-haiku-4-5-20251001"
  api_key_env: "ANTHROPIC_API_KEY"

graphrag:
  enabled: true
  store_type: "kuzu"  # Persistent for large codebases
  use_code_metadata: true  # Extract imports, classes from AST
  use_llm_extraction: true  # Extract semantic relationships
  traversal_depth: 2

---

Security Best Practices

Config File Permissions

If storing API keys in config files:

# Restrict to owner only
chmod 600 ~/.agent-brain/config.yaml

Git Ignore

Add to .gitignore:

config.yaml
agent-brain.yaml
.env
.env.local

Key Rotation

Regenerate API keys periodically and update configurations.

---

Troubleshooting

Config File Not Loading

# Check config file exists
ls -la ~/.agent-brain/config.yaml

# Verify YAML syntax
python -c "import yaml; yaml.safe_load(open('config.yaml'))"

# Force specific config
export AGENT_BRAIN_CONFIG="$HOME/.agent-brain/config.yaml"

API Key Not Working

# Test OpenAI key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Check if key is in config or env
cat ~/.agent-brain/config.yaml | grep api_key
echo ${OPENAI_API_KEY:+SET}

Wrong Server URL

# Check runtime.json for actual port
cat .agent-brain/runtime.json

# Override URL
export AGENT_BRAIN_URL="http://127.0.0.1:49321"

---

File Watcher Configuration (v8.0+)

The file watcher enables automatic re-indexing when files change in watched folders.

Environment Variables

Folder Watch Setup

# Enable file watching on a folder
agent-brain folders add ./src --watch auto --include-code

# Custom debounce (10 seconds)
agent-brain folders add ./src --watch auto --debounce 10

# Disable watching
agent-brain folders add ./docs --watch off

Behavior

• Changes are debounced per-folder (default 30 seconds)
• Watcher-triggered jobs use incremental diff (only changed files re-processed)
• Excluded directories: .git/, node_modules/, __pycache__/, dist/, build/
• Jobs show source: auto in the queue

---

Embedding Cache Configuration (v8.0+)

The embedding cache reduces API costs by caching computed embeddings locally.

Environment Variables

CLI Commands

# View cache statistics
agent-brain cache status

# View as JSON
agent-brain cache status --json

# Clear all cached embeddings
agent-brain cache clear --yes

Behavior

• Two-tier: in-memory LRU + SQLite disk cache
• Identical content returns cached embedding (no API call)
• Cache is invalidated per-chunk when content changes
• Healthy cache shows >80% hit rate after first full index

---

Reranking Configuration (v8.0+)

Two-stage retrieval with reranking for higher precision results.

Environment Variables

YAML Configuration

reranking:
  enabled: true
  provider: "sentence-transformers"
  model: "cross-encoder/ms-marco-MiniLM-L-6-v2"
  top_k_multiplier: 10
  max_candidates: 100

---

Folder Management Configuration (v7.0+)

CLI Commands

# Add folder to index
agent-brain folders add ./docs

# Add with code file support
agent-brain folders add ./src --include-code

# List indexed folders
agent-brain folders list

# Remove folder and its chunks
agent-brain folders remove ./docs --yes

---

File Type Presets (v7.0+)

# List available file type presets
agent-brain types list

# Index with specific file type preset
agent-brain index ./src --include-type python
agent-brain index ./src --include-type typescript

---

Content Injection (v7.0+)

Content injection allows enriching documents during indexing with custom scripts.

# Index with content injection script
agent-brain inject --script enrich.py ./docs

---

Multi-Runtime Install (v9.0+)

Install the Agent Brain plugin into different AI coding assistant runtimes:

agent-brain install-agent --agent claude     # Claude Code
agent-brain install-agent --agent opencode   # OpenCode
agent-brain install-agent --agent gemini     # Gemini
agent-brain install-agent --agent codex      # Codex
agent-brain install-agent --agent skill-runtime --dir /path  # Generic

---

Next Steps

After configuration: 1. Initialize project: /agent-brain:agent-brain-init 2. Start server: /agent-brain:agent-brain-start 3. Index documents: /agent-brain:agent-brain-index /path/to/docs 4. Search: /agent-brain:agent-brain-search "your search"

Agent Brain Installation Guide

Overview

This guide covers the complete installation process for Agent Brain, including multiple installation methods, prerequisites, and verification steps.

Prerequisites

Python 3.10+

Agent Brain requires Python 3.10 or higher.

Check Python Version:

python --version
# or
python3 --version

Install Python (if needed):

---

Installation Methods

Choose the best method for your workflow:

---

Method 1: pipx (Recommended)

Best for: Most users who want a simple, global CLI installation

pipx installs the CLI globally while keeping dependencies isolated in their own virtual environment.

Install pipx

# Check if pipx is installed
pipx --version

# Install pipx (if needed)
python -m pip install --user pipx
python -m pipx ensurepath

Restart your terminal after installing pipx.

Install Agent Brain

pipx install agent-brain-cli

Verify

agent-brain --version

Upgrade

pipx upgrade agent-brain-cli

Uninstall

pipx uninstall agent-brain-cli

---

Method 2: uv

Best for: Power users, those already using uv, or wanting fast installs

uv is a modern, Rust-based Python package installer that's very fast.

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Install Agent Brain

uv tool install agent-brain-cli

Verify

agent-brain --version

Upgrade

uv tool upgrade agent-brain-cli

Uninstall

uv tool uninstall agent-brain-cli

---

Method 3: pip with Virtual Environment

Best for: Project-scoped installations, CI/CD environments

This method keeps Agent Brain local to a specific project directory.

Create Virtual Environment

# Create venv
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

Install Agent Brain

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

Verify

agent-brain --version

Note: You must activate the virtual environment before using Agent Brain:

source .venv/bin/activate  # Run this each time

Upgrade

source .venv/bin/activate
pip install --upgrade agent-brain-rag agent-brain-cli

Uninstall

pip uninstall agent-brain-rag agent-brain-cli

---

Method 4: Conda

Best for: Data science users already in the conda ecosystem

Agent Brain is distributed on PyPI (not conda-forge), so you install it with pip inside a conda environment.

Create Conda Environment

conda create -n agent-brain python=3.12 -y
conda activate agent-brain

Install Agent Brain

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

Verify

agent-brain --version

Note: Activate the conda environment before using Agent Brain:

conda activate agent-brain  # Run this each time

Upgrade

conda activate agent-brain
pip install --upgrade agent-brain-rag agent-brain-cli

---

Post-Installation Verification

After installation, verify everything is working:

# Check CLI is available
agent-brain --help

# Check version
agent-brain --version

Expected help output:

Usage: agent-brain [OPTIONS] COMMAND [ARGS]...

  Agent Brain CLI - Document search and indexing management

Options:
  --version  Show version
  --help     Show this message and exit.

Commands:
  index   Index documents
  init    Initialize project
  list    List running instances
  query   Search documents
  reset   Clear index
  start   Start server
  status  Check server status
  stop    Stop server

---

Quick Reference

---

Troubleshooting Installation

Issue: Command Not Found

Symptom: agent-brain: command not found

Solutions by method:

pipx:

python -m pipx ensurepath
# Restart terminal

uv:

uv tool list  # Verify it's installed
# Restart terminal

pip (venv):

source .venv/bin/activate  # Must activate first
which agent-brain

conda:

conda activate agent-brain  # Must activate first
which agent-brain

Issue: Permission Denied

Symptom: Permission denied during installation

Solutions:

1. Use pipx (recommended): Avoids permission issues entirely 2. Use user installation: pip install --user agent-brain-cli 3. Use virtual environment: See Method 3 above 4. Never use sudo with pip

Issue: Module Not Found

Symptom: ModuleNotFoundError when running

Solutions:

# Reinstall packages
pip install --force-reinstall agent-brain-rag agent-brain-cli

# Check Python environment
which python
pip list | grep agent-brain

Issue: pip Not Found

Symptom: pip: command not found

Solutions:

# Use python -m pip
python -m pip install agent-brain-rag agent-brain-cli

# Or install pip
python -m ensurepip --upgrade

Issue: Python Version Too Low

Symptom: Installation fails with Python version error

Solutions:

# Install newer Python
brew install python@3.11  # macOS
sudo apt install python3.11  # Ubuntu
uv python install 3.12  # Using uv

# Or use conda
conda create -n agent-brain python=3.12

Issue: SSL Certificate Error

Symptom: SSL errors during installation

Solutions:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org agent-brain-rag agent-brain-cli

---

Dependencies

Agent Brain installs these major dependencies:

System Requirements

---

Multi-Runtime Installation (v9.0+)

After installing the CLI, deploy the Agent Brain plugin to your AI coding assistant:

# Install for Claude Code (default)
agent-brain install-agent --agent claude

# Install for OpenCode
agent-brain install-agent --agent opencode

# Install for Gemini
agent-brain install-agent --agent gemini

# Install for Codex (generates skill directories + AGENTS.md)
agent-brain install-agent --agent codex

# Install for any skill-based runtime (requires --dir)
agent-brain install-agent --agent skill-runtime --dir /path/to/skills

# Dry run to preview files
agent-brain install-agent --agent claude --dry-run

# Global (user-level) installation
agent-brain install-agent --agent claude --scope global

Supported Runtimes

Uninstalling

agent-brain uninstall --agent claude
agent-brain uninstall --agent claude --scope global

---

Key Features by Version

---

Next Steps

After installation: 1. Configure providers (API keys or Ollama) 2. Initialize project: /agent-brain:agent-brain-init 3. Start server: /agent-brain:agent-brain-start 4. Index documents: /agent-brain:agent-brain-index /path/to/docs

Provider Configuration Guide

Agent Brain supports pluggable providers for embeddings and summarization. This guide covers all configuration options.

Provider Overview

Embedding Providers

Embeddings convert text into vector representations for semantic search.

Summarization Providers

Summarization generates concise descriptions of code and documents during indexing.

Configuration Methods

Method 1: YAML Configuration File (Recommended)

Create a config.yaml file with API keys and settings. Agent Brain searches these locations in order:

1. AGENT_BRAIN_CONFIG environment variable (explicit path) 2. Current directory: ./agent-brain.yaml or ./config.yaml 3. Project directory: ./.agent-brain/config.yaml 4. User home: ~/.agent-brain/config.yaml 5. XDG config: ~/.config/agent-brain/config.yaml

Complete example (~/.agent-brain/config.yaml):

# Server settings (for CLI connection)
server:
  url: "http://127.0.0.1:8000"
  port: 8000
  host: "127.0.0.1"
  auto_port: true

# Project settings
project:
  state_dir: null  # null = default (.agent-brain)
  # state_dir: "/custom/path/agent-brain"  # Custom location

# Embedding configuration
embedding:
  provider: "openai"  # openai, ollama, cohere, gemini
  model: "text-embedding-3-large"
  api_key: "sk-proj-..."  # Direct API key
  # api_key_env: "OPENAI_API_KEY"  # OR read from env var
  base_url: null  # Custom endpoint (for Ollama: http://localhost:11434/v1)

# Summarization configuration
summarization:
  provider: "anthropic"  # anthropic, openai, ollama, gemini, grok
  model: "claude-haiku-4-5-20251001"
  api_key: "sk-ant-..."  # Direct API key
  # api_key_env: "ANTHROPIC_API_KEY"  # OR read from env var
  base_url: null

API key resolution order: api_key field → environment variable from api_key_env → default env var

Security warning: If storing API keys in config files:

chmod 600 ~/.agent-brain/config.yaml  # Restrict permissions
echo "config.yaml" >> .gitignore       # Exclude from version control

Method 2: Environment Variables

Set variables in your shell or .env file:

# Embedding configuration
export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large

# Summarization configuration
export SUMMARIZATION_PROVIDER=anthropic
export SUMMARIZATION_MODEL=claude-haiku-4-5-20251001

# API keys (as needed)
export OPENAI_API_KEY=sk-proj-...
export ANTHROPIC_API_KEY=sk-ant-...

# State directory (optional)
export AGENT_BRAIN_STATE_DIR=/custom/path/.agent-brain
export AGENT_BRAIN_URL=http://127.0.0.1:8000

Method 3: .env File

Create .agent-brain/.env in your project:

# Provider settings
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-large
SUMMARIZATION_PROVIDER=anthropic
SUMMARIZATION_MODEL=claude-haiku-4-5-20251001

# API keys
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...

Configuration Precedence

Resolution order (highest to lowest priority):

1. CLI options (--url, --port) 2. Environment variables (AGENT_BRAIN_URL, OPENAI_API_KEY) 3. Config file values (config.yaml) 4. Default values

Configuration Profiles

Fully Local (No API Keys)

Best for: Privacy, air-gapped environments, no API costs

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
SUMMARIZATION_PROVIDER=ollama
SUMMARIZATION_MODEL=llama4:scout
OLLAMA_BASE_URL=http://localhost:11434

Requirements: 1. Install Ollama: https://ollama.ai 2. Pull required models:

   ollama pull nomic-embed-text
   ollama pull llama4:scout

Cloud (Best Quality)

Best for: Production use, highest quality results

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

Mixed (Quality + Privacy)

Best for: Quality embeddings with local summarization

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-large
SUMMARIZATION_PROVIDER=ollama
SUMMARIZATION_MODEL=llama4:scout
OPENAI_API_KEY=sk-proj-...
OLLAMA_BASE_URL=http://localhost:11434

Budget-Conscious

Best for: Lower API costs while maintaining quality

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
SUMMARIZATION_PROVIDER=openai
SUMMARIZATION_MODEL=gpt-5-mini
OPENAI_API_KEY=sk-proj-...

Multi-Language

Best for: International content, multiple languages

EMBEDDING_PROVIDER=cohere
EMBEDDING_MODEL=embed-multilingual-v3.0
SUMMARIZATION_PROVIDER=anthropic
SUMMARIZATION_MODEL=claude-haiku-4-5-20251001
COHERE_API_KEY=...
ANTHROPIC_API_KEY=sk-ant-...

Provider-Specific Configuration

OpenAI Configuration

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-large  # or text-embedding-3-small
OPENAI_API_KEY=sk-proj-...
OPENAI_ORG_ID=org-...                   # Optional: organization ID
OPENAI_BASE_URL=https://api.openai.com  # Optional: custom endpoint

Available Models:

• text-embedding-3-large: 3072 dimensions, highest quality
• text-embedding-3-small: 1536 dimensions, faster, cheaper
• text-embedding-ada-002: 1536 dimensions, legacy

Cohere Configuration

EMBEDDING_PROVIDER=cohere
EMBEDDING_MODEL=embed-english-v3.0
COHERE_API_KEY=...

Available Models:

• embed-english-v3.0: English-optimized, 1024 dimensions
• embed-multilingual-v3.0: 100+ languages, 1024 dimensions
• embed-english-light-v3.0: Faster, smaller model

Ollama Configuration

EMBEDDING_PROVIDER=ollama
EMBEDDING_MODEL=nomic-embed-text
SUMMARIZATION_PROVIDER=ollama
SUMMARIZATION_MODEL=llama4:scout
OLLAMA_BASE_URL=http://localhost:11434  # Default Ollama URL

Setup:

# Install Ollama (macOS)
brew install ollama

# Install Ollama (Linux)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull embedding model
ollama pull nomic-embed-text

# Pull summarization model
ollama pull llama4:scout

Available Embedding Models:

• nomic-embed-text: General purpose, 768 dimensions
• mxbai-embed-large: High quality, 1024 dimensions
• all-minilm: Lightweight, fast

Available Summarization Models:

• llama4:scout: Meta's Llama 4 Scout - lightweight, fast
• mistral-small3.2: Mistral Small 3.2 - balanced
• qwen3-coder: Alibaba Qwen 3 Coder - code-focused
• gemma3: Google Gemma 3 - efficient
• deepseek-coder-v3: DeepSeek Coder V3 - code-focused

Anthropic Configuration

SUMMARIZATION_PROVIDER=anthropic
SUMMARIZATION_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_API_KEY=sk-ant-...

Available Models:

• claude-haiku-4-5-20251001: Fast, cost-effective
• claude-sonnet-4-5-20250514: Balanced quality/speed
• claude-opus-4-5-20251101: Highest quality

Gemini Configuration

SUMMARIZATION_PROVIDER=gemini
SUMMARIZATION_MODEL=gemini-3-flash
GOOGLE_API_KEY=...

Available Models:

• gemini-3-flash: Fast, efficient
• gemini-3-pro: Higher quality

Grok Configuration

SUMMARIZATION_PROVIDER=grok
SUMMARIZATION_MODEL=grok-4
XAI_API_KEY=...

SentenceTransformers Reranker Configuration (v8.0+)

Agent Brain supports two-stage retrieval with reranking for higher-precision results.

ENABLE_RERANKING=true
RERANKER_PROVIDER=sentence-transformers  # or "ollama"
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
RERANKER_TOP_K_MULTIPLIER=10
RERANKER_MAX_CANDIDATES=100

Reranker Providers:

YAML Configuration:

reranking:
  enabled: true
  provider: "sentence-transformers"
  model: "cross-encoder/ms-marco-MiniLM-L-6-v2"
  top_k_multiplier: 10
  max_candidates: 100

---

Verifying Configuration

# Show current configuration
agent-brain config show

# Verify providers are working
agent-brain verify

# Test embedding provider
agent-brain test-embedding "sample text"

# Test summarization provider
agent-brain test-summarize "sample code content"

Switching Providers

When switching providers, you may need to re-index documents if the embedding dimensions differ:

# Check current embedding dimensions
agent-brain status

# If switching embedding providers with different dimensions:
agent-brain reset --yes
agent-brain index /path/to/docs

Troubleshooting

API Key Issues

Error: Invalid API key

Resolution: Verify your API key is correct and has the necessary permissions.

Ollama Connection Failed

Error: Could not connect to Ollama at http://localhost:11434

Resolution:

# Check if Ollama is running
ollama list

# Start Ollama
ollama serve

Model Not Found

Error: Model 'model-name' not found

Resolution:

# For Ollama, pull the model
ollama pull model-name

# For cloud providers, verify model name spelling

Rate Limiting

Error: Rate limit exceeded

Resolution:

• Wait and retry
• Use a different provider temporarily
• Upgrade your API plan

Cost Considerations

Embedding Costs (per 1M tokens)

Summarization Costs (per 1M tokens)

Prices as of 2026, subject to change.

Agent Brain Troubleshooting Guide

Overview

This guide covers common issues and their solutions when using Agent Brain for document indexing and search.

Quick Diagnostics

Run these commands to diagnose common issues:

# Check server status
agent-brain status

# Check API keys are set
echo "OpenAI: ${OPENAI_API_KEY:+SET}"
echo "Anthropic: ${ANTHROPIC_API_KEY:+SET}"

# Check Python environment
which python
python --version

# Test basic connectivity
agent-brain query "test" --mode bm25

---

Server Issues

Server Won't Start

Symptoms:

• agent-brain start fails
• Error messages about missing modules
• Port already in use errors

Solutions:

Module Import Errors:

# Reinstall packages
pip install --force-reinstall agent-brain-rag agent-brain-cli

Port Already in Use:

# Find what's using the port
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or use auto-port (recommended)
agent-brain start

Permission Errors:

# Check directory permissions
ls -la .agent-brain/

# Fix permissions
chmod 755 .agent-brain/

Connection Refused Errors

Symptoms:

• Commands fail with connection errors
• "Unable to connect to server" messages

Solutions:

Start the Server:

agent-brain start
agent-brain status

Check Runtime File:

cat .agent-brain/runtime.json | jq '.base_url'

Override URL if Needed:

export DOC_SERVE_URL="http://localhost:49321"
agent-brain status

PostgreSQL Backend Issues

Connection refused (PostgreSQL):

• Confirm the container is running:

docker compose -f docker-compose.postgres.yml ps

• Check readiness:

docker compose -f docker-compose.postgres.yml exec postgres \
  pg_isready -U agent_brain -d agent_brain

pgvector extension missing:

• Use the pgvector image (pgvector/pgvector:pg16).
• If using another image, install the pgvector extension before start.

Pool exhaustion / too many connections:

• Increase pool_size and pool_max_overflow under storage.postgres.
• Ensure PostgreSQL max_connections is high enough for your workload.

Embedding dimension mismatch:

• If you change embedding models, reset and re-index:

agent-brain reset --yes
agent-brain index /path/to/docs

Stale Server State

Symptoms:

• runtime.json exists but server not responding
• Previous server crashed without cleanup

Solutions:

# Manual cleanup
rm .agent-brain/runtime.json
rm .agent-brain/lock.json
rm .agent-brain/pid

# Start fresh
agent-brain start

---

API Key Issues

Missing OpenAI API Key

Symptoms:

• Hybrid/vector queries fail with authentication errors
• Error: "No API key found for OpenAI"
• BM25 works but hybrid/vector don't

Solutions:

Set API Key:

export OPENAI_API_KEY="sk-proj-your-key-here"

Persistent Setup:

echo 'export OPENAI_API_KEY="sk-proj-..."' >> ~/.bashrc
source ~/.bashrc

Get API Key:

• Visit: https://platform.openai.com/account/api-keys

Invalid API Key Errors

Symptoms:

• Authentication failed messages
• 401 Unauthorized responses

Solutions:

Test Key Validity:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Verify Key Format:

# Should start with sk-proj- or sk-
echo $OPENAI_API_KEY | head -c 10

Check Account Credits:

• Visit: https://platform.openai.com/account/usage
• Ensure account has credits

Regenerate Key if Needed:

• Visit: https://platform.openai.com/account/api-keys
• Delete old key, create new one

---

Search Issues

No Documents Indexed

Symptoms:

• agent-brain status shows 0 documents
• All queries return empty results

Solutions:

Check Status:

agent-brain status
# Should show: Documents: > 0

Run Indexing:

agent-brain index /path/to/your/docs
# Wait for completion

Verify Document Path:

ls -la /path/to/your/docs
# Should contain .md, .txt, .pdf files

Check Supported Formats:

• Supported: Markdown (.md), Text (.txt), PDF (.pdf), Code files
• Not Supported: Word docs (.docx), images

No Search Results Found

Symptoms:

• Queries return empty results
• Documents are indexed but no matches

Solutions:

Lower Threshold:

# Default is 0.7, try lower values
agent-brain query "your search" --threshold 0.3

Try Different Modes:

# BM25 for exact matches
agent-brain query "exact term" --mode bm25 --threshold 0.1

# Vector for semantic search
agent-brain query "concept" --mode vector --threshold 0.5

Verify Content Exists:

# Search for common words
agent-brain query "the" --mode bm25 --threshold 0.01

BM25 Index Not Ready

Symptoms:

• BM25 queries fail with "index not initialized"
• Hybrid queries fail but vector works

Solutions:

Wait for Indexing:

agent-brain status
# Wait until indexing shows complete

Re-index:

agent-brain reset --yes
agent-brain index /path/to/docs

---

Performance Issues

Slow Query Performance

Symptoms:

• Queries take longer than expected
• Hybrid/vector queries > 2 seconds

Solutions:

Use BM25 for Speed:

# Fastest option, no API calls
agent-brain query "exact terms" --mode bm25

Reduce Result Count:

agent-brain query "search" --top-k 3

Check Network:

# Test OpenAI connectivity
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

Memory Issues

Symptoms:

• Server crashes with out of memory
• System becomes unresponsive

Solutions:

Restart with Clean State:

agent-brain stop
agent-brain reset --yes
agent-brain start
agent-brain index /path/to/docs

Monitor Resources:

ps aux | grep agent-brain

---

Installation Issues

Command Not Found

Symptoms:

• agent-brain: command not found

Solutions:

Check Installation:

pip list | grep agent-brain

Add to PATH:

export PATH="$HOME/.local/bin:$PATH"

Reinstall:

pip install --force-reinstall agent-brain-cli

Module Not Found

Symptoms:

• ModuleNotFoundError when running

Solutions:

Reinstall Packages:

pip install --force-reinstall agent-brain-rag agent-brain-cli

Check Python Environment:

which python
pip list | grep agent-brain

---

File Permission Issues

Symptoms:

• Cannot read documents during indexing
• Permission denied errors

Solutions:

Check Permissions:

ls -la /path/to/docs
chmod 644 /path/to/docs/*.md

Check Index Directory:

ls -la .agent-brain/
chmod 755 .agent-brain/

---

Diagnostic Commands Reference

Full System Check

# 1. Check installation
agent-brain --version

# 2. Check API keys
echo "OpenAI: ${OPENAI_API_KEY:+SET}"
echo "Anthropic: ${ANTHROPIC_API_KEY:+SET}"

# 3. Check server status
agent-brain status

# 4. Check runtime file
cat .agent-brain/runtime.json 2>/dev/null || echo "No runtime file"

# 5. Test BM25 (no API needed)
agent-brain query "test" --mode bm25 --threshold 0.01

# 6. Test vector (needs API)
agent-brain query "test" --mode vector --threshold 0.3

Environment Check

# Python environment
which python
python --version

# Package versions
pip show agent-brain-rag
pip show agent-brain-cli

# Network connectivity
ping -c 3 api.openai.com

---

Getting Help

If these solutions don't resolve your issue:

1. Run diagnostics and capture output 2. Include error messages (full text) 3. Describe your setup: OS, Python version, installation method 4. Report issues: https://github.com/SpillwaveSolutions/agent-brain-plugin/issues

---

File Watcher Issues (v8.0+)

Watcher Not Triggering Re-index

Symptoms:

• Files changed but no re-index job appears
• agent-brain jobs shows no auto-triggered jobs

Solutions:

# Verify folder has watch mode enabled
agent-brain folders list
# Look for "Watch: auto" column

# Re-add folder with watch mode
agent-brain folders add ./src --watch auto --include-code

# Check debounce interval (default 30s, changes within window are batched)
# Lower debounce for faster response
agent-brain folders add ./src --watch auto --debounce 10

Watcher Ignoring Certain Files

The watcher excludes: .git/, node_modules/, __pycache__/, dist/, build/, .next/, .nuxt/, coverage/, htmlcov/

These directories are intentionally excluded to avoid indexing build artifacts.

---

Embedding Cache Issues (v8.0+)

Low Cache Hit Rate

Symptoms:

• agent-brain cache status shows low hit rate
• Re-indexing is slow despite no content changes

Solutions:

# Check cache status
agent-brain cache status

# If switching embedding providers, clear old cache
agent-brain cache clear --yes

# Re-index to rebuild cache
agent-brain index /path/to/docs

Cache Disk Space

# Check cache size
agent-brain cache status --json | jq '.size_bytes'

# Clear if too large
agent-brain cache clear --yes

Configuration: Set EMBEDDING_CACHE_MAX_DISK_MB (default: 500MB) to limit disk usage.

---

Multi-Runtime Install Issues (v9.0+)

Install-Agent Not Finding Plugin Directory

Symptoms:

• agent-brain install-agent --agent claude fails with "plugin directory not found"

Solutions:

# Ensure agent-brain-plugin directory exists
ls agent-brain-plugin/commands/

# Or install from an existing Claude plugin installation
ls ~/.claude/plugins/agent-brain/commands/

Uninstall Not Removing Files

# Uninstall for specific runtime
agent-brain uninstall --agent claude

# Manual cleanup if needed
rm -rf .claude/plugins/agent-brain

---

Prevention Tips

• Always verify agent-brain status before searching
• Keep API keys secure and never commit them
• Run agent-brain stop when done to free resources
• Use BM25 mode when you don't need semantic search
• Lower threshold values when getting no results
• Re-index after major document changes
• Use agent-brain cache status to monitor embedding cache health
• Enable file watcher (--watch auto) for automatic re-indexing