Using Agent Brain

Agent Brain Expert Skill

Expert-level skill for Agent Brain document search with five modes: BM25 (keyword), Vector (semantic), Hybrid (fusion), Graph (knowledge graph), and Multi (comprehensive fusion).

Contents

• Search Modes
• Mode Selection Guide
• GraphRAG (Knowledge Graph)
• Indexing & Folder Management
• Content Injection
• Job Queue Management
• Server Management
• Cache Management
• When Not to Use
• Best Practices
• Reference Documentation

---

Search Modes

Mode Parameters

---

Mode Selection Guide

Use BM25 When

Searching for exact technical terms:

agent-brain query "recursiveCharacterTextSplitter" --mode bm25
agent-brain query "ValueError: invalid token" --mode bm25
agent-brain query "def process_payment" --mode bm25

Counter-example - Wrong mode choice:

# BM25 is wrong for conceptual queries
agent-brain query "how does error handling work" --mode bm25  # Wrong
agent-brain query "how does error handling work" --mode vector  # Correct

Use Vector When

Searching for concepts or natural language:

agent-brain query "best practices for error handling" --mode vector
agent-brain query "how to implement caching" --mode vector

Counter-example - Wrong mode choice:

# Vector is wrong for exact function names
agent-brain query "getUserById" --mode vector  # Wrong - may miss exact match
agent-brain query "getUserById" --mode bm25    # Correct - finds exact match

Use Hybrid When

Need comprehensive results (default mode):

agent-brain query "OAuth implementation" --mode hybrid --alpha 0.6
agent-brain query "database connection pooling" --mode hybrid

Alpha tuning:

• --alpha 0.3 - More keyword weight (technical docs)
• --alpha 0.7 - More semantic weight (conceptual docs)

Use Graph When

Exploring relationships and dependencies:

agent-brain query "what functions call process_payment" --mode graph
agent-brain query "classes that inherit from BaseService" --mode graph --traversal-depth 3
agent-brain query "modules that import authentication" --mode graph

Prerequisite: Requires ENABLE_GRAPH_INDEX=true during server startup.

Use Multi When

Need the most comprehensive results:

agent-brain query "complete payment flow implementation" --mode multi --include-relationships

---

GraphRAG (Knowledge Graph)

GraphRAG enables relationship-aware retrieval by building a knowledge graph from indexed documents.

Enabling GraphRAG

export ENABLE_GRAPH_INDEX=true
agent-brain start

Graph Query Types

See Graph Search Guide for detailed usage.

---

Indexing & Folder Management

Indexing with File Type Presets

# Index only Python files
agent-brain index ./src --include-type python

# Index Python and documentation
agent-brain index ./project --include-type python,docs

# Index all code files
agent-brain index ./repo --include-type code

# Force full re-index (bypass incremental)
agent-brain index ./docs --force

Use agent-brain types list to see all 14 available presets.

Folder Management

agent-brain folders list                    # List indexed folders with chunk counts
agent-brain folders add ./docs              # Add folder (triggers indexing)
agent-brain folders add ./src --include-type python  # Add with preset filter
agent-brain folders remove ./old-docs --yes # Remove folder and evict chunks

Incremental Indexing

Re-indexing a folder automatically detects changes:

• Unchanged files are skipped (mtime + SHA-256 checksum)
• Changed files have old chunks evicted and new ones created
• Deleted files have their chunks automatically removed
• Use --force to bypass manifest and fully re-index

---

Content Injection

Enrich chunk metadata during indexing with custom Python scripts or static JSON metadata.

When to Use

• Tag chunks with project/team/category metadata
• Classify chunks by content type
• Add custom fields for filtered search
• Merge folder-level metadata into all chunks

Basic Usage

# Inject via Python script
agent-brain inject ./docs --script enrich.py

# Inject via static JSON metadata
agent-brain inject ./src --folder-metadata project-meta.json

# Validate script before indexing
agent-brain inject ./docs --script enrich.py --dry-run

Injector Script Protocol

Scripts export a process_chunk(chunk: dict) -> dict function:

def process_chunk(chunk: dict) -> dict:
    chunk["project"] = "my-project"
    chunk["team"] = "backend"
    return chunk

• Values must be scalars (str, int, float, bool)
• Per-chunk exceptions are logged as warnings, not fatal
• See docs/INJECTOR_PROTOCOL.md for the full specification

---

Job Queue Management

Indexing runs asynchronously via a job queue. Monitor and manage jobs:

agent-brain jobs                    # List all jobs
agent-brain jobs --watch            # Live polling every 3s
agent-brain jobs <job_id>           # Job details + eviction summary
agent-brain jobs <job_id> --cancel  # Cancel a job

Eviction Summary

When re-indexing, job details show what changed:

Eviction Summary:
  Files added:     3
  Files changed:   2
  Files deleted:   1
  Files unchanged: 42
  Chunks evicted:  15
  Chunks created:  25

This confirms incremental indexing is working efficiently.

---

Server Management

Quick Start

agent-brain init              # Initialize project (first time)
agent-brain start    # Start server
agent-brain index ./docs      # Index documents
agent-brain query "search"    # Search
agent-brain stop              # Stop when done

Progress Checklist:

• [ ] /agent-brain:agent-brain-init succeeded
• [ ] /agent-brain:agent-brain-status shows healthy
• [ ] Document count > 0
• [ ] Query returns results (or "no matches" - not error)

Lifecycle Commands

Pre-Query Validation

Before querying, verify setup:

agent-brain status

Expected:

• Status: healthy
• Documents: > 0
• Provider: configured

Counter-example - Querying without validation:

# Wrong - querying without checking status
agent-brain query "search term"  # May fail if server not running

# Correct - validate first
agent-brain status && agent-brain query "search term"

See Server Discovery Guide for multi-instance details.

---

Cache Management

The embedding cache automatically stores computed embeddings to avoid redundant API calls during reindexing. No setup is required — the cache is active by default.

When to Check Cache Status

• After indexing — verify cache is working and hit rate is growing
• When queries seem slow — a low or zero hit rate means embeddings are being recomputed on every reindex
• To monitor cache growth — track disk usage over time for large indexes

agent-brain cache status

A healthy cache shows:

• Hit rate > 80% after the first full reindex cycle
• Growing disk entries over time as more content is indexed
• Low misses relative to hits

When to Clear the Cache

• After changing embedding provider or model — prevents dimension mismatches and stale cached vectors
• Suspected cache corruption — if embeddings seem incorrect or search quality degrades unexpectedly
• To force fresh embeddings — when you need to ensure all vectors reflect the current provider/model

# Clear with confirmation prompt
agent-brain cache clear

# Clear without prompt (use in scripts)
agent-brain cache clear --yes

Cache is Automatic

No configuration is required. Embeddings are cached on first compute and reused on subsequent reindexes of unchanged content (identified by SHA-256 hash). The cache complements the ManifestTracker — files that haven't changed on disk won't need to recompute embeddings.

See the API Reference for GET /index/cache and DELETE /index/cache endpoint details, including response schemas.

---

When Not to Use

This skill focuses on searching and querying. Do NOT use for:

• Installation - Use configuring-agent-brain skill
• API key configuration - Use configuring-agent-brain skill
• Server setup issues - Use configuring-agent-brain skill
• Provider configuration - Use configuring-agent-brain skill

Scope boundary: This skill assumes Agent Brain is already installed, configured, and the server is running with indexed documents.

---

Best Practices

1. Mode Selection: BM25 for exact terms, Vector for concepts, Hybrid for comprehensive, Graph for relationships 2. Threshold Tuning: Start at 0.7, lower to 0.3-0.5 for more results 3. Server Discovery: Use runtime.json rather than assuming port 8000 4. Resource Cleanup: Run agent-brain stop when done 5. Source Citation: Always reference source filenames in responses 6. Graph Queries: Use graph mode for "what calls X", "what imports Y" patterns 7. Traversal Depth: Start with depth 2, increase to 3-4 for deeper chains 8. File Type Presets: Use --include-type python,docs instead of manual glob patterns 9. Incremental Indexing: Re-index without --force for efficient updates 10. Injection Validation: Always --dry-run injector scripts before full indexing 11. Job Monitoring: Use agent-brain jobs --watch for long-running index jobs

---

Reference Documentation

---

Limitations

• Vector/hybrid/graph/multi modes require embedding provider configured
• Graph mode requires additional memory (~500MB extra)
• Supported formats: Markdown, PDF, plain text, code files (Python, JS, TS, Java, Go, Rust, C, C++)
• Not supported: Word docs (.docx), images
• Server requires ~500MB RAM for typical collections (~1GB with graph)
• Ollama requires local installation and model download

Agent Brain API Reference

Base URL

Discover from runtime file (multi-instance mode):

cat .agent-brain/runtime.json | jq -r '.base_url'
# Example: http://127.0.0.1:54321

Default (single instance): http://127.0.0.1:8000

Override via environment: DOC_SERVE_URL

---

Health Endpoints

GET /health

Check server health status.

Response:

{
  "status": "healthy | indexing | degraded | unhealthy",
  "message": "Server is running and ready for queries",
  "version": "1.0.0",
  "timestamp": "2024-12-15T10:00:00Z"
}

Status Values:

• healthy - Server ready for queries
• indexing - Indexing in progress, queries may fail
• degraded - Server up but some services unavailable
• unhealthy - Server not operational

---

GET /health/status

Get detailed indexing status.

Response:

