claude-code-workflow 6.3.18 → 6.3.19

package/codex-lens/src/codexlens/search/chain_search.py

@@ -9,18 +9,30 @@ from __future__ import annotations
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Optional, Dict, Any
+from typing import List, Optional, Dict, Any, Literal, Tuple, TYPE_CHECKING
+import json
 import logging
 import os
 import time
 
 from codexlens.entities import SearchResult, Symbol
+
+if TYPE_CHECKING:
+    import numpy as np
+
+try:
+    import numpy as np
+    NUMPY_AVAILABLE = True
+except ImportError:
+    NUMPY_AVAILABLE = False
 from codexlens.config import Config
 from codexlens.storage.registry import RegistryStore, DirMapping
 from codexlens.storage.dir_index import DirIndexStore, SubdirLink
 from codexlens.storage.global_index import GlobalSymbolIndex
 from codexlens.storage.path_mapper import PathMapper
 from codexlens.storage.sqlite_store import SQLiteStore
+from codexlens.storage.vector_meta_store import VectorMetadataStore
+from codexlens.config import VECTORS_META_DB_NAME
 from codexlens.search.hybrid_search import HybridSearchEngine
 
 
@@ -33,13 +45,18 @@ class SearchOptions:
         max_workers: Number of parallel worker threads
         limit_per_dir: Maximum results per directory
         total_limit: Total result limit across all directories
+        offset: Pagination offset - skip first N results (default 0)
         include_symbols: Whether to include symbol search results
         files_only: Return only file paths without excerpts
         include_semantic: Whether to include semantic keyword search results
+        code_only: Only return code files (excludes md, txt, json, yaml, xml, etc.)
+        exclude_extensions: List of file extensions to exclude (e.g., ["md", "txt", "json"])
         hybrid_mode: Enable hybrid search with RRF fusion (default False)
         enable_fuzzy: Enable fuzzy FTS in hybrid mode (default True)
         enable_vector: Enable vector semantic search (default False)
         pure_vector: If True, only use vector search without FTS fallback (default False)
+        enable_splade: Enable SPLADE sparse neural search (default False)
+        enable_cascade: Enable cascade (binary+dense) two-stage retrieval (default False)
         hybrid_weights: Custom RRF weights for hybrid search (optional)
         group_results: Enable grouping of similar results (default False)
         grouping_threshold: Score threshold for grouping similar results (default 0.01)
@@ -48,13 +65,18 @@ class SearchOptions:
     max_workers: int = 8
     limit_per_dir: int = 10
     total_limit: int = 100
+    offset: int = 0
     include_symbols: bool = False
     files_only: bool = False
     include_semantic: bool = False
+    code_only: bool = False
+    exclude_extensions: Optional[List[str]] = None
     hybrid_mode: bool = False
     enable_fuzzy: bool = True
     enable_vector: bool = False
     pure_vector: bool = False
+    enable_splade: bool = False
+    enable_cascade: bool = False
     hybrid_weights: Optional[Dict[str, float]] = None
     group_results: bool = False
     grouping_threshold: float = 0.01
@@ -83,6 +105,7 @@ class ChainSearchResult:
     Attributes:
         query: Original search query
         results: List of SearchResult objects
