zvec-grep : rechercher du code et des documents par le sens
zvec-grep, ou zg, est un outil de recherche privilégiant l'exécution locale pour le code source, les documents et les données structurées. Il réunit la recherche exacte ou par expression régulière avec ripgrep, le classement par mots-clés avec BM25 et la recherche vectorielle par proximité de sens. Il est utile lorsque vous connaissez le rôle d'un morceau de code mais pas son nom, ou cherchez un document existant sur un sujet.
Pour un identifiant connu, la recherche exacte est souvent le point de départ le plus simple. Pour « où sont répartis les frais d'exécution ? », la recherche sémantique peut suggérer du code pertinent même si l'implémentation emploie d'autres mots. La similarité aide à trouver des candidats ; elle ne prouve pas que l'outil comprend la règle métier.
Ce qu'apporte un index
L'indexation découpe les fichiers en éléments interrogeables tout en conservant leur structure utile et leurs emplacements sources. Les résultats de code peuvent inclure des symboles et des signatures ; ceux des documents peuvent pointer vers des sections et des passages. Vous pouvez ainsi choisir la prochaine source à ouvrir sans avoir d'abord lu tous les fichiers.
Les résultats ne se limitent pas à des coordonnées. La sortie par défaut est un Markdown compact destiné aux agents ; --human fournit un affichage adapté au terminal, avec des aperçus complets par défaut. La longueur dépend de la requête, du nombre de résultats et des réglages d'aperçu. Une plage de lignes est un point de départ : lisez les appelants, les tests, les définitions environnantes ou le fichier entier lorsque la tâche l'exige.
Les index vectoriels expliquent comment la recherche approximative réduit les comparaisons ; les voisins retrouvés doivent encore être vérifiés dans la source.
Créer et interroger l'index d'un espace de travail
Ces exemples nécessitent Node.js 22 ou ultérieur et le paquet npm officiel. npx peut télécharger le paquet s'il n'est pas installé. Exécutez les commandes depuis le répertoire à indexer. Choisissez un seul modèle initial pour cet espace de travail :
# Dépôt de code
npx @zvec/zvec-grep index --embedding local/potion-code-16m-v2
Pour une collection documentaire multilingue, utilisez plutôt cette variante :
npx @zvec/zvec-grep index --embedding local/potion-multilingual-128m
L'index est stocké dans .zvec-grep/ à la racine du projet. Ne placez pas cet index généré sous contrôle de version. Les modèles locaux peuvent nécessiter un téléchargement initial ; une inférence locale n'implique pas une installation hors ligne. L'outil prend aussi en charge des fournisseurs de calcul vectoriel distants, qui nécessitent une autorisation pour recevoir des données. Vérifiez le choix du modèle avant d'indexer des contenus sensibles.
Dans un dépôt Python indexé, recherchez la logique liée aux frais :
npx @zvec/zvec-grep query "order execution slippage commission fee" -g '*.py' --limit 3 --human
Dans un dépôt documentaire indexé contenant un répertoire docs/, recherchez les contenus existants :
npx @zvec/zvec-grep query "personal knowledge system" -g 'docs/**' --limit 3
Ici, -g filtre les chemins et --limit plafonne les résultats par groupe de requêtes. Si une page traite déjà du sujet, envisagez de la mettre à jour ou de créer un lien vers elle. Une petite limite facilite un premier repérage, mais ne permet pas d'établir l'absence d'un sujet.
Vérifier la source avant de la modifier
Ouvrez les résultats prometteurs dans l'arbre de travail actuel et confirmez le comportement à l'aide des tests ou des documents pertinents. Si les résultats manquent ou sont périmés, vérifiez le périmètre indexé et son état, puis actualisez l'index si nécessaire :
npx @zvec/zvec-grep status
npx @zvec/zvec-grep index
Ces commandes supposent un index existant et réutilisent sa configuration de modèle. Pertinence et performances varient selon le corpus, le modèle et le matériel. Ni un résultat court ni un index local ne garantissent un correctif juste ou n'empêchent un assistant de dépasser le périmètre demandé.
Outils associés
QMD se concentre sur la recherche dans des collections documentaires, notamment des notes Markdown. Basic Memory gère des notes liées que les personnes et les assistants peuvent lire et modifier entre sessions. Ce sont des compléments possibles, pas des couches obligatoires. Mémoire et recherche d'information pour les agents explique comment associer recherche, lecture des sources et instructions actuelles.