{
  "total_documents": 100,
  "total_chunks": 500,
  "indexing_in_progress": false,
  "current_job_id": null,
  "progress_percent": 0.0,
  "last_indexed_at": "2024-12-15T10:00:00Z",
  "indexed_folders": ["/docs/kubernetes", "/docs/python"],
  "graph_index": {
    "enabled": true,
    "entity_count": 450,
    "relationship_count": 1200,
    "store_type": "simple"
  }
}

Graph Index Fields (when ENABLE_GRAPH_INDEX=true):

• enabled - Whether graph indexing is active
• entity_count - Number of extracted entities (functions, classes, modules)
• relationship_count - Number of relationships (calls, imports, inherits)
• store_type - Graph store backend (simple or kuzu)

---

Query Endpoints

POST /query

Execute a semantic search on indexed documents.

Request Body:

{
  "query": "how to configure pod networking",
  "top_k": 5,
  "similarity_threshold": 0.7,
  "mode": "hybrid",
  "alpha": 0.5,
  "traversal_depth": 2,
  "include_relationships": false
}

Response:

{
  "results": [
    {
      "text": "Pod networking in Kubernetes allows...",
      "source": "docs/kubernetes/networking.md",
      "score": 0.92,
      "vector_score": 0.92,
      "bm25_score": 0.85,
      "graph_score": 0.78,
      "chunk_id": "chunk_abc123",
      "metadata": {
        "page": 1,
        "section": "Pod Networking"
      },
      "relationships": [
        {
          "type": "CALLS",
          "target": "configure_network",
          "source_entity": "setup_pod"
        },
        {
          "type": "IMPORTS",
          "target": "kubernetes.networking",
          "source_entity": "pod_manager"
        }
      ]
    }
  ],
  "query_time_ms": 45.2,
  "total_results": 1
}

Response Fields:

• graph_score - Graph relevance score (only present in graph/multi modes)
• relationships - Entity relationships (only when include_relationships=true)

Error Responses:

---

GET /query/count

Get the total number of indexed document chunks.

Response:

{
  "total_chunks": 500,
  "ready": true
}

---

Index Endpoints

POST /index

Start indexing documents from a folder. The system uses stable IDs based on file paths and chunk indices, meaning re-indexing the same folder will update existing records (upsert) rather than creating duplicates.

Request Body:

{
  "folder_path": "/path/to/documents",
  "recursive": true,
  "chunk_size": 512,
  "chunk_overlap": 50
}

---

POST /index/add

Add documents incrementally without clearing existing index.

Request Body:

{
  "folder_path": "/path/to/more/documents",
  "recursive": true
}

---

DELETE /index

Clear all indexed documents.

Response:

{
  "job_id": "reset",
  "status": "completed",
  "message": "Index cleared successfully"
}

---

Cache Endpoints

GET /index/cache

Retrieve embedding cache statistics for the current session and persisted disk cache.

Response:

{
  "hits": 5432,
  "misses": 800,
  "hit_rate": 0.8712,
  "mem_entries": 500,
  "entry_count": 1234,
  "size_bytes": 15531008
}

Response Fields:

Note: Both /index/cache and /index/cache/ are accepted (trailing-slash alias). Use the no-trailing-slash form (/index/cache) to avoid 307 redirects.

Error Responses:

---

DELETE /index/cache

Clear all cached embeddings from the disk cache. The next reindex will recompute embeddings via the configured embedding provider.

Response:

{
  "count": 1234,
  "size_bytes": 15531008,
  "size_mb": 14.81
}

Response Fields:

Note: Both /index/cache and /index/cache/ are accepted (trailing-slash alias).

Error Responses:

---

OpenAPI Documentation

Interactive API documentation available at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json

---

CLI Commands Reference

The agent-brain CLI provides these commands:

# Server lifecycle
agent-brain init                      # Initialize project config
agent-brain start            # Start server with auto-port
agent-brain stop                      # Stop running server
agent-brain list                      # List all running instances

# Check server health and status
agent-brain status
agent-brain status --json

# Query documents
agent-brain query "search text"
agent-brain query "search text" --mode hybrid --top-k 10
agent-brain query "search text" --mode graph --traversal-depth 3
agent-brain query "search text" --mode multi --include-relationships
agent-brain query "search text" --json

# Index documents
agent-brain index /path/to/docs
agent-brain index /path/to/docs --recursive

# Folder management
agent-brain folders add ./docs                          # Index a folder
agent-brain folders add ./src --include-code            # Index with code
agent-brain folders add ./src --watch auto              # Enable auto-reindex
agent-brain folders add ./src --watch auto --debounce 10  # Custom debounce
agent-brain folders list                                # Show all folders
agent-brain folders remove ./docs --yes                 # Remove folder

# Job queue
agent-brain jobs                      # List all jobs
agent-brain jobs --watch              # Watch queue live
agent-brain jobs JOB_ID               # Show job details
agent-brain jobs JOB_ID --cancel      # Cancel a job

# Clear index
agent-brain reset --yes

# Embedding cache
agent-brain cache status             # View cache metrics (human-readable)
agent-brain cache status --json      # View metrics as JSON
agent-brain cache clear              # Clear cache (prompts for confirmation)
agent-brain cache clear --yes        # Clear cache (skips confirmation)

Folder Options (folders add):

• --include-code - Index source code files alongside documents
• --watch MODE - Watch mode: auto (enable file watching) or off (default)
• --debounce N - Debounce interval in seconds for file watching (default: 30)

Folders List Output:

Jobs List Output:

Query Options:

• --mode MODE - Search mode: bm25, vector, hybrid, graph, multi
• --top-k N - Number of results (default: 5)
• --threshold F - Minimum similarity (default: 0.7)
• --alpha F - Hybrid balance, 0=BM25, 1=Vector (default: 0.5)
• --traversal-depth N - Graph traversal depth (default: 2)
• --include-relationships - Include entity relationships in output

File Type Presets (v7.0+):

agent-brain types list                          # Show available presets
agent-brain index ./src --include-type python   # Index with preset filter
agent-brain index ./src --include-type typescript

Content Injection (v7.0+):

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

Configuration (v8.0+):

agent-brain config show                         # Show current configuration
agent-brain config set embedding.provider openai  # Set a config value

Multi-Runtime Install (v9.0+):

agent-brain install-agent --agent claude        # Install for Claude
agent-brain install-agent --agent opencode      # Install for OpenCode
agent-brain install-agent --agent gemini        # Install for Gemini
agent-brain install-agent --agent codex         # Install for Codex
agent-brain install-agent --agent skill-runtime --dir /path  # Generic
agent-brain install-agent --agent claude --dry-run  # Preview
agent-brain install-agent --agent claude --scope global  # Global install
agent-brain uninstall --agent claude            # Uninstall

Global Options:

• --url URL - Server URL (default: http://127.0.0.1:8000)
• --json - Output as JSON
• --help - Show help message

---

File Watcher

Folders configured with watch_mode: auto are automatically re-indexed when files change. This eliminates the need to manually re-run indexing after edits.

How it works:

• After agent-brain folders add ./src --watch auto, the server monitors the folder for file changes
• Per-folder debounce collapses rapid changes (e.g., git checkout, IDE save-all) into a single reindex job
• Watcher-triggered jobs use incremental diff (force=False) for efficiency -- only changed files are re-processed
• Jobs created by the watcher show source: auto in the jobs list

Excluded directories: The watcher ignores changes in: .git/, node_modules/, __pycache__/, dist/, build/, .next/, .nuxt/, coverage/, htmlcov/

Configuration:

• Default debounce: 30 seconds (configurable via AGENT_BRAIN_WATCH_DEBOUNCE_SECONDS)
• Per-folder override: --debounce N on folders add

Examples:

# Enable auto-reindex with default 30s debounce
agent-brain folders add ./src --watch auto --include-code

# Custom 10-second debounce for fast iteration
agent-brain folders add ./src --watch auto --debounce 10

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

BM25 Keyword Search Guide

Overview

BM25 (Best Matching 25) is a keyword-based search algorithm that finds exact term matches in your indexed documents. It's excellent for technical queries where you need precise word matching rather than semantic understanding.

When to Use BM25 Search

Choose BM25 when:

• Looking for specific function names, class names, or API endpoints
• Searching for error codes, status codes, or technical terms
• Need exact word matches rather than conceptual similarity
• Working with code documentation, API references, or technical specifications
• The query contains specific technical jargon or identifiers

Examples of BM25 queries:

• "AuthenticationError" - Find exact error class references
• "HTTP 404" - Find status code documentation
• "recursiveCharacterTextSplitter" - Find specific function names
• "OAuth2 flow" - Find exact OAuth implementation details

How to Use BM25 Search

CLI Usage

# Basic BM25 search
agent-brain query "your exact terms" --mode bm25

# With custom threshold (lower for more results)
agent-brain query "functionName" --mode bm25 --threshold 0.1

# With result count limit
agent-brain query "error code" --mode bm25 --top-k 10

API Usage

# POST /query endpoint
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AuthenticationError",
    "mode": "bm25",
    "threshold": 0.2,
    "top_k": 5
  }'

BM25 Search Options

Why Choose BM25 Over Other Modes

BM25 Advantages:

• ⚡ Fast: ~10-20ms response time
• 🎯 Precise: Finds exact word matches
• 🔍 Predictable: Results based on term frequency and document length
• 💾 Lightweight: No API keys required

When BM25 is better than Hybrid:

• Searching for specific identifiers (function names, error codes)
• Technical documentation with exact terminology
• When you need guaranteed exact matches
• Performance-critical applications

