/using-agent-brain

name: using-agent-brain
description: |
  Expert Agent Brain skill for document search with BM25 keyword, semantic vector, hybrid, graph, and multi retrieval modes.
  Use when asked to "search documentation", "query domain", "find in docs",
  "bm25 search", "hybrid search", "semantic search", "graph search", "multi search",
  "find dependencies", "code relationships", "searching knowledge base",
  "querying indexed documents", "finding code references", "exploring codebase",
  "what calls this function", "find imports", "trace dependencies",
  "brain search", "brain query", "knowledge base search",
  "cache management", "clear embedding cache", "cache hit rate", or "cache status".
  Supports multi-instance architecture with automatic server discovery.
  GraphRAG mode enables relationship-aware queries for code dependencies and entity connections.
  Pluggable providers for embeddings (OpenAI, Cohere, Ollama) and summarization (Anthropic, OpenAI, Gemini, Grok, Ollama).
  Supports multiple runtimes (Claude Code, OpenCode, Gemini CLI) with shared .agent-brain/ data directory,
  plus MCP-aware clients (Claude Desktop, Cursor, Windsurf) via the agent-brain-mcp server.
license: MIT
allowed-tools:
  - Bash
  - Read
metadata:
  version: 10.3.0
  category: ai-tools
  author: Spillwave
  last_validated: 2026-06-10

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](#search-modes)
• [Mode Selection Guide](#mode-selection-guide)
• [GraphRAG (Knowledge Graph)](#graphrag-knowledge-graph)
• [Indexing & Folder Management](#indexing--folder-management)
• [Content Injection](#content-injection)
• [Job Queue Management](#job-queue-management)
• [Server Management](#server-management)
• [Cache Management](#cache-management)
• [When Not to Use](#when-not-to-use)
• [Best Practices](#best-practices)
• [Reference Documentation](#reference-documentation)

---

Search Modes

| Mode | Speed | Best For | Example Query | |------|-------|----------|---------------| | `bm25` | Fast (10-50ms) | Technical terms, function names, error codes | `"AuthenticationError"` | | `vector` | Slower (800-1500ms) | Concepts, explanations, natural language | `"how authentication works"` | | `hybrid` | Slower (1000-1800ms) | Comprehensive results combining both | `"OAuth implementation guide"` | | `graph` | Medium (500-1200ms) | Relationships, dependencies, call chains | `"what calls AuthService"` | | `multi` | Slowest (1500-2500ms) | Most comprehensive with entity context | `"complete auth flow with dependencies"` |

Mode Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | `--mode` | hybrid | Search mode: bm25, vector, hybrid, graph, multi | | `--threshold` | 0.3 | Minimum similarity (0.0-1.0) | | `--top-k` | 5 | Number of results | | `--alpha` | 0.5 | Hybrid balance (0=BM25, 1=Vector) |

---

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

| Query Pattern | Example | |---------------|---------| | Function callers | `"what calls process_payment"` | | Class inheritance | `"classes extending BaseController"` | | Import dependencies | `"modules importing auth"` | | Data flow | `"where does user_id come from"` |

See [Graph Search Guide](references/graph-search-guide.md) 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