La recherche dans la documentation — explication

De quoi s'agit-il ?

/docs et l'outil search_docs (ticket 106) cherchent dans les fichiers texte de dossiers et renvoient des passages — une section d'une page, avec le chemin de ses titres et son lien chemin:ligne. Ils répondent à un autre besoin que search_memory : les sessions enregistrées contiennent ce qui a été dit et décidé ; un dossier de documentation contient ce qui est écrit et maintenu. Les deux recherches sont des outils séparés, avec des moteurs séparés, volontairement.

Pourquoi BM25, et aucun modèle

La recherche classe les passages avec BM25, le calcul de score de la plupart des moteurs plein texte : un mot compte davantage quand il est rare dans le dossier et fréquent dans le passage, et un passage long n'est pas favorisé parce qu'il est long. Il n'a besoin d'aucun modèle. Les alternatives étudiées (ticket 104) — les modes vectoriel et hybride de qmd, les outils à embeddings — trouvent les passages par le sens, entre langues et synonymes, mais chargent un à trois modèles de plus (de 300 Mo à 2 Go pour qmd query) à côté du modèle de chat, sur des machines où c'est la mémoire qui manque en premier. qmd search, son mode BM25, est l'équivalent le plus proche de ce que fait mm, et il demande Node ou Bun, un index à construire et à tenir à jour.

BM25 corrige aussi ce qui rendait au début la recherche dans les sessions bruyante : là, chaque mot comptait autant, si bien qu'un mot court et courant correspondait à presque tous les messages. Avec BM25, un mot présent partout ne pèse presque rien à lui seul.

Pourquoi pas d'index

Les dossiers sont lus à chaque appel. Le docs/ de mm — 137 fichiers Markdown, 1,3 Mo, 1 320 passages — est lu, découpé et noté en 45 ms environ ; les dix fichiers de la démo (44 passages) en 1 ms environ (mesuré le 2026-10-20, meilleur de dix essais). Un index irait plus vite et apporterait ce qu'apporte un index : un endroit où le stocker, une étape pour le reconstruire, et des réponses fausses entre une modification et la reconstruction. Pour un dossier de documentation lu quand une question le demande, un parcours suffit et n'est jamais périmé.

Pourquoi des passages qui sont des sections

Un résultat est fait pour être lu par le modèle ; il doit donc être une unité de sens qui tient à côté de quatre autres : une section — un titre et ce qui le suit — est ce que l'auteur a écrit d'un tenant. Le chemin de ses titres (« Lists and selection › Keep the selection with ListState ») dit de quoi elle parle même quand son texte ne le répète pas, d'où le poids supplémentaire des mots de titre. Une section longue est recoupée aux lignes vides, jamais à l'intérieur d'un bloc de code : la moitié d'un programme n'aide personne. Le lien pointe sur la première ligne du passage, pour que le modèle puisse lire la page entière avec read_file quand un passage ne suffit pas.

Pourquoi des préfixes, et pas de racinisation

Les mots de quatre lettres ou plus trouvent aussi les mots plus longs (list → ListState) et les pluriels (widgets → widget). C'est une réponse peu coûteuse aux manques les plus courants, quelle que soit la langue. Un vrai raciniseur ferait mieux pour une langue et moins bien pour les autres, et serait une dépendance de plus.

Ce qu'elle ne fait pas

Elle porte sur les mots, pas sur le sens. « Comment découper l'écran ? » ne trouve rien dans des tutoriels en anglais. Dans la démo, un modèle de 4B à qui l'on demande de chercher avec les mots de la documentation a traduit lui-même la question — « header footer body layout » — à chaque fois (6 questions en français sur 6) ; la recherche n'a pas eu à le faire.

Liens avec le reste

internal/docsearch contient le moteur (passages, BM25, parcours des dossiers) et ne dépend que de internal/config et d'internal/textfold, le repli casse et accents qu'il partage avec la recherche dans les sessions. /docs est dans la table de commandes partagée ; le REPL, la fenêtre et la façade ACP y répondent chacun depuis leur répertoire de travail. search_docs est déclaré dans main.go à côté des autres outils intégrés.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# La recherche dans la documentation — explication

## De quoi s'agit-il ?