When BM25 is better than Vector:

• Non-English text or technical jargon
• When semantic meaning could be misleading
• Code search and technical documentation
• Exact string matching requirements

BM25 Algorithm Details

BM25 scores documents based on: 1. Term Frequency (TF): How often the search term appears 2. Inverse Document Frequency (IDF): How rare the term is across documents 3. Document Length Normalization: Shorter documents score higher for same term frequency

Formula: score = Σ IDF(q_i) × (TF(q_i,D) × (k₁ + 1)) / (TF(q_i,D) + k₁ × (1 - b + b × |D|/avgDL))

Where:

• q_i: Query terms
• D: Document
• k₁ = 1.5 (term frequency saturation)
• b = 0.75 (length normalization factor)

Example Queries and Results

Example 1: Function Name Search

Query: agent-brain query "recursiveCharacterTextSplitter" --mode bm25

Response:

{
  "results": [
    {
      "text": "The recursiveCharacterTextSplitter splits text recursively using character separators...",
      "source": "/docs/api/text-splitters.md",
      "score": 0.85,
      "vector_score": null,
      "bm25_score": 0.85,
      "chunk_id": "chunk_123",
      "metadata": {
        "file_name": "text-splitters.md",
        "chunk_index": 0
      }
    }
  ],
  "query_time_ms": 12.5,
  "total_results": 1
}

Example 2: Error Code Search

Query: agent-brain query "HTTP 404" --mode bm25

Response:

{
  "results": [
    {
      "text": "HTTP 404 Not Found indicates the requested resource could not be found...",
      "source": "/docs/api/http-status-codes.md",
      "score": 0.92,
      "vector_score": null,
      "bm25_score": 0.92,
      "chunk_id": "chunk_456",
      "metadata": {
        "file_name": "http-status-codes.md",
        "chunk_index": 2
      }
    },
    {
      "text": "404 errors commonly occur when:\n- URL is mistyped\n- Resource was deleted...",
      "source": "/docs/troubleshooting/404-errors.md",
      "score": 0.78,
      "vector_score": null,
      "bm25_score": 0.78,
      "chunk_id": "chunk_789",
      "metadata": {
        "file_name": "404-errors.md",
        "chunk_index": 0
      }
    }
  ],
  "query_time_ms": 15.2,
  "total_results": 2
}

Performance Characteristics

• Response Time: 10-50ms (fastest of all modes)
• CPU Usage: Low (pure algorithmic scoring)
• Memory Usage: Minimal (uses pre-built BM25 index)
• Scalability: Excellent (index built once, queried many times)

Best Practices

1. Use exact terms: BM25 works best with specific words, not general concepts 2. Lower threshold for technical searches: Technical docs may need threshold 0.1-0.3 3. Combine with domain knowledge: Know what terms are likely to appear in your docs 4. Use for code search: Perfect for finding function definitions, class names, imports

Common Issues

• No results found: Try lowering the threshold or using different terminology
• Too many results: Increase threshold or add more specific terms
• Index not ready: Ensure documents are indexed before searching (agent-brain status)

Integration Examples

In Scripts

#!/bin/bash
# Search for specific error codes
agent-brain query "$1" --mode bm25 --json | jq '.results[0].text'

With Other Tools

# Find all mentions of a function
agent-brain query "myFunction" --mode bm25 --json | jq -r '.results[].source'

API Integration

import requests

response = requests.post('http://localhost:8000/query/', json={
    'query': 'AuthenticationError',
    'mode': 'bm25',
    'threshold': 0.2
})
results = response.json()['results']

Graph Search Guide

Overview

Graph search (GraphRAG) enables relationship-aware retrieval by building a knowledge graph from your documents. Unlike traditional search that finds content based on text similarity, graph search discovers entities (functions, classes, modules) and their relationships (calls, imports, inherits), allowing you to explore code dependencies and architectural connections. You can run graph-only queries or multi-mode fusion that blends vector + BM25 + graph with Reciprocal Rank Fusion (RRF).

When to Use Graph Search

Choose `graph` mode when:

• Exploring code dependencies ("what calls this function?")
• Understanding inheritance hierarchies ("what extends BaseService?")
• Finding import relationships ("what modules import authentication?")
• Tracing data flow through code paths
• Answering "how does X connect to Y?" questions

Choose `multi` mode when:

• Need the most comprehensive results combining all retrieval methods
• Want both content matches AND relationship context
• Investigating complex code paths with semantic understanding
• Uncertain which mode would work best

Avoid graph mode when:

• Looking for specific text content (use bm25)
• Searching for conceptual explanations (use vector)
• Graph indexing is not enabled

How Graph Search Works

Entity & Relationship Extraction

During indexing, Agent Brain extracts:

Relationship Types

Relationships between entities are automatically detected:

Graph Traversal

When you query, the system: 1. Finds entities matching your query 2. Traverses the graph to find connected entities 3. Returns results ranked by graph relevance 4. Optionally includes relationship metadata

How to Use Graph Search

CLI Usage

# Basic graph search
agent-brain query "what calls process_payment" --mode graph

# With more results
agent-brain query "classes inheriting from BaseService" --mode graph --top-k 10

# Lower threshold for broader results
agent-brain query "auth module dependencies" --mode graph --threshold 0.2

# Multi-mode (vector + bm25 + graph via RRF)
agent-brain query "complete payment flow" --mode multi --top-k 10

API Usage

# Graph search
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what functions call authenticate_user",
    "mode": "graph",
    "top_k": 10,
    "similarity_threshold": 0.3
  }'

# Multi-mode search
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "complete authentication implementation",
    "mode": "multi",
    "top_k": 10,
    "similarity_threshold": 0.3
  }'

Graph Search Options

Note: Graph search returns relationship metadata in the result's metadata field when available.

Enabling GraphRAG

GraphRAG must be explicitly enabled during server startup:

Environment Variables (server)

# Required: master switch (default: false)
export ENABLE_GRAPH_INDEX=true

# Optional backends
export GRAPH_STORE_TYPE=simple      # or kuzu
export GRAPH_INDEX_PATH=./graph_index

# Extraction controls
export GRAPH_USE_CODE_METADATA=true
export GRAPH_USE_LLM_EXTRACTION=true
export GRAPH_MAX_TRIPLETS_PER_CHUNK=10
export GRAPH_EXTRACTION_MODEL=claude-haiku-4-5

# Query behavior
export GRAPH_TRAVERSAL_DEPTH=2
export GRAPH_RRF_K=60               # RRF constant for multi mode

Configuration File (.env)

# .env file in project root
ENABLE_GRAPH_INDEX=true
GRAPH_STORE_TYPE=simple
GRAPH_INDEX_PATH=./graph_index
GRAPH_USE_CODE_METADATA=true
GRAPH_USE_LLM_EXTRACTION=true
GRAPH_MAX_TRIPLETS_PER_CHUNK=10
GRAPH_TRAVERSAL_DEPTH=2
GRAPH_EXTRACTION_MODEL=claude-haiku-4-5

Optional Dependencies

• Default simple store: included.
• Enhanced extraction: pip install "agent-brain-rag[graphrag]"
• Kuzu backend: pip install "agent-brain-rag[graphrag-kuzu]"

Starting with Graph Enabled

# Set environment and start
export ENABLE_GRAPH_INDEX=true
agent-brain start

# Verify graph is enabled
agent-brain status --json | jq '.graph_index'

Example Queries and Results

Example 1: Finding Function Callers

Query: agent-brain query "what calls process_payment" --mode graph --top-k 10

Response:

{
  "results": [
    {
      "text": "def checkout_handler(request):\n    ...\n    result = process_payment(order)\n    ...",
      "source": "/src/handlers/checkout.py",
      "score": 0.95,
      "graph_score": 0.95,
      "chunk_id": "chunk_checkout_001",
      "relationships": [
        {
          "type": "CALLS",
          "source_entity": "checkout_handler",
          "target": "process_payment"
        }
      ]
    },
    {
      "text": "class PaymentProcessor:\n    def handle_order(self, order):\n        return process_payment(order.payment_info)",
      "source": "/src/services/payment_processor.py",
      "score": 0.89,
      "graph_score": 0.89,
      "chunk_id": "chunk_payment_002",
      "relationships": [
        {
          "type": "CALLS",
          "source_entity": "PaymentProcessor.handle_order",
          "target": "process_payment"
        }
      ]
    }
  ],
  "query_time_ms": 820.5,
  "total_results": 2
}

Example 2: Exploring Class Hierarchy

Query: agent-brain query "classes that inherit from BaseService" --mode graph --top-k 10

Response:

{
  "results": [
    {
      "text": "class AuthService(BaseService):\n    def authenticate(self, credentials):\n        ...",
      "source": "/src/services/auth_service.py",
      "score": 0.92,
      "graph_score": 0.92,
      "relationships": [
        {
          "type": "INHERITS",
          "source_entity": "AuthService",
          "target": "BaseService"
        }
      ]
    },
    {
      "text": "class PaymentService(BaseService):\n    def process(self, payment):\n        ...",
      "source": "/src/services/payment_service.py",
      "score": 0.91,
      "graph_score": 0.91,
      "relationships": [
        {
          "type": "INHERITS",
          "source_entity": "PaymentService",
          "target": "BaseService"
        }
      ]
    }
  ],
  "query_time_ms": 650.3,
  "total_results": 2
}

Example 3: Multi-Mode Comprehensive Search

