Command Semantic

---

name: agent-brain-semantic description: Search using semantic vector similarity for conceptual queries parameters:

• name: query description: The conceptual search query required: true
• name: top-k description: Number of results (1-20) required: false default: 5
• name: threshold description: Minimum similarity score (0.0-1.0) required: false default: 0.3 skills:
• using-agent-brain

---

Agent Brain Semantic Search

Purpose

Performs pure semantic vector search using OpenAI embeddings. This mode finds documents based on meaning and conceptual similarity rather than exact keyword matching.

Semantic search is ideal for:

• Conceptual questions ("how does X work?")
• Finding related documentation even without exact term matches
• Natural language queries
• Discovering documents about similar concepts

Usage

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

Parameters

Parameter	Required	Default	Description
query	Yes	-	The conceptual search query
top-k	No	5	Number of results (1-20)
threshold	No	0.3	Minimum similarity score (0.0-1.0)

When to Use Semantic Search

Use Semantic Search	Use BM25/Keyword Instead
"how does authentication work"	"AuthenticationError"
"best practices for caching"	"cache_ttl_seconds"
"explain the data model"	"UserSchema"
"what is the purpose of..."	exact function names

Execution

Pre-flight Check

Verify the server is running and has indexed documents:

agent-brain status

Expected output shows:

• Server status: healthy
• Document count: > 0
• Mode: project or shared

Search Command

agent-brain query "<query>" --mode vector --top-k <top-k> --threshold <threshold>

Examples

# Conceptual query
agent-brain query "how does the authentication system work" --mode vector

# More results for broader exploration
agent-brain query "best practices for error handling" --mode vector --top-k 10

# Higher threshold for more precise matches
agent-brain query "explain caching strategy" --mode vector --threshold 0.5

# Lower threshold to find tangentially related docs
agent-brain query "security considerations" --mode vector --threshold 0.2

Output

Format search results with source citations:

Result Format

For each result, present:

1. Source: File path or document name
2. Score: Semantic similarity score (0-1)
3. Content: Relevant excerpt from the document

Example Output

## Semantic Search Results for "how does caching work"

### 1. docs/architecture/caching.md (Score: 0.92)
The caching layer uses a multi-tier approach with in-memory LRU cache
for hot data and Redis for distributed caching. Cache invalidation
follows the write-through pattern...

### 2. docs/performance/optimization.md (Score: 0.78)
Performance optimization relies heavily on caching strategies.
The system implements time-based expiration with configurable TTL
values per resource type...

### 3. src/cache/redis_client.py (Score: 0.71)
"""Redis cache client with connection pooling and retry logic."""
class RedisCache:
    def __init__(self, ttl: int = 3600):
        ...

---
Found 3 results above threshold 0.3

Citation Format

When referencing results in responses, always cite the source:

• "The caching documentation (docs/architecture/caching.md) explains..."
• "Based on the performance guide..."

Error Handling

Server Not Running

Error: Could not connect to Agent Brain server

Resolution: Start the server with agent-brain start --daemon

No Results Found

No results found above threshold 0.3

Resolution:

• Try lowering the threshold: --threshold 0.1
• Rephrase the query with different conceptual terms
• Consider using hybrid search for better coverage: --mode hybrid

API Key Missing

Error: OPENAI_API_KEY not set

Resolution: Semantic search requires OpenAI API for embeddings:

export OPENAI_API_KEY="sk-proj-..."

Slow Response

Semantic search typically takes 800-1500ms due to embedding generation.

If consistently slow:

• Check network connectivity to OpenAI API
• Consider using BM25 for time-sensitive queries
• Use hybrid search with lower alpha for faster results

Index Empty

Warning: No documents indexed

Resolution: Index documents first:

agent-brain index /path/to/docs

Performance Notes

Metric	Typical Value
Latency	800-1500ms
API calls	1 embedding request per query
Best for	Conceptual queries, natural language