zvec-grep (zg): motor de búsqueda híbrido local para humanos y agentes AI
zvec-grep combina ripgrep, BM25 y búsqueda vectorial local para ofrecer consultas semánticas y exactas sin salir del terminal.
zvec-grep (zg) llega como una capa de búsqueda local que integra la rapidez de ripgrep, la relevancia de BM25 y la inteligencia de embeddings de Alibaba – todo desde la línea de comandos.
¿Qué aporta?
- Búsqueda híbrida. La herramienta elimina el dilema entre búsqueda exacta y semántica. Los usuarios pueden buscar expresiones regulares y, al mismo tiempo, descubrir funciones y patrones arquitectónicos mediante embeddings, incluso cuando los nombres no coinciden.
- Optimización para agentes AI. Cuando Claude Code, Codex o OpenCode recorren un repositorio, zg devuelve fragmentos ordenados y vinculados a la fuente, reduciendo el número de llamadas y el consumo de tokens.
- Privacidad al 100 %. Todos los índices, embeddings y código se conservan en la carpeta “.zvec-grep” del equipo; no se envían datos a APIs externas.
- CLI y MCP. Los desarrolladores pueden usarlo directamente en el shell, y los agentes pueden instalarlo como herramienta mediante
zg install --target opencode --yes.
Instalación y uso básico
# Instalación global (Node.js 22+)
npm install -g @zvec/zvec-grep
# Índice con embeddings locales
zg index --embedding local /ruta/al/proyecto
# Búsqueda humana
zg query --human "¿Cómo se valida el token de autenticación?" --limit 3
# Como herramienta para un agente
zg install --target opencode --yes
La sintaxis combina --human para consultas conceptuales y --limit para controlar la cantidad de resultados.
Impacto
Para los equipos que manejan bases de código extensas, zg ofrece una alternativa más intuitiva que los grep tradicionales. Al evitar la necesidad de adivinar patrones exactos, el flujo de trabajo se acelera. Para los agentes AI, la reducción de llamadas y el contexto limitado son críticos, especialmente cuando se enfrentan a límites de tokens.
El proyecto es de código abierto y se mantiene en el repositorio de GitHub de zvec‑ai. La comunidad puede contribuir y adaptar el motor a sus flujos de trabajo.
Próximos pasos
El equipo planea añadir soporte para otros lenguajes de programación y mejorar la generación de embeddings con modelos más pequeños, manteniendo el rendimiento local. Si tu equipo busca una búsqueda semántica sin comprometer la privacidad, zvec-grep merece una prueba.
