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)
• Server 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.

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 init succeeded
• 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.

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

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