Query: agent-brain query "authentication flow implementation" --mode multi --top-k 10

Response:

{
  "results": [
    {
      "text": "The authentication flow starts with validate_credentials(), which calls authenticate_user()...",
      "source": "/docs/auth-guide.md",
      "score": 0.94,
      "vector_score": 0.96,
      "bm25_score": 0.88,
      "graph_score": 0.91,
      "relationships": []
    },
    {
      "text": "def authenticate_user(username, password):\n    user = get_user(username)\n    if verify_password(password, user.hash):\n        return create_session(user)",
      "source": "/src/auth/authenticator.py",
      "score": 0.92,
      "vector_score": 0.85,
      "bm25_score": 0.94,
      "graph_score": 0.97,
      "relationships": [
        {
          "type": "CALLS",
          "source_entity": "authenticate_user",
          "target": "get_user"
        },
        {
          "type": "CALLS",
          "source_entity": "authenticate_user",
          "target": "verify_password"
        },
        {
          "type": "CALLS",
          "source_entity": "authenticate_user",
          "target": "create_session"
        }
      ]
    }
  ],
  "query_time_ms": 1850.7,
  "total_results": 2
}

Graph Store Types

Simple Store (Default)

• In-memory graph storage
• Fast queries, no external dependencies
• Data persists in JSON file
• Best for: Development, small-medium codebases

GRAPH_STORE_TYPE=simple

Kuzu Store (Production)

• Persistent graph database
• Better performance for large graphs
• ACID compliant
• Best for: Production, large codebases

GRAPH_STORE_TYPE=kuzu

Performance Considerations

Response Times

Memory Usage

• Graph index adds ~200-500MB for typical codebases
• Kuzu store uses disk-based storage for large graphs
• Entity count scales with code complexity

Optimization Tips

1. Limit traversal depth: Start with 2, increase only if needed 2. Use graph mode for relationships: Skip vector/BM25 overhead 3. Index selectively: Focus on code files, skip generated content 4. Consider Kuzu: For codebases with 10k+ entities

Comparison: Graph vs Other Modes

Common Issues

Graph Index Not Available

Error: Graph index not enabled

Solution: Set ENABLE_GRAPH_INDEX=true and restart the server.

No Relationships Found

Possible causes:

• Documents haven't been re-indexed after enabling graph
• Query doesn't match any entities
• Traversal depth too shallow

Solution: Re-index documents and try lowering --threshold (e.g., --threshold 0.1).

Slow Graph Queries

Possible causes:

• Large graph with many relationships
• High traversal depth
• Simple store with large dataset

Solution: Reduce traversal depth or switch to Kuzu store.

Best Practices

1. Enable graph for code-heavy projects: Most valuable for source code exploration 2. Use multi mode for comprehensive searches: Combines all retrieval strengths 3. Start with traversal depth 2: Increase for deeper dependency chains 4. Include relationships for debugging: Helps understand result relevance 5. Monitor entity/relationship counts: Use /health/status to track graph size

Hybrid Search Guide

Overview

Hybrid search combines the best of both vector semantic search and BM25 keyword search using Relative Score Fusion. It provides the most robust retrieval by leveraging both semantic understanding and exact term matching, then intelligently combining the results.

When to Use Hybrid Search

Choose hybrid search when:

• You want the most comprehensive and accurate results
• The query combines both conceptual elements and specific technical terms
• You're unsure which search mode would work better
• You need high-quality results for critical applications
• The query involves both natural language and technical jargon

Examples of hybrid queries:

• "how to implement OAuth2 authentication with JWT tokens" - Combines concept + technical terms
• "troubleshooting HTTP 500 errors in production" - Error codes + troubleshooting concepts
• "best practices for recursive text splitting algorithms" - Methodology + specific algorithms
• "configuring database connection pooling for high traffic" - Configuration + technical terms

How to Use Hybrid Search

CLI Usage

# Basic hybrid search (default mode)
agent-brain query "implement authentication with error handling"

# With alpha weighting (70% vector, 30% BM25)
agent-brain query "oauth flow implementation" --alpha 0.7

# Show individual scores for debugging
agent-brain query "troubleshooting guide" --scores

# Custom settings for precision
agent-brain query "api documentation" --alpha 0.8 --threshold 0.6 --top-k 8

API Usage

# POST /query endpoint (default hybrid)
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication implementation guide",
    "alpha": 0.6,
    "threshold": 0.5
  }'

# Explicit hybrid mode
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "error handling patterns",
    "mode": "hybrid",
    "alpha": 0.7,
    "top_k": 10
  }'

Hybrid Search Options

Why Choose Hybrid Over Other Modes

Hybrid Advantages:

• 🎯 Highest Quality: Combines strengths of both approaches
• ⚖️ Balanced Results: Semantic understanding + exact matching
• 🎛️ Tunable: Alpha parameter for optimization
• 📊 Transparent: Individual scores for debugging
• 🏆 Recommended Default: Best overall performance for most queries

When Hybrid is better than Vector-only:

• Queries contain specific technical terms that vector search might miss
• Need guaranteed exact matches alongside semantic understanding
• Working with mixed technical/conceptual content

When Hybrid is better than BM25-only:

• Queries involve natural language or conceptual elements
• Want to find related content beyond exact keyword matches
• Technical terms might vary or use synonyms

Alpha Weighting System

The alpha parameter controls the balance between vector and BM25 search:

• `alpha = 1.0`: 100% vector search (pure semantic)
• `alpha = 0.8`: 80% vector, 20% BM25 (mostly semantic, some keyword boost)
• `alpha = 0.5`: 50% vector, 50% BM25 (balanced - recommended default)
• `alpha = 0.3`: 20% vector, 80% BM25 (mostly keyword, some semantic boost)
• `alpha = 0.0`: 100% BM25 search (pure keyword)

Choosing Alpha Values:

• Technical documentation: Try alpha = 0.3-0.4 (favor BM25 for exact terms)
• Conceptual guides: Try alpha = 0.7-0.8 (favor vector for meaning)
• Mixed content: Keep alpha = 0.5 (balanced approach)
• API references: Try alpha = 0.4 (technical terms + some context)
• Tutorials: Try alpha = 0.6 (explanations + specific code)

Fusion Algorithm Details

Hybrid search uses Relative Score Fusion:

1. Execute Both Searches: Run vector and BM25 searches in parallel 2. Normalize Scores: Convert both score ranges to 0.0-1.0 scale 3. Weighted Combination: final_score = alpha × vector_score + (1-alpha) × bm25_score 4. Re-rank Results: Sort by combined scores 5. Deduplication: Remove duplicate results from overlapping matches

Benefits:

• Maintains ranking quality from both algorithms
• Allows fine-grained control via alpha parameter
• Provides best-of-both-worlds results
• Mathematically sound combination approach

Example Queries and Results

Example 1: Technical Implementation Query

Query: agent-brain query "implement OAuth2 authentication with JWT tokens" --alpha 0.6 --scores

Response:

{
  "results": [
    {
      "text": "OAuth2 implementation guide: 1) Register application with OAuth provider, 2) Implement authorization code flow, 3) Handle token refresh, 4) Validate JWT tokens...",
      "source": "/docs/security/oauth-implementation.md",
      "score": 0.89,
      "vector_score": 0.85,
      "bm25_score": 0.93,
      "chunk_id": "chunk_123",
      "metadata": {
        "file_name": "oauth-implementation.md",
        "chunk_index": 0
      }
    },
    {
      "text": "JWT token structure: header.payload.signature - use HS256 for HMAC, RS256 for RSA signatures...",
      "source": "/docs/security/jwt-guide.md",
      "score": 0.82,
      "vector_score": 0.78,
      "bm25_score": 0.86,
      "chunk_id": "chunk_456",
      "metadata": {
        "file_name": "jwt-guide.md",
        "chunk_index": 1
      }
    }
  ],
  "query_time_ms": 1450.8,
  "total_results": 2
}

Example 2: Troubleshooting Query

Query: agent-brain query "fix HTTP 500 errors in production deployment"

Response:

{
  "results": [
    {
      "text": "HTTP 500 Internal Server Error typically indicates application crashes. Common causes: unhandled exceptions, database connection failures, resource exhaustion...",
      "source": "/docs/troubleshooting/http-500-errors.md",
      "score": 0.91,
      "vector_score": 0.88,
      "bm25_score": 0.94,
      "chunk_id": "chunk_789",
      "metadata": {
        "file_name": "http-500-errors.md",
        "chunk_index": 0
      }
    },
    {
      "text": "Production deployment checklist: 1) Environment variables set, 2) Database migrations run, 3) SSL certificates valid, 4) Monitoring configured...",
      "source": "/docs/deployment/production-checklist.md",
      "score": 0.79,
      "vector_score": 0.82,
      "bm25_score": 0.76,
      "chunk_id": "chunk_101",
      "metadata": {
        "file_name": "production-checklist.md",
        "chunk_index": 2
      }
    }
  ],
  "query_time_ms": 1320.3,
  "total_results": 2
}

Performance Characteristics

• Response Time: 1000-1800ms (parallel vector + BM25 execution)
• CPU Usage: High (two search algorithms + fusion)
• Memory Usage: High (loads both vector and BM25 indexes)
• API Costs: Requires OpenAI API credits (for vector component)
• Scalability: Good (parallel execution, pre-computed indexes)

Best Practices

