Code Semantic Search

Overview

Semantic code search using Phase 1 vector embeddings and Phase 2 hybrid search (semantic + structural). Find code by meaning, not just keywords.

Core principle: Search code by what it does, not what it's called.

Phase 2: Hybrid Search

This skill now supports three search modes:

Hybrid (Default):

• Combines semantic + structural search

• Best accuracy (95%+)

• Slightly slower but still <150ms

• Recommended for all searches

Semantic-Only:

• Uses only Phase 1 semantic vectors

• Fastest (<50ms)

• Good for conceptual searches

• Use when structure doesn't matter

Structural-Only:

• Uses only ast-grep patterns

• Precise for exact matches

• Best for finding function/class definitions

• Use when you need exact structural patterns

Performance Comparison

Mode Speed Accuracy Best For

Hybrid <150ms 95% General search

Semantic-only <50ms 85% Concepts

Structural-only <50ms 100% Exact patterns

Phase 1 only <50ms 80% Legacy (fallback)

When to Use

Always:

• Finding authentication logic without knowing function names

• Searching for error handling patterns

• Locating database queries

• Finding similar code to a concept

• Discovering implementation patterns

Don't Use:

• Exact text matching (use Grep instead)

• File name searches (use Glob instead)

• Simple keyword searches (use ripgrep instead)

Usage Examples

Hybrid Search (Recommended)

// Basic hybrid search Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options Skill({ skill: 'code-semantic-search', args: 'database queries', options: { mode: 'hybrid', language: 'javascript', limit: 10, }, });

Semantic-Only Search

// Fast conceptual search Skill({ skill: 'code-semantic-search', args: 'find authentication', options: { mode: 'semantic-only' }, });

Structural-Only Search

// Exact pattern matching Skill({ skill: 'code-semantic-search', args: 'find function authenticate', options: { mode: 'structural-only' }, });

Implementation Reference

Hybrid Search: .claude/lib/code-indexing/hybrid-search.cjs

Query Analysis: .claude/lib/code-indexing/query-analyzer.cjs

Result Ranking: .claude/lib/code-indexing/result-ranker.cjs

Integration Points

• developer: Code exploration, implementation discovery

• architect: System understanding, pattern analysis

• code-reviewer: Finding similar patterns, consistency checks

• reverse-engineer: Understanding unfamiliar codebases

• researcher: Research existing implementations

Iron Laws

• ALWAYS use hybrid mode (semantic + structural) for general searches — semantic-only misses exact matches; structural-only misses conceptual variants; hybrid provides 95% accuracy vs 85% for single mode.

• ALWAYS use ripgrep/keyword search first for fast keyword discovery — semantic search is for meaning-based queries; exact strings, function names, and filenames are found faster with ripgrep.

• NEVER use semantic search without a meaningful natural-language query — single-word or code-syntax queries produce poor semantic results; describe what the code does, not what it's called.

• ALWAYS combine with code-structural-search for precision refinement — start broad with semantic discovery, then use ast-grep patterns to find exact structural matches from the semantic results.

• NEVER ignore low-similarity results without checking them — similarity scores are approximations; a 0.7 score result may be more relevant than a 0.9 score result for uncommon patterns.

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Semantic search for exact string matching Slower and less accurate than text search Use ripgrep/Grep for exact keyword matching

Single-word queries ("auth") Too vague for semantic matching; returns noise Use natural-language descriptions ("authentication token validation logic")

Using semantic-only mode for general searches Misses structural variants; 85% vs 95% accuracy Use hybrid mode (default) for general queries

Ignoring search results that don't match expectations Semantic results find surprising-but-relevant code Read all results; unexpected matches are often the most valuable

Not combining with structural search Finds concepts but not exact patterns Use semantic for discovery → structural for precision

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.