# Vector Search

> Búsqueda vectorial vía embeddings_* (HNSW a gran escala) y ruvllm_hnsw_* (enrutador WASM para hasta 11 patrones), con cuantización RaBitQ de 1 bit para reducir la memoria 32×.

Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/vector-search
Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/vector-search.md

Repositorio: https://github.com/ruvnet/ruflo
Autor: ruvnet
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 41 tok instalada, 1.5k tok al activarse, 1.5k tok con todos los archivos del bundle
Bundle: 1 archivo, 6 KB
Permisos que pide: mcp__plugin_ruflo-core_ruflo__embeddings_generate mcp__plugin_ruflo-core_ruflo__embeddings_search mcp__plugin_ruflo-core_ruflo__embeddings_compare mcp__plugin_ruflo-core_ruflo__embeddings_init mcp__plugin_ruflo-core_ruflo__embeddings_status mcp__plugin_ruflo-core_ruflo__embeddings_hyperbolic mcp__plugin_ruflo-core_ruflo__embeddings_neural mcp__plugin_ruflo-core_ruflo__embeddings_rabitq_build mcp__plugin_ruflo-core_ruflo__embeddings_rabitq_search mcp__plugin_ruflo-core_ruflo__embeddings_rabitq_status mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_create mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_add mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_route mcp__plugin_ruflo-core_ruflo__memory_search_unified bash

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ruvnet/ruflo --skill vector-search --agent claude-code
# Cursor
npx -y skills add ruvnet/ruflo --skill vector-search --agent cursor
# Codex
npx -y skills add ruvnet/ruflo --skill vector-search --agent codex
# Gemini CLI
npx -y skills add ruvnet/ruflo --skill vector-search --agent gemini
# Windsurf
npx -y skills add ruvnet/ruflo --skill vector-search --agent windsurf
# Cline
npx -y skills add ruvnet/ruflo --skill vector-search --agent cline
```

## Qué hace

- Ofrece dos rutas de búsqueda vectorial distintas: embeddings_* (HNSW a gran escala, hasta millones de vectores) y ruvllm_hnsw_* (enrutador WASM para hasta 11 patrones).
- Incluye cuantización RaBitQ de 1 bit para reducir 32× la memoria en corpus de 5.000 vectores o más, con reranking exacto opcional.
- Expone perfiles de ajuste (recall-first, balanced, latency-first) que controlan efSearch y M en el índice HNSW.

## Cuándo usarla

- Necesitas buscar en un corpus de 500 documentos o más, comparar dos textos o enrutar una consulta entre un máximo de 11 patrones prioritarios.
- El corpus es grande y hay restricción de memoria (5.000 vectores o más): usa la ruta cuantizada RaBitQ.

## Qué la activa

- "Busca en el corpus de embeddings patrones de autenticación"
- "Compara la similitud entre estos dos textos"

## Antes de instalar

- Requiere las herramientas MCP embeddings_* y ruvllm_hnsw_* del plugin ruflo-agentdb.
- Necesita en el PATH: npx

## Archivos

- SKILL.md — 6 KB

## SKILL.md

Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés.

# Vector Search

Two distinct vector-search paths live in this plugin. Pick the right one — they're not interchangeable.

| Path | Tool family | Backing | Capacity | Latency |
|------|-------------|---------|----------|---------|
| **Large-scale corpus** | `embeddings_*` | `@claude-flow/memory` HNSW (Rust/Native) | up to millions of vectors | ~1.9× at N=20k, ~3.2×–4.7× at N=5k vs brute-force (measured; recall@10 ≈ 0.99). ANN wins above the crossover |
| **Hot-path router** | `ruvllm_hnsw_*` | WASM-backed router (v2.0.1) | **~11 patterns max** (`ruvllm-tools.ts:58`) | sub-ms; designed for high-priority routing, not corpus search |

The "12,500×" headline applies to the large-scale `embeddings_search` path. The WASM router is **not** that path.

## When to use

| Need | Path |
|---|---|
| Search a corpus of N ≥ 500 documents | `embeddings_search` |
| Memory-constrained corpus (≥5,000 vectors) | RaBitQ quantized — see "Quantized search" below |
| Compare two strings | `embeddings_compare` |
| Hierarchical / taxonomic data | `embeddings_hyperbolic` (Poincare ball) |
| Route a query to one of ≤11 hot patterns | `ruvllm_hnsw_route` |
| Cross-namespace search | `memory_search_unified` |

## Standard search

1. **Check status** — `mcp__plugin_ruflo-core_ruflo__embeddings_status` to verify the embedding engine.
2. **Initialize** — `mcp__plugin_ruflo-core_ruflo__embeddings_init` if not active.
3. **Generate** — `mcp__plugin_ruflo-core_ruflo__embeddings_generate` for text input.
4. **Search** — `mcp__plugin_ruflo-core_ruflo__embeddings_search` with the query.
5. **Compare** — `mcp__plugin_ruflo-core_ruflo__embeddings_compare` to measure similarity.
6. **Unified search** — `mcp__plugin_ruflo-core_ruflo__memory_search_unified` for cross-namespace.

## Quantized search (32× memory reduction)

For corpora ≥5,000 vectors and/or memory-constrained environments, use the RaBitQ 1-bit quantization workflow. Below 5,000 vectors the rebuild cost outweighs the savings — use the standard path instead.

| Step | Tool | Purpose |
|---|---|---|
| 1 | `embeddings_init` | Engine warm |
| 2 | `embeddings_rabitq_build` | One-time build of the 1-bit index after corpus is loaded |
| 3 | `embeddings_rabitq_search` | Hamming-prefilter returns top-N candidate IDs (cheap) |
| 4 | `embeddings_search` | Optional exact rerank on the candidate set (full-precision) |
| 5 | `embeddings_rabitq_status` | Index health, memory footprint, build time |

> **Note**: `embeddings_rabitq_search` returns candidate IDs only — the rerank in step 4 is the user's responsibility (mirrors the docstring at `embeddings-tools.ts:911`). Without rerank, results are approximate; with rerank, you get full-precision quality at 32× lower memory.

## Tuning

HNSW exposes three knobs that trade recall against latency. The "12,500×" headline assumes **defaults**; tune deliberately for your workload:

| Profile | `efSearch` | `M` | When to use |
|---------|-----------|-----|-------------|
| `recall-first` | 200 | 32 | Pattern recall during planning; quality matters more than ms |
| `balanced` (default) | 64 | 16 | General-purpose semantic recall |
| `latency-first` | 16 | 8 | Hot-path routing where p99 latency matters |

`efSearch` is passed via `ruvllm_hnsw_create` (`ruvllm-tools.ts:64`). `M` is registry-level today; raise as a follow-up if it should be MCP-tunable. `efConstruction` defaults to 200 in the lite index (`hnsw-index.ts:537`).

## HNSW pattern router (WASM, ≤11 patterns)

For routing a small number of high-priority patterns:
- `mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_create` — create the WASM index (cap ~11)
- `mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_add` — add a pattern
- `mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_route` — route an incoming query

This is **not** a corpus index. Treat it as a fast classifier over a curated set of patterns.

## Hyperbolic embeddings

For hierarchical data (code trees, org charts), use `mcp__plugin_ruflo-core_ruflo__embeddings_hyperbolic` which maps to Poincare ball space. Distance is geodesic, not cosine.

## CLI alternative

```bash
npx @claude-flow/cli@latest embeddings search --query "authentication patterns"
npx @claude-flow/cli@latest embeddings init
npx @claude-flow/cli@latest memory search --query "your query"
```

## Performance

Measured numbers (source: `scripts/benchmark-intelligence.mjs`, ruvector NAPI backend; recall@10 ≈ 0.99). The older "150×–12,500×" figures were brute-force-fallback artifacts and have been retired — see project CLAUDE.md "V3 Performance Targets".

| Method | Measured speedup vs brute-force |
|--------|---------------------------------|
| Brute-force scan | Baseline |
| HNSW (N=5,000) | ~3.2×–4.7× faster |
| HNSW (N=20,000) | ~1.9× faster |
| HNSW (below crossover, small N) | ties/loses vs brute-force |
| RaBitQ quantization | 32× memory reduction; 0.60 ms/query at N≈14.7k |
| `ruvllm_hnsw_route` (n≤11) | sub-ms per route, fixed cost |

## Dónde encaja

- Categoría: [Bases de datos](https://skillsagentes.com/categorias/bases-de-datos.md) — Diseño de esquemas, migraciones y optimización de consultas.
- Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución.
- [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde.
- [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento.
- [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP.
- [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)