1. Start with defaults: Use alpha = 0.5 and threshold = 0.7 initially 2. Tune alpha for content type: Adjust based on whether your docs are more technical or conceptual 3. Use scores for debugging: --scores flag helps understand result quality 4. Combine with domain knowledge: Know whether your docs favor technical terms or explanations

Advanced Usage Patterns

Technical Documentation Focus

# Favor BM25 for technical docs
agent-brain query "implement caching strategy" --alpha 0.3 --threshold 0.8

Conceptual Documentation Focus

# Favor vector for conceptual docs
agent-brain query "understand microservices architecture" --alpha 0.8 --threshold 0.6

Balanced General Queries

# Default balanced approach
agent-brain query "how to optimize database queries" --alpha 0.5 --top-k 10

Embedding Cache and Query Cache (v8.0+)

Hybrid search benefits from two caching layers:

• Embedding Cache: Caches computed embeddings to reduce API costs during re-indexing. Check with agent-brain cache status.
• Query Cache: Caches identical query results for a configurable TTL (default: 5 minutes). Identical hybrid queries within the TTL return instantly. Configure with QUERY_CACHE_TTL and QUERY_CACHE_MAX_SIZE.

# Check embedding cache health
agent-brain cache status

# Disable query cache if needed
export QUERY_CACHE_TTL=0

---

Common Issues

• API key required: Must have valid OpenAI API key for vector component
• Slower than BM25: Expected due to dual algorithm execution
• Cost considerations: Consumes OpenAI credits for each query (mitigated by embedding cache)
• Alpha tuning needed: May require experimentation for optimal results

Integration Examples

In Scripts

#!/bin/bash
# Comprehensive search with balanced weighting
agent-brain query "$1" --mode hybrid --alpha 0.5 --json | jq '.results[0]'

With Other Tools

# Find comprehensive documentation
agent-brain query "complete $TOPIC guide" --mode hybrid --alpha 0.6 --json | jq -r '.results[].source'

API Integration

import requests

response = requests.post('http://localhost:8000/query/', json={
    'query': 'implement authentication with error handling',
    'mode': 'hybrid',
    'alpha': 0.6,  # 60% semantic, 40% keyword
    'threshold': 0.5,
    'top_k': 8
})
results = response.json()['results']

Multi-Mode Fusion (Graph + Hybrid)

When GraphRAG is enabled, you can use multi mode to combine all four retrieval methods: Vector, BM25, Hybrid, and Graph. Multi-mode uses Reciprocal Rank Fusion (RRF) to merge results from all sources.

How Multi-Mode Works

1. Execute All Retrievers: Run vector, BM25, and graph searches in parallel 2. Compute Hybrid Score: Combine vector + BM25 using alpha weighting 3. Apply RRF: Merge hybrid and graph results using Reciprocal Rank Fusion 4. Re-rank Results: Sort by combined RRF scores 5. Deduplicate: Remove duplicate chunks from overlapping matches

RRF Formula

RRF_score = sum(1 / (k + rank_i)) for each retriever i

Where k is a smoothing constant (default: 60) and rank_i is the result's rank in retriever i.

When to Use Multi-Mode

Choose multi mode when:

• Need the most comprehensive results possible
• Want both content relevance AND relationship context
• Investigating complex code paths
• Uncertain which single mode would work best
• Building knowledge exploration workflows

Multi-Mode Usage

# CLI: Multi-mode with relationship details
agent-brain query "complete authentication implementation" --mode multi --include-relationships

# CLI: Multi-mode with custom settings
agent-brain query "payment processing flow" --mode multi --top-k 10 --traversal-depth 3

# API: Multi-mode request
response = requests.post('http://localhost:8000/query/', json={
    'query': 'authentication flow with all dependencies',
    'mode': 'multi',
    'alpha': 0.6,
    'traversal_depth': 2,
    'include_relationships': True,
    'top_k': 10
})

Multi-Mode Performance

• Response Time: 1500-2500ms (all retrievers + fusion)
• Memory Usage: Highest (loads all indexes)
• Best Results: Combines strengths of all retrieval methods

See Graph Search Guide for detailed GraphRAG documentation.

---

Comparison Matrix

Agent Brain Installation Guide

Complete installation options for Agent Brain with pluggable providers and GraphRAG support.

Prerequisites

• Python 3.10 or higher
• pip, pipx, uv, or conda (package manager)
• Optional: Ollama for local embeddings/summarization

---

Installation Methods

Choose the best method for your workflow:

---

Method 1: pipx (Recommended)

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

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

# Install Agent Brain
pipx install agent-brain-cli

# Verify
agent-brain --version

# Upgrade later
pipx upgrade agent-brain-cli

---

Method 2: uv

Best for: Power users, those already using uv

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

# Install Agent Brain
uv tool install agent-brain-cli

# Verify
agent-brain --version

# Upgrade later
uv tool upgrade agent-brain-cli

---

Method 3: pip with Virtual Environment

Best for: Project-scoped installations, CI/CD

# Create and activate venv
python -m venv .venv
source .venv/bin/activate  # Linux/macOS

# Install Agent Brain
pip install agent-brain-rag agent-brain-cli

# Verify
agent-brain --version

Note: Must activate venv each time: source .venv/bin/activate

---

Method 4: Conda

Best for: Data science users

# Create conda environment
conda create -n agent-brain python=3.12 -y
conda activate agent-brain

# Install Agent Brain (pip inside conda)
pip install agent-brain-rag agent-brain-cli

# Verify
agent-brain --version

Note: Must activate env each time: conda activate agent-brain

---

Installation Extras

Basic Installation

Installs core RAG functionality with hybrid search (BM25 + semantic):

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

With GraphRAG Support

Includes knowledge graph capabilities with SimplePropertyGraphStore:

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

With All Features

Includes GraphRAG with Kuzu database backend for production use:

pip install "agent-brain-rag[graphrag-all]" agent-brain-cli

Installation Extras Reference

---

Development Installation

For contributors or local development:

# Clone repository
git clone https://github.com/SpillwaveSolutions/agent-brain.git
cd agent-brain

# Install in editable mode
pip install -e "./agent-brain-server[dev]"
pip install -e "./agent-brain-cli[dev]"

# Or use Poetry
cd agent-brain-server && poetry install
cd ../agent-brain-cli && poetry install

---

Verifying Installation

# Check CLI version
agent-brain --version

# Check server package
python -c "import agent_brain_server; print(agent_brain_server.__version__)"

# Verify all dependencies
agent-brain verify

---

Quick Reference

---

System Requirements

Minimum Requirements

With GraphRAG

---

Troubleshooting Installation

Command Not Found

pipx:

python -m pipx ensurepath
# Restart terminal

uv:

uv tool list  # Verify installed
# Restart terminal

pip (venv):

source .venv/bin/activate  # Must activate first

pip installation fails

# Upgrade pip first
pip install --upgrade pip

# Try with --no-cache-dir
pip install --no-cache-dir agent-brain-rag agent-brain-cli

Dependency conflicts

Use a virtual environment (Method 3) or pipx (Method 1) to isolate dependencies.

ChromaDB build issues

On some systems, ChromaDB may require additional build tools:

# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

# Then reinstall
pip install --no-cache-dir agent-brain-rag

Kuzu installation issues (graphrag-all)

Kuzu requires a C++ compiler:

# Ubuntu/Debian
sudo apt-get install g++

# macOS (already included with Xcode)
xcode-select --install

---

Uninstallation

---

Multi-Runtime Installation (v9.0+)

Agent Brain supports installing its plugin into multiple AI coding assistant runtimes. After installing the CLI, use the install-agent command to deploy the plugin:

# 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 (skill-directory format with 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

# Preview what will be installed (no files written)
agent-brain install-agent --agent claude --dry-run

# Install globally (user-level) instead of project-level
agent-brain install-agent --agent claude --scope global

Supported Runtimes

Uninstalling

# Remove plugin for a specific runtime
agent-brain uninstall --agent claude

# Remove from global scope
agent-brain uninstall --agent claude --scope global

---

Key Features by Version

---

Next Steps

After installation:

1. Configure providers 2. Initialize your project 3. Index documents 4. Start searching

Integration Guide

Patterns for integrating Agent Brain into scripts, applications, and CI/CD pipelines.

Contents

• CLI Scripting
• Python API Integration
• CI/CD Integration
• Multi-Project Workflow

---

CLI Scripting

# Basic query with JSON output
RESULT=$(agent-brain query "$QUERY" --mode hybrid --json)
echo "$RESULT" | jq '.results[0].text'

# Check if results found
if agent-brain query "search term" --mode bm25 --threshold 0.1 > /dev/null 2>&1; then
    echo "Found matching documents"
fi

# Iterate over results
agent-brain query "error handling" --json | jq -r '.results[].source'

---

Python API Integration

import json
import subprocess
from pathlib import Path
import requests

def get_server_url():
    """Get server URL from runtime.json or default."""
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            capture_output=True, text=True, check=True
        )
        project_root = Path(result.stdout.strip())
        runtime_path = project_root / ".agent-brain" / "runtime.json"
        if runtime_path.exists():
            state = json.loads(runtime_path.read_text())
            return state.get("base_url", "http://localhost:8000")
    except Exception:
        pass
    return "http://localhost:8000"


def query_docs(query: str, mode: str = "hybrid", top_k: int = 5) -> list:
    """Query Agent Brain and return results."""
    server_url = get_server_url()
    response = requests.post(
        f'{server_url}/query/',
        json={'query': query, 'mode': mode, 'top_k': top_k}
    )
    response.raise_for_status()
    return response.json().get('results', [])


