Code Semantic Search

Overview

Phase 2: Hybrid Search

1. Hybrid (Default):
   • Combines semantic + structural search
   • Best accuracy (95%+)
   • Slightly slower but still <150ms
   • Recommended for all searches
2. Semantic-Only:
   • Uses only Phase 1 semantic vectors
   • Fastest (<50ms)
   • Good for conceptual searches
   • Use when structure doesn't matter
3. 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

When to Use

• Finding authentication logic without knowing function names
• Searching for error handling patterns
• Locating database queries
• Finding similar code to a concept
• Discovering implementation patterns

• 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

.claude/lib/code-indexing/hybrid-search.cjs

.claude/lib/code-indexing/query-analyzer.cjs

.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

Memory Protocol (MANDATORY)

.claude/context/memory/learnings.md

• 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.