/agent-brain-vector

name: agent-brain-vector
description: Search using semantic vector similarity for concepts
parameters:
  - name: query
    description: The conceptual search query
    required: true
  - name: top-k
    description: Number of results to return (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
last_validated: 2026-03-16

Agent Brain Vector Search

Purpose

Performs semantic vector similarity search using embeddings. This mode understands meaning and concepts, finding relevant content even when exact terms don't match.

Vector search is ideal for:

• Conceptual questions ("how does X work")
• Natural language queries
• Finding related content
• Questions about purpose or design
• When exact terms are unknown

Usage

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

Parameters

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | query | Yes | - | The conceptual search query | | --top-k, -k | No | 5 | Number of results (1-20) | | --threshold, -t | No | 0.3 | Minimum similarity (0.0-1.0) | | --source-types | No | - | Filter by source type (doc,code,test) | | --languages | No | - | Filter by programming language | | --file-paths | No | - | Filter by file path patterns (wildcards) | | --scores | No | false | Show individual vector/BM25 scores | | --full | No | false | Show full text content | | --json | No | false | Output as JSON | | --url | No | from config | Server URL (env: AGENT_BRAIN_URL) |

When to Use Vector vs Other Modes

| Use Vector | Use BM25 Instead | |------------|------------------| | "how does authentication work" | "AuthenticationError" | | "best practices for caching" | "LRUCache" | | "explain the deployment process" | "deploy.yml" | | "security considerations" | "CVE-2024-1234" | | "similar to user validation" | "validate_user" |

Execution

Pre-flight Check

# Verify server is running
agent-brain status

If not running:

agent-brain start

Search Command

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

Examples

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

# Natural language
agent-brain query "best practices for handling errors" --mode vector

# Find related content
agent-brain query "similar to user authentication flow" --mode vector

# Lower threshold for more results
agent-brain query "security considerations" --mode vector --threshold 0.2

# More results
agent-brain query "explain the API design" --mode vector --top-k 10

Output

Result Format

For each result, present:

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

Example Output

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

### 1. docs/architecture/caching.md (Score: 0.92)
## Caching Architecture

The system implements a multi-tier caching strategy:

1. **L1 Cache (In-Memory LRU)**: Fast access for frequently used data
2. **L2 Cache (Redis)**: Distributed cache for cross-instance sharing
3. **L3 Cache (CDN)**: Edge caching for static assets

Cache invalidation uses a write-through strategy...

### 2. docs/performance/optimization.md (Score: 0.78)
## Caching for Performance

Proper cache configuration can improve response times by 10-100x.

**Configuration options:**
- TTL by resource type
- Cache warming strategies
- Invalidation webhooks

### 3. src/cache/redis_client.py (Score: 0.71)
class RedisCache:
    """
    Redis-based distributed cache implementation.

    Provides connection pooling, automatic reconnection,
    and configurable TTL per key prefix.
    """

---
Found 3 results above threshold 0.3
Search mode: vector (semantic)
Response time: 1247ms

Citation Format

When referencing results in responses:

• "The caching architecture is documented in `docs/architecture/caching.md`..."
• "According to `docs/performance/optimization.md`..."

Error Handling

Server Not Running

Error: Could not connect to Agent Brain server

**Resolution:**

agent-brain start

No Results Found

No results found above threshold 0.3

**Resolution:**

• Try lowering threshold: `--threshold 0.1`
• Rephrase the query
• Use hybrid mode for mixed queries: `--mode hybrid`
• Verify documents are indexed: `agent-brain status`

Embedding Provider Not Configured

Error: Embedding provider not configured

**Resolution:**

# OpenAI (cloud)
export OPENAI_API_KEY="sk-proj-..."

# Or use local Ollama (free, no API key):
# Configure in config.yaml: embedding.provider: ollama, embedding.model: nomic-embed-text

Embedding Provider Error

Error: Failed to generate embedding

**Resolution:**

• Check API key is valid
• For Ollama: ensure model is pulled and server is running
• Verify embedding provider configuration: `agent-brain verify`

Index Empty

Warning: No documents indexed

**Resolution:**

agent-brain index /path/to/docs

Performance Notes

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

Comparison with Other Modes

| Aspect | Vector | BM25 | Hybrid | |--------|--------|------|--------| | Speed | Slow | Fast | Medium | | Exact terms | Poor | Excellent | Good | | Concepts | Excellent | Poor | Good | | API cost | Per query | Free | Per query |

Embedding Quality Factors

Vector search quality depends on: 1. **Embedding model**: text-embedding-3-large > small > ada-002 2. **Document quality**: Well-written docs match better 3. **Query phrasing**: Natural language works best 4. **Threshold setting**: Lower for more recall,