Communitygithub.com

nmdra/notebrain-cli

NoteBrain est un outil CLI Go hautes performances qui indexe votre coffre Obsidian dans une base de données vectorielles ChromaDB locale, permettant aux agents IA d'explorer intelligemment votre base de connaissances personnelle. Il offre une recherche sémantique puissante, un parcours des backlinks et une découverte par tags pour aider les agents à retrouver et raisonner sur vos notes avec contexte.

Qu'est-ce que notebrain-cli ?

NoteBrain est un outil CLI Go hautes performances qui indexe un coffre Obsidian dans une base de données vectorielles ChromaDB locale, offrant 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. Il est conçu pour les agents IA (comme Claude Code, Cursor, Codex) et leur fournit une interface structurée pour explorer les connaissances personnelles via des commandes spécialisées. Ses principaux atouts incluent : l'exécution non interactive avec `--format json` pour éviter les blocages, le chaînage de commandes avec `--jsonpath` pour extraire des champs spécifiques, et une chaîne de requêtes multi-signaux (`search → backlinks → connections → hidden`) qui surpasse une simple recherche vectorielle. NoteBrain fonctionne comme une base de données embarquée (`~/.notebrain/chroma`) sans nécessiter de conteneurs Docker, et l'ingestion est automatisée via cron ou systemd. Les commandes clés incluent `search`, `get`, `backlinks`, `connections`, `hidden`, `boosted`, `tags`, `stats` et `ingest`, chacune optimisée pour un objectif analytique spécifique.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. NoteBrain uniquement — Pas de recherche générique de fichiers : N'utilisez jamais grep, find, ls ou 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érez notebrain comme la seule interface vers le contenu du coffre. Si une commande notebrain semble ne rien renvoyer d'utile, affinez la requête notebrain (formulation différente, --limit plus large, commande alternative) plutôt que de recourir à une recherche générique de fichiers.
  2. 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és snake_case propres (note_slug, title, file_path, score, tags, text).
  3. 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 --jsonpath est 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 de jq.
  4. Récupération complète des notes (notebrain get) : Lorsque search renvoie un extrait de note pertinent, utilisez notebrain 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 jamais cat sur le fichier sous-jacent du coffre — get reconstruit correctement les notes fragmentées et respecte l'état indexé du coffre.
  5. Récupération du contenu pour la synthèse (--include-text) : Par défaut, search et 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 champ text renvoyé contient un markdown riche avec des blocs de code préservés, afin que les extraits de code soient copiables.
  6. Résolution binaire et guillemets : Dans les environnements de développement, exécutez ./notebrain si notebrain n'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.
  7. 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.
  8. 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 ingest avant 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'utilisateurCommandePourquoi et comment utiliser
"Que disent mes notes sur X ?"searchEffectue 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"getRé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 ?"backlinksTrouve les références explicites [[wikilink]] pointant vers la note cible.
"Qu'est-ce qui est structurellement proche dans le graphe ?"connectionsExé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 ?"hiddenMet 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"boostedCombine la similarité vectorielle avec la proximité dans le graphe par rapport à une note --seed.
"Quelles notes partagent des tags avec X ?"tagsAnalyse le chevauchement des tags. Renvoie des chaînes de tags propres dans le tableau tags.
"La base de données est-elle à jour ?"statsProduit des comptes de collections (chunks, links). Prend en charge --format=json et --jsonpath.
"Indexer ou réindexer le coffre"ingestSynchronise 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

IndicateurObjectifDéfaut
--top-k NNombre 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 NRé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-tasksRenvoie uniquement les extraits contenant des listes de tâches (cases à cocher).off
--has-codeRenvoie uniquement les extraits contenant des blocs de code délimités.off
--sectionFiltre les résultats pour ne garder que les extraits sous un chemin d'en-tête spécifique (ex : "Architecture > Composants").—
--limit NNombre maximum total de résultats à renvoyer.10
--tag "NomTag"Filtrer ou rechercher par nom de tag.—
--min-score FSupprime les résultats en dessous de ce score de similarité (0–1).0

Quand utiliser --context-window vs notebrain get

  • Utilisez --context-window 1 lorsque 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 get lorsque 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..."
      ]
    }
  ]
}
ChampPrésent lorsqueDescription
note_slugToujoursIdentifiant sûr pour les URL dérivé du chemin de fichier.
titleToujoursTitre de la note provenant du frontmatter ou du nom de fichier.
file_pathToujoursChemin relatif dans le coffre.
scoreToujoursScore de similarité (0–1) pour la recherche ; nombre de sauts pour les connexions.
chunk_indexRecherche, hidden, boostedQuel extrait de la note a correspondu (indexé à partir de 0).
tagsLorsque la note a des tagsTableau de chaînes de tags.
heading_pathLorsque l'extrait est sous un en-têteChemin de fil d'Ariane comme "Section > Sous-section".
textLorsque --include-text est passéTexte markdown complet de l'extrait correspondant, avec les blocs de code préservés.
contextLorsque --context-window N > 0Tableau des textes des ±N extraits adjacents, ordonnés par indice d'extrait.
extraConnections, tags, boostedInformations 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 :

  1. Recherche avec contexte — exécutez search avec --context-window 1 --include-text --top-k 2 pour 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.
  2. Récupérez les backlinks pour chaque note source — exécutez notebrain backlinks <slug-source> --format json --include-text pour 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.
  3. Parcourez les connexions vers l'extérieur — exécutez notebrain connections <slug-source> --hops 2 --format json pour 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.
  4. Vérifiez les liens cachés — exécutez notebrain hidden <slug-source> --include-text --context-window 1 pour 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.
  5. Synthétisez, ne vous contentez pas de lister — combinez la ou les notes sources, leurs backlinks, le voisinage des connections et les résultats hidden en 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

Skills associés