Compétence NoteBrain CLI pour Agents IA
NoteBrain est un outil CLI Go hautes performances qui indexe un coffre Obsidian dans une base de données vectorielles ChromaDB locale. Il offre une recherche sémantique, un parcours de graphe, une découverte de backlinks, une recherche de relations cachées, une récupération complète de notes et une analyse par tags sur les notes markdown.
Principes fondamentaux d'exécution et justification
Pour fonctionner efficacement et éviter de gaspiler des tokens ou de bloquer des sessions, suivez ces principes fondamentaux :
- NoteBrain uniquement — Pas de recherche générique de fichiers : N'utilisez jamais
grep,find,lsou des scripts shell ad hoc sur les fichiers markdown du coffre pour répondre à la question de l'utilisateur. Les commandes de NoteBrain sont spécialement conçues sur la base de la base de données vectorielles et du graphe indexés, et produiront toujours des résultats de meilleure qualité et plus pertinents qu'une recherche textuelle au niveau du système de fichiers. Considéreznotebraincomme la seule interface vers le contenu du coffre. Si une commandenotebrainsemble ne rien renvoyer d'utile, affinez la requêtenotebrain(formulation différente,--limitplus large, commande alternative) plutôt que de recourir à une recherche générique de fichiers. - Exécution non interactive (
--format json) : Par défaut, NoteBrain lance un terminal interactif TUI (Bubble Tea) conçu pour la navigation humaine. Cette interface interactive bloquera les sessions d'agents automatisés. Spécifiez toujours--format json(ou--format ndjson/--format tsv) sur les commandes de requête pour recevoir immédiatement des données structurées et analysables. Notez que tous les champs de l'enveloppe JSON utilisent des cléssnake_casepropres (note_slug,title,file_path,score,tags,text). - Chaînage de commandes pour agents IA (
--jsonpath) : Chaque fois que vous n'avez besoin que de champs spécifiques (comme extraire des slugs de notes ou du texte à transmettre à des commandes suivantes), utilisez--jsonpath(par exemple,--jsonpath="$.results[0].note_slug"ou--jsonpath="$.results[*].note_slug"). Lorsque--jsonpathest utilisé, les valeurs scalaires sont produites sous forme de chaînes brutes non échappées et les tableaux impriment chaque élément sur une nouvelle ligne, permettant une extraction transparente des variables shell sans avoir besoin dejq. - Récupération complète des notes (
notebrain get) : Lorsquesearchrenvoie un extrait de note pertinent, utiliseznotebrain get <note-slug-or-path>plutôt que de deviner les indices d'extrait pour récupérer le texte complet de la note markdown reconstruite, assemblé à partir de tous ses extraits indexés. N'utilisez jamaiscatsur le fichier sous-jacent du coffre —getreconstruit correctement les notes fragmentées et respecte l'état indexé du coffre. - Récupération du contenu pour la synthèse (
--include-text) : Par défaut,searchet les commandes de parcours renvoient des enveloppes de métadonnées légères (titres, chemins de fichiers, tags, scores de similarité). Chaque fois que votre tâche nécessite de résumer ou de raisonner sur des extraits individuels directement à partir des résultats de recherche, ajoutez--include-text. Le champtextrenvoyé contient un markdown riche avec des blocs de code préservés, afin que les extraits de code soient copiables. - Résolution binaire et guillemets : Dans les environnements de développement, exécutez
./notebrainsinotebrainn'est pas dans le PATH système. Les titres de notes contiennent souvent des espaces ou des crochets ("Planification Q3 [Brouillon]"), alors encapsulez toujours les titres de notes, les tags et les requêtes de recherche entre guillemets doubles. - Stockage persistant embarqué : NoteBrain fonctionne exclusivement comme une base de données embarquée (
~/.notebrain/chroma). Aucun conteneur Docker ChromaDB autonome ni serveur HTTP n'est requis ou pris en charge. - Ingestion automatisée : L'ingestion est gérée par des planificateurs OS (cron/systemd toutes les 3 heures). Vous n'avez pas besoin d'exécuter manuellement
ingestavant les requêtes, sauf si l'utilisateur demande explicitement une réindexation immédiate après avoir modifié des notes.
Guide de sélection des commandes
Sélectionnez la commande spécialisée adaptée à l'objectif analytique de l'utilisateur :
| Intention de l'utilisateur | Commande | Pourquoi et comment utiliser |
|---|---|---|
| "Que disent mes notes sur X ?" | search | Effectue une recherche de similarité vectorielle sur tous les extraits de notes. Utilisez --tag="TagName" pour filtrer par tag. |
| "Lire le contenu complet de la note Y" | get | Récupère et reconstruit le texte complet de la note et ses métadonnées par slug ou chemin de fichier. |
| "Quels liens pointent directement vers cette note ?" | backlinks | Trouve les références explicites [[wikilink]] pointant vers la note cible. |
| "Qu'est-ce qui est structurellement proche dans le graphe ?" | connections | Exécute une recherche en largeur (BFS) sur les wikiliens jusqu'à --hops N. Gardez --hops 1 ou --hops 2 pour éviter une explosion exponentielle. |
| "Qu'est-ce qui est lié par le sens mais PAS par un lien ?" | hidden | Met en surface des notes sémantiquement similaires mais non liées. Très utile pour découvrir des ponts conceptuels. |
| "Trouver des concepts liés à X autour de la note Y" | boosted | Combine la similarité vectorielle avec la proximité dans le graphe par rapport à une note --seed. |
| "Quelles notes partagent des tags avec X ?" | tags | Analyse le chevauchement des tags. Renvoie des chaînes de tags propres dans le tableau tags. |
| "La base de données est-elle à jour ?" | stats | Produit des comptes de collections (chunks, links). Prend en charge --format=json et --jsonpath. |
| "Indexer ou réindexer le coffre" | ingest | Synchronise les notes markdown dans ChromaDB. La réingestion est idempotente. |
Syntaxe des commandes
Recherche sémantique et filtrage par tag (search)
notebrain search "réconciliation Kubernetes" --tag="Kubernetes" --limit 5 --format json --include-text
Principaux indicateurs de recherche
| Indicateur | Objectif | Défaut |
|---|---|---|
--top-k N | Nombre maximum d'extraits à conserver par note. Empêche une longue note de dominer les résultats tout en préservant la profondeur. | 3 |
--context-window N | Récupère ±N extraits adjacents autour de chaque correspondance et remplit le tableau context. Utilisez 1 ou 2 pour la plupart des tâches. | 0 |
--has-tasks | Renvoie uniquement les extraits contenant des listes de tâches (cases à cocher). | off |
--has-code | Renvoie uniquement les extraits contenant des blocs de code délimités. | off |
--section | Filtre les résultats pour ne garder que les extraits sous un chemin d'en-tête spécifique (ex : "Architecture > Composants"). | — |
--limit N | Nombre maximum total de résultats à renvoyer. | 10 |
--tag "NomTag" | Filtrer ou rechercher par nom de tag. | — |
--min-score F | Supprime les résultats en dessous de ce score de similarité (0–1). | 0 |
Quand utiliser --context-window vs notebrain get
- Utilisez
--context-window 1lorsque vous avez besoin d'un contexte environnant léger pour plusieurs résultats de recherche à la fois. C'est efficace — un seul appel de recherche vous donne à la fois les extraits correspondants et leurs voisins, suffisamment pour comprendre le contexte local sans récupérer des notes entières. - Utilisez
notebrain getlorsque vous avez besoin du texte de note complet reconstruit — par exemple, lorsque l'utilisateur demande de lire ou de résumer une note spécifique, ou lorsque vous devez voir la structure complète du document.
L'approche par fenêtre de contexte est particulièrement précieuse lors du traitement de nombreux résultats de recherche, car la récupération des notes complètes pour chaque résultat serait inutile. Récupérez d'abord la fenêtre, puis sélectionnez get uniquement pour les notes qui ont vraiment besoin d'un contexte complet.
Récupération complète de note (get)
notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json
Connexions de graphe et liens cachés (connections, hidden)
notebrain connections "Systèmes Distribués" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text
Schéma de sortie JSON
Comprendre la structure des résultats est essentiel pour une extraction fiable des champs. Chaque commande de requête encapsule les résultats dans cette enveloppe :
{
"command": "search",
"query": "Recherche sémantique : \"kubernetes\"",
"total": 3,
"results": [
{
"note_slug": "02areaskubernetes-architecture",
"title": "Architecture Kubernetes",
"file_path": "02.Areas/Kubernetes/Architecture.md",
"score": 0.82,
"chunk_index": 2,
"tags": ["Kubernetes", "DevOps"],
"heading_path": "Composants > Plan de contrôle",
"text": "Le serveur API valide et configure...",
"context": [
"Texte de l'extrait précédent sur le stockage etcd...",
"Le serveur API valide et configure...",
"Le planificateur surveille les nouveaux Pods..."
]
}
]
}
| Champ | Présent lorsque | Description |
|---|---|---|
note_slug | Toujours | Identifiant sûr pour les URL dérivé du chemin de fichier. |
title | Toujours | Titre de la note provenant du frontmatter ou du nom de fichier. |
file_path | Toujours | Chemin relatif dans le coffre. |
score | Toujours | Score de similarité (0–1) pour la recherche ; nombre de sauts pour les connexions. |
chunk_index | Recherche, hidden, boosted | Quel extrait de la note a correspondu (indexé à partir de 0). |
tags | Lorsque la note a des tags | Tableau de chaînes de tags. |
heading_path | Lorsque l'extrait est sous un en-tête | Chemin de fil d'Ariane comme "Section > Sous-section". |
text | Lorsque --include-text est passé | Texte markdown complet de l'extrait correspondant, avec les blocs de code préservés. |
context | Lorsque --context-window N > 0 | Tableau des textes des ±N extraits adjacents, ordonnés par indice d'extrait. |
extra | Connections, tags, boosted | Informations spécifiques à la commande (ex : "2 saut(s)", "graph-boosted"). |
Amélioration de la qualité des réponses : Récupération multi-signaux
Avant de répondre à toute question de type "que sais-je sur X" ou "résume mes notes sur X", ne vous arrêtez pas à un seul appel search. Les résultats de recherche ne font remonter que les extraits sémantiquement proches de la requête — ils manquent le contexte environnant que l'utilisateur a délibérément construit dans son graphe. Élargissez toujours le champ de vision :
- Recherche avec contexte — exécutez
searchavec--context-window 1 --include-text --top-k 2pour obtenir les extraits les plus pertinents avec leurs paragraphes environnants. Cela vous donne à la fois la précision (l'extrait correspondant) et le contexte (ce qui vient avant et après) en un seul appel. - Récupérez les backlinks pour chaque note source — exécutez
notebrain backlinks <slug-source> --format json --include-textpour extraire chaque note qui pointe explicitement vers la note source. Ce sont des notes que l'utilisateur a manuellement organisées comme étant liées, donc leur contenu est presque toujours de haute qualité et doit être fortement pondéré dans votre synthèse. - Parcourez les connexions vers l'extérieur — exécutez
notebrain connections <slug-source> --hops 2 --format jsonpour cartographier le voisinage local du graphe autour de la note source. Cela révèle les notes structurellement adjacentes (par exemple, les notes à deux liens de distance) qui peuvent ne pas apparaître dans une recherche vectorielle pure mais qui font partie du même groupe de connaissances. - Vérifiez les liens cachés — exécutez
notebrain hidden <slug-source> --include-text --context-window 1pour détecter les notes conceptuellement liées que l'utilisateur n'a pas encore liées. Signalez-les explicitement à l'utilisateur comme des liens potentiellement manquants dans son coffre, car c'est l'un des différenciateurs les plus précieux de NoteBrain par rapport à une simple recherche. - Synthétisez, ne vous contentez pas de lister — combinez la ou les notes sources, leurs backlinks, le voisinage des
connectionset les résultatshiddenen une seule réponse cohérente, en distinguant ce qui est explicitement lié (haute confiance) de ce qui n'est que sémantiquement similaire (mérite une double vérification).
Cette chaîne search → backlinks → connections → hidden devrait être le flux de travail par défaut pour toute question exploratoire non triviale, et pas seulement un seul appel search, car elle remet en surface à la fois la structure explicite construite par l'utilisateur et la structure implicite que NoteBrain peut détecter.
Pipeline de chaînage pour agent IA
# 1. Recherche avec contexte environnant — top-k maintient la diversité des résultats entre les notes
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
--context-window 1 --include-text --format json \
--jsonpath="$.results[0].note_slug")
# 2. Récupère le texte complet de la note reconstruite pour le premier résultat
notebrain get "$SLUG" --jsonpath="$.text"
# 3. Trouve tous les slugs de notes de backlink pointant vers cette note, avec leur contenu,
# pour ancrer la réponse dans ce que l'utilisateur a explicitement lié
notebrain backlinks "$SLUG" --format json --include-text
# 4. Parcourt le voisinage du graphe pour révéler les notes structurellement adjacentes
# qu'une recherche vectorielle seule manquerait
notebrain connections "$SLUG" --hops 2 --format json
# 5. Découvre les liens cachés pour trouver des relations non liées mais pertinentes
notebrain hidden "$SLUG" --include-text --context-window 1 --format json
# 6. Synthétise tous les résultats en une réponse cohérente