AgentSkillsCN

using-agent-brain

精通 Agent Brain 的文档搜索功能，支持 BM25 关键词检索、语义向量检索、混合检索、图谱检索以及多路检索等多种模式。 当用户需要“搜索文档”、“查询特定领域”、“在文档中查找相关内容”、“执行 BM25 检索”、“开展混合检索”、“进行语义检索”、“实施图谱检索”、“执行多路检索”、“查找依赖关系”、“探寻代码间的关联”、“搜索知识库”、“查询已索引的文档”、“定位代码引用”、“探索代码库”、“查明某函数的调用来源”、“寻找导入模块”、“追踪依赖关系”、“开展 Brain 检索”、“进行 Brain 查询”或“执行知识库搜索”时，可借助本技能获得专业支持。 支持多实例架构，并具备自动发现服务器的功能。 GraphRAG 模式可实现对代码依赖关系与实体关联的智能感知查询。 提供可插拔的嵌入式模型（OpenAI、Cohere、Ollama）与摘要生成模型（Anthropic、OpenAI、Gemini、Grok、Ollama）。

SKILL.md
--- frontmatter
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", or "knowledge base search".
  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).
license: MIT
allowed-tools:
  - Bash
  - Read
metadata:
  version: 4.0.0
  category: ai-tools
  author: Spillwave

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

ModeSpeedBest ForExample Query
bm25Fast (10-50ms)Technical terms, function names, error codes"AuthenticationError"
vectorSlower (800-1500ms)Concepts, explanations, natural language"how authentication works"
hybridSlower (1000-1800ms)Comprehensive results combining both"OAuth implementation guide"
graphMedium (500-1200ms)Relationships, dependencies, call chains"what calls AuthService"
multiSlowest (1500-2500ms)Most comprehensive with entity context"complete auth flow with dependencies"

Mode Parameters

ParameterDefaultDescription
--modehybridSearch mode: bm25, vector, hybrid, graph, multi
--threshold0.3Minimum similarity (0.0-1.0)
--top-k5Number of results
--alpha0.5Hybrid balance (0=BM25, 1=Vector)

Mode Selection Guide

Use BM25 When

Searching for exact technical terms:

bash
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:

bash
# 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:

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

Counter-example - Wrong mode choice:

bash
# 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):

bash
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:

bash
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:

bash
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

bash
export ENABLE_GRAPH_INDEX=true
agent-brain start

Graph Query Types

Query PatternExample
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 for detailed usage.

Server Management

Quick Start

bash
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

CommandDescription
agent-brain initInitialize project config
agent-brain startStart with auto-port
agent-brain statusShow port, mode, document count
agent-brain listList all running instances
agent-brain stopGraceful shutdown

Pre-Query Validation

Before querying, verify setup:

bash
agent-brain status

Expected:

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

Counter-example - Querying without validation:

bash
# 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

GuideDescription
BM25 SearchKeyword matching for technical queries
Vector SearchSemantic similarity for concepts
Hybrid SearchCombined keyword and semantic search
Graph SearchKnowledge graph and relationship queries
Server DiscoveryAuto-discovery, multi-agent sharing
Provider ConfigurationEnvironment variables and API keys
Integration GuideScripts, Python API, CI/CD patterns
API ReferenceREST endpoint documentation
TroubleshootingCommon issues and solutions

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