# Usage
results = query_docs("authentication guide", mode="hybrid")
for r in results:
    print(f"{r['source']}: {r['score']:.2f}")

---

CI/CD Integration

#!/bin/bash
# Documentation validation in CI pipeline

set -e

# Initialize and start server
agent-brain init
agent-brain start

# Wait for server readiness
for i in {1..10}; do
    if agent-brain status > /dev/null 2>&1; then
        break
    fi
    sleep 1
done

# Index documentation
agent-brain index ./docs

# Run validation queries
echo "Checking for deprecated features..."
if agent-brain query "deprecated" --mode bm25 --threshold 0.1 --json | jq -e '.total_results > 0' > /dev/null; then
    echo "Warning: Found deprecated content"
fi

echo "Verifying API documentation..."
agent-brain query "API endpoint" --mode hybrid --threshold 0.5

# Cleanup
agent-brain stop

echo "Documentation validation complete"

---

Multi-Project Workflow

# Work with multiple projects simultaneously
cd /project-a && agent-brain start  # Auto-port (e.g., 54321)
cd /project-b && agent-brain start  # Different port (e.g., 54322)

# List all running instances
agent-brain list
# Instance   Project          Port   Status
# a1b2c3d4   /project-a       54321  running
# e5f6g7h8   /project-b       54322  running

# Query specific project (from its directory)
cd /project-a && agent-brain query "auth module"
cd /project-b && agent-brain query "database schema"

# Cleanup
cd /project-a && agent-brain stop
cd /project-b && agent-brain stop

---

Additional Integration Patterns

File Watcher Integration (v8.0+)

Enable auto-reindex for continuous integration workflows:

# Enable file watcher on source directory
agent-brain folders add ./src --watch auto --include-code --debounce 10

# Monitor auto-triggered jobs
agent-brain jobs --watch

Embedding Cache Integration (v8.0+)

Monitor cache health in CI pipelines:

# Check cache hit rate
agent-brain cache status --json | jq '.hit_rate'

# Clear cache if switching providers
agent-brain cache clear --yes

---

Environment Variables

Interactive Setup Guide

Guide for configuring Agent Brain through interactive prompts.

Configuration Profile Selection

When setting up Agent Brain, choose a configuration profile based on requirements:

Profile Options

Profile 1: Fully Local (Ollama)

No API keys required. Requires Ollama installed locally.

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

Prerequisites: 1. Install Ollama: https://ollama.ai 2. Pull models: ollama pull nomic-embed-text && ollama pull llama4:scout 3. Start Ollama: ollama serve

Profile 2: Cloud (Best Quality)

Requires OpenAI and Anthropic API keys.

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-..."

Profile 3: Mixed

Requires OpenAI API key only.

export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large
export SUMMARIZATION_PROVIDER=ollama
export SUMMARIZATION_MODEL=llama4:scout
export OPENAI_API_KEY="sk-proj-..."

Profile 4: Custom

Choose embedding and summarization providers independently.

Embedding Provider Options:

Summarization Provider Options:

API Key Configuration

Required Keys by Provider

Setting Environment Variables

Temporary (current session):

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

Persistent (shell profile):

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

Post-Configuration: Enable v8.0+ Features

After setting up providers, consider enabling these optional features:

Embedding Cache (v8.0+)

Automatically enabled. Reduces API costs by caching computed embeddings. Monitor with:

agent-brain cache status

File Watcher (v8.0+)

Enable automatic re-indexing when files change:

agent-brain folders add ./src --watch auto --include-code
agent-brain folders add ./docs --watch auto

Reranking (v8.0+)

Enable two-stage retrieval for higher precision:

export ENABLE_RERANKING=true
export RERANKER_PROVIDER=sentence-transformers

Multi-Runtime Install (v9.0+)

Install the plugin for your AI coding assistant:

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

---

Verification Steps

After configuration, verify setup:

# 1. Check provider configuration
echo "Embedding: ${EMBEDDING_PROVIDER:-openai}"
echo "Summarization: ${SUMMARIZATION_PROVIDER:-anthropic}"

# 2. Check API keys (if using cloud providers)
echo "OpenAI: ${OPENAI_API_KEY:+SET}"
echo "Anthropic: ${ANTHROPIC_API_KEY:+SET}"

# 3. Full verification
agent-brain verify

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. The reranker re-scores initial results for higher precision.

ENABLE_RERANKING=true
RERANKER_PROVIDER=sentence-transformers  # or "ollama"
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
RERANKER_TOP_K_MULTIPLIER=10  # Fetch 10x candidates in Stage 1
RERANKER_MAX_CANDIDATES=100   # Cap on Stage 1 results

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.

Server Discovery Guide

Automatic discovery and management of Agent Brain instances.

Contents

• Runtime File
• Discovery Process
• Python Discovery Script
• Cross-Agent Sharing
• Troubleshooting

---

Runtime File

Agent Brain writes connection details to .agent-brain/runtime.json:

{
  "schema_version": "1.0",
  "mode": "project",
  "project_root": "/path/to/project",
  "instance_id": "a1b2c3d4e5f6",
  "base_url": "http://127.0.0.1:54321",
  "port": 54321,
  "pid": 12345,
  "started_at": "2026-01-28T10:30:00+00:00"
}

---

Discovery Process

1. Project Root Resolution: git rev-parse --show-toplevel or marker files (.claude/, pyproject.toml) 2. Runtime File Check: Look for .agent-brain/runtime.json 3. Health Validation: Verify server via /health/ endpoint 4. URL Extraction: Use base_url for API calls

---

Python Discovery Script

import json
import subprocess
from pathlib import Path
import urllib.request

def discover_server():
    """Discover a running Agent Brain instance for the current project.

    Returns:
        str: Server base URL if found and healthy, None otherwise.
    """
    # Find project root
    try:
        result = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            capture_output=True, text=True, check=True
        )
        project_root = Path(result.stdout.strip())
    except subprocess.CalledProcessError:
        project_root = Path.cwd()

    # Check for runtime.json
    runtime_path = project_root / ".agent-brain" / "runtime.json"
    if not runtime_path.exists():
        return None

    # Read and parse runtime state
    try:
        state = json.loads(runtime_path.read_text())
    except json.JSONDecodeError:
        return None

    # Validate server is alive
    base_url = state.get("base_url", "")
    if not base_url:
        return None

    try:
        req = urllib.request.Request(f"{base_url}/health/", method="GET")
        with urllib.request.urlopen(req, timeout=3) as resp:
            if resp.status == 200:
                return base_url
    except Exception:
        pass

    return None


def get_server_url():
    """Get server URL, starting server if needed.

    Returns:
        str: Server base URL.
    """
    url = discover_server()
    if url:
        return url

    # Start server and wait
    subprocess.run(["agent-brain", "start"], check=True)

    # Re-discover after startup
    import time
    for _ in range(10):
        time.sleep(1)
        url = discover_server()
        if url:
            return url

    raise RuntimeError("Failed to start Agent Brain server")


# Usage
if __name__ == "__main__":
    server_url = discover_server()
    if server_url:
        print(f"Connected to: {server_url}")
    else:
        print("No running server found - starting one...")
        subprocess.run(["agent-brain", "start"])

---

Cross-Agent Sharing

Multiple Claude agents in the same project share one instance:

1. First agent starts server: agent-brain start 2. Other agents discover via runtime.json 3. All agents use same base_url 4. Any agent can stop when work complete

Lock file protocol prevents race conditions during concurrent startup attempts.

---

Troubleshooting

Server Not Found

Error: No running Agent Brain instance found for this project

Solution: agent-brain start

Stale Server State

Warning: Server not responding, cleaning up stale state

Solution: CLI auto-cleans stale files. Manual cleanup:

rm .agent-brain/runtime.json
agent-brain start

Port Conflict

Solution: Use auto-port (default): agent-brain start

Multiple Agents Racing

Lock file prevents double-start. If blocked, run agent-brain status to discover existing instance.

Finding Server Port

agent-brain status                              # Recommended
cat .agent-brain/runtime.json | jq '.port' # Direct read
agent-brain list                                # All instances

Environment Override

export DOC_SERVE_URL="http://127.0.0.1:8000"
agent-brain query "search term"

Troubleshooting Guide

Overview

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

Common Problems and Solutions

1. Server Won't Start

Symptoms:

• agent-brain-serve command fails to start
• Error messages about missing modules or imports
• Port already in use errors

Solutions:

Module Import Errors:

# Reinstall global CLI tools
pip install agent-brain-rag agent-brain-cli

# Or run locally
cd agent-brain-server && poetry run agent-brain-serve

Port Already in Use:

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

# Kill the process
kill -9 <PID>

# Or use different port
agent-brain-serve --port 8001

Permission Errors:

# Check if you can write to the directory
ls -la agent-brain-server/
chmod 755 agent-brain-server/

2. 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 in .env file:

cd agent-brain-server
echo "OPENAI_API_KEY=sk-your-key-here" > .env
echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" >> .env

Set as Environment Variables:

export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
agent-brain-serve

Get API Keys:

• OpenAI: https://platform.openai.com/account/api-keys
• Anthropic: https://console.anthropic.com/

Verify Key Format:

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

3. Missing Anthropic API Key

Symptoms:

• Some summarization features fail
• Warnings about missing Anthropic key
• Core search still works

Solutions:

Add to .env file:

cd agent-brain-server
echo "ANTHROPIC_API_KEY=sk-ant-your-key-here" >> .env

