/agent-brain-hybrid

name: agent-brain-hybrid
description: Search using hybrid BM25 + semantic with alpha tuning
parameters:
  - name: query
    description: The search query text
    required: true
  - name: alpha
    description: Balance between vector (1.0) and BM25 (0.0)
    required: false
    default: 0.5
  - name: top-k
    description: Number of results to return (1-20)
    required: false
    default: 5
  - name: threshold
    description: Minimum relevance score (0.0-1.0)
    required: false
    default: 0.3
skills:
  - using-agent-brain
last_validated: 2026-03-16

Agent Brain Hybrid Search

Purpose

Performs hybrid search combining BM25 keyword matching with semantic vector similarity. This is the default and most versatile search mode, balancing exact term matching with conceptual understanding.

Hybrid search is ideal for:

• General documentation queries
• Mixed technical and conceptual questions
• When you need both precise terms and semantic relevance
• Comprehensive search across diverse content

Usage

/agent-brain:agent-brain-hybrid <query> [--alpha <a>] [--top-k <n>] [--threshold <t>]

Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | query | Yes | - | The search query text | | --alpha | No | 0.5 | Hybrid blend factor (0.0-1.0) | | --top-k | No | 5 | Number of results (1-20) | | --threshold | No | 0.3 | Minimum relevance score (0.0-1.0) |

Alpha Tuning Guide

The `--alpha` parameter controls the blend between semantic and keyword matching:

| Alpha | Semantic | BM25 | Best For | |-------|----------|------|----------| | 1.0 | 100% | 0% | Pure semantic (concepts, explanations) | | 0.7 | 70% | 30% | Favor meaning over exact terms | | 0.5 | 50% | 50% | Balanced (default) | | 0.3 | 30% | 70% | Favor exact terms with some semantic | | 0.0 | 0% | 100% | Pure keyword (exact terms only) |

When to Adjust Alpha

| Query Type | Suggested Alpha | |------------|-----------------| | "how does authentication work" | 0.7 | | "OAuth implementation guide" | 0.5 | | "AuthenticationError handling" | 0.3 | | "def process_document" | 0.0 |

Execution

Pre-flight Check

# Verify server is running
agent-brain status

If not running:

agent-brain start

Search Command

agent-brain query "<query>" --mode hybrid --alpha <alpha> --top-k <k> --threshold <t>

Examples

# Balanced hybrid search (default)
agent-brain query "OAuth implementation" --mode hybrid

# Favor semantic understanding
agent-brain query "how does caching work" --mode hybrid --alpha 0.7

# Favor exact terms
agent-brain query "ConnectionRefusedError" --mode hybrid --alpha 0.3

# More results with lower threshold
agent-brain query "error handling patterns" --mode hybrid --top-k 10 --threshold 0.2

# Full custom search
agent-brain query "authentication flow" --mode hybrid --alpha 0.6 --top-k 8 --threshold 0.25

Output

Result Format

For each result, present:

1. **Source**: File path or document name 2. **Score**: Combined relevance score (normalized 0-1) 3. **Content**: Relevant excerpt from the document

Example Output

## Hybrid Search Results for "OAuth implementation"
Alpha: 0.5 (balanced)

### 1. docs/auth/oauth-guide.md (Score: 0.89)
OAuth 2.0 implementation requires configuring the authorization endpoint,
token endpoint, and callback URL. The recommended flow for server-side
applications is the Authorization Code flow...

### 2. src/auth/oauth_client.py (Score: 0.76)
class OAuthClient:
    """Handles OAuth 2.0 authentication flow."""
    def __init__(self, client_id: str, client_secret: str):
        self.client_id = client_id
        ...

### 3. docs/api/authentication.md (Score: 0.71)
The API supports OAuth 2.0 Bearer tokens. Include the token in the
Authorization header: `Authorization: Bearer <token>`...

---
Found 3 results above threshold 0.3
Search mode: hybrid (alpha=0.5)

Citation Format

When referencing results in responses, always cite the source:

• "According to `docs/auth/oauth-guide.md`..."
• "The implementation in `src/auth/oauth_client.py` shows..."

Error Handling

Server Not Running

Error: Could not connect to Agent Brain server

**Resolution:**

agent-brain start

No Results Found

No results found above threshold 0.3

**Resolution:**

• Try lowering threshold: `--threshold 0.1`
• Adjust alpha based on query type
• Try different search terms
• Verify documents are indexed: `agent-brain status`

Invalid Alpha Value

Error: Alpha must be between 0.0 and 1.0

**Resolution:** Use a value in the range [0.0, 1.0]

API Key Missing (for semantic component)

Error: OPENAI_API_KEY not set

**Resolution:**

export OPENAI_API_KEY="sk-proj-..."
# Or use Ollama for local embeddings:
export EMBEDDING_PROVIDER=ollama

Index Empty

Warning: No documents indexed

**Resolution:**

agent-brain index /path/to/docs

Performance Notes

| Metric | Typical Value | |--------|---------------| | Latency | 1000-1800ms | | API calls | 1 embedding call | | Best for | General queries, mixed content |

Comparison with Other Modes

| Mode | Speed | Exact Match | Concepts | Use Case | |------|-------|-------------|----------|----------| | BM25 | Fast | Excellent | Poor | Technical terms | | Vector | Slow | Poor | Excellent | Concepts | | **Hybrid** | Medium | Good | Good | **Balanced** |

Related Commands

• `/agent-brain:agent-brain-bm25` - Pure keyword search
• `/agent-brain:agent-brain-vector` - Pure semantic search
• `/agent-brain:agent-brain-search` - Alias for hybrid search
• `/agent-brain:agent-brain-multi` - Multi-mode fusion search