agent-brain-keyword

Agent Brain Keyword Search

Purpose

Performs BM25 keyword search for fast, exact term matching. This mode is optimized for technical queries where you know the exact terms, function names, error codes, or identifiers.

Keyword search is ideal for:

• Error messages and codes
• Function and class names
• Configuration keys
• Technical identifiers
• When speed is critical (10-50ms response)

Usage

/agent-brain:agent-brain-keyword <query> [--top-k <n>]

Parameters

Parameter	Required	Default	Description
query	Yes	-	The exact search terms
top-k	No	5	Number of results (1-20)

When to Use Keyword Search

Use Keyword/BM25	Use Semantic Instead
"AuthenticationError"	"how does auth work"
"recursiveCharacterTextSplitter"	"text splitting strategies"
"OPENAI_API_KEY"	"API configuration"
"def process_document"	"document processing flow"
error codes, stack traces	conceptual explanations

Execution

Pre-flight Check

Verify the server is running:

agent-brain status

Search Command

agent-brain query "<query>" --mode bm25 --top-k <top-k>

Examples

# Search for error message
agent-brain query "ConnectionRefusedError" --mode bm25

# Search for function name
agent-brain query "process_document" --mode bm25

# Search for configuration key
agent-brain query "EMBEDDING_MODEL" --mode bm25

# More results
agent-brain query "AuthenticationError" --mode bm25 --top-k 10

# Search for multiple terms
agent-brain query "OAuth client_id redirect_uri" --mode bm25

Output

Format search results with source citations:

Result Format

For each result, present:

1. Source: File path or document name
2. Score: BM25 relevance score
3. Content: Relevant excerpt with matching terms highlighted

Example Output

## Keyword Search Results for "AuthenticationError"

### 1. src/auth/exceptions.py (Score: 12.4)
class AuthenticationError(Exception):
    """Raised when authentication fails."""
    def __init__(self, message: str, code: str = "AUTH_FAILED"):
        self.code = code
        super().__init__(message)

### 2. tests/test_auth.py (Score: 8.7)
def test_invalid_credentials_raises_authentication_error():
    with pytest.raises(AuthenticationError) as exc:
        auth_client.authenticate("invalid", "credentials")
    assert exc.value.code == "AUTH_FAILED"

### 3. docs/errors/authentication.md (Score: 6.2)
## AuthenticationError

Raised when user credentials are invalid or expired.

**Common causes:**
- Invalid API key
- Expired token
- Missing credentials

---
Found 3 results