`/docs` et l'outil `search_docs` (ticket 106) cherchent dans les fichiers texte de dossiers et renvoient des passages — une section d'une page, avec le chemin de ses titres et son lien `chemin:ligne`. Ils répondent à un autre besoin que [`search_memory`](persistent-sessions.md) : les sessions enregistrées contiennent ce qui a été dit et décidé ; un dossier de documentation contient ce qui est écrit et maintenu. Les deux recherches sont des outils séparés, avec des moteurs séparés, volontairement.

## Pourquoi BM25, et aucun modèle

La recherche classe les passages avec BM25, le calcul de score de la plupart des moteurs plein texte : un mot compte davantage quand il est rare dans le dossier et fréquent dans le passage, et un passage long n'est pas favorisé parce qu'il est long. Il n'a besoin d'aucun modèle. Les alternatives étudiées (ticket 104) — les modes vectoriel et hybride de `qmd`, les outils à embeddings — trouvent les passages par le sens, entre langues et synonymes, mais chargent un à trois modèles de plus (de 300 Mo à 2 Go pour `qmd query`) à côté du modèle de chat, sur des machines où c'est la mémoire qui manque en premier. `qmd search`, son mode BM25, est l'équivalent le plus proche de ce que fait mm, et il demande Node ou Bun, un index à construire et à tenir à jour.

BM25 corrige aussi ce qui rendait au début la recherche dans les sessions bruyante : là, chaque mot comptait autant, si bien qu'un mot court et courant correspondait à presque tous les messages. Avec BM25, un mot présent partout ne pèse presque rien à lui seul.

## Pourquoi pas d'index

Les dossiers sont lus à chaque appel. Le `docs/` de mm — 137 fichiers Markdown, 1,3 Mo, 1 320 passages — est lu, découpé et noté en 45 ms environ ; les dix fichiers de la démo (44 passages) en 1 ms environ (mesuré le 2026-10-20, meilleur de dix essais). Un index irait plus vite et apporterait ce qu'apporte un index : un endroit où le stocker, une étape pour le reconstruire, et des réponses fausses entre une modification et la reconstruction. Pour un dossier de documentation lu quand une question le demande, un parcours suffit et n'est jamais périmé.

## Pourquoi des passages qui sont des sections

Un résultat est fait pour être lu par le modèle ; il doit donc être une unité de sens qui tient à côté de quatre autres : une section — un titre et ce qui le suit — est ce que l'auteur a écrit d'un tenant. Le chemin de ses titres (« Lists and selection › Keep the selection with ListState ») dit de quoi elle parle même quand son texte ne le répète pas, d'où le poids supplémentaire des mots de titre. Une section longue est recoupée aux lignes vides, jamais à l'intérieur d'un bloc de code : la moitié d'un programme n'aide personne. Le lien pointe sur la première ligne du passage, pour que le modèle puisse lire la page entière avec `read_file` quand un passage ne suffit pas.

## Pourquoi des préfixes, et pas de racinisation

Les mots de quatre lettres ou plus trouvent aussi les mots plus longs (`list` → `ListState`) et les pluriels (`widgets` → `widget`). C'est une réponse peu coûteuse aux manques les plus courants, quelle que soit la langue. Un vrai raciniseur ferait mieux pour une langue et moins bien pour les autres, et serait une dépendance de plus.

## Ce qu'elle ne fait pas

Elle porte sur les mots, pas sur le sens. « Comment découper l'écran ? » ne trouve rien dans des tutoriels en anglais. Dans la démo, un modèle de 4B à qui l'on demande de chercher avec les mots de la documentation a traduit lui-même la question — « header footer body layout » — à chaque fois (6 questions en français sur 6) ; la recherche n'a pas eu à le faire.

## Liens avec le reste

`internal/docsearch` contient le moteur (passages, BM25, parcours des dossiers) et ne dépend que de `internal/config` et d'`internal/textfold`, le repli casse et accents qu'il partage avec la recherche dans les sessions. `/docs` est dans la table de commandes partagée ; le REPL, la fenêtre et la façade ACP y répondent chacun depuis leur répertoire de travail. `search_docs` est déclaré dans `main.go` à côté des autres outils intégrés.