Démarrer avec Noezis en 5 minutes

Tutorial — à la fin, Noezis sera branché sur votre repo, aura indexé un document, et répondra à une question par une unité de connaissance scorée et traçable (pas un dump de fichiers). Suivez les étapes dans l'ordre : chaque commande est réelle et chaque sortie ci-dessous a été capturée pour de vrai.

Durée : ~5 min. Niveau : débutant. Vous n'écrivez aucune ligne de code.

Ce que vous allez obtenir

Un repo où un agent (ou vous, en CLI) peut demander « pourquoi a-t-on choisi OAuth2 ? » et recevoir la réponse ancrée à sa source, avec un score de confiance — au lieu d'une réponse inventée ou d'un grep qui rate tout ce qui est formulé autrement.

Pré-requis

1. Câbler Noezis sur votre repo (une seule commande)

Depuis la racine de votre repo :

noezis onboard

Cette commande idempotente fait tout en un passage. Sa sortie se termine ainsi :

[3/5] AGENTS.md (agent discovery)…
OK AGENTS.md written → /chemin/AGENTS.md

[4/5] Daemon lifecycle…
OK systemd unit generated → .noezis/noezis-mcp-<repo>.service

[5/5] Summary
OK Repo wired. Next steps:
  1. (human) Reload the agent to activate the MCP hooks…
  2. Verify the installation: noezis doctor

Concrètement, onboard a créé le store local (.noezis/store.db), écrit .mcp.json (découverte par les agents MCP), installé les hooks Claude Code, généré AGENTS.md, et préparé le cycle de vie du daemon. Le daemon est le propriétaire unique du store (un seul writer à la fois — c'est lui qui évite les blocages de verrou).

Bon à savoir. L'unité systemd est générée mais pas installée (ça demande sudo). Pour un agent local en session, ce n'est pas nécessaire : le daemon est lancé à la demande. Pour un service permanent, suivez les 2 lignes sudo … affichées par onboard.

2. Vérifier l'installation

noezis doctor

Sortie réelle (repo correctement câblé) :

  config: ✓ found
  store: ✓ accessible
  embedder (current): onnx:nomic-multi
  compatibility: consistent embedder (onnx:nomic-multi) — no re-indexing required
  triggers: ✓ configured
  daemon: ✓ serves this store (ping OK)
  store: ✓ contains indexed data
  version: 0.2.0

Tout doit être au vert. Si une ligne est ✗, doctor propose une remédiation précise en bas — par exemple noezis onboard pour régénérer un .mcp.json manquant. Pour tout réparer d'un coup : noezis doctor --fix.

3. Ingérer un document

Ajoute un document à indexer (ici, une note de décision technique) :

noezis ingest ./auth.md

Sortie réelle :

OK 2be2c1…447b07 created — 2 chunks
  lid: 2be2c121640a263d4308dbb6776b6dcbf8e8a96e91f0889644cca8dec0447b07

Noezis a découpé le document en passages, les a indexés par le sens (sans aucun LLM), vérifiés et rangés. Le lid est l'identifiant stable du document dans la base. Vous pouvez aussi ingérer un dossier entier (récursif) : noezis ingest ./DOCS/.

4. Chercher (lecture humaine)

noezis search "pourquoi OAuth2 et pas les sessions"

Sortie réelle :

Results for « pourquoi OAuth2 et pas les sessions »
   1. [chunk] 8af8778517e9 score=0.881 (ready)
      # Authentification — Nous utilisons OAuth2 pour le SSO entreprise plutôt que…
   2. [document] 2be2c121640a score=0.867 (ready)
      auth.md
   3. [chunk] b01c435dd6e3 score=0.794 (ready)
      Le flux : l'agent redirige vers le fournisseur, reçoit un code…

Notez bien : la question ne contient pas le mot « sessions classiques » ni la formulation exacte du document, et pourtant le bon passage remonte en tête à 0.881. C'est la recherche sémantique — un grep "OAuth2" aurait raté une question posée autrement.

5. Chercher (sortie machine, pour un agent ou un script)

Le flag global --json donne une sortie structurée. Les nœuds et leurs scores sont dans deux tableaux parallèles (.nodes et .scores) — voici comment les recombiner avec jq :

noezis search "pourquoi OAuth2 et pas les sessions" --json \
  | jq -c '[.nodes, .scores] | transpose | .[:3]
           | map({score:.[1], kind:.[0].kind, lid:.[0].lid[0:12]})'

Sortie réelle :

[{"score":0.8808,"kind":"chunk","lid":"8af8778517e9"},
 {"score":0.8674,"kind":"document","lid":"2be2c121640a"},
 {"score":0.7940,"kind":"chunk","lid":"b01c435dd6e3"}]

Chaque résultat expose lid, kind, state, summary, content_hash — jamais la représentation numérique interne, qui n'est pas exposée.

6. Affiner la recherche

Deux leviers utiles dès le départ :

  1. 8af8778517e9 bm25=1.515 (l.5 — bm25: oauth2, auth2)
  Le mode `hybrid` lance les deux en parallèle.

## Et après ?

- **How-to** : [tracer une décision](../how-to/trace-a-decision.md) ·
  [les modes de recherche en détail](../how-to/search-modes.md) ·
  [ingérer et surveiller un dossier](../how-to/ingest-and-watch.md)
- **Comprendre** : [pourquoi la recherche n'utilise aucun LLM](../explanation/why-no-llm-in-search.md) ·
  [l'arbre de connaissance](../explanation/the-knowledge-tree.md)
- **Référence** : [tous les verbes / flags](../reference/cli.md)

## En cas de souci

| Symptôme | Quoi faire |
|---|---|
| `noezis: command not found` | `export PATH="$HOME/.noezis/bin:$PATH"` |
| `doctor` affiche une ligne `✗` | suivre la remédiation affichée, ou `noezis doctor --fix` |
| ingest : `MCP daemon did not start` | le store n'a pas de daemon ; relance `noezis onboard`, ou vérifie le service (`../reference/cli.md`, section `mcp`) |
| recherche dégradée / scores bizarres | `noezis doctor` → vérifier `embedder (current): onnx` (et non `mock`) |