Get API Key:

• Anthropic: https://console.anthropic.com/

Note: Anthropic key is optional for basic search functionality.

4. No Documents Indexed

Symptoms:

• agent-brain status shows 0 documents
• All queries return empty results
• Indexing seems to complete but no data

Solutions:

Check if indexing ran:

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

Run indexing:

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

Verify document path:

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

Check supported formats:

• ✅ Markdown (.md)
• ✅ Text (.txt)
• ✅ PDF (.pdf)
• ❌ Word docs, images (not supported)

5. BM25 Index Not Ready

Symptoms:

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

Solutions:

Wait for indexing to complete:

agent-brain status
# Wait until indexing shows "Idle"

Re-index if needed:

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

Check server logs:

# Look for BM25 indexing messages
tail -f server.log

6. No Search Results Found

Symptoms:

• Queries return empty results array
• Server is running and documents are indexed

Solutions:

Lower threshold:

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

Check query spelling:

# Try variations of your query
agent-brain query "alternative wording"

Use different search modes:

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

# Try vector for semantic search
agent-brain query "conceptual description" --mode vector --threshold 0.5

Verify content exists:

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

7. Slow Query Performance

Symptoms:

• Queries take longer than expected
• Hybrid/vector queries are slow (>2 seconds)

Solutions:

Use BM25 for speed:

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

Optimize hybrid settings:

# Reduce top-k for faster results
agent-brain query "search" --top-k 3 --alpha 0.5

Check network connectivity:

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

Monitor server resources:

# Check if server is overloaded
top -p $(pgrep -f "agent-brain")

8. Connection Refused Errors

Symptoms:

• agent-brain commands fail with connection errors
• "Unable to connect to server" messages

Solutions:

Start the server (multi-instance mode):

agent-brain start   # Uses auto-port allocation
agent-brain status           # Shows the actual port

Check server status:

agent-brain status
# Should show server is healthy with port number

Verify port from runtime.json:

# Check what port was assigned
cat .agent-brain/runtime.json | jq '.port'

List all running instances:

agent-brain list
# Shows all projects with their ports

Use correct URL:

# Override URL if needed
export DOC_SERVE_URL="http://localhost:54321"
agent-brain status

8. 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

8a. Stale Server State (Multi-Instance)

Symptoms:

• runtime.json exists but server is not responding
• "Server not responding" warnings
• Previous server crashed without cleanup

Solutions:

Let the CLI handle it:

# CLI automatically detects stale state and starts fresh
agent-brain start

Manual cleanup:

# Remove stale state files
rm .agent-brain/runtime.json
rm .agent-brain/lock.json
rm .agent-brain/pid

# Start fresh
agent-brain start

8b. Multiple Agents Racing to Start

Symptoms:

• "Another instance is already running" error
• Lock acquisition failures

Solutions:

The lock file protocol prevents double-start automatically:

# First agent wins and starts the server
# Second agent should detect the running instance
agent-brain status

# If lock is stale (process died), cleanup happens automatically
agent-brain start

If locks persist incorrectly:

# Manual lock cleanup (only if process is truly dead)
ps aux | grep agent-brain  # Verify no process running
rm .agent-brain/lock.json
agent-brain start

9. Invalid API Key Errors

Symptoms:

• Authentication failed messages
• 401 Unauthorized responses
• Works with BM25 but fails with hybrid/vector

Solutions:

Check API key validity:

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

Verify key format:

# Should be sk-proj-... or sk-...
echo $OPENAI_API_KEY | grep -E "^sk-(proj-)?[a-zA-Z0-9]"

Check account credits:

• OpenAI: https://platform.openai.com/account/usage
• Ensure account has credits and API access

Regenerate key if needed:

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

10. Memory or Resource Issues

Symptoms:

• Server crashes with out of memory errors
• Queries fail with resource exhaustion
• System becomes unresponsive

Solutions:

Reduce batch sizes:

# Smaller embedding batches
export EMBEDDING_BATCH_SIZE=50

Limit concurrent requests:

# Use single-threaded mode if needed
export WEB_CONCURRENCY=1

Monitor resource usage:

# Check memory usage
ps aux | grep agent-brain
top -p $(pgrep -f "agent-brain")

Restart with clean state:

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

11. JSON Parsing Errors

Symptoms:

• --json output is malformed
• Parsing errors in scripts
• Unexpected response format

Solutions:

Check API response:

curl -s http://localhost:8000/health | python -m json.tool

Validate JSON output:

agent-brain query "test" --json | jq .

Update CLI version:

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

12. File Permission Issues

Symptoms:

• Cannot read documents during indexing
• Cannot write index files
• Permission denied errors

Solutions:

Check file permissions:

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

Check index directory permissions:

ls -la agent-brain-server/
chmod 755 agent-brain-server/
mkdir -p agent-brain-server/chroma_db
chmod 755 agent-brain-server/chroma_db

Run as appropriate user:

# Don't run as root unless necessary
whoami

Diagnostic Commands

Check System Status

# Server health
agent-brain status

# Check API connectivity
curl http://localhost:8000/health

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

Check Environment

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

# Python environment
which python
python --version

# Poetry environment
cd agent-brain-server && poetry env info

Check Logs

# Server logs
tail -f server.log

# System logs
dmesg | tail -20

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

Getting Help

If these solutions don't resolve your issue:

1. Check GitHub Issues: https://github.com/SpillwaveSolutions/agent-brain/issues 2. Provide diagnostic info: Run the diagnostic commands above 3. Include error messages: Copy full error output 4. Describe your setup: OS, Python version, installation method

File Watcher Issues (v8.0+)

Watcher Not Triggering Re-index

Symptoms:

• Edited files not automatically re-indexed
• No auto-triggered jobs in agent-brain jobs

Solutions:

# Verify watch mode is enabled on folder
agent-brain folders list

# Enable watching
agent-brain folders add ./src --watch auto --include-code

# Lower debounce for faster response (default 30s)
agent-brain folders add ./src --watch auto --debounce 10

Excluded directories: .git/, node_modules/, __pycache__/, dist/, build/, .next/, .nuxt/, coverage/, htmlcov/

---

Embedding Cache Issues (v8.0+)

Low Hit Rate or Slow Re-indexing

# Check cache health
agent-brain cache status

# If you changed embedding provider, clear old cached embeddings
agent-brain cache clear --yes

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

Configuration: EMBEDDING_CACHE_MAX_DISK_MB (default: 500MB), EMBEDDING_CACHE_MAX_MEM_ENTRIES (default: 1000)

---

Multi-Runtime Install Issues (v9.0+)

Plugin Not Found After Install

# Verify plugin was installed
ls .claude/plugins/agent-brain/  # For Claude
ls .opencode/plugins/agent-brain/  # For OpenCode

# Re-install
agent-brain install-agent --agent claude

# Preview what will be installed
agent-brain install-agent --agent claude --dry-run

---

Prevention Tips

• Always run task pr-qa-gate before committing changes
• Keep API keys secure and don't commit them
• Use environment variables for sensitive configuration
• Regularly update dependencies with poetry update
• Monitor server logs for early warning signs
• Test with different search modes when queries fail
• Use agent-brain cache status to monitor embedding cache health
• Enable file watcher (--watch auto) for automatic re-indexing

Vector Search Guide

Overview

Vector search uses semantic similarity to find documents based on meaning rather than exact word matches. It converts both your query and documents into vector embeddings, then finds the most similar vectors using mathematical distance calculations.

When to Use Vector Search

Choose vector search when:

• Looking for conceptual understanding or semantic similarity
• The query uses natural language descriptions
• You want to find related content even if exact terms don't match
• Working with conceptual documentation, tutorials, or explanatory content
• The query involves synonyms, related concepts, or abstract ideas

Examples of vector queries:

• "How do I authenticate users?" - Finds authentication-related content even with different terminology
• "troubleshooting connection issues" - Finds related problems and solutions
• "best practices for error handling" - Finds conceptual guidance on error management
• "understanding OAuth flow" - Finds explanations of OAuth concepts

How to Use Vector Search

CLI Usage

# Basic vector search (default mode)
agent-brain query "how does authentication work"

# Explicit vector mode
agent-brain query "troubleshooting guide" --mode vector

# With custom settings
agent-brain query "error handling patterns" --mode vector --threshold 0.5 --top-k 10

API Usage

# POST /query endpoint
curl -X POST http://localhost:8000/query/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does authentication work",
    "mode": "vector",
    "threshold": 0.5,
    "top_k": 8
  }'

Vector Search Options

Why Choose Vector Over Other Modes

Vector Advantages:

• 🧠 Semantic Understanding: Finds meaning, not just keywords
• 🔄 Flexible Matching: Works with synonyms and related concepts
• 🌍 Language Agnostic: Works across languages and domains
• 🎯 Conceptual Search: Great for tutorials and explanations

When Vector is better than BM25:

• Natural language queries
• Conceptual or explanatory content
• When exact terminology might vary
• Cross-language or multilingual content

When Vector is better than Hybrid:

• Pure semantic understanding needed
• No exact technical terms to match
• Performance-critical applications
• When keyword matching could be misleading

Vector Algorithm Details

Vector search uses: 1. Text Embedding: Converts text to high-dimensional vectors (3072 dimensions for text-embedding-3-large) 2. Cosine Similarity: Measures angle between query and document vectors 3. Ranking: Sorts by similarity score (higher = more similar)

Similarity Range: 0.0 (completely dissimilar) to 1.0 (identical meaning)

