17 KiB
17 KiB
name, description, allowed-tools
| name | description | allowed-tools |
|---|---|---|
| semantic-search | Use semantic search to find relevant code and documentation when user asks about specific functionality, features, or implementation patterns. Automatically invoke when user asks "where is...", "how does... work", "find code that...", or similar conceptual queries. More powerful than grep for concept-based searches. Uses odino CLI with BGE embeddings for fully local semantic search. | Bash, Read |
Semantic Search
Overview
Enable natural language semantic search across codebases and notes using odino CLI with BGE embeddings. Unlike grep (exact text matching) or glob (filename patterns), semantic search finds code by what it does, not what it's called.
When to Use This Skill
Automatically invoke semantic search when the user:
- Asks "where is [concept]" or "how does [feature] work"
- Wants to find implementation of a concept/pattern
- Needs to understand codebase structure around a topic
- Searches for patterns by meaning, not exact text
- Asks exploratory questions like "show me authentication logic"
Do not use for:
- Exact string matching (use grep)
- Filename patterns (use glob)
- Known file paths (use read)
- When the user explicitly requests grep/glob
Directory Traversal Logic
Odino requires running commands from the directory containing .odino/ config. To make this transparent (like git), use this helper function:
# Function to find .odino directory by traversing up the directory tree
find_odino_root() {
local dir="$PWD"
while [[ "$dir" != "/" ]]; do
if [[ -d "$dir/.odino" ]]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
return 1
}
# Usage in commands
if ODINO_ROOT=$(find_odino_root); then
echo "Found index at: $ODINO_ROOT"
(cd "$ODINO_ROOT" && odino query -q "$QUERY")
else
echo "No .odino index found in current path"
echo "Suggestion: Run /semq:index to create an index"
fi
Why this matters:
- User can be in any subdirectory of their project
- Commands automatically find the project root (where
.odino/lives) - Mirrors git behavior (works from anywhere in the tree)
Quick Start
Check if Directory is Indexed
Before searching, verify an index exists:
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino status)
else
echo "No index found. Suggest running /semq:index"
fi
Search Indexed Codebase
# Basic search
odino query -q "authentication logic"
# With directory traversal
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino query -q "$QUERY")
fi
Parse and Present Results
Odino returns results in a formatted table:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Search Algorithms.md │ 0.361 │ 1 --- │
│ │ │ 2 tags: [todo/stub] │
│ │ │ 3 module: CMPU 4010 │
│ │ │ ... │
│ │ │ 7 # Search Algorithms in AI │
│ │ │ ... │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Found 2 results
Enhanced workflow:
- Parse table to extract file paths, scores, and content previews
- Read top 2-3 results (score > 0.3) for full context
- Summarize findings with explanations
- Use code-pointer to open most relevant file
- Suggest follow-up queries or related concepts
Query Inference
Transform user requests into better semantic queries with realistic output examples.
Example 1: Conceptual Query
User asks: "error handling"
Inferred query: error handling exception management try catch validation
Sample odino output:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Error Handling.md │ 0.876 │ 1 --- │
│ │ │ 2 tags: [software-eng, best- │
│ │ │ 3 --- │
│ │ │ 4 # Error Handling │
│ │ │ 5 │
│ │ │ 6 Error handling is the proc │
│ │ │ 7 runtime errors gracefully │
│ │ │ 8 system stability. │
│ │ │ 9 │
│ │ │ 10 ## Key Concepts │
│ │ │ 11 - Try-catch blocks for syn │
│ │ │ 12 - Promise rejection handli │
│ │ │ 13 - Input validation to prev │
│ │ │ 14 - Logging errors for debug │
│ │ │ 15 - User-friendly error mess │
│ │ │ 16 │
│ │ │ 17 ## Best Practices │
│ │ │ 18 1. Fail fast - validate ea │
│ │ │ 19 2. Log with context - incl │
│ │ │ 20 3. Don't swallow errors - │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Example 2: Code Query
User asks: "DB connection code" Inferred query:
database connection pooling setup
import mysql.connector
pool = mysql.connector.pooling.MySQLConnectionPool(
pool_name="mypool",
pool_size=5,
host="localhost",
database="mydb"
)
connection = pool.get_connection()
Sample odino output:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/db/connection.js │ 0.924 │ 1 const mysql = require('mys │
│ │ │ 2 │
│ │ │ 3 // Create connection pool │
│ │ │ 4 const pool = mysql.createP │
│ │ │ 5 host: process.env.DB_HOS │
│ │ │ 6 user: process.env.DB_USE │
│ │ │ 7 password: process.env.DB │
│ │ │ 8 database: process.env.DB │
│ │ │ 9 waitForConnections: true │
│ │ │ 10 connectionLimit: 10, │
│ │ │ 11 queueLimit: 0 │
│ │ │ 12 }); │
│ │ │ 13 │
│ │ │ 14 // Test connection │
│ │ │ 15 pool.getConnection((err, c │
│ │ │ 16 if (err) { │
│ │ │ 17 console.error('DB conn │
│ │ │ 18 process.exit(1); │
│ │ │ 19 } │
│ │ │ 20 console.log('Connected t │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Example 3: Algorithm Query (with code)
User asks: "BFS algorithm in Python" Inferred query:
breadth first search BFS graph traversal queue
def bfs(graph, start):
visited = set()
queue = [start]
while queue:
node = queue.pop(0)
if node not in visited:
visited.add(node)
queue.extend(graph[node])
return visited
Sample odino output:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Search Algorithms.md │ 0.891 │ 1 --- │
│ │ │ 2 tags: [ai, algorithms] │
│ │ │ 3 module: CMPU 4010 AI │
│ │ │ 4 --- │
│ │ │ 5 # Search Algorithms in AI │
│ │ │ 6 │
│ │ │ 7 Algorithms for finding sol │
│ │ │ 8 problem spaces. Used in pa │
│ │ │ 9 game AI, and optimization. │
│ │ │ 10 │
│ │ │ 11 ## Types │
│ │ │ 12 │
│ │ │ 13 ### Uninformed Search │
│ │ │ 14 - **BFS**: Explores level │
│ │ │ 15 - **DFS**: Explores deeply │
│ │ │ 16 - **Uniform Cost**: Expand │
│ │ │ 17 │
│ │ │ 18 ### Informed Search │
│ │ │ 19 - **A***: Uses heuristic + │
│ │ │ 20 - **Greedy**: Only conside │
│ │ │ 21 - **Hill Climbing**: Local │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Inference Patterns
- Expand abbreviations: DB → database, auth → authentication
- Code queries include sample code: User asks "connection pooling" → Query includes Python example with
pool.get_connection() - Use specified language: User mentions "JavaScript" → Use JavaScript syntax in query
- Default to Python: No language specified → Use Python code examples
- Add related concepts: "search" → include BFS, DFS, A* terminology
- Add context words: "handling", "management", "setup", "configuration"
Core Capabilities
1. Semantic Search
Find code by describing what it does, not exact text:
User asks: "Where is the database connection handling?"
Workflow:
- Check if directory is indexed (use
find_odino_root) - Run
odino query -q "database connection handling" - Parse results and rank by score
- Read top 2-3 results for context
- Summarize findings with file paths
- Suggest using code-pointer to open specific files
Example:
if ODINO_ROOT=$(find_odino_root); then
RESULTS=$(cd "$ODINO_ROOT" && odino query -q "database connection handling")
# Parse results, read top files, summarize
else
echo "No index found. Would you like me to index this directory?"
fi
2. Index Status Check
Verify indexing status before operations:
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino status)
# Shows: indexed files, model, last update
else
echo "No .odino index found"
fi
3. Integration with Other Tools
Semantic search → code-pointer:
# After finding relevant file
echo "Found authentication logic in src/auth/middleware.js:42"
echo "Opening file..."
code -g src/auth/middleware.js:42
Semantic search → grep refinement:
# Use semantic search to find the area
odino query -q "API endpoint handlers"
# Then use grep for exact matches in those files
grep -n "app.get\|app.post" src/routes/*.js
4. Handling Edge Cases
No index found:
if ! ODINO_ROOT=$(find_odino_root); then
echo "No semantic search index found in current path."
echo ""
echo "To create an index, run:"
echo " /semq:index"
echo ""
echo "This will index the current directory for semantic search."
fi
Empty results:
if [[ -z "$RESULTS" ]]; then
echo "No results found for query: $QUERY"
echo ""
echo "Suggestions:"
echo "- Try a different query (more general or specific)"
echo "- Verify the index is up to date (/semq:status)"
echo "- Consider using grep for exact text matching"
fi
Slash Commands
This skill provides several slash commands for explicit control:
/semq:search <query>- Search indexed codebase/semq:here <query>- Search with automatic directory traversal/semq:index [path]- Index directory for semantic search/semq:status [path]- Show indexing status and stats
Best Practices
- Always check for index first - Use
find_odino_rootbefore search operations - Parse results clearly - Show scores, file paths, and context
- Combine with other tools - Use code-pointer for opening files, grep for exact matches
- Handle failures gracefully - Suggest solutions when no index or no results
- Read top results - Provide context by reading the most relevant files
- Use directory traversal - Don't assume user is in project root
Effective Query Patterns
Good queries are conceptual, not literal:
-
❌ "config.js" → Use glob instead
-
✅ "configuration loading logic"
-
❌ "validateEmail" → Use grep instead
-
✅ "email validation functions"
-
❌ "class AuthService" → Use grep instead
-
✅ "authentication service implementation"
Technical Details
Model: BAAI/bge-small-en-v1.5 (33M params, ~133MB)
Vector DB: ChromaDB (stored in .odino/chroma_db/)
Index location: .odino/ directory in project root
Embedding batch size: 16 (GPU) or 8 (CPU)
Reference Documentation
For detailed information, see:
references/cli_basics.md- Odino CLI syntax, commands, and optionsreferences/search_patterns.md- Effective query examples and tipsreferences/integration.md- Workflows with code-pointer, grep, glob
Load these references as needed for deeper technical details or complex use cases.