/agent-brain-multi

name: agent-brain-multi
description: Search using multi-mode fusion combining all search modes
parameters:
  - name: query
    description: The comprehensive search query
    required: true
  - 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 Multi-Mode Search

Purpose

Performs multi-mode fusion search combining BM25 keyword matching, semantic vector search, and GraphRAG relationships using Reciprocal Rank Fusion (RRF). This is the most comprehensive search mode, finding results from all angles.

Multi-mode search is ideal for:

• Complex queries requiring comprehensive results
• When you want both content matches AND relationships
• Investigating full implementation details
• Combining technical terms with conceptual understanding
• When you're not sure which mode would be best

Usage

/agent-brain:agent-brain-multi <query> [--top-k <n>] [--threshold <t>]

Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | query | Yes | - | The comprehensive search query | | --top-k, -k | No | 5 | Number of results (1-20) | | --threshold, -t | No | 0.3 | Minimum relevance score (0.0-1.0) | | --source-types | No | - | Filter by source type (doc,code,test) | | --languages | No | - | Filter by programming language | | --file-paths | No | - | Filter by file path patterns (wildcards) | | --scores | No | false | Show individual vector/BM25 scores | | --full | No | false | Show full text content | | --json | No | false | Output as JSON | | --url | No | from config | Server URL (env: AGENT_BRAIN_URL) |

How Multi-Mode Works

1. **BM25 Search**: Finds exact term matches 2. **Vector Search**: Finds semantically similar content 3. **Graph Search**: Finds related entities and relationships 4. **RRF Fusion**: Combines results using Reciprocal Rank Fusion

RRF_score(d) = Σ 1/(k + rank_i(d))

Where `k` is a constant (typically 60) and `rank_i(d)` is the rank of document `d` in result list `i`.

Execution

Pre-flight Check

# Verify server is running and capabilities
agent-brain status

Multi-mode works best with all indices available:

• BM25 index: Built during indexing
• Vector index: Requires embedding provider
• Graph index: Requires `ENABLE_GRAPH_INDEX=true`

Search Command

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

Examples

# Comprehensive implementation search
agent-brain query "complete authentication implementation" --mode multi

# More results for exploration
agent-brain query "error handling patterns" --mode multi --top-k 10

# Lower threshold for broader search
agent-brain query "caching strategy" --mode multi --threshold 0.2

# Payment processing with more context
agent-brain query "payment processing flow" --mode multi --top-k 8

Output

Result Format

The CLI displays results in panels showing:

• Source file path
• Relevance score (RRF-fused percentage)
• Text content excerpt

Multi-mode combines results from BM25, Vector, and Graph (if enabled) using Reciprocal Rank Fusion.

Example Output

Query: complete authentication implementation
Found 3 results in 2341ms

╭─ [1] src/auth/oauth_client.py  Score: 94% ────────────────────╮
│ class OAuthClient:                                             │
│     """                                                        │
│     Complete OAuth 2.0 client implementation.                  │
│                                                                │
│     Handles authorization code flow, token refresh,            │
│     and automatic retry with exponential backoff.              │
│     """                                                        │
│                                                                │
│     def authenticate(self, code: str) -> Token:                │
│         ...                                                    │
╰────────────────────────────────────────────────────────────────╯

╭─ [2] docs/auth/oauth-guide.md  Score: 87% ────────────────────╮
│ ## OAuth 2.0 Implementation Guide                              │
│                                                                │
│ This guide covers the complete OAuth 2.0 implementation:       │
│ - Authorization Code Flow                                      │
│ - Token Management                                             │
│ - Security Best Practices                                      │
╰────────────────────────────────────────────────────────────────╯

╭─ [3] src/auth/token_manager.py  Score: 72% ───────────────────╮
│ class TokenManager:                                            │
│     """Manages token lifecycle including refresh."""           │
│                                                                │
│     def refresh_token(self, token: Token) -> Token:            │
│         ...                                                    │
╰────────────────────────────────────────────────────────────────╯

Detailed Scores (with --scores flag)

Use `--scores` to see individual BM25 and vector scores:

agent-brain query "authentication" --mode multi --scores

Shows `[V: 0.92 B: 0.88]` after each score for debugging.

Error Handling

Server Not Running

Error: Could not connect to Agent Brain server

**Resolution:**

agent-brain start

Graph Index Not Available

Warning: Graph index not enabled. Multi-mode will use BM25 + Vector only.

**Resolution (optional):**

export ENABLE_GRAPH_INDEX=true
agent-brain stop && agent-brain start
agent-brain reset --yes
agent-brain index /path/to/code

Multi-mode gracefully degrades if graph is unavailable.

**Note:** When using PostgreSQL backend, graph is a