1. Semantic Search: Find code/text by meaning, not just keywords
2. Workspace Management: Index large codebases for fast repeated searches
3. Document Parsing: Convert PDFs, DOCX, PPTX to searchable text (requires API key)

• Finding code that implements a concept ("error handling", "data validation")
• Discovering similar functionality across different modules
• Locating examples of a pattern when you don't know exact names
• Understanding what code does without reading everything

• Searching documentation by concept, not keywords
• Finding related discussions in comments or docs
• Discovering similar issues or solutions
• Analyzing technical documents (PDFs, reports)

• "Find all authentication-related code" (without knowing function names)
• "Show me error handling patterns" (regardless of specific error types)
• "Find code similar to this implementation" (semantic similarity)
• "Search research papers for 'distributed consensus'" (document search)

• You know the concept but not the keywords
• Exact string matching misses relevant results
• You want semantically similar code, not exact matches
• Searching across languages or mixed content

• You know exact keywords, function names, or patterns
• You need structural code matching (ast-grep)
• Speed is critical (ripgrep is faster for exact matches)
• You're searching for specific symbols or references

execute_command

• search

  - Semantic search across code and text files

• workspace

  - Manage workspaces for caching embeddings

• parse

  - Convert documents (PDF, DOCX, PPTX) to searchable text

**Parameters:**
- `--n-lines N`: Show N lines of context around matches (default: 3)
- `--top-k K`: Return top K most similar matches (default: 3)
- `--max-distance D`: Maximum embedding distance (0.0-1.0, default: 0.3)
- `-i`: Case-insensitive matching

**Output format:**

Match 1 (similarity: 0.12) File: src/auth/handlers.py Lines: 42-47

def authenticate_user(username: str, password: str) -> Optional[User]: """Authenticate user credentials against database.""" user = get_user_by_username(username) if user and verify_password(password, user.password_hash): return user return None

undefined

• Distance 0.0: Identical meaning
• Distance 0.1-0.2: Very similar (synonyms, paraphrases)
• Distance 0.2-0.3: Related concepts (default threshold)
• Distance 0.3-0.4: Loosely related
• Distance 0.5+: Weakly related or unrelated

undefined

• Uses local embeddings (model2vec, potion-multilingual-128M)
• No API calls or cloud dependencies
• Fast, private, no cost
• Works offline

• Uses LlamaParse API (cloud-based)
• Requires API key and internet connection
• Processes PDFs, DOCX, PPTX
• Usage-based pricing (check LlamaIndex pricing)

• First search: ~2-5 seconds (embedding computation)
• Subsequent searches: ~2-5 seconds each (re-compute embeddings)

• First search: ~2-5 seconds (builds index)
• Subsequent searches: ~0.1-0.5 seconds (cached)
• Large codebases: IVF_PQ indexing for scalability

• ripgrep: 0.01-0.1 seconds (fastest, exact match)
• ast-grep: 0.1-0.5 seconds (fast, structural)
• semtools (cached): 0.1-0.5 seconds (fast, semantic)
• semtools (uncached): 2-5 seconds (slower, semantic)

1. Exact keyword search: Use ripgrep for known keywords
   bash

   # WRONG TOOL: Semantic search for exact function name
   search "authenticate_user"
   
   # RIGHT TOOL: Use ripgrep for exact matches
   rg "authenticate_user" --type py

2. Structural code patterns: Use ast-grep for syntax matching
   bash

   # WRONG TOOL: Semantic search for code structure
   search "class with constructor"
   
   # RIGHT TOOL: Use ast-grep for structure
   sg --pattern 'class $NAME { constructor($$$) { $$$ } }'

3. Symbol references: Use serena for LSP-based tracking
   bash

   # WRONG TOOL: Semantic search for all usages
   search "MyClass usage"
   
   # RIGHT TOOL: Use serena for precise references
   serena find_referencing_symbols --name 'MyClass'

4. Small codebases: Overhead not worth it for <100 files
   • ripgrep is faster and simpler for small projects

• Ambiguous queries: Vague concepts return broad results
• Technical jargon: Domain-specific terms may have lower accuracy
• Short code snippets: Limited context reduces embedding quality
• Mixed languages: Embeddings tuned for English (multilingual model used)
• Generated code: Repetitive patterns may cluster together

1. Verify files exist: Use ripgrep to confirm content
   bash

   rg "concept" src/

2. Increase similarity threshold: Be more lenient
   bash

   search "query" --max-distance 0.5

3. Rephrase query: Try different terminology
   bash

   search "user authentication"
   search "verify user credentials"
   search "login validation"

4. Check file types: Ensure searching correct extensions
   bash

   search "query" src/*.py  # Target specific types

1. Decrease similarity threshold: Be more strict
   bash

   search "query" --max-distance 0.2

2. Limit result count: Review top matches only
   bash

   search "query" --top-k 3

3. Narrow directory scope: Search specific paths
   bash

   search "query" src/specific_module/

4. Refine query: Add more specific concepts
   bash

   # Vague
   search "data"
   
   # Specific
   search "data validation with regex patterns"

parse

1. Verify API key is set:
   bash

   echo $LLAMA_CLOUD_API_KEY

2. Check file format: Ensure supported format (PDF, DOCX, PPTX)
   bash

   file document.pdf  # Verify file type

3. Check file size: Large files may timeout
   bash

   du -h document.pdf  # Check size

4. Review parse config: Adjust timeouts if needed
   bash

   cat ~/.parse_config.json

• Semtools GitHub
• LlamaParse Documentation
• model2vec Embeddings
• Semantic Search Concepts