Embedding Model: OpenAI text-embedding-3-large (high quality, semantic understanding)

Example Queries and Results

Example 1: Conceptual Query

Query: agent-brain query "how does user authentication work"

Response:

{
  "results": [
    {
      "text": "User authentication involves validating credentials against a user database. The process typically includes: 1) Username/password verification, 2) Token generation for session management, 3) Optional two-factor authentication...",
      "source": "/docs/security/auth-overview.md",
      "score": 0.87,
      "vector_score": 0.87,
      "bm25_score": null,
      "chunk_id": "chunk_123",
      "metadata": {
        "file_name": "auth-overview.md",
        "chunk_index": 0
      }
    },
    {
      "text": "OAuth 2.0 provides a secure way to authenticate users without sharing passwords. The flow involves: authorization request, user consent, token exchange...",
      "source": "/docs/api/oauth-integration.md",
      "score": 0.82,
      "vector_score": 0.82,
      "bm25_score": null,
      "chunk_id": "chunk_456",
      "metadata": {
        "file_name": "oauth-integration.md",
        "chunk_index": 1
      }
    }
  ],
  "query_time_ms": 1240.5,
  "total_results": 2
}

Example 2: Troubleshooting Query

Query: agent-brain query "connection problems and solutions"

Response:

{
  "results": [
    {
      "text": "Common connection issues: 1) Network timeouts - increase timeout values, 2) SSL certificate problems - verify certificates, 3) Firewall blocking - check port access...",
      "source": "/docs/troubleshooting/network-issues.md",
      "score": 0.91,
      "vector_score": 0.91,
      "bm25_score": null,
      "chunk_id": "chunk_789",
      "metadata": {
        "file_name": "network-issues.md",
        "chunk_index": 0
      }
    },
    {
      "text": "Database connection pooling can prevent connection exhaustion. Configure minimum and maximum pool sizes based on your application load...",
      "source": "/docs/database/connection-pooling.md",
      "score": 0.78,
      "vector_score": 0.78,
      "bm25_score": null,
      "chunk_id": "chunk_101",
      "metadata": {
        "file_name": "connection-pooling.md",
        "chunk_index": 2
      }
    }
  ],
  "query_time_ms": 1180.2,
  "total_results": 2
}

Performance Characteristics

• Response Time: 800-1500ms (requires API calls to OpenAI)
• CPU Usage: Medium (vector similarity calculations)
• Memory Usage: High (loads all document vectors)
• API Costs: Requires OpenAI API credits
• Scalability: Good (vectors pre-computed, similarity calculated locally)

Best Practices

1. Use natural language: Vector search works best with conversational queries 2. Adjust thresholds carefully: Start with 0.7, lower to 0.3-0.5 for more results 3. Combine with domain knowledge: Understand what concepts are covered in your docs 4. Use for exploration: Great for discovering related content you didn't know existed

Common Issues

• API key required: Must have valid OpenAI API key
• Slow responses: Expected due to API calls (800-1500ms typical)
• Cost considerations: Each query consumes OpenAI credits
• No exact matches: Won't find content that uses completely different terminology

Integration Examples

In Scripts

#!/bin/bash
# Semantic search for troubleshooting
agent-brain query "fix $1 problem" --mode vector --json | jq '.results[0].text'

With Other Tools

# Find related documentation
agent-brain query "best practices for $TOPIC" --mode vector --json | jq -r '.results[].source'

API Integration

import requests

response = requests.post('http://localhost:8000/query/', json={
    'query': 'how to handle errors gracefully',
    'mode': 'vector',
    'threshold': 0.6
})
results = response.json()['results']

Embedding Cache (v8.0+)

Vector search benefits from the embedding cache. After the first query or indexing run, embeddings are cached locally to reduce API calls and improve response times:

# Check cache hit rate
agent-brain cache status

# Clear cache if switching embedding providers
agent-brain cache clear --yes

A healthy cache (>80% hit rate) means most re-indexing operations skip API calls for unchanged content.

---

Comparison with Other Modes

Agent Brain Version Management

Guide for installing, upgrading, and managing Agent Brain versions.

Current Version

Resolve the latest version dynamically from PyPI:

VERSION=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
echo "Latest: $VERSION"

Version History

Checking Version

# CLI version
agent-brain --version

# Server package version
python -c "import agent_brain_server; print(agent_brain_server.__version__)"

# Both packages
pip show agent-brain-rag agent-brain-cli

Installing Specific Versions

Latest Stable (Recommended)

# Resolve and install latest
VERSION=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
pip install agent-brain-rag==$VERSION agent-brain-cli==$VERSION

Specific Version

# Install exact version (replace $VERSION with desired version)
pip install agent-brain-rag==$VERSION agent-brain-cli==$VERSION

Version Range

# Compatible with 3.x
pip install "agent-brain-rag>=3.0.0,<4.0.0"

# Minimum version
pip install "agent-brain-rag>=3.0.0"

Listing Available Versions

# List all available versions
pip index versions agent-brain-rag

# Alternative with pip
pip install agent-brain-rag==  # Shows error with all versions listed

Upgrading

Upgrade to Latest

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

Upgrade to Specific Version

# Resolve latest first
VERSION=$(curl -sf https://pypi.org/pypi/agent-brain-rag/json | python3 -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
pip install --upgrade agent-brain-rag==$VERSION agent-brain-cli==$VERSION

Check for Updates

# Check if updates are available
pip list --outdated | grep agent-brain

Downgrading

To downgrade to a previous version:

# Set target version
TARGET_VERSION="X.Y.Z"  # e.g., 2.0.0

# Downgrade to specific version
pip install agent-brain-rag==$TARGET_VERSION agent-brain-cli==$TARGET_VERSION

# Force reinstall if needed
pip install --force-reinstall agent-brain-rag==$TARGET_VERSION

Migration Considerations

When downgrading, be aware of:

1. Index Compatibility: Newer indexes may not work with older versions 2. Configuration: New config options won't be recognized 3. Features: New features won't be available

Recommended Steps:

# 1. Set target version
TARGET_VERSION="X.Y.Z"

# 2. Stop server
agent-brain stop

# 3. Backup configuration
cp -r .agent-brain .agent-brain.backup

# 4. Reset index (if needed)
agent-brain reset --yes

# 5. Downgrade
pip install agent-brain-rag==$TARGET_VERSION agent-brain-cli==$TARGET_VERSION

# 6. Re-index
agent-brain start
agent-brain index /path/to/docs

Version Compatibility

Package Alignment

Always keep agent-brain-rag and agent-brain-cli on the same version:

Python Version Compatibility

Index Compatibility

Indexes created with one version may not be compatible with another:

Version Pinning

In requirements.txt

# Pin to specific version (resolve latest first)
agent-brain-rag==X.Y.Z
agent-brain-cli==X.Y.Z

In pyproject.toml

[project]
dependencies = [
    "agent-brain-rag>=3.0.0,<4.0.0",
    "agent-brain-cli>=3.0.0,<4.0.0",
]

In Poetry

[tool.poetry.dependencies]
agent-brain-rag = "^3.0.0"
agent-brain-cli = "^3.0.0"

Development Versions

Installing Pre-release

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

Installing from Git

# Latest main branch
pip install git+https://github.com/SpillwaveSolutions/agent-brain.git#subdirectory=agent-brain-server
pip install git+https://github.com/SpillwaveSolutions/agent-brain.git#subdirectory=agent-brain-cli

# Specific branch
pip install git+https://github.com/SpillwaveSolutions/agent-brain.git@feature-branch#subdirectory=agent-brain-server

Release Notes

v9.1.0

New Features:

• Generic skill-runtime converter for any skill-based AI assistant
• Codex named adapter with AGENTS.md generation
• --dry-run support for all runtime installs

v9.0.0

New Features:

• Multi-runtime plugin installation (install-agent command)
• Support for 5 runtimes: Claude, OpenCode, Gemini, Codex, skill-runtime
• Plugin uninstall command
• Project and global scope installation

v8.0.0

New Features:

• File watcher for automatic re-indexing on file changes
• Embedding cache (two-tier: in-memory LRU + SQLite disk)
• Query cache with configurable TTL
• Reranking with SentenceTransformers and Ollama providers
• Setup wizard for interactive configuration

v7.0.0

New Features:

• Folder management (folders add/list/remove)
• File type presets (types list, --include-type)
• Content injection (inject command with custom scripts)
• Chunk eviction for folder removal

v3.0.0

New Features:

• Server-side job queue for async indexing
• Background job processing
• Job status tracking and cancellation
• Improved performance for large document sets

Breaking Changes:

• Job queue API changes
• Index format may require re-indexing

For full release notes, see: https://github.com/SpillwaveSolutions/agent-brain/releases

v2.0.0

New Features:

• Pluggable embedding providers (OpenAI, Cohere, Ollama)
• Pluggable summarization providers (Anthropic, OpenAI, Gemini, Grok, Ollama)
• Fully local mode with Ollama (no API keys required)
• Enhanced GraphRAG support

v1.4.0

Features:

• Graph search mode
• Multi-mode fusion search
• Improved entity extraction

v1.3.0

Features:

• AST-aware code ingestion
• Support for Python, TypeScript, JavaScript, Java, Go, Rust, C, C++
• Improved code summarization

v1.2.0

Features:

• Multi-instance architecture
• Per-project isolation
• Automatic server discovery

Support Lifecycle

Active: Full support, new features Maintenance: Security fixes only End of Life: No support