+        related_results: Expanded results from graph neighbors (optional)
         symbols: List of Symbol objects (if include_symbols=True)
         stats: SearchStats with execution metrics
     """
@@ -90,6 +113,7 @@ class ChainSearchResult:
     results: List[SearchResult]
     symbols: List[Symbol]
     stats: SearchStats
+    related_results: List[SearchResult] = field(default_factory=list)
 
 
 class ChainSearchEngine:
@@ -217,8 +241,14 @@ class ChainSearchEngine:
         )
         stats.errors = search_stats.errors
 
+        # Step 3.5: Filter by extension if requested
+        if options.code_only or options.exclude_extensions:
+            results = self._filter_by_extension(
+                results, options.code_only, options.exclude_extensions
+            )
+
         # Step 4: Merge and rank
-        final_results = self._merge_and_rank(results, options.total_limit)
+        final_results = self._merge_and_rank(results, options.total_limit, options.offset)
 
         # Step 5: Optional grouping of similar results
         if options.group_results:
@@ -236,13 +266,1562 @@ class ChainSearchEngine:
                 index_paths, query, None, options.total_limit
             )
 
+        # Optional: graph expansion using precomputed neighbors
+        related_results: List[SearchResult] = []
+        if self._config is not None and getattr(self._config, "enable_graph_expansion", False):
+            try:
+                from codexlens.search.enrichment import SearchEnrichmentPipeline
+
+                pipeline = SearchEnrichmentPipeline(self.mapper, config=self._config)
+                related_results = pipeline.expand_related_results(final_results)
+            except Exception as exc:
+                self.logger.debug("Graph expansion failed: %s", exc)
+                related_results = []
+
         stats.time_ms = (time.time() - start_time) * 1000
 
         return ChainSearchResult(
             query=query,
             results=final_results,
             symbols=symbols,
-            stats=stats
+            stats=stats,
+            related_results=related_results,
+        )
+
+    def hybrid_cascade_search(
+        self,
+        query: str,
+        source_path: Path,
+        k: int = 10,
+        coarse_k: int = 100,
+        options: Optional[SearchOptions] = None,
+    ) -> ChainSearchResult:
+        """Execute two-stage cascade search with hybrid coarse retrieval and cross-encoder reranking.
+
+        Hybrid cascade search process:
+        1. Stage 1 (Coarse): Fast retrieval using RRF fusion of FTS + SPLADE + Vector
+           to get coarse_k candidates
+        2. Stage 2 (Fine): CrossEncoder reranking of candidates to get final k results
+
+        This approach balances recall (from broad coarse search) with precision
+        (from expensive but accurate cross-encoder scoring).
+
+        Note: This method is the original hybrid approach. For binary vector cascade,
+        use binary_cascade_search() instead.
+
+        Args:
+            query: Natural language or keyword query string
+            source_path: Starting directory path
+            k: Number of final results to return (default 10)
+            coarse_k: Number of coarse candidates from first stage (default 100)
+            options: Search configuration (uses defaults if None)
+
+        Returns:
+            ChainSearchResult with reranked results and statistics
+
+        Examples:
+            >>> engine = ChainSearchEngine(registry, mapper, config=config)
+            >>> result = engine.hybrid_cascade_search(
+            ...     "how to authenticate users",
+            ...     Path("D:/project/src"),
+            ...     k=10,
+            ...     coarse_k=100
+            ... )
+            >>> for r in result.results:
+            ...     print(f"{r.path}: {r.score:.3f}")
+        """
+        options = options or SearchOptions()
+        start_time = time.time()
+        stats = SearchStats()
+
+        # Use config defaults if available
+        if self._config is not None:
+            if hasattr(self._config, "cascade_coarse_k"):
+                coarse_k = coarse_k or self._config.cascade_coarse_k
+            if hasattr(self._config, "cascade_fine_k"):
+                k = k or self._config.cascade_fine_k
+
+        # Step 1: Find starting index
+        start_index = self._find_start_index(source_path)
+        if not start_index:
+            self.logger.warning(f"No index found for {source_path}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Step 2: Collect all index paths
+        index_paths = self._collect_index_paths(start_index, options.depth)
+        stats.dirs_searched = len(index_paths)
+
+        if not index_paths:
+            self.logger.warning(f"No indexes collected from {start_index}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Stage 1: Coarse retrieval with hybrid search (FTS + SPLADE + Vector)
+        # Use hybrid mode for multi-signal retrieval
+        coarse_options = SearchOptions(
+            depth=options.depth,
+            max_workers=1,  # Single thread for GPU safety
+            limit_per_dir=max(coarse_k // len(index_paths), 20),
+            total_limit=coarse_k,
+            hybrid_mode=True,
+            enable_fuzzy=options.enable_fuzzy,
+            enable_vector=True,  # Enable vector for semantic matching
+            pure_vector=False,
+            hybrid_weights=options.hybrid_weights,
+        )
+
+        self.logger.debug(
+            "Cascade Stage 1: Coarse retrieval for %d candidates", coarse_k
+        )
+        coarse_results, search_stats = self._search_parallel(
+            index_paths, query, coarse_options
+        )
+        stats.errors = search_stats.errors
+
+        # Merge and deduplicate coarse results
+        coarse_merged = self._merge_and_rank(coarse_results, coarse_k)
+        self.logger.debug(
+            "Cascade Stage 1 complete: %d candidates retrieved", len(coarse_merged)
+        )
+
+        if not coarse_merged:
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Stage 2: Cross-encoder reranking
+        self.logger.debug(
+            "Cascade Stage 2: Cross-encoder reranking %d candidates to top-%d",
+            len(coarse_merged),
+            k,
+        )
+
+        final_results = self._cross_encoder_rerank(query, coarse_merged, k)
+
+        # Optional: grouping of similar results
+        if options.group_results:
+            from codexlens.search.ranking import group_similar_results
+            final_results = group_similar_results(
+                final_results, score_threshold_abs=options.grouping_threshold
+            )
+
+        stats.files_matched = len(final_results)
+        stats.time_ms = (time.time() - start_time) * 1000
+
+        self.logger.debug(
+            "Cascade search complete: %d results in %.2fms",
+            len(final_results),
+            stats.time_ms,
+        )
+
+        return ChainSearchResult(
+            query=query,
+            results=final_results,
+            symbols=[],
+            stats=stats,
+        )
+
+    def binary_cascade_search(
+        self,
+        query: str,
+        source_path: Path,
+        k: int = 10,
+        coarse_k: int = 100,
+        options: Optional[SearchOptions] = None,
+    ) -> ChainSearchResult:
+        """Execute binary cascade search with binary coarse ranking and dense fine ranking.
+
+        Binary cascade search process:
+        1. Stage 1 (Coarse): Fast binary vector search using Hamming distance
+           to quickly filter to coarse_k candidates (256-dim binary, 32 bytes/vector)
+        2. Stage 2 (Fine): Dense vector cosine similarity for precise reranking
+           of candidates (2048-dim float32)
+
+        This approach leverages the speed of binary search (~100x faster) while
+        maintaining precision through dense vector reranking.
+
+        Performance characteristics:
+        - Binary search: O(N) with SIMD-accelerated XOR + popcount
+        - Dense rerank: Only applied to top coarse_k candidates
+        - Memory: 32 bytes (binary) + 8KB (dense) per chunk
+
+        Args:
+            query: Natural language or keyword query string
+            source_path: Starting directory path
+            k: Number of final results to return (default 10)
+            coarse_k: Number of coarse candidates from first stage (default 100)
+            options: Search configuration (uses defaults if None)
+
+        Returns:
+            ChainSearchResult with reranked results and statistics
+
+        Examples:
+            >>> engine = ChainSearchEngine(registry, mapper, config=config)
+            >>> result = engine.binary_cascade_search(
+            ...     "how to authenticate users",
+            ...     Path("D:/project/src"),
+            ...     k=10,
+            ...     coarse_k=100
+            ... )
+            >>> for r in result.results:
+            ...     print(f"{r.path}: {r.score:.3f}")
+        """
+        if not NUMPY_AVAILABLE:
+            self.logger.warning(
+                "NumPy not available, falling back to hybrid cascade search"
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        options = options or SearchOptions()
+        start_time = time.time()
+        stats = SearchStats()
+
+        # Use config defaults if available
+        if self._config is not None:
+            if hasattr(self._config, "cascade_coarse_k"):
+                coarse_k = coarse_k or self._config.cascade_coarse_k
+            if hasattr(self._config, "cascade_fine_k"):
+                k = k or self._config.cascade_fine_k
+
+        # Step 1: Find starting index
+        start_index = self._find_start_index(source_path)
+        if not start_index:
+            self.logger.warning(f"No index found for {source_path}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Step 2: Collect all index paths
+        index_paths = self._collect_index_paths(start_index, options.depth)
+        stats.dirs_searched = len(index_paths)
+
+        if not index_paths:
+            self.logger.warning(f"No indexes collected from {start_index}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Initialize embedding backends
+        try:
+            from codexlens.indexing.embedding import (
+                BinaryEmbeddingBackend,
+                DenseEmbeddingBackend,
+            )
+            from codexlens.semantic.ann_index import BinaryANNIndex
+        except ImportError as exc:
+            self.logger.warning(
+                "Binary cascade dependencies not available: %s. "
+                "Falling back to hybrid cascade search.",
+                exc
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Stage 1: Binary vector coarse retrieval
+        self.logger.debug(
+            "Binary Cascade Stage 1: Binary coarse retrieval for %d candidates",
+            coarse_k,
+        )
+
+        use_gpu = True
+        if self._config is not None:
+            use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+        try:
+            binary_backend = BinaryEmbeddingBackend(use_gpu=use_gpu)
+            query_binary_packed = binary_backend.embed_packed([query])[0]
+        except Exception as exc:
+            self.logger.warning(
+                "Failed to generate binary query embedding: %s. "
+                "Falling back to hybrid cascade search.",
+                exc
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Try centralized BinarySearcher first (preferred for mmap indexes)
+        # The index root is the parent of the first index path
+        index_root = index_paths[0].parent if index_paths else None
+        all_candidates: List[Tuple[int, int, Path]] = []  # (chunk_id, distance, index_path)
+        used_centralized = False
+
+        if index_root:
+            centralized_searcher = self._get_centralized_binary_searcher(index_root)
+            if centralized_searcher is not None:
+                try:
+                    # BinarySearcher expects dense vector, not packed binary
+                    from codexlens.semantic.embedder import Embedder
+                    embedder = Embedder()
+                    query_dense = embedder.embed_to_numpy([query])[0]
+
+                    # Centralized search - returns (chunk_id, hamming_distance) tuples
+                    results = centralized_searcher.search(query_dense, top_k=coarse_k)
+                    for chunk_id, dist in results:
+                        all_candidates.append((chunk_id, dist, index_root))
+                    used_centralized = True
+                    self.logger.debug(
+                        "Centralized binary search found %d candidates", len(results)
+                    )
+                except Exception as exc:
+                    self.logger.debug(
+                        "Centralized binary search failed: %s, falling back to per-directory",
+                        exc
+                    )
+                    centralized_searcher.clear()
+
+        # Fallback: Search per-directory indexes with legacy BinaryANNIndex
+        if not used_centralized:
+            for index_path in index_paths:
+                try:
+                    # Get or create binary index for this path (uses deprecated BinaryANNIndex)
+                    binary_index = self._get_or_create_binary_index(index_path)
+                    if binary_index is None or binary_index.count() == 0:
+                        continue
+
+                    # Search binary index
+                    ids, distances = binary_index.search(query_binary_packed, coarse_k)
+                    for chunk_id, dist in zip(ids, distances):
+                        all_candidates.append((chunk_id, dist, index_path))
+
+                except Exception as exc:
+                    self.logger.debug(
+                        "Binary search failed for %s: %s", index_path, exc
+                    )
+                    stats.errors.append(f"Binary search failed for {index_path}: {exc}")
+
+        if not all_candidates:
+            self.logger.debug("No binary candidates found, falling back to hybrid")
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Sort by Hamming distance and take top coarse_k
+        all_candidates.sort(key=lambda x: x[1])
+        coarse_candidates = all_candidates[:coarse_k]
+
+        self.logger.debug(
+            "Binary Cascade Stage 1 complete: %d candidates retrieved",
+            len(coarse_candidates),
+        )
+
+        # Stage 2: Dense vector fine ranking
+        self.logger.debug(
+            "Binary Cascade Stage 2: Dense reranking %d candidates to top-%d",
+            len(coarse_candidates),
+            k,
+        )
+
+        try:
+            dense_backend = DenseEmbeddingBackend(use_gpu=use_gpu)
+            query_dense = dense_backend.embed_to_numpy([query])[0]
+        except Exception as exc:
+            self.logger.warning(
+                "Failed to generate dense query embedding: %s. "
+                "Using Hamming distance scores only.",
+                exc
+            )
+            # Fall back to using Hamming distance as score
+            return self._build_results_from_candidates(
+                coarse_candidates[:k], index_paths, stats, query, start_time,
+                use_centralized=used_centralized
+            )
+
+        # Group candidates by index path for batch retrieval
+        candidates_by_index: Dict[Path, List[int]] = {}
+        for chunk_id, _, index_path in coarse_candidates:
+            if index_path not in candidates_by_index:
+                candidates_by_index[index_path] = []
+            candidates_by_index[index_path].append(chunk_id)
+
+        # Retrieve dense embeddings and compute cosine similarity
+        scored_results: List[Tuple[float, SearchResult]] = []
+        import sqlite3
+
+        for index_path, chunk_ids in candidates_by_index.items():
+            try:
+                # Collect valid rows and dense vectors for batch processing
+                valid_rows: List[Dict[str, Any]] = []
+                dense_vectors: List["np.ndarray"] = []
+
+                if used_centralized:
+                    # Centralized mode: index_path is actually index_root directory
+                    # Dense embeddings are in per-directory _index.db files
+                    # referenced by source_index_db in chunk_metadata
+                    meta_db_path = index_path / VECTORS_META_DB_NAME
+                    if not meta_db_path.exists():
+                        self.logger.debug(
+                            "VectorMetadataStore not found at %s, skipping dense reranking", meta_db_path
+                        )
+                        continue
+
+                    # Get chunk metadata with source_index_db references
+                    meta_store = VectorMetadataStore(meta_db_path)
+                    chunks_meta = meta_store.get_chunks_by_ids(chunk_ids)
+
+                    # Group chunks by source_index_db
+                    chunks_by_source: Dict[str, List[Dict[str, Any]]] = {}
+                    for chunk in chunks_meta:
+                        source_db = chunk.get("source_index_db")
+                        if source_db:
+                            if source_db not in chunks_by_source:
+                                chunks_by_source[source_db] = []
+                            chunks_by_source[source_db].append(chunk)
+
+                    # Retrieve dense embeddings from each source_index_db
+                    for source_db, source_chunks in chunks_by_source.items():
+                        try:
+                            source_chunk_ids = [c["chunk_id"] for c in source_chunks]
+                            conn = sqlite3.connect(source_db)
+                            conn.row_factory = sqlite3.Row
+
+                            placeholders = ",".join("?" * len(source_chunk_ids))
+                            # Try semantic_chunks first (newer schema), fall back to chunks
+                            try:
+                                rows = conn.execute(
+                                    f"SELECT id, embedding_dense FROM semantic_chunks WHERE id IN ({placeholders})",
+                                    source_chunk_ids
+                                ).fetchall()
+                            except sqlite3.OperationalError:
+                                rows = conn.execute(
+                                    f"SELECT id, embedding_dense FROM chunks WHERE id IN ({placeholders})",
+                                    source_chunk_ids
+                                ).fetchall()
+                            conn.close()
+
+                            # Build dense vector lookup
+                            dense_lookup = {row["id"]: row["embedding_dense"] for row in rows}
+
+                            # Process chunks with their embeddings
+                            for chunk in source_chunks:
+                                chunk_id = chunk["chunk_id"]
+                                dense_bytes = dense_lookup.get(chunk_id)
+                                if dense_bytes is not None:
+                                    valid_rows.append({
+                                        "id": chunk_id,
+                                        "file_path": chunk["file_path"],
+                                        "content": chunk["content"],
+                                    })
+                                    dense_vectors.append(np.frombuffer(dense_bytes, dtype=np.float32))
+                        except Exception as exc:
+                            self.logger.debug(
+                                "Failed to get dense embeddings from %s: %s", source_db, exc
+                            )
+                else:
+                    # Per-directory mode: index_path is the _index.db file
+                    conn = sqlite3.connect(str(index_path))
+                    conn.row_factory = sqlite3.Row
+
+                    placeholders = ",".join("?" * len(chunk_ids))
+                    rows = conn.execute(
+                        f"SELECT id, file_path, content, embedding_dense FROM semantic_chunks WHERE id IN ({placeholders})",
+                        chunk_ids
+                    ).fetchall()
+                    conn.close()
+
+                    for row in rows:
+                        dense_bytes = row["embedding_dense"]
+                        if dense_bytes is not None:
+                            valid_rows.append(dict(row))
+                            dense_vectors.append(np.frombuffer(dense_bytes, dtype=np.float32))
+
+                # Skip if no dense embeddings found
+                if not dense_vectors:
+                    continue
+
+                # Stack into matrix for batch computation
+                doc_matrix = np.vstack(dense_vectors)
+
+                # Batch compute cosine similarities
+                scores = self._compute_cosine_similarity_batch(query_dense, doc_matrix)
+
+                # Create search results
+                for i, row in enumerate(valid_rows):
+                    score = float(scores[i])
+                    excerpt = (row.get("content") or "")[:500]
+                    result = SearchResult(
+                        path=row.get("file_path") or "",
+                        score=score,
+                        excerpt=excerpt,
+                    )
+                    scored_results.append((score, result))
+
+            except Exception as exc:
+                self.logger.debug(
+                    "Dense reranking failed for %s: %s", index_path, exc
+                )
+                stats.errors.append(f"Dense reranking failed for {index_path}: {exc}")
+
+        # Sort by score descending and deduplicate by path
+        scored_results.sort(key=lambda x: x[0], reverse=True)
+
+        path_to_result: Dict[str, SearchResult] = {}
+        for score, result in scored_results:
+            if result.path not in path_to_result:
+                path_to_result[result.path] = result
+
+        final_results = list(path_to_result.values())[:k]
+
+        # Optional: grouping of similar results
+        if options.group_results:
+            from codexlens.search.ranking import group_similar_results
+            final_results = group_similar_results(
+                final_results, score_threshold_abs=options.grouping_threshold
+            )
+
+        stats.files_matched = len(final_results)
+        stats.time_ms = (time.time() - start_time) * 1000
+
+        self.logger.debug(
+            "Binary cascade search complete: %d results in %.2fms",
+            len(final_results),
+            stats.time_ms,
+        )
+
+        return ChainSearchResult(
+            query=query,
+            results=final_results,
+            symbols=[],
+            stats=stats,
+        )
+
+    def cascade_search(
+        self,
+        query: str,
+        source_path: Path,
+        k: int = 10,
+        coarse_k: int = 100,
+        options: Optional[SearchOptions] = None,
+        strategy: Optional[Literal["binary", "hybrid", "binary_rerank", "dense_rerank"]] = None,
+    ) -> ChainSearchResult:
+        """Unified cascade search entry point with strategy selection.
+
+        Provides a single interface for cascade search with configurable strategy:
+        - "binary": Uses binary vector coarse ranking + dense fine ranking (fastest)
+        - "hybrid": Uses FTS+SPLADE+Vector coarse ranking + cross-encoder reranking (original)
+        - "binary_rerank": Uses binary vector coarse ranking + cross-encoder reranking (best balance)
+        - "dense_rerank": Uses dense vector coarse ranking + cross-encoder reranking
+
+        The strategy is determined with the following priority:
+        1. The `strategy` parameter (e.g., from CLI --cascade-strategy option)
+        2. Config `cascade_strategy` setting from settings.json
+        3. Default: "binary"
+
+        Args:
+            query: Natural language or keyword query string
+            source_path: Starting directory path
+            k: Number of final results to return (default 10)
+            coarse_k: Number of coarse candidates from first stage (default 100)
+            options: Search configuration (uses defaults if None)
+            strategy: Cascade strategy - "binary", "hybrid", or "binary_rerank".
+
+        Returns:
+            ChainSearchResult with reranked results and statistics
+
+        Examples:
+            >>> engine = ChainSearchEngine(registry, mapper, config=config)
+            >>> # Use binary cascade (default, fastest)
+            >>> result = engine.cascade_search("auth", Path("D:/project"))
+            >>> # Use hybrid cascade (original behavior)
+            >>> result = engine.cascade_search("auth", Path("D:/project"), strategy="hybrid")
+            >>> # Use binary + cross-encoder (best balance of speed and quality)
+            >>> result = engine.cascade_search("auth", Path("D:/project"), strategy="binary_rerank")
+        """
+        # Strategy priority: parameter > config > default
+        effective_strategy = strategy
+        valid_strategies = ("binary", "hybrid", "binary_rerank", "dense_rerank")
+        if effective_strategy is None:
+            # Not passed via parameter, check config
+            if self._config is not None:
+                config_strategy = getattr(self._config, "cascade_strategy", None)
+                if config_strategy in valid_strategies:
+                    effective_strategy = config_strategy
+
+        # If still not set, apply default
+        if effective_strategy not in valid_strategies:
+            effective_strategy = "binary"
+
+        if effective_strategy == "binary":
+            return self.binary_cascade_search(query, source_path, k, coarse_k, options)
+        elif effective_strategy == "binary_rerank":
+            return self.binary_rerank_cascade_search(query, source_path, k, coarse_k, options)
+        elif effective_strategy == "dense_rerank":
+            return self.dense_rerank_cascade_search(query, source_path, k, coarse_k, options)
+        else:
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+    def binary_rerank_cascade_search(
+        self,
+        query: str,
+        source_path: Path,
+        k: int = 10,
+        coarse_k: int = 100,
+        options: Optional[SearchOptions] = None,
+    ) -> ChainSearchResult:
+        """Execute binary cascade search with cross-encoder reranking.
+
+        Combines the speed of binary vector coarse search with the quality of
+        cross-encoder reranking for the best balance of speed and accuracy.
+
+        Binary + Reranker cascade process:
+        1. Stage 1 (Coarse): Fast binary vector search using Hamming distance
+           to quickly filter to coarse_k candidates (256-dim binary, 32 bytes/vector)
+        2. Stage 2 (Fine): Cross-encoder reranking for precise semantic ranking
+           of candidates using query-document attention
+
+        This approach is typically faster than hybrid_cascade_search while
+        achieving similar or better quality through cross-encoder reranking.
+
+        Performance characteristics:
+        - Binary search: O(N) with SIMD-accelerated XOR + popcount (~8ms)
+        - Cross-encoder: Applied to top coarse_k candidates (~15-20s for API)
+        - Total: Faster coarse + high-quality fine = best balance
+
+        Args:
+            query: Natural language or keyword query string
+            source_path: Starting directory path
+            k: Number of final results to return (default 10)
+            coarse_k: Number of coarse candidates from first stage (default 100)
+            options: Search configuration (uses defaults if None)
+
+        Returns:
+            ChainSearchResult with cross-encoder reranked results and statistics
+
+        Examples:
+            >>> engine = ChainSearchEngine(registry, mapper, config=config)
+            >>> result = engine.binary_rerank_cascade_search(
+            ...     "how to authenticate users",
+            ...     Path("D:/project/src"),
+            ...     k=10,
+            ...     coarse_k=100
+            ... )
+            >>> for r in result.results:
+            ...     print(f"{r.path}: {r.score:.3f}")
+        """
+        if not NUMPY_AVAILABLE:
+            self.logger.warning(
+                "NumPy not available, falling back to hybrid cascade search"
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        options = options or SearchOptions()
+        start_time = time.time()
+        stats = SearchStats()
+
+        # Use config defaults if available
+        if self._config is not None:
+            if hasattr(self._config, "cascade_coarse_k"):
+                coarse_k = coarse_k or self._config.cascade_coarse_k
+            if hasattr(self._config, "cascade_fine_k"):
+                k = k or self._config.cascade_fine_k
+
+        # Step 1: Find starting index
+        start_index = self._find_start_index(source_path)
+        if not start_index:
+            self.logger.warning(f"No index found for {source_path}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Step 2: Collect all index paths
+        index_paths = self._collect_index_paths(start_index, options.depth)
+        stats.dirs_searched = len(index_paths)
+
+        if not index_paths:
+            self.logger.warning(f"No indexes collected from {start_index}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Initialize binary embedding backend
+        try:
+            from codexlens.indexing.embedding import BinaryEmbeddingBackend
+        except ImportError as exc:
+            self.logger.warning(
+                "BinaryEmbeddingBackend not available: %s, falling back to hybrid cascade",
+                exc
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Step 4: Binary coarse search (same as binary_cascade_search)
+        binary_coarse_time = time.time()
+        coarse_candidates: List[Tuple[int, int, Path]] = []
+
+        # Try centralized BinarySearcher first (preferred for mmap indexes)
+        # The index root is the parent of the first index path
+        index_root = index_paths[0].parent if index_paths else None
+        used_centralized = False
+
+        if index_root:
+            binary_searcher = self._get_centralized_binary_searcher(index_root)
+            if binary_searcher is not None:
+                try:
+                    # BinarySearcher expects dense vector, not packed binary
+                    from codexlens.semantic.embedder import Embedder
+                    embedder = Embedder()
+                    query_dense = embedder.embed_to_numpy([query])[0]
+
+                    results = binary_searcher.search(query_dense, top_k=coarse_k)
+                    for chunk_id, distance in results:
+                        coarse_candidates.append((chunk_id, distance, index_root))
+                    # Only mark as used if we got actual results
+                    if coarse_candidates:
+                        used_centralized = True
+                        self.logger.debug(
+                            "Binary coarse search (centralized): %d candidates in %.2fms",
+                            len(results), (time.time() - binary_coarse_time) * 1000
+                        )
+                except Exception as exc:
+                    self.logger.debug(f"Centralized binary search failed: {exc}")
+
+        if not used_centralized:
+            # Get GPU preference from config
+            use_gpu = True
+            if self._config is not None:
+                use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+            try:
+                binary_backend = BinaryEmbeddingBackend(use_gpu=use_gpu)
+                query_binary = binary_backend.embed_packed([query])[0]
+            except Exception as exc:
+                self.logger.warning(f"Failed to generate binary query embedding: {exc}")
+                return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+            # Fallback to per-directory binary indexes
+            for index_path in index_paths:
+                try:
+                    binary_index = self._get_or_create_binary_index(index_path)
+                    if binary_index is None or binary_index.count() == 0:
+                        continue
+                    # BinaryANNIndex returns (ids, distances) arrays
+                    ids, distances = binary_index.search(query_binary, coarse_k)
+                    for chunk_id, dist in zip(ids, distances):
+                        coarse_candidates.append((chunk_id, dist, index_path))
+                except Exception as exc:
+                    self.logger.debug(
+                        "Binary search failed for %s: %s", index_path, exc
+                    )
+
+        if not coarse_candidates:
+            self.logger.info("No binary candidates found, falling back to hybrid cascade for reranking")
+            # Fall back to hybrid_cascade_search which uses FTS+Vector coarse + cross-encoder rerank
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Sort by Hamming distance and take top coarse_k
+        coarse_candidates.sort(key=lambda x: x[1])
+        coarse_candidates = coarse_candidates[:coarse_k]
+
+        self.logger.debug(
+            "Binary coarse search: %d candidates in %.2fms",
+            len(coarse_candidates), (time.time() - binary_coarse_time) * 1000
+        )
+
+        # Step 5: Build SearchResult objects for cross-encoder reranking
+        # Group candidates by index path for efficient retrieval
+        candidates_by_index: Dict[Path, List[int]] = {}
+        for chunk_id, distance, index_path in coarse_candidates:
+            if index_path not in candidates_by_index:
+                candidates_by_index[index_path] = []
+            candidates_by_index[index_path].append(chunk_id)
+
+        # Retrieve chunk content for reranking
+        # Always use centralized VectorMetadataStore since chunks are stored there
+        import sqlite3
+        coarse_results: List[SearchResult] = []
+
+        # Find the centralized metadata store path (project root)
+        # index_root was computed earlier, use it for chunk retrieval
+        central_meta_path = index_root / VECTORS_META_DB_NAME if index_root else None
+        central_meta_store = None
+        if central_meta_path and central_meta_path.exists():
+            central_meta_store = VectorMetadataStore(central_meta_path)
+
+        for index_path, chunk_ids in candidates_by_index.items():
+            try:
+                chunks_data = []
+                if central_meta_store:
+                    # Try centralized VectorMetadataStore first (preferred)
+                    chunks_data = central_meta_store.get_chunks_by_ids(chunk_ids)
+
+                if not chunks_data and used_centralized:
+                    # Fallback to per-index-path meta store
+                    meta_db_path = index_path / VECTORS_META_DB_NAME
+                    if meta_db_path.exists():
+                        meta_store = VectorMetadataStore(meta_db_path)
+                        chunks_data = meta_store.get_chunks_by_ids(chunk_ids)
+
+                if not chunks_data:
+                    # Final fallback: query semantic_chunks table directly
+                    # This handles per-directory indexes with semantic_chunks table
+                    try:
+                        conn = sqlite3.connect(str(index_path))
+                        conn.row_factory = sqlite3.Row
+                        placeholders = ",".join("?" * len(chunk_ids))
+                        cursor = conn.execute(
+                            f"""
+                            SELECT id, file_path, content, metadata, category
+                            FROM semantic_chunks
+                            WHERE id IN ({placeholders})
+                            """,
+                            chunk_ids
+                        )
+                        chunks_data = [
+                            {
+                                "id": row["id"],
+                                "file_path": row["file_path"],
+                                "content": row["content"],
+                                "metadata": row["metadata"],
+                                "category": row["category"],
+                            }
+                            for row in cursor.fetchall()
+                        ]
+                        conn.close()
+                    except Exception:
+                        pass  # Skip if table doesn't exist
+
+                for chunk in chunks_data:
+                    # Find the Hamming distance for this chunk
+                    chunk_id = chunk.get("id") or chunk.get("chunk_id")
+                    distance = next(
+                        (d for cid, d, _ in coarse_candidates if cid == chunk_id),
+                        256
+                    )
+                    # Initial score from Hamming distance (will be replaced by reranker)
+                    score = 1.0 - (distance / 256.0)
+
+                    content = chunk.get("content", "")
+                    result = SearchResult(
+                        path=chunk.get("file_path", ""),
+                        score=float(score),
+                        excerpt=content[:500] if content else "",
+                        content=content,
+                    )
+                    coarse_results.append(result)
+            except Exception as exc:
+                self.logger.debug(
+                    "Failed to retrieve chunks from %s: %s", index_path, exc
+                )
+
+        if not coarse_results:
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query, results=[], symbols=[], stats=stats
+            )
+
+        self.logger.debug(
+            "Retrieved %d chunks for cross-encoder reranking", len(coarse_results)
+        )
+
+        # Step 6: Cross-encoder reranking (same as hybrid_cascade_search)
+        rerank_time = time.time()
+        reranked_results = self._cross_encoder_rerank(query, coarse_results, top_k=k)
+
+        self.logger.debug(
+            "Cross-encoder reranking: %d results in %.2fms",
+            len(reranked_results), (time.time() - rerank_time) * 1000
+        )
+
+        # Deduplicate by path (keep highest score)
+        path_to_result: Dict[str, SearchResult] = {}
+        for result in reranked_results:
+            if result.path not in path_to_result or result.score > path_to_result[result.path].score:
+                path_to_result[result.path] = result
+
+        final_results = list(path_to_result.values())[:k]
+
+        stats.files_matched = len(final_results)
+        stats.time_ms = (time.time() - start_time) * 1000
+
+        self.logger.debug(
+            "Binary+Rerank cascade search complete: %d results in %.2fms",
+            len(final_results),
+            stats.time_ms,
+        )
+
+        return ChainSearchResult(
+            query=query,
+            results=final_results,
+            symbols=[],
+            stats=stats,
+        )
+
+    def dense_rerank_cascade_search(
+        self,
+        query: str,
+        source_path: Path,
+        k: int = 10,
+        coarse_k: int = 100,
+        options: Optional[SearchOptions] = None,
+    ) -> ChainSearchResult:
+        """Execute dense cascade search with cross-encoder reranking.
+
+        Combines dense vector coarse search (HNSW) with cross-encoder reranking
+        for comparison with binary_rerank strategy.
+
+        Dense + Reranker cascade process:
+        1. Stage 1 (Coarse): Dense vector search using HNSW (cosine similarity)
+           to get coarse_k candidates (2048-dim float32)
+        2. Stage 2 (Fine): Cross-encoder reranking for precise semantic ranking
+
+        Args:
+            query: Natural language or keyword query string
+            source_path: Starting directory path
+            k: Number of final results to return (default 10)
+            coarse_k: Number of coarse candidates from first stage (default 100)
+            options: Search configuration (uses defaults if None)
+
+        Returns:
+            ChainSearchResult with cross-encoder reranked results and statistics
+        """
+        if not NUMPY_AVAILABLE:
+            self.logger.warning(
+                "NumPy not available, falling back to hybrid cascade search"
+            )
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        options = options or SearchOptions()
+        start_time = time.time()
+        stats = SearchStats()
+
+        # Use config defaults if available
+        if self._config is not None:
+            if hasattr(self._config, "cascade_coarse_k"):
+                coarse_k = coarse_k or self._config.cascade_coarse_k
+            if hasattr(self._config, "cascade_fine_k"):
+                k = k or self._config.cascade_fine_k
+
+        # Step 1: Find starting index
+        start_index = self._find_start_index(source_path)
+        if not start_index:
+            self.logger.warning(f"No index found for {source_path}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Step 2: Collect all index paths
+        index_paths = self._collect_index_paths(start_index, options.depth)
+        stats.dirs_searched = len(index_paths)
+
+        if not index_paths:
+            self.logger.warning(f"No indexes collected from {start_index}")
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query,
+                results=[],
+                symbols=[],
+                stats=stats
+            )
+
+        # Step 3: Find centralized HNSW index and read model config
+        from codexlens.config import VECTORS_HNSW_NAME
+        central_hnsw_path = None
+        index_root = start_index.parent
+        current_dir = index_root
+        for _ in range(10):  # Limit search depth
+            candidate = current_dir / VECTORS_HNSW_NAME
+            if candidate.exists():
+                central_hnsw_path = candidate
+                index_root = current_dir  # Update to where HNSW was found
+                break
+            parent = current_dir.parent
+            if parent == current_dir:  # Reached root
+                break
+            current_dir = parent
+
+        # Step 4: Generate query dense embedding using same model as centralized index
+        # Read embedding config to match the model used during indexing
+        dense_coarse_time = time.time()
+        try:
+            from codexlens.semantic.factory import get_embedder
+
+            # Get embedding settings from centralized index config (preferred) or fallback to self._config
+            embedding_backend = "litellm"  # Default to API for dense
+            embedding_model = "qwen3-embedding-sf"  # Default model
+            use_gpu = True
+
+            # Try to read model config from centralized index's embeddings_config table
+            central_index_db = index_root / "_index.db"
+            if central_index_db.exists():
+                try:
+                    from codexlens.semantic.vector_store import VectorStore
+                    with VectorStore(central_index_db) as vs:
+                        model_config = vs.get_model_config()
+                        if model_config:
+                            embedding_backend = model_config.get("backend", embedding_backend)
+                            embedding_model = model_config.get("model_name", embedding_model)
+                            self.logger.debug(
+                                "Read model config from centralized index: %s/%s",
+                                embedding_backend, embedding_model
+                            )
+                except Exception as e:
+                    self.logger.debug("Failed to read centralized model config: %s", e)
+
+            # Fallback to self._config if not read from index
+            if self._config is not None:
+                if embedding_backend == "litellm" and embedding_model == "qwen3-embedding-sf":
+                    # Only use config values if we didn't read from centralized index
+                    config_backend = getattr(self._config, "embedding_backend", None)
+                    config_model = getattr(self._config, "embedding_model", None)
+                    if config_backend:
+                        embedding_backend = config_backend
+                    if config_model:
+                        embedding_model = config_model
+                use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+            # Create embedder matching index configuration
+            if embedding_backend == "litellm":
+                embedder = get_embedder(backend="litellm", model=embedding_model)
+            else:
+                embedder = get_embedder(backend="fastembed", profile=embedding_model, use_gpu=use_gpu)
+
+            query_dense = embedder.embed_to_numpy([query])[0]
+            self.logger.debug(f"Dense query embedding: {query_dense.shape[0]}-dim via {embedding_backend}/{embedding_model}")
+        except Exception as exc:
+            self.logger.warning(f"Failed to generate dense query embedding: {exc}")
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Step 5: Dense coarse search using centralized HNSW index
+        coarse_candidates: List[Tuple[int, float, Path]] = []  # (chunk_id, distance, index_path)
+
+        if central_hnsw_path is not None:
+            # Use centralized index
+            try:
+                from codexlens.semantic.ann_index import ANNIndex
+                ann_index = ANNIndex.create_central(
+                    index_root=index_root,
+                    dim=query_dense.shape[0],
+                )
+                if ann_index.load() and ann_index.count() > 0:
+                    # Search centralized HNSW index
+                    ids, distances = ann_index.search(query_dense, top_k=coarse_k)
+                    for chunk_id, dist in zip(ids, distances):
+                        coarse_candidates.append((chunk_id, dist, index_root / "_index.db"))
+                    self.logger.debug(
+                        "Centralized dense search: %d candidates from %s",
+                        len(ids), central_hnsw_path
+                    )
+            except Exception as exc:
+                self.logger.debug(
+                    "Centralized dense search failed for %s: %s", central_hnsw_path, exc
+                )
+
+        # Fallback: try per-directory HNSW indexes if centralized not found
+        if not coarse_candidates:
+            for index_path in index_paths:
+                try:
+                    # Load HNSW index
+                    from codexlens.semantic.ann_index import ANNIndex
+                    ann_index = ANNIndex(index_path, dim=query_dense.shape[0])
+                    if not ann_index.load():
+                        continue
+
+                    if ann_index.count() == 0:
+                        continue
+
+                    # Search HNSW index
+                    ids, distances = ann_index.search(query_dense, top_k=coarse_k)
+                    for chunk_id, dist in zip(ids, distances):
+                        coarse_candidates.append((chunk_id, dist, index_path))
+
+                except Exception as exc:
+                    self.logger.debug(
+                        "Dense search failed for %s: %s", index_path, exc
+                    )
+
+        if not coarse_candidates:
+            self.logger.info("No dense candidates found, falling back to hybrid cascade")
+            return self.hybrid_cascade_search(query, source_path, k, coarse_k, options)
+
+        # Sort by distance (ascending for cosine distance) and take top coarse_k
+        coarse_candidates.sort(key=lambda x: x[1])
+        coarse_candidates = coarse_candidates[:coarse_k]
+
+        self.logger.debug(
+            "Dense coarse search: %d candidates in %.2fms",
+            len(coarse_candidates), (time.time() - dense_coarse_time) * 1000
+        )
+
+        # Step 6: Build SearchResult objects for cross-encoder reranking
+        candidates_by_index: Dict[Path, List[int]] = {}
+        for chunk_id, distance, index_path in coarse_candidates:
+            if index_path not in candidates_by_index:
+                candidates_by_index[index_path] = []
+            candidates_by_index[index_path].append(chunk_id)
+
+        # Retrieve chunk content for reranking
+        import sqlite3
+        coarse_results: List[SearchResult] = []
+
+        for index_path, chunk_ids in candidates_by_index.items():
+            try:
+                # For centralized index, use _vectors_meta.db for chunk metadata
+                # which contains file_path, content, start_line, end_line
+                if central_hnsw_path is not None and index_path == index_root / "_index.db":
+                    # Use centralized metadata from _vectors_meta.db
+                    meta_db_path = index_root / "_vectors_meta.db"
+                    if meta_db_path.exists():
+                        conn = sqlite3.connect(str(meta_db_path))
+                        conn.row_factory = sqlite3.Row
+                        placeholders = ",".join("?" * len(chunk_ids))
+                        cursor = conn.execute(
+                            f"""
+                            SELECT chunk_id, file_path, content, start_line, end_line
+                            FROM chunk_metadata
+                            WHERE chunk_id IN ({placeholders})
+                            """,
+                            chunk_ids
+                        )
+                        chunks_data = [
+                            {
+                                "id": row["chunk_id"],
+                                "file_path": row["file_path"],
+                                "content": row["content"],
+                                "metadata": json.dumps({
+                                    "start_line": row["start_line"],
+                                    "end_line": row["end_line"]
+                                }),
+                                "category": "code" if row["file_path"].endswith(('.py', '.ts', '.js', '.java', '.go', '.rs', '.cpp', '.c')) else "doc",
+                            }
+                            for row in cursor.fetchall()
+                        ]
+                        conn.close()
+                    else:
+                        chunks_data = []
+                else:
+                    # Fall back to per-directory semantic_chunks table
+                    conn = sqlite3.connect(str(index_path))
+                    conn.row_factory = sqlite3.Row
+                    placeholders = ",".join("?" * len(chunk_ids))
+                    cursor = conn.execute(
+                        f"""
+                        SELECT id, file_path, content, metadata, category
+                        FROM semantic_chunks
+                        WHERE id IN ({placeholders})
+                        """,
+                        chunk_ids
+                    )
+                    chunks_data = [
+                        {
+                            "id": row["id"],
+                            "file_path": row["file_path"],
+                            "content": row["content"],
+                            "metadata": row["metadata"],
+                            "category": row["category"],
+                        }
+                        for row in cursor.fetchall()
+                    ]
+                    conn.close()
+
+                for chunk in chunks_data:
+                    chunk_id = chunk.get("id")
+                    distance = next(
+                        (d for cid, d, _ in coarse_candidates if cid == chunk_id),
+                        1.0
+                    )
+                    # Convert cosine distance to score (clamp to [0, 1] for Pydantic validation)
+                    # Cosine distance can be > 1 for anti-correlated vectors, causing negative scores
+                    score = max(0.0, 1.0 - distance)
+
+                    content = chunk.get("content", "")
+                    result = SearchResult(
+                        path=chunk.get("file_path", ""),
+                        score=float(score),
+                        excerpt=content[:500] if content else "",
+                        content=content,
+                    )
+                    coarse_results.append(result)
+            except Exception as exc:
+                self.logger.debug(
+                    "Failed to retrieve chunks from %s: %s", index_path, exc
+                )
+
+        if not coarse_results:
+            stats.time_ms = (time.time() - start_time) * 1000
+            return ChainSearchResult(
+                query=query, results=[], symbols=[], stats=stats
+            )
+
+        self.logger.debug(
+            "Retrieved %d chunks for cross-encoder reranking", len(coarse_results)
+        )
+
+        # Step 6: Cross-encoder reranking
+        rerank_time = time.time()
+        reranked_results = self._cross_encoder_rerank(query, coarse_results, top_k=k)
+
+        self.logger.debug(
+            "Cross-encoder reranking: %d results in %.2fms",
+            len(reranked_results), (time.time() - rerank_time) * 1000
+        )
+
+        # Deduplicate by path (keep highest score)
+        path_to_result: Dict[str, SearchResult] = {}
+        for result in reranked_results:
+            if result.path not in path_to_result or result.score > path_to_result[result.path].score:
+                path_to_result[result.path] = result
+
+        final_results = list(path_to_result.values())[:k]
+
+        stats.files_matched = len(final_results)
+        stats.time_ms = (time.time() - start_time) * 1000
+
+        self.logger.debug(
+            "Dense+Rerank cascade search complete: %d results in %.2fms",
+            len(final_results),
+            stats.time_ms,
+        )
+
+        return ChainSearchResult(
+            query=query,
+            results=final_results,
+            symbols=[],
+            stats=stats,
+        )
+
+    def _get_or_create_binary_index(self, index_path: Path) -> Optional[Any]:
+        """Get or create a BinaryANNIndex for the given index path.
+
+        .. deprecated::
+            This method uses the deprecated BinaryANNIndex. For centralized indexes,
+            use _get_centralized_binary_searcher() instead.
+
+        Attempts to load an existing binary index from disk. If not found,
+        returns None (binary index should be built during indexing).
+
+        Args:
+            index_path: Path to the _index.db file
+
+        Returns:
+            BinaryANNIndex instance or None if not available
+        """
+        try:
+            import warnings
+            # Suppress deprecation warning since we're using it intentionally for legacy support
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=DeprecationWarning)
+                from codexlens.semantic.ann_index import BinaryANNIndex
+
+                binary_index = BinaryANNIndex(index_path, dim=256)
+                if binary_index.load():
+                    return binary_index
+            return None
+        except Exception as exc:
+            self.logger.debug("Failed to load binary index for %s: %s", index_path, exc)
+            return None
+
+    def _get_centralized_binary_searcher(self, index_root: Path) -> Optional[Any]:
+        """Get centralized BinarySearcher for memory-mapped binary vectors.
+
+        This is the preferred method for centralized indexes, providing faster
+        search via memory-mapped files.
+
+        Args:
+            index_root: Root directory containing centralized index files
+
+        Returns:
+            BinarySearcher instance or None if not available
+        """
+        try:
+            from codexlens.search.binary_searcher import BinarySearcher
+
+            binary_searcher = BinarySearcher(index_root)
+            if binary_searcher.load():
+                self.logger.debug(
+                    "Using centralized BinarySearcher with %d vectors (mmap=%s)",
+                    binary_searcher.vector_count,
+                    binary_searcher.is_memmap
+                )
+                return binary_searcher
+            return None
+        except Exception as exc:
+            self.logger.debug("Failed to load centralized binary searcher: %s", exc)
+            return None
+
+    def _compute_cosine_similarity(
+        self,
+        query_vec: "np.ndarray",
+        doc_vec: "np.ndarray",
+    ) -> float:
+        """Compute cosine similarity between query and document vectors.
+
+        Args:
+            query_vec: Query embedding vector
+            doc_vec: Document embedding vector
+
+        Returns:
+            Cosine similarity score in range [-1, 1]
+        """
+        if not NUMPY_AVAILABLE:
+            return 0.0
+
+        # Ensure same shape
+        min_len = min(len(query_vec), len(doc_vec))
+        q = query_vec[:min_len]
+        d = doc_vec[:min_len]
+
+        # Compute cosine similarity
+        dot_product = np.dot(q, d)
+        norm_q = np.linalg.norm(q)
+        norm_d = np.linalg.norm(d)
+
+        if norm_q == 0 or norm_d == 0:
+            return 0.0
+
+        return float(dot_product / (norm_q * norm_d))
+
+    def _compute_cosine_similarity_batch(
+        self,
+        query_vec: "np.ndarray",
+        doc_matrix: "np.ndarray",
+    ) -> "np.ndarray":
+        """Compute cosine similarity between query and multiple document vectors.
+
+        Uses vectorized matrix operations for efficient batch computation.
+
+        Args:
+            query_vec: Query embedding vector of shape (dim,)
+            doc_matrix: Document embeddings matrix of shape (n_docs, dim)
+
+        Returns:
+            Array of cosine similarity scores of shape (n_docs,)
+        """
+        if not NUMPY_AVAILABLE:
+            return np.zeros(doc_matrix.shape[0])
+
+        # Ensure query is 1D
+        if query_vec.ndim > 1:
+            query_vec = query_vec.flatten()
+
+        # Handle dimension mismatch by truncating to smaller dimension
+        min_dim = min(len(query_vec), doc_matrix.shape[1])
+        q = query_vec[:min_dim]
+        docs = doc_matrix[:, :min_dim]
+
+        # Compute query norm once
+        norm_q = np.linalg.norm(q)
+        if norm_q == 0:
+            return np.zeros(docs.shape[0])
+
+        # Normalize query
+        q_normalized = q / norm_q
+
+        # Compute document norms (vectorized)
+        doc_norms = np.linalg.norm(docs, axis=1)
+
+        # Avoid division by zero
+        nonzero_mask = doc_norms > 0
+        scores = np.zeros(docs.shape[0], dtype=np.float32)
+
+        if np.any(nonzero_mask):
+            # Normalize documents with non-zero norms
+            docs_normalized = docs[nonzero_mask] / doc_norms[nonzero_mask, np.newaxis]
+
+            # Batch dot product: (n_docs, dim) @ (dim,) = (n_docs,)
+            scores[nonzero_mask] = docs_normalized @ q_normalized
+
+        return scores
+
+    def _build_results_from_candidates(
+        self,
+        candidates: List[Tuple[int, int, Path]],
+        index_paths: List[Path],
+        stats: SearchStats,
+        query: str,
+        start_time: float,
+        use_centralized: bool = False,
+    ) -> ChainSearchResult:
+        """Build ChainSearchResult from binary candidates using Hamming distance scores.
+
+        Used as fallback when dense embeddings are not available.
+
+        Args:
+            candidates: List of (chunk_id, hamming_distance, index_path) tuples
+            index_paths: List of all searched index paths
+            stats: SearchStats to update
+            query: Original query string
+            start_time: Search start time for timing
+            use_centralized: If True, index_path is the index_root directory
+                and VectorMetadataStore should be used instead of SQLiteStore
+
+        Returns:
+            ChainSearchResult with results scored by Hamming distance
+        """
+        results: List[SearchResult] = []
+
+        # Group by index path
+        candidates_by_index: Dict[Path, List[Tuple[int, int]]] = {}
+        for chunk_id, distance, index_path in candidates:
+            if index_path not in candidates_by_index:
+                candidates_by_index[index_path] = []
+            candidates_by_index[index_path].append((chunk_id, distance))
+
+        for index_path, chunk_tuples in candidates_by_index.items():
+            try:
+                chunk_ids = [c[0] for c in chunk_tuples]
+
+                # Use VectorMetadataStore for centralized search, SQLiteStore for per-directory
+                if use_centralized:
+                    # index_path is actually index_root directory for centralized search
+                    meta_db_path = index_path / VECTORS_META_DB_NAME
+                    if not meta_db_path.exists():
+                        self.logger.debug(
+                            "VectorMetadataStore not found at %s, skipping", meta_db_path
+                        )
+                        continue
+                    meta_store = VectorMetadataStore(meta_db_path)
+                    chunks_data = meta_store.get_chunks_by_ids(chunk_ids)
+                else:
+                    store = SQLiteStore(index_path)
+                    chunks_data = store.get_chunks_by_ids(chunk_ids)
+
+                chunk_content: Dict[int, Dict[str, Any]] = {
+                    c["id"]: c for c in chunks_data
+                }
+
+                for chunk_id, distance in chunk_tuples:
+                    chunk_info = chunk_content.get(chunk_id)
+                    if chunk_info is None:
+                        continue
+
+                    # Convert Hamming distance to score (lower distance = higher score)
+                    # Max Hamming distance for 256-bit is 256
+                    score = 1.0 - (distance / 256.0)
+
+                    excerpt = chunk_info.get("content", "")[:500]
+                    result = SearchResult(
+                        path=chunk_info.get("file_path", ""),
+                        score=float(score),
+                        excerpt=excerpt,
+                    )
+                    results.append(result)
+
+            except Exception as exc:
+                self.logger.debug(
+                    "Failed to build results from %s: %s", index_path, exc
+                )
+
+        # Deduplicate by path
+        path_to_result: Dict[str, SearchResult] = {}
+        for result in results:
+            if result.path not in path_to_result or result.score > path_to_result[result.path].score:
+                path_to_result[result.path] = result
+
+        final_results = sorted(
+            path_to_result.values(),
+            key=lambda r: r.score,
+            reverse=True,
+        )
+
+        stats.files_matched = len(final_results)
+        stats.time_ms = (time.time() - start_time) * 1000
+
+        return ChainSearchResult(
+            query=query,
+            results=final_results,
+            symbols=[],
+            stats=stats,
+        )
+
+    def _cross_encoder_rerank(
+        self,
+        query: str,
+        results: List[SearchResult],
+        top_k: int,
+    ) -> List[SearchResult]:
+        """Rerank results using cross-encoder model.
+
+        Args:
+            query: Search query string
+            results: Candidate results to rerank
+            top_k: Number of top results to return
+
+        Returns:
+            Reranked results sorted by cross-encoder score
+        """
+        if not results:
+            return []
+
+        # Try to get reranker from config or create new one
+        reranker = None
+        try:
+            from codexlens.semantic.reranker import (
+                check_reranker_available,
+                get_reranker,
+            )
+
+            # Determine backend and model from config
+            backend = "onnx"
+            model_name = None
+            use_gpu = True
+
+            if self._config is not None:
+                backend = getattr(self._config, "reranker_backend", "onnx") or "onnx"
+                model_name = getattr(self._config, "reranker_model", None)
+                use_gpu = getattr(self._config, "embedding_use_gpu", True)
+
+            ok, err = check_reranker_available(backend)
+            if not ok:
+                self.logger.debug("Reranker backend unavailable (%s): %s", backend, err)
+                return results[:top_k]
+
+            # Create reranker
+            kwargs = {}
+            if backend == "onnx":
+                kwargs["use_gpu"] = use_gpu
+            elif backend == "api":
+                # Pass max_input_tokens for adaptive batching
+                max_tokens = getattr(self._config, "reranker_max_input_tokens", None)
+                if max_tokens:
+                    kwargs["max_input_tokens"] = max_tokens
+
+            reranker = get_reranker(backend=backend, model_name=model_name, **kwargs)
+
+        except ImportError as exc:
+            self.logger.debug("Reranker not available: %s", exc)
+            return results[:top_k]
+        except Exception as exc:
+            self.logger.debug("Failed to initialize reranker: %s", exc)
+            return results[:top_k]
+
+        # Use cross_encoder_rerank from ranking module
+        from codexlens.search.ranking import cross_encoder_rerank
+
+        return cross_encoder_rerank(
+            query=query,
+            results=results,
+            reranker=reranker,
+            top_k=top_k,
+            batch_size=32,
         )
 
     def search_files_only(self, query: str,
@@ -522,6 +2101,7 @@ class ChainSearchEngine:
                 options.enable_fuzzy,
                 options.enable_vector,
                 options.pure_vector,
+                options.enable_splade,
                 options.hybrid_weights
             ): idx_path
             for idx_path in index_paths
@@ -550,6 +2130,7 @@ class ChainSearchEngine:
                               enable_fuzzy: bool = True,
                               enable_vector: bool = False,
                               pure_vector: bool = False,
+                              enable_splade: bool = False,
                               hybrid_weights: Optional[Dict[str, float]] = None) -> List[SearchResult]:
         """Search a single index database.
 
@@ -565,6 +2146,7 @@ class ChainSearchEngine:
             enable_fuzzy: Enable fuzzy FTS in hybrid mode
             enable_vector: Enable vector semantic search
             pure_vector: If True, only use vector search without FTS fallback
+            enable_splade: If True, force SPLADE sparse neural search
             hybrid_weights: Custom RRF weights for hybrid search
 
         Returns:
@@ -581,6 +2163,7 @@ class ChainSearchEngine:
                     enable_fuzzy=enable_fuzzy,
                     enable_vector=enable_vector,
                     pure_vector=pure_vector,
+                    enable_splade=enable_splade,
                 )
             else:
                 # Single-FTS search (exact or fuzzy mode)
@@ -624,21 +2207,72 @@ class ChainSearchEngine:
             self.logger.debug(f"Search error in {index_path}: {exc}")
             return []
 
+    def _filter_by_extension(self, results: List[SearchResult],
+                              code_only: bool = False,
+                              exclude_extensions: Optional[List[str]] = None) -> List[SearchResult]:
+        """Filter search results by file extension.
+
+        Args:
+            results: Search results to filter
+            code_only: If True, exclude non-code files (md, txt, json, yaml, xml, etc.)
+            exclude_extensions: List of extensions to exclude (e.g., ["md", "txt"])
+
+        Returns:
+            Filtered results
+        """
+        # Non-code file extensions (same as MCP tool smart-search.ts)
+        NON_CODE_EXTENSIONS = {
+            'md', 'txt', 'json', 'yaml', 'yml', 'xml', 'csv', 'log',
+            'ini', 'cfg', 'conf', 'toml', 'env', 'properties',
+            'html', 'htm', 'svg', 'png', 'jpg', 'jpeg', 'gif', 'ico', 'webp',
+            'pdf', 'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx',
+            'lock', 'sum', 'mod',
+        }
+
+        # Build exclusion set
+        excluded_exts = set()
+        if exclude_extensions:
+            # Normalize extensions (remove leading dots, lowercase)
+            excluded_exts = {ext.lower().lstrip('.') for ext in exclude_extensions}
+        if code_only:
+            excluded_exts.update(NON_CODE_EXTENSIONS)
+
+        if not excluded_exts:
+            return results
+
+        # Filter results
+        filtered = []
+        for result in results:
+            path_str = result.path
+            if not path_str:
+                continue
+
+            # Extract extension from path
+            if '.' in path_str:
+                ext = path_str.rsplit('.', 1)[-1].lower()
+                if ext in excluded_exts:
+                    continue  # Skip this result
+
+            filtered.append(result)
+
+        return filtered
+
     def _merge_and_rank(self, results: List[SearchResult],
-                         limit: int) -> List[SearchResult]:
+                         limit: int, offset: int = 0) -> List[SearchResult]:
         """Aggregate, deduplicate, and rank results.
 
         Process:
         1. Deduplicate by path (keep highest score)
         2. Sort by score descending
-        3. Limit to requested count
+        3. Apply offset and limit for pagination
 
         Args:
             results: Raw results from all indexes
             limit: Maximum results to return
+            offset: Number of results to skip (pagination offset)
 
         Returns:
-            Deduplicated and ranked results
+            Deduplicated and ranked results with pagination
         """
         # Deduplicate by path, keeping best score
         path_to_result: Dict[str, SearchResult] = {}
@@ -651,8 +2285,8 @@ class ChainSearchEngine:
         unique_results = list(path_to_result.values())
         unique_results.sort(key=lambda r: r.score, reverse=True)
 
-        # Apply limit
-        return unique_results[:limit]
+        # Apply offset and limit for pagination
+        return unique_results[offset:offset + limit]
 
     def _search_symbols_parallel(self, index_paths: List[Path],
                                   name: str,