_ _ ___ _____ ____ ___ ____ | \ | |/ _ \| ____|_ /|_ _/ ___| | \| | | | | _| / / | |\___ \ | |\ | |_| | |___/ /_ | | ___) | |_| \_|\___/|_____/____|___|____/ Noezis — documentation lisible par machine (format llmstxt.org). Ce fichier contient le CORPUS COMPLET de la doc, concaténé. 👋 Humain ? La version lisible et illustrée est sur → /docs/ 🤖 Agent ? Ce fichier est fait pour toi : ingère-le tel quel. ℹ️ Format : https://llmstxt.org ──────────────────────────────────────────────────────────────────────────── # Noezis > Noezis is an agent-first knowledge substrate: a governed, auditable knowledge graph navigated deterministically (no LLM in the search loop) that tells an agent what is known, contested, stale or missing — replacing static context to curb hallucination and environment blindness. --- # file: tutorial/getting-started.md # 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 - **Linux**, `python3` et `jq` disponibles (`jq` sert juste à lire le JSON, optionnel). - Le binaire **`noezis` sur le `PATH`** : ```bash export PATH="$HOME/.noezis/bin:$PATH" noezis --version # affiche la version installée (ex. noezis 0.2.x) ``` Si `noezis` est introuvable, installez-le puis initialisez les modèles avec `noezis init` (télécharge l'embedder ONNX). Voir `../how-to/` pour les détails. ## 1. Câbler Noezis sur votre repo (une seule commande) Depuis la racine de votre repo : ```bash 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-.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 ```bash 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) : ```bash 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) ```bash 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` : ```bash 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 : ```json [{"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 : - **Plancher de score** — ne garder que les résultats au-dessus d'un seuil (ciblage). Sur un petit corpus, monte le seuil pour écarter le bruit : ```bash noezis search "pourquoi OAuth2 et pas les sessions" --min-score 0.85 ``` ne renvoie alors que les deux nœuds ≥ 0.85, et laisse tomber le 0.794. - **Mode lexical** — quand vous cherchez un **mot exact** (un symbole, un nom propre) plutôt qu'un sens, le mode `lexical` cherche ce mot tel quel et répond même quand l'index sémantique est indisponible : ```bash noezis search "OAuth2" --mode lexical ``` ``` Lexical results (BM25) for « OAuth2 » 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`) | --- # file: how-to/check-health.md # Vérifier que Noezis va bien > How-to — objectif : diagnostiquer en quelques secondes si Noezis sert bien le > contexte à votre agent, et savoir quoi regarder quand une réponse semble à côté. ## Quand Une session démarre sans contexte projet, une recherche vous paraît pauvre, ou vous voulez simplement confirmer que tout tourne avant de vous appuyer dessus. ## Faire ### 1. L'état de l'installation ```bash noezis doctor ``` Vérifie l'installation complète : magasin accessible, modèle de recherche présent, configuration de l'agent, service en vie. Il liste ce qui manque et, avec `--fix`, répare ce qu'il peut tout seul. Un signal important remonté ici : le **mode de recherche**. S'il est *dégradé*, la recherche par le sens ne marche pas (le modèle est absent) — installez-le avant de juger la qualité des résultats. ### 2. L'état du magasin ```bash noezis status ``` Donne la forme du contenu indexé : combien de documents sont prêts, et la structure d'ensemble. Utile pour confirmer qu'il y a bien quelque chose à interroger (un magasin vide ne peut rien remonter). ### 3. Est-ce que l'agent utilise vraiment le contexte ? ```bash noezis context-report ``` Rapport lisible : sur les sessions récentes, à quel point le contexte poussé à l'agent a été effectivement utilisé. C'est l'outil de calibrage — il vous dit si le problème est « Noezis ne pousse pas » ou « l'agent ignore ce qui est poussé ». ## Vérifier Une installation saine donne : - `doctor` sans erreur bloquante et un mode de recherche **complet** (non dégradé) ; - `status` avec des documents *prêts* (`ready`) en nombre cohérent avec le dépôt ; - une recherche test qui remonte du sens, pas juste des chaînes : ```bash noezis search "une question conceptuelle sur votre projet" ``` ## Voir aussi - Brancher un dépôt proprement → [Brancher Noezis sur un dépôt](onboard-a-repo.md) - Choisir le bon mode de recherche → [Modes de recherche](search-modes.md) - Ce que Noezis apporte vraiment → [Proprioception](../explanation/proprioception.md) --- # file: how-to/ingest-and-watch.md # Ingérer des documents et surveiller un dossier > How-to — objectif : alimenter le graphe avec vos documents, ponctuellement ou en > continu. ## Ingérer un fichier ou un dossier ```bash noezis ingest ./README.md # un fichier noezis ingest ./docs/ # un dossier, récursif ``` Formats supportés : texte/Markdown, PDF, image, .doc/.docx. Chaque document est découpé en passages, indexé par le sens (sans LLM), vérifié puis rangé. Les doublons (même contenu) sont détectés et ignorés. ## Reprendre une ingestion interrompue ```bash noezis ingest ./gros-corpus/ --resume ``` Noezis reprend là où il s'était arrêté (checkpoint par lot ; ajoute `--batch-id ` pour cibler un lot précis). ## Surveiller un dossier (ré-ingestion automatique) ```bash noezis watch start ./docs/ # surveille et ré-ingère à chaque changement noezis watch list # ce qui est surveillé noezis watch stop ./docs/ ``` ## Vérifier l'indexation ```bash noezis status # rapport structurel (nœuds, communautés) noezis progress # progression d'une indexation en cours ``` ## Voir aussi - Comment l'arbre se construit ensuite → [Un index par sujet](../explanation/the-knowledge-tree.md) - Démarrage complet → [Démarrer avec Noezis en 5 minutes](../tutorial/getting-started.md) --- # file: how-to/onboard-a-repo.md # Brancher Noezis sur un dépôt > How-to — objectif : connecter Noezis à un dépôt en une commande, pour que votre > agent reçoive le contexte du projet dès la session suivante, sans réglage manuel. ## Quand Vous démarrez Noezis sur un nouveau dépôt (ou un dépôt frère d'un projet déjà branché). Vous voulez que l'agent ait, à chaque session : l'état du projet, les décisions récentes et les documents pertinents — sans rien câbler à la main. ## Faire Depuis la racine du dépôt : ```bash noezis onboard ``` Une seule commande, idempotente (la relancer ne casse rien), qui met en place : - le magasin de connaissances propre au dépôt ; - la configuration de l'agent (le fichier `.mcp.json` + les hooks de session) ; - le fichier `AGENTS.md` qui décrit à l'agent comment utiliser Noezis ; - le cycle de vie du service en arrière-plan ; - l'ingestion des documents fondateurs du dépôt (`README.md`, `DOCS/`, …). Pour brancher un dépôt qui n'est pas le répertoire courant : ```bash noezis onboard --repo /chemin/vers/le/depot ``` Pour onboarder sans ingérer tout de suite les documents (par exemple en CI) : ```bash noezis onboard --no-ingest ``` Chaque dépôt a son propre magasin : un projet ne voit jamais la connaissance d'un autre. Lancer Noezis depuis le dépôt A interroge le magasin du dépôt A, point. ## Vérifier ```bash noezis doctor ``` `doctor` vérifie que tout est en place (configuration agent, service, magasin) et liste ce qui manque. Pour qu'il répare automatiquement ce qu'il peut : ```bash noezis doctor --fix ``` Pour défaire le branchement (retirer la configuration sans toucher au code) : ```bash noezis cleanup --repo /chemin/vers/le/depot ``` ## Voir aussi - Première prise en main pas à pas → [Démarrer](../tutorial/getting-started.md) - Ingérer et suivre des documents → [Ingérer et surveiller](ingest-and-watch.md) - Pourquoi un magasin par dépôt → [L'arbre de connaissance](../explanation/the-knowledge-tree.md) --- # file: how-to/search-modes.md # Choisir le bon mode de recherche > How-to — objectif : savoir quand utiliser la recherche sémantique, lexicale ou > hybride, et régler la précision. ## Les trois modes | Mode | Quand | Ce qu'il fait | |---|---|---| | **semantic** (défaut) | question conceptuelle, « comment X marche », « pourquoi Y » | cherche **par le sens** | | **lexical** | vous connaissez le **mot/symbole exact** (nom de fonction, sigle) | cherche le **mot exact**, répond même quand l'index sémantique est indisponible | | **hybrid** | vous voulez les deux à la fois | lance les deux en parallèle, résultats présentés séparément | ```bash noezis search "comment l'authentification fonctionne" # semantic noezis search "OAuth2Provider" --mode lexical # mot exact noezis search "gestion des sessions" --mode hybrid --json ``` ## Régler la précision - `--min-score 0.85` — résultats ciblés (haut seuil) ; `--min-score 0.3` — large. - `--max-results 10` — nombre de résultats retournés. - `--path-prefix DOCS/` — restreint aux documents sous un préfixe de chemin (recherche par le sens). - `--community-id ` — restreint à un sujet précis (l'identifiant vient du rapport de graphe). ```bash noezis search "politique d'authentification" --min-score 0.7 --max-results 5 --path-prefix DOCS/ --json ``` ## Côté agent (MCP) Le verbe `noezis_search` expose les mêmes modes (`mode: semantic|lexical|hybrid`). La plupart du temps un agent n'a **pas** besoin d'appeler `noezis_search` : le contexte pertinent lui est déjà **fourni au début du tour**. On appelle `noezis_search` pour **creuser** plus loin. ## Voir aussi - Pourquoi la recherche est déterministe → [Pourquoi la recherche n'utilise pas de LLM](../explanation/why-no-llm-in-search.md) - Tous les flags → [CLI](../reference/cli.md) · le verbe → [Verbes MCP](../reference/mcp-verbs.md) --- # file: how-to/trace-a-decision.md # Tracer une décision > How-to — objectif : enregistrer une décision structurée dans le graphe pour que > les sessions futures s'en souviennent et que les contradictions soient détectées. ## Quand Vous avez fait un choix qui fait autorité (archi, scope, doctrine, nommage, pivot) et vous voulez qu'il survive à la session courante. ## Faire Une décision est un triplet `(subject, predicate, value)` + une `rationale` (jamais auto-générée). Via un agent MCP : ```jsonc // tool: noezis_assert_decision { "subject": "auth_backend", "predicate": "uses", "value": "oauth2", "rationale": "Choisi pour le SSO entreprise ; alternatives (session cookie) écartées car multi-tenant." } ``` Si une décision existe déjà sur le même `(subject, predicate)` avec une `value` différente, Noezis **bloque** et signale la contradiction. Pour remplacer une décision périmée : `noezis_supersede` (chaîne `deprecated → replacement`). Pour l'annuler : `noezis_retract_decision` (réversible). ## Vérifier La décision est fournie automatiquement au début des sessions suivantes, et reste consultable via : ```bash noezis search "auth_backend" --json | jq '.nodes[] | select(.kind=="decision")' ``` ## Voir aussi - Pourquoi décision ≠ document → [Décision ≠ document](../explanation/registre-vs-prose.md) - Tous les verbes de décision → [Verbes MCP](../reference/mcp-verbs.md) --- # file: reference/cli.md # Reference — CLI (`noezis`) > 22 subcommands (git/kubectl-style). Version `0.2.0`. Flags are shown verbatim from `--help` (authoritative, never paraphrased). > **Reserved values.** Some flags list enum values that are **not yet active** in V1 (e.g. `--scope cloud|both`, `--mode cloud|hybrid`): only `local` is wired today. They are reserved for a future cloud/multi-instance tier and currently behave as `local`. ## Ingestion ### `noezis ingest` Ingest a file, folder or raw text
flags & usage ``` Ingests a file, a recursive folder, or raw text Usage: noezis ingest [OPTIONS] [SOURCE] Arguments: [SOURCE] Source to ingest: file path, folder (recursive), or ignored if `--text` Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --text Ingests raw text directly (alternative to ``) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --summary Explicit summary — otherwise generated automatically --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --resume Resumes an interrupted batch from the last checkpoint. Files already processed in the last run are skipped --batch-id Explicit batch identifier (to resume a specific batch). Without this argument, `--resume` resumes the directory's last batch --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --force Bypasses content deduplication: re-ingests even the documents already indexed (upsert on the same LID). Use it to repopulate the `content` field of a store predating full-text persistence, without losing the Decisions/OpEvents (which are not re-ingested). See RB-06 --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --async Asynchronous ingestion (ADR-0004 D3): launches a job on the daemon and tracks its progress by polling instead of holding the RPC connection open during the whole embedding. No effect in embedded mode (`--ephemeral`/`--resume`) where ingestion is already local synchronous. Reserved for ingesting a single file or text (not a directory, which already iterates file by file). `--wait` is the agent-first alias (T211): same behavior, flag name aligned with the standards (HeyGen). Blocks until `done`/`failed`, returns the full job report (not the `job_id`). Exit: `0` done, `1` failed, `124` timeout (see `--wait-timeout`). **CLI only**: the MCP tools stay atomic/non-blocking (maintainer decision). [aliases: --wait] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] --wait-timeout Max wait time for the async/`--wait` job, in seconds (T211). Beyond → exit 124 (`ExitCode::Timeout`). Default 600, aligned with the hooks timeout [default: 600] -h, --help Print help (see a summary with '-h') ```
### `noezis ingest-session` Ingest a session transcript (closed learning loop)
flags & usage ``` Ingests a session transcript (closes the learning loop) Usage: noezis ingest-session [OPTIONS] [FILE] Arguments: [FILE] Transcript file to ingest (stdin if absent) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --session-id Session identifier (generated if absent) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --extract-skills Extracts and indexes the skills detected in the session --min-ingest-delta Idempotence: re-ingests the full transcript (costly embedding) only if it has grown by at least N bytes since this session's last successful ingestion. The delta's decisions are always asserted. `0` disables the threshold (re-ingests on every call — old behavior) [default: 4096] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --no-checkpoint Ignores the session checkpoint (re-processes the whole transcript) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis watch` Watch a folder continuously (start/stop/list)
flags & usage ``` Watches a folder (start/stop/list) Usage: noezis watch [OPTIONS] Commands: start Starts a watch stop Stops a watch list Lists the currently watched paths help Print this message or the help of the given subcommand(s) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Learning ### `noezis skill` Skill management (list/feedback/show/prune)
flags & usage ``` Management of the skills indexed in the graph Usage: noezis skill [OPTIONS] Commands: list Lists the indexed skills with status and last-use date feedback Records feedback on the use of a skill show Displays the full content of a skill prune Removes obsolete or contradictory skills help Print this message or the help of the given subcommand(s) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Meta ### `noezis feedback` Send product feedback (opt-in local/central)
flags & usage ``` Sends product feedback (opt-in, T217) — local spool + central send if `[feedback].enabled`. Store-free Usage: noezis feedback [OPTIONS] [MESSAGE] Arguments: [MESSAGE] Feedback message (read from stdin if absent) Options: --category Free-form category (e.g. `bug`, `idea`, `praise`) [default: general] --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --send Attempts the central send (requires the `[feedback].enabled` opt-in + endpoint) --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --status Displays the central feedback opt-in state without sending anything --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis inspect` Inventory of CLI commands and MCP tools
flags & usage ``` Inventory of the available CLI commands and MCP tools (agent discovery) Usage: noezis inspect [OPTIONS] Options: --include-mcp Includes the MCP tools with their JSON schema in the output --json Line-delimited JSON output (eases `jq`, scripts, CI) --check-parity CLI↔MCP parity gate (T210a): verifies that every MCP tool and every CLI command is classified (paired or exempted) and that the enum values of the paired commands do not diverge. Exit 1 on drift. No runtime --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --skill Prints the workflows manifest (embedded SKILL.md, T212) — introspection level "how to chain the commands", above the plain list. Human or machine reading (markdown) --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis version` Version and compiled features
flags & usage ``` Displays the version and the compiled features Usage: noezis version [OPTIONS] Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Navigation ### `noezis children` Structural children of a LID
flags & usage ``` Structural children of a LID Usage: noezis children [OPTIONS] Arguments: LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis community` All members of a LID's community
flags & usage ``` All members of the community containing the LID Usage: noezis community [OPTIONS] Arguments: LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis parent` Structural parent of a LID
flags & usage ``` Structural parent of a LID (or null if root) Usage: noezis parent [OPTIONS] Arguments: LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis path` A* path between two LIDs
flags & usage ``` A* path between two LIDs Usage: noezis path [OPTIONS] Arguments: Source LID (hex 64 chars) Target LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --max-hops Maximum A* depth --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis search` tree navigation semantic search
flags & usage ``` Semantic search (MCTS over the snapshot) Usage: noezis search [OPTIONS] Arguments: Text query Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --scope Search scope (V1: only `local` is wired) [default: local] [possible values: local, cloud, both] --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --max-hops Maximum MCTS traversal depth --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --simulations Number of MCTS simulations --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --min-score Floor score (inclusive) applied after MCTS — `f32` in `[0, 1]`. Enables adaptive exploration (broad with `0.3`, targeted with `0.85`) --max-results Maximum number of nodes returned (post-MCTS truncation) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mode Search leg (parity with the `noezis_search` MCP tool): `semantic` (default, MCTS over embeddings), `lexical` (pure BM25 — exact tokens/symbols, zero embed, answers even when ONNX is saturated), `hybrid` (both in parallel, sections + per-LID vote — never a combined score, decision `lexical_index_b_fusion_arbitration`) [default: semantic] [possible values: semantic, lexical, hybrid] --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] --path-prefix R5 — restrict results to documents whose source_path starts with this prefix (e.g. `--path-prefix DOCS/`). Semantic leg only --community-id R6 — restrict results to a Leiden community (id from graph_report). Semantic leg only -h, --help Print help ```
### `noezis siblings` Neighbors in the same community
flags & usage ``` Neighbors of the node within its community Usage: noezis siblings [OPTIONS] Arguments: LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis summary` Public summary of a LID
flags & usage ``` Public summary of a LID (without centroid) Usage: noezis summary [OPTIONS] Arguments: LID (hex 64 chars) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Reporting ### `noezis status` Structural report (over-connected topics, communities, entropy)
flags & usage ``` Formatted structural report (god nodes, communities, entropy) Usage: noezis status [OPTIONS] Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis store` Statistics and validation pipeline verification
flags & usage ``` K-RITIK statistics and verification of the store Usage: noezis store [OPTIONS] Commands: stats Store statistics (nodes by state, edges by kind, etc.) verify Verifies the K-RITIK invariants on the full snapshot (INV_N1-N7 via `verify_all`). With `--full`, additionally re-applies the 4 deterministic checks of the `IngestValidator` node by node (Merkle, Versioning, Centroid, NoEdgeToTransient), without rollback. The global `--json` then produces a structured `VerifyReport` usable in CI migrate Applies the V1→V2 schema migrations (idempotent). Reads the current version in `/_migrations/`, applies only the migrations not yet played gc Purges dead nodes: `Failed` tombstones (K-RITIK rollback) + `Indexing` orphans (lost embedding/hash). WRITE — routed to the daemon (never steals the single-writer LOCK, ADR-0004). Run it outside active ingestion: any `Indexing` node is treated as an orphan merge-entities `merge-entities` (G3) — retroactively merges historical duplicate entities sharing one canonical identity AND the same kind (no fuzzy matching; type-conflicts skipped). Surfaced by the entity-health audit. Dry-run by default — pass `--apply` to write. WRITE — routed to the daemon (ADR-0004); tombstones finalized by `store gc` retype-entities `retype-entities` (gazetteer A4/B2/B5) — applies the curated project gazetteer to existing entities: authoritative re-typing of known project entities + tombstoning of project-garbage fragments D2 misses. Dry-run by default — pass `--apply` to write. WRITE — routed to the daemon (ADR-0004) purge-superseded Purges old document versions (chained `SUPERSEDED_BY`). Safeguard: a document is purged only if the end of its version chain exists and is `Ready` (the live successor guarantees no content is lost). WRITE — routed to the daemon (ADR-0004) purge-uncited Opt-in KM-4 purge of Documents uncited for more than `--days` days (default 90). Tombstones the document + its chunks to `Failed` (reversible until a later `store gc` finalizes them — never a hard delete). SAFE BY DEFAULT: simulates unless `--confirm` is passed (double-confirmation guard). WRITE — routed to the daemon (ADR-0004) relation-replay Replays relation extraction for the chunks spooled after a Groq 429 rate-limit (decision `relation_spool_replay`). WRITE — routed to the daemon (ADR-0004) help Print this message or the help of the given subcommand(s) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Setup ### `noezis doctor` Full health check (store, embedder, triggers)
flags & usage ``` Verifies the full installation: store, embedder, triggers, version Usage: noezis doctor [OPTIONS] Options: --cpu CPU self-test: samples the CPU of the `noezis-mcp-server` daemons bound to this store and alerts if one exceeds `--cpu-threshold` **at rest** (leak symptom — see 2026-06-02 audit: orphan resident at ~1.2 core). Does not open the store; reads `/proc` --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --cpu-threshold CPU alert threshold as a percentage of a core (default 20.0). Above, `--cpu` emits a warning and exits with code 1 [default: 20] --fix Automatically repairs the missing links by running `noezis onboard` (idempotent) on the current repo, then re-verifies. Without this flag, doctor only STATES the remediation command per link (agent-first) --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis init` Initialize the store and TOML configuration
flags & usage ``` Initializes the store and the TOML configuration Usage: noezis init [OPTIONS] Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --store Path to the RocksDB store --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --mode Operating mode (V1: local only) [default: local] [possible values: local, cloud, hybrid] --embedder Embedder to pre-configure [default: nomic-multi] [possible values: jina-v2, siglip-base, nomic-multi, mock] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --download Downloads the configured ONNX model into ~/.noezis/models/ after init. Required before any startup of the MCP server or the CLI in Onnx mode --force Rewrites the configuration even if it already exists --ephemeral Uses an in-memory (non-persistent) store — handy for tests --ingest-path [] Immediately ingests all files in the folder after init. Without an argument: ingests the current directory. Example: `noezis init --ingest-path` → ingests `.` `noezis init --ingest-path /root/lumis` → ingests /root/lumis --cpu-profile CPU consumption level during indexing and the watcher. turbo — all cores, 0 ms/chunk (first install, dedicated machine) balanced — half the cores, 50 ms/chunk (active desktop) background — 1 core, 200 ms/chunk, nice 19 (default — invisible in the background) minimal — 1 core, 500 ms/chunk, nice 19 (laptop in a meeting) [default: background] --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] --with-degraded-ner Downloads the SUB-GATE local entity models (DistilBERT NER ONNX + Qwen-0.5B relation GGUF + llama-server). OFF by default: the entity layer is gated on a capable model (cloud ≥ ~8B, BYOK) and these local backends fall below the quality bar (NER F1≈0.24) — decision `ner_quality_gate_skip_degraded`. Enable ONLY to experiment with the degraded local path (`NOEZIS_NER_ALLOW_DEGRADED=1`). The embedder, NLI and ORT runtime are always downloaded (hard deps, unaffected) -h, --help Print help (see a summary with '-h') ```
### `noezis ls` List the stores configured on this machine
flags & usage ``` Lists the Noezis stores configured on this machine Usage: noezis ls [OPTIONS] Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis progress` Indexing progress INDEXING vs READY
flags & usage ``` Progress of the ongoing indexing (INDEXING vs READY) Usage: noezis progress [OPTIONS] Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --wait Blocks until indexing finishes (no INDEXING/PENDING node) instead of returning a snapshot. Designed for scripts/CI that launch an async job (`noezis ingest --async`) then wait for its completion. Exit codes: 0 = finished without failure, 1 = finished with `failed` nodes, 124 = timeout exceeded (`--timeout`). Internal polling, no LLM dependency --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --timeout Maximum wait time in seconds (with `--wait`). Beyond → exit 124 [default: 300] --poll-interval Polling interval in seconds (with `--wait`) [default: 2] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
### `noezis setup` Configure triggers for the closed learning loop
flags & usage ``` Configures the triggers for the closed learning loop Usage: noezis setup [OPTIONS] Options: --agent Target agent for hook generation [default: claude-code] [possible values: claude-code, hermes, generic] --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --dry-run Displays the generated configuration without applying it --config-path Path to the agent config (auto-detected if absent) --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
## Transport ### `noezis mcp` MCP JSON-RPC 2.0 stdio transport
flags & usage ``` MCP JSON-RPC 2.0 stdio transport (mode 2) Usage: noezis mcp [OPTIONS] Commands: serve Launches the stdio MCP server (mode 2 — external agents) inspect Lists the 12 MCP tools with their JSON schemas schema Exports the full catalog of MCP tools (name, description, tier, use_when, inputSchema) as JSON on stdout — single source for SDK generation or third-party agent documentation generate-sdk Generates a thin SDK (~10 lines per tool) emitting the corresponding `tools/call` JSON-RPC calls over stdio, from the descriptors help Print this message or the help of the given subcommand(s) Options: --json Line-delimited JSON output (eases `jq`, scripts, CI) --config Path to the TOML configuration (default: `~/.noezis/config.toml`) [env: NOEZIS_CONFIG=] --profile Named configuration profile (T215) — loads `~/.noezis/profiles/.toml` instead of the default config. Ignored if `--config` is passed explicitly [env: NOEZIS_PROFILE=] --deliver Delivers JSON output somewhere other than stdout (T216): `file:` or `webhook:`. Opt-in: the target must match a prefix of `[delivery] allow` in the config (otherwise refused) --store Path to the SurrealDB store (overrides the config's `[store].path`) [env: NOEZIS_STORE=] --ephemeral Uses an in-memory (non-persistent) store — handy for tests --mock-embedder Forces the use of MockEmbedder (deterministic SHA-256) regardless of the configuration. Useful for tests without a downloaded ONNX model. Equivalent to `NOEZIS_MOCK_EMBEDDER=1` [env: NOEZIS_MOCK_EMBEDDER=] -h, --help Print help ```
--- # file: reference/mcp-verbs.md # Reference — MCP verbs > 61 verbs exposed over JSON-RPC 2.0 (stdio). Each verb is callable by any MCP-capable agent. Grouped by capability tier. > **Maturity note.** The entity-relations verbs (`noezis_relations`, `noezis_entity_neighbors`, `noezis_path_entities`, `noezis_chains`, `noezis_triplets`, `noezis_explain_chain`) rely on an **experimental** named-entity layer that is **de-scoped from retrieval**: their reliability depends on entity-extraction quality on your corpus. Document retrieval (`noezis_search`, the tree, decisions) does not depend on this layer. ## Read — inspection (no mutation) ### `noezis_audit_contradictions` Full graph scan to detect the contradictions between passages and active Decisions. Costly on a large corpus — reserve for periodic audits or after ingesting a whole corpus. Returns the tensions grouped by severity (critical/high/low). **When to use** — To audit the contradictions in the whole graph. After ingesting a large corpus to see the detected inconsistencies. | Parameter | Type | Required | Description | |---|---|---|---| | `include_resolved` | boolean \| null | — | Include the already-resolved tensions. Default: false. | | `max_results` | integer \| null | — | Maximum number of tensions returned. Default: 50. | | `min_severity` | number \| null | — | Minimum severity (0.0 = everything). Default: 0.0. | ### `noezis_briefing` [DEPRECATED — use noezis_context] State-of-the-world summary: recent ADRs, active tensions, hot topics, codifications, paradigms. Kept as a transitional alias; will be removed at V-next. The state-of-world is now a section of noezis_context (pushed at the start of the turn). **When to use** — Do not use anymore for new code — see noezis_context. Alias maintained for compatibility of the deployed hooks/skills. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Filtering by actor — if set, only the elements whose `actor` matches are surfaced (Decisions, OpEvents, Codifications). Format `Principal` (`user:alice`, `agent:claude-code/sess-A`, …). | | `include_resolved_tensions` | boolean \| null | — | If `true`, also surfaces the resolved tensions. Default: `false` (cf. T48-S08). | | `max_items_per_section` | integer \| null | — | Upper bound per section. Server default: `10`. Max: `100` (silent clamp on the server side — value observable via `BriefingResponse.since_used`). | | `since` | string \| null | — | Lower temporal window (inclusive). Server default: `now() - 7d`. | ### `noezis_capabilities` Tool discovery by INTENT (ADR-0005): returns the catalog verbs relevant to a natural-language `intent`, ranked by overlap (name + description + use_when), with their input_schema for direct call. Dynamic entry point to the long tail of tools (analogous to ToolSearch) — additive, does not replace tools/list. Pure read. **When to use** — When you don't know which Noezis tool covers your need, or to find an uncommon advanced verb without browsing the whole catalog. | Parameter | Type | Required | Description | |---|---|---|---| | `intent` | string | yes | Natural-language intent (e.g. "audit the contradictions", "explore the entity graph"). Tokenized for the matching. | | `max_results` | integer \| null | — | Max number of tools returned. Default 8, cap 30. | ### `noezis_compare_registers` Compares two knowledge registers and detects the divergences: same concept, contradictory values between the two registers. Pure read — does not modify the graph. Emits a `registers_compared` OpEvent for the audit. Typically used to verify that the ADRs and the documentation stay consistent. **When to use** — To audit the consistency between two registers (e.g.: architectural decisions vs documentation) before a merge or in a periodic audit. | Parameter | Type | Required | Description | |---|---|---|---| | `first_register` | string | yes | Name of the first register to compare (e.g.: `"adr"`). | | `include_resolved` | boolean \| null | — | Include the already-resolved divergences. Default: `false`. | | `max_results` | integer \| null | — | Maximum number of divergences returned. Default: `100`. | | `second_register` | string | yes | Name of the second register to compare (e.g.: `"doc"`). Must be different from the first. | | `severity_threshold` | number \| null | — | Only return the divergences with a severity score greater than or equal to this threshold. Value between `0.0` (include everything) and `1.0` (only the direct conflicts). Default: `0.0`. | ### `noezis_context` SINGLE entry point for retrieving the project context. In one bounded call: store health, state-of-world (recent decisions/tensions + last handoff), search results on the `query`, and agentic skills to apply. The context is normally PUSHED automatically at the start of the turn (UserPromptSubmit hook) — only call this tool yourself if that context was not injected (fallback) or to refresh on a new `query`. Successor of inquire/briefing. **When to use** — As a fallback if the context block was not injected at the start of the turn, or to target a new query. Replaces noezis_inquire + noezis_briefing. | Parameter | Type | Required | Description | |---|---|---|---| | `ablation_exclude` | string \| null | — | **Ablation harness (brick D)** — component(s) to drop from this single response, comma-separated (`decisions,search,skills,handoff`, or the sentinel `off` for the whole envelope). Lets the eval harness sweep every arm against one live daemon. `None`/absent in normal use. OR-merged with the daemon's `NOEZIS_FRONTLOAD_EXCLUDE` env (neither shadows the other). | | `max_tokens` | integer \| null | — | Token ceiling of the envelope. `None` → server default (~1500). | | `query` | string \| null | — | Prompt / topic of the turn. Absent or empty → no search (pure cold-start, only health + state-of-world). Present → search + skills. | | `since` | string \| null | — | Lower bound of the state-of-world window (RFC3339). `None` → full (cold-start). Provided → delta since this date. It's the caller (hook/CLI) that holds the session marker and passes the last call. | ### `noezis_doc_audit` Audits a documentary scope on TWO axes: (1) the tensions ALREADY persisted in the graph (Pass3 contradictions, stale sections) filtered by path/topic; (2) **de novo detection of doc↔code divergences** (`code_divergences` field) — deterministic scan (without LLM) that confronts the symbols claimed by the doctrine (algos/libs/identifiers) with the real code and flags when the doc asserts X "bare" while the code uses a contradictor Y. Pure read — modifies neither the graph nor the files. **When to use** — Before modifying doc, or in an anti-drift audit: see the recorded tensions AND the doc↔code gaps detected on the fly (direct filesystem scan, without prior ingestion). | Parameter | Type | Required | Description | |---|---|---|---| | `max_results` | integer \| null | — | Maximum number of results. Default: 30. | | `min_severity` | number \| null | — | Minimum severity (0.0–1.0). Default: 0.3. | | `scope` | string | yes | Audit scope: file path, directory, or free topic. Use `"*"` for the whole documentary graph. | | `since` | string \| null | — | Only return the tensions after this date (ISO 8601). | ### `noezis_doc_briefing` Briefing focused on the documentation: recent modifications, active tensions, potentially stale sections. Extension of noezis_briefing for the doc-maintenance agents. Pure read. **When to use** — At the start of a doc-maintenance session — to quickly see what moved, what is in tension, and what could be stale. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Filter by actor. | | `include_stale` | boolean \| null | — | If `true`, include the docs not updated for > 30 days. | | `scope` | string \| null | — | Optional scope: path, directory, or topic. | | `since` | string \| null | — | Temporal window (default: 7 days). ISO 8601. | ### `noezis_doctor` Health report of the Noezis server: version, embedder mode, node counters (ready/indexing/failed), latest ingestion failures. Call at the start of a session to diagnose the store's state. **When to use** — To diagnose the server's state, detect nodes stuck in INDEXING, or see the latest documents rejected by validation pipeline. _No parameters._ ### `noezis_entities` Searches named entities in the graph by text/concept. Returns the entities whose name (raw or canonical) or kind contains the query. Sorted by decreasing confidence. **When to use** — To find an entity (person, org, tech, product…) in the graph. Returns the EntityNodes with LID, canonical_name, kind, confidence. | Parameter | Type | Required | Description | |---|---|---|---| | `max_results` | integer \| null | — | Max number of results (default: 20). | | `min_confidence` | number \| null | — | Minimum confidence (default: 0.5). | | `query` | string | yes | Text query (name, alias, concept). | ### `noezis_explain_chain` Explains a chain of relations between entities with active tensions, aggregated confidence and sources: returns the path + the tensions on the chain + the total weighted confidence. Note: relies on the experimental entity-relations layer (de-scoped from retrieval) — reliability depends on entity-extraction quality. **When to use** — After noezis_path_entities to get the full explanation of a path: tensions, sources, confidence. Usage: multi-hop reasoning. | Parameter | Type | Required | Description | |---|---|---|---| | `from_lid` | string | yes | LID of the start entity. | | `include_tensions` | boolean | — | Include the active tensions on the path. Default: true. | | `max_hops` | integer \| null | — | Maximum number of hops (default: 4). | | `to_lid` | string | yes | LID of the end entity. | ### `noezis_gaps_report` Report of what the graph CANNOT answer (KL-1): distinct `no_match` search queries (with count and last occurrence), orphan entities (mentioned in passages but participating in zero typed relation), and Q5 routing misses (native search without noezis_search). Optional filters: since (default now − 14 days), max_misses, max_entities (default 20, cap 50). Pure read — pull-only, never pushed. **When to use** — To decide what to document next: the questions the graph keeps failing to answer and the concepts mentioned everywhere but defined nowhere. The MISS side of the usage telemetry. | Parameter | Type | Required | Description | |---|---|---|---| | `max_entities` | integer \| null | — | Max orphan entities returned. Default 20, cap 50. | | `max_misses` | integer \| null | — | Max distinct miss queries returned. Default 20, cap 50. | | `since` | string \| null | — | Inclusive lower bound on the telemetry events. Default: now − 14 days. | ### `noezis_get_paradigms` Returns all the active paradigms for a (subject, predicate): each paradigm = an active Decision of a distinct actor. Lets you see which actors have different views on the same subject without it being a contradiction — it's paradigm coexistence (T75 V2.5). **When to use** — To inspect the coexisting paradigms on a subject. E.g.: user:alice says auth=OAuth2, agent:claude says auth=JWT → two paradigms, no conflict. | Parameter | Type | Required | Description | |---|---|---|---| | `predicate` | string | yes | Predicate (e.g.: `"uses"`). | | `subject` | string | yes | Subject of the decision (e.g.: `"auth_backend"`). | ### `noezis_graph_report` Structural report of the graph: over-connected topics, communities, entropy ratio, suggested entry points, plus an `entity_health` audit (duplicates, type conflicts, garbage — the entity-layer doctor). Mode `scope: "recent"` (+ `since_hours`) returns only the recent activity — ideal for cold start. Mode `scope: "full"` (default) — full report. **When to use** — At the start of a session (`scope: "recent", since_hours: 24`) to see what changed, or once at startup (`scope: "full"`) to map the whole graph. | Parameter | Type | Required | Description | |---|---|---|---| | `scope` | string \| null | — | Report scope. `"full"` (default) — full graph report. `"recent"` — adds a `recent_activity` section with the OpEvents of the last `since_hours` hours (default 24h). Useful for a session's cold start: check what changed without re-reading the full report. | | `since_hours` | integer \| null | — | Temporal window for the `"recent"` mode (hours, default 24). Ignored if `scope != "recent"`. | ### `noezis_inquire` [DEPRECATED — use noezis_context] Consults the Noezis graph on a topic and returns the context (results, tensions, paradigms). Kept as a transitional alias; will be removed at V-next. Prefer noezis_context (store health + state-of-world + search + skills in one bounded call). **When to use** — Do not use anymore for new code — see noezis_context. Alias maintained for compatibility of the deployed hooks/configs. | Parameter | Type | Required | Description | |---|---|---|---| | `min_score` | number \| null | — | Floor score for the results (default: 0.70). | | `scope` | array \| null | — | Scope-restriction LIDs (optional) — searches only in these nodes and their descendants. | | `suggested_queries` | array \| null | — | Queries suggested by the agent for this topic. | | `topic` | string | yes | Subject of the next answer — used to target the search. | ### `noezis_inquire_skip` Explicitly declares that no graph knowledge is relevant for this answer turn. Audit-grade traceability. To use only for the out-of-graph-scope queries (e.g.: 'what time is it?', pure computation). Never use to avoid a search on a documented subject. **When to use** — When the question has nothing to do with the indexed documents. Provide an explicit reason. | Parameter | Type | Required | Description | |---|---|---|---| | `reason` | string | yes | Explicit reason why the graph is not consulted. | ### `noezis_list_tensions` Lists the graph's tensions with AND filters (since/until, register, status, min_severity). Severity derived from the kind (Direct=1.0, Structural=0.7, Inferential=0.4). Sorted severity DESC, tie-break edge_id lex DESC. Deterministic pagination via max_results (default 50, hard cap 200). Pure read. **When to use** — To audit the active or resolved tensions of a register / a period, or sort by severity the conflicts to handle in priority. | Parameter | Type | Required | Description | |---|---|---|---| | `max_results` | integer \| null | — | Maximum number of tensions returned. Server default: `50`. Hard cap: `200` (silent clamp, consistent T47-B01). `0` → typed error `invalid_max_results`. | | `min_severity` | number \| null | — | Filter by minimum severity, bounded `[0, 1]`. Severity derived from the `kind` (A1 proxy). Default: `0.0` (all severities). `NaN` / `Inf` / out of bounds → typed error `invalid_severity`. | | `register` | string \| null | — | Filter by knowledge register (e.g.: `"adr"`, `"doc"`, `"personal_schedule"`). snake_case format. Unknown register → silent empty list. | | `since` | string \| null | — | Inclusive lower bound on `detected_at`. Default: none. | | `status` | string \| null | — | Filter by resolution state. Values: `"open"`, `"resolved"`, `"all"`. Server default: `"open"` (active snapshot, not the history). Strict case, no CSV tolerance; value outside the enum → typed error `invalid_status`. | | `until` | string \| null | — | Inclusive upper bound on `detected_at`. Default: none. `since > until` → typed error `invalid_range`. | ### `noezis_list_watched` Lists the currently watched folders. Use to audit the watcher's state. **When to use** — To audit the list of folders currently watched by the watcher. _No parameters._ ### `noezis_node_summary` Returns a node's metadata from its identifier. By default, only the short `summary` is exposed (Document/passage); Decisions expose their full triple. Pass `include_content: true` to get the `content` — the FULL TEXT of the Document/passage, including when the source file is gone. **When to use** — To read a node whose LID you have (from noezis_search or a navigation). Add include_content: true for the full text. | Parameter | Type | Required | Description | |---|---|---|---| | `include_content` | boolean | — | If `true`, adds the `content` field to the returned node — the **full text** (Document/passage/UserProfile). Indispensable to re-read an ingested document whose source file is gone. Default `false` to keep responses compact; the Decisions already expose their full triple without this flag. | | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ### `noezis_op` Inspects a single event of the op-mem journal (OpEvent) from its hex 64 LID. Returns the full event: action, actor, target_lid, detailed metadata (BTreeMap), timestamp, content_hash. Typed refusal if the LID points to another kind (`not_an_op_event`). Pure read, no generation. **When to use** — When you have already seen an OpEvent LID in another response (summary, history) and you want the full detail of a specific event. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Hex 64-char LID of the `OpEvent` to inspect. | ### `noezis_op_history` Paginated search in the op-mem journal (OpEvent). Optional AND filters: actor (exact Principal), action (open catalog), target_lid (hex 64), since/until (inclusive-inclusive). Sorted DESC by timestamp, tie-break hex LID DESC. Hard cap 200 events per call (silent clamp). The response exposes `total_matched`, `truncated`, `max_results_used` for the audit. Pure read. **When to use** — To audit the action trace (ingest, decided, tool_invoked) of an agent, or detect MCP catalog usage patterns via `action = 'tool_invoked'`. | Parameter | Type | Required | Description | |---|---|---|---| | `action` | string \| null | — | Exact filter on the `OpAction` string (open catalog, strict snake_case). E.g.: `tool_invoked`, `ingested`, `decided`. | | `actor` | string \| null | — | Exact filter on `Principal::as_str()` (e.g.: `user:alice`, `agent:claude-code/sess-A`). Invalid value → typed error `invalid_actor`. | | `include_metadata` | boolean | — | Include each event's full `metadata` map in the response (audit / failure-classification use cases — e.g. `tool_invoked` carries `success`, `latency_ms`, `outcome_kind`). Default `false` (light summaries). Avoids one `noezis_op` detail call per event. | | `max_results` | integer \| null | — | Maximum number of events returned. Server default: `50`. Hard cap: `200` (silent clamp). `0` → error `invalid_max_results`. | | `session_id` | string \| null | — | Exact filter on the `session_id` injected into the metadata of the `tool_invoked` OpEvents (key `"session_id"`). Format: `"mcp-"`. Obtained via `noezis_briefing` or inspected in a previous OpEvent. Allows reconstructing the complete history of a session without parsing the transcript. | | `since` | string \| null | — | Inclusive lower bound on `timestamp`. Default: none. | | `target_lid` | string \| null | — | Exact filter on the `target_lid` (hex 64). Events with `target_lid = None` are **excluded** when this filter is set. | | `until` | string \| null | — | Inclusive upper bound on `timestamp`. Default: none. `since > until` → error `invalid_range`. | ### `noezis_pending_decisions` Returns the decisions awaiting validation: assertions blocked by conflict detection (`kind: decision_blocked`) and suggested non-asserted decisions (`kind: decision_suggested`). Lets the agent catch the weak signals detected but not committed in session. Pure read, sorted DESC by timestamp. **When to use** — At the start or end of a session to check whether decisions were blocked or remain to be validated. Complement to noezis_briefing. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Optional filter by actor. | | `max_results` | integer \| null | — | Maximum number of results. Default: 50. | ### `noezis_prefs_list` Lists the behavioural preferences stored for this workspace. Preferences are inferred from friction signals and govern how the agent should respond (tone, format, process). Filter by lifecycle: candidate | active | pinned | dormant. **When to use** — To inspect what the workspace has learned about your working style, or before deciding whether to pin/drop a preference. | Parameter | Type | Required | Description | |---|---|---|---| | `lifecycle` | string \| null | — | Filter by lifecycle: `candidate`, `active`, `pinned`, `dormant`. Omit for all lifecycles. | ### `noezis_propose_decision` Dry-run of a Decision: simulates noezis_assert_decision without committing. Returns the potential conflicts (conflict detection) and the coexisting paradigms BEFORE laying the decision. Use to check before asserting, especially if you are unsure whether a contradictory decision exists. **When to use** — Before noezis_assert_decision, to preview the conflicts. Returns would_conflict=true/false without mutating the graph. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string | yes | Proposing actor. | | `predicate` | string | yes | Predicate. | | `rationale` | string | yes | Rationale (mandatory even in dry-run). | | `subject` | string | yes | Subject of the decision to propose. | | `value` | string | yes | Value. | ### `noezis_read_sub_tree` Extraction of a 'semantic bubble' around a topic: searches the topic, then BFS-expands up to a token budget. Returns a complete focused context — ideal to quickly load the context on a concept before reasoning on it. By default each node only exposes its summary; pass include_content: true for the FULL TEXT (re-read a document/handoff by topic without its LID) — then increase max_tokens, the content counts toward the budget. **When to use** — To load a dense context on a subject before reasoning. Provides more context than noezis_search alone. include_content: true to read the full text and not just the summaries. | Parameter | Type | Required | Description | |---|---|---|---| | `include_content` | boolean \| null | — | If `true`, each returned node carries its `content` (full text) instead of just the truncated `summary` — useful to re-read documents by topic without knowing their LID. The `content` counts toward the `max_tokens` budget (increase it accordingly). Default: `false`. | | `max_depth` | integer \| null | — | Max expansion depth. Default: 3. | | `max_tokens` | integer \| null | — | Maximum estimated token budget. Default: 4000. | | `topic` | string | yes | Start topic or LID. | ### `noezis_report` On-demand thematic auto-documentation: assembles a human-readable Markdown report about a topic from what the graph already knows — decisions, knowledge passages, entities and contradictions on that topic. Deterministic (no LLM at read time); regenerable; thematic (unlike the chronological handoffs). Pure read. **When to use** — To produce a readable synthesis of everything Noezis knows about a subject (knowledge-maintenance, briefing a human, onboarding a topic) — not a navigation, a finished document. | Parameter | Type | Required | Description | |---|---|---|---| | `max_chunks` | integer \| null | — | Max knowledge passages to surface. Server default: 15. | | `min_score` | number \| null | — | Floor score on the topic search in `[0, 1]`. Server default: 0.55. | | `polish` | boolean \| null | — | Opt-in narrative polish via the boundary LLM (no-op if none configured; also enabled by `NOEZIS_REPORT_POLISH=1`). Default: deterministic only. | | `topic` | string | yes | Topic to document (free text, semantically searched in the graph). | ### `noezis_review_queue` Signal-driven review queue (KL-2): (1) non-decision knowledge (insight/preference/method/analysis) whose review window has elapsed (existing Pending lifecycle); (2) permanent decisions flagged by RECENT signals — a newer decision asserted on the same subject inside the window, or recurrent no_match searches mentioning the subject. Never age-based (a decision is superseded, not expired). Pure read. **When to use** — To re-validate knowledge: what awaits review and which standing decisions show recent activity suggesting they may be outdated. The front-load shows terse counts; this verb gives the detail. | Parameter | Type | Required | Description | |---|---|---|---| | `max_results` | integer \| null | — | Max flagged decisions returned. Default 10, cap 50. | | `since` | string \| null | — | Inclusive lower bound for the signals. Default: now − 14 days. | ### `noezis_search` Semantic search in the Noezis knowledge graph. Returns 3-5 results with lid, score and summary directly included (`include_text: true` by default — no need for a second call to noezis_node_summary). Set `include_text: false` for a minimal payload. Prefer this tool over any other for documentary questions. **When to use** — To find relevant documents from a natural-language question. Returns the text directly — no extra call needed to read the content. | Parameter | Type | Required | Description | |---|---|---|---| | `community_id` | integer \| null | — | R6 (search-ux) — restrict results to the members of a topic clustering community (id read from `noezis_graph_report`, deterministic per snapshot). Applies to the SEMANTIC leg only. `None` → no restriction. | | `explain` | boolean | — | Include `matched_on` in each result — indicates on which surface the node was selected (`"semantic"` for tree navigation nodes, `"metadata"` for non-geometric V2 nodes). Default: `false`. Useful to diagnose why a result appeared. | | `include_text` | boolean | — | Include the text summary (`summary`) in each result. Default: `true` — avoids a second call to `noezis_node_summary`. Set to `false` if only the LID is needed (minimal payload). | | `max_hops` | integer \| null | — | Maximum tree navigation depth (server default: 3-4 depending on config). | | `max_results` | integer \| null | — | Maximum number of nodes returned (post-tree navigation truncation). | | `min_score` | number \| null | — | Floor score (inclusive) applied after tree navigation — `f32` in `[0, 1]`. Enables adaptive exploration: broad with `0.3`, targeted with `0.85`. | | `mode` | string \| null | — | Search leg(s): `"semantic"` (default — tree navigation on embeddings), `"lexical"` (BM25 on the passages + decisions text — exact tokens, symbols, identifiers; does not touch the embedder), or `"hybrid"` (both in parallel — sections by signal + `corroborated` by vote, never a combined score). Raw BM25 scores, incommensurable with the cosine scores (decision `lexical_index_b_fusion_arbitration`). | | `path_prefix` | string \| null | — | R5 (search-ux) — restrict results to nodes whose provenance document's `source_path` starts with this prefix (e.g. `"DOCS/"`, `"crates/noezis-mcp"`). Applies to the SEMANTIC leg only — the lexical leg is unaffected. `None` → no restriction. | | `query` | string | yes | Natural-language question — re-encoded on the server side, never returned as-is. | | `scope` | object | — | Scope. Default: `both` (local + cloud in dual-track). | | `simulations` | integer \| null | — | Number of tree navigation simulations (server default: ~100). | | `timeout_ms` | integer \| null | — | Timeout in milliseconds for the full tree navigation call. If exceeded, returns a JSON-RPC error `kind: "timeout"`. Default: no timeout (usual behavior). Recommended: 5000 ms for the agents with a real-time constraint. | ### `noezis_since` Event cursor: everything that changed since an instant T — finished async jobs (ingest/recluster, done/failed), asserted decisions (including by other agents), detected tensions. Returns new_cursor to re-pass on the next call. Pure read, bounded. **When to use** — At the start of a turn to catch up on what happened since the previous turn (job launched async, decision by another agent), without polling verb by verb. | Parameter | Type | Required | Description | |---|---|---|---| | `max_items` | integer \| null | — | Item ceiling per section. Server default: 20, cap 100. | | `since` | string | yes | RFC 3339 cursor (typically the `new_cursor` of the previous call). | ### `noezis_status` Store indexation status: percentage of ready nodes, counters by state (ready/pending/indexing/failed), breakdown by node type, embedder mode. Call at the start of a session to check whether the corpus is well indexed before running searches. **When to use** — Before a search, to check that documents are indexed (indexation_pct > 0). Distinct from noezis_doctor (health/errors). With job_id: tracks an async ingestion job. | Parameter | Type | Required | Description | |---|---|---|---| | `job_id` | string \| null | — | R-MCP-07 — identifier of an async job (obtained via `noezis_ingest(async: true)` or `noezis_recluster(async: true)`). If provided, the call targets this job. | ### `noezis_task_list` Lists Task nodes in the work ledger, optionally filtered by scope and/or status (open, claimed, in_progress, done, blocked). **When to use** — To see pending or active tasks in a given workspace. Also surfaced automatically via open_tasks in the front-load context. | Parameter | Type | Required | Description | |---|---|---|---| | `scope` | string \| null | — | Filter by scope (exact match). Omit for all scopes. | | `status` | string \| null | — | Filter by status (`open`, `claimed`, `in_progress`, `done`, `blocked`). | ### `noezis_tools_summary` Aggregates the MCP catalog usage: for each tool, from the `tool_invoked` OpEvents, computes invocation_count, latency_p50_ms, latency_p99_ms, success_rate and last_invoked_at. Optional filters: since/until (timestamp), session_id. Sorted by count DESC (tie-break name). Hard cap 200 tools (clamp). Pure read — no mutation. **When to use** — To audit which tools are actually used, how often, with which latencies/success rates — detect the little-adopted or slow tools. Aggregated complement of `noezis_op_history(action='tool_invoked')`. | Parameter | Type | Required | Description | |---|---|---|---| | `max_results` | integer \| null | — | Max number of distinct tools returned. Default 50, cap 200, `0` → error. | | `session_id` | string \| null | — | Exact filter on the `session_id` of the `tool_invoked` OpEvents. | | `since` | string \| null | — | Inclusive lower bound on `timestamp`. Default: none. | | `until` | string \| null | — | Inclusive upper bound on `timestamp`. `since > until` → `invalid_range`. | ### `noezis_triplets` Returns all SPO triplets (Subject-Predicate-Object) in the graph. Optional filters: predicate label (e.g. "uses"), subject/object name substring, minimum confidence. Sorted by decreasing confidence. **When to use** — To query all relations of a given type across the graph (e.g. all 'uses' relations, all relations touching a given tech). Complement to noezis_relations (per-entity) with global scope. | Parameter | Type | Required | Description | |---|---|---|---| | `limit` | integer \| null | — | Maximum number of results (default: 100). | | `min_confidence` | number \| null | — | Minimum confidence per triplet (default: 0.0). | | `object_query` | string \| null | — | Substring match on the object entity name (optional). | | `predicate` | string \| null | — | Filter by predicate label, e.g. `"uses"`, `"owned_by"` (case-insensitive, optional). | | `subject_query` | string \| null | — | Substring match on the subject entity name (optional). | ## Navigation — graph traversal ### `noezis_chains` All N-hop chains from an entity. Optional predicate filter. Depth filtering mandatory for depth > 2 (combinatorial explosion guard). **When to use** — To explore all the N-hop connections from an entity, with or without a predicate filter. | Parameter | Type | Required | Description | |---|---|---|---| | `depth` | integer \| null | — | Maximum depth (default: 2, max: 4). | | `lid` | string | yes | LID of the start entity. Accepts `entity_lid` as an alias (same agent-guess tolerance as `noezis_relations`). | | `max_chains` | integer \| null | — | Max number of chains (default: 20). | | `min_confidence` | number \| null | — | Minimum confidence per edge (default: 0.4). | | `predicate_filter` | integer \| null | — | Filter by predicate_id. Mandatory if depth > 2. | ### `noezis_children` Lists ALL the structural children of a node (exhaustive, not sampled). Use when you want to explore the full decomposition of a document or aggregate. **When to use** — To go one level down in the hierarchy from a known LID. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ### `noezis_community` All members of the topic clustering community containing the node. Use for an exhaustive panorama of a detected theme. **When to use** — To get an exhaustive panorama of a thematic zone of the graph. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ### `noezis_entity_neighbors` Returns the 1-hop neighboring entities via the typed relations. For each neighbor: the entity + the relation (predicate, confidence). Use after noezis_entities to explore the relations graph. **When to use** — To explore the entities directly linked to a known entity. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ### `noezis_explore_tree` Unified topological navigation: returns in one call the parent, the structural children, and the siblings (topic clustering neighbors) of a node. Replaces 2-3 separate calls (noezis_parent + noezis_children + noezis_siblings). Ideal to quickly explore the neighborhood of a known LID. **When to use** — To explore the immediate neighborhood of a known node in a single call. More efficient than 3 separate parent/children/siblings calls. | Parameter | Type | Required | Description | |---|---|---|---| | `depth` | integer \| null | — | Maximum depth (1 = parent + children + immediate siblings). Default: 1. Max: 3. | | `include_siblings` | boolean | — | Include the node's siblings (topic clustering neighbors). Default: true. | | `lid` | string | yes | Root LID of the exploration. | ### `noezis_parent` Returns the direct structural parent of a node, or null for a root. Use to go up the hierarchy one level at a time. **When to use** — To go up one level and get the enclosing context of a node. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ### `noezis_path_between` A* path between two LIDs in the graph. Returns null if disconnected or max_hops reached. Use to explain how two documents are linked. **When to use** — To explain how two nodes (known LIDs) are linked in the graph. | Parameter | Type | Required | Description | |---|---|---|---| | `from_lid` | string | yes | LID of the start node (64 hex characters) — obtained via `noezis_search` or a navigation tool. | | `max_hops` | integer \| null | — | Maximum number of hops allowed. Recommended server default. | | `to_lid` | string | yes | LID of the end node (64 hex characters) — obtained via `noezis_search` or a navigation tool. | ### `noezis_path_entities` A* path between two entities in the relations graph. Returns the shortest relation path (by weighted confidence). Note: the entity-relations layer is experimental and de-scoped from retrieval — result reliability depends on entity-extraction quality on your corpus. **When to use** — To find how two entities are connected. E.g.: TechCorp → uses → Neo4j → has_flaw → CVE-XYZ. | Parameter | Type | Required | Description | |---|---|---|---| | `from_lid` | string | yes | LID of the start entity. | | `max_hops` | integer \| null | — | Maximum number of hops (default: 4). | | `min_confidence` | number \| null | — | Minimum confidence per edge (default: 0.3). | | `predicate_filter` | integer \| null | — | Filter by predicate_id (u64, optional). | | `to_lid` | string | yes | LID of the end entity. | ### `noezis_relations` Returns an entity's typed relations — outgoing, incoming, or bidirectional. Optional filter by predicate_id. **When to use** — To see all of an entity's relations (who uses it, what it is linked to, what it affects). | Parameter | Type | Required | Description | |---|---|---|---| | `direction` | string \| null | — | Direction: `"outgoing"`, `"incoming"`, or `"both"`. Default: `"both"`. | | `lid` | string | yes | LID of the entity. Accepts `entity_lid` as an alias — measured 2026-06-09: agents naturally guess `entity_lid` for an entity verb (2 of the 3 noezis_relations failures were exactly that). | | `predicate_id` | integer \| null | — | Filter by predicate_id (u64, optional). | ### `noezis_siblings` Neighbors of the node in its topic clustering community (semantic proximity). Use to discover thematically close documents without re-running a search. **When to use** — To discover a node's immediate thematic neighbors (without a new search). | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | Unique node identifier (64 hex characters). Obtained via `noezis_search`, `noezis_children`, `noezis_parent`, or any other navigation tool that returns a `lid` field. | ## Write — mutations ### `noezis_assert_decision` Records a durable decision (ADR) in the graph. Blocks and returns a conflict if a contradictory decision already exists on the same subject — the agent must decide before continuing. Idempotent: re-asserting an identical decision returns `kind: "duplicate"`. **When to use** — To trace a durable architectural decision. Reserved for structuring choices that must be remembered across sessions. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Actor identifier — validated via `Principal::new`. If absent, default = MCP session principal (`agent:mcp/`) — reduces friction ("missing actor" failures measured via `noezis_tools_summary`). | | `kind` | string \| null | — | Semantic kind of this node. - `"decision"` (default) — strict conflict detection block, permanent ADR. - `"insight"` — technical analysis; conflict detection warn-only, reviewed after 2 sessions. - `"preference"` — workspace/user working preference; reviewed after 3 sessions. - `"method"` — validated approach or workflow; reviewed after 4 sessions. - `"analysis"` — exploratory design (no conflict detection); reviewed after 2 sessions. Non-decision kinds enter a `Pending` review lifecycle and are surfaced by `session-review` for confirmation or purge. | | `predicate` | string | yes | Predicate (e.g.: `"uses"`). Non-empty, ≤ 128 characters. | | `rationale` | string | yes | Explicit rationale — never auto-generated (T39 anti-pattern). Non-empty after trim, ≤ 65536 characters. | | `review_after_sessions` | integer \| null | — | Override the default review window (sessions). `None` = use kind default. | | `subject` | string | yes | Subject of the decision (e.g.: `"auth_backend"`). Non-empty, ≤ 256 characters. | | `value` | string | yes | Value (e.g.: `"OAuth2"`). Non-empty, ≤ 4096 characters. | ### `noezis_capture_decision` Normalizes a statement into a triple (subject, predicate, value) and asserts it directly. Two modes: (1) arrow — `statement = 'store_backend → surrealdb'`; (2) explicit — provide `subject` + `value` (the statement serves as rationale). `dry_run: true` returns the normalized triple without commit. Non-blocking on contradiction: returns `kind: "blocked"` with the conflicting LID. Idempotent. **When to use** — When the agent wants to capture a decision from a natural-language sentence or an arrow format, without manually building the SPV triple. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Actor identifier. If absent, default = MCP session principal (`agent:mcp/`) — reduces friction ("missing actor" failures measured via `noezis_tools_summary`). | | `dry_run` | boolean | — | `true` → returns the normalized triple without asserting it. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 (generalized, redesign 2026-06-06) — idempotency key: a retry after timeout replays the cached result (the underlying assert is already deduplicated by the conflict detection pre-check, but the replay avoids a misleading `duplicate`). | | `predicate` | string \| null | — | Predicate. Default: `"is"`. | | `rationale` | string \| null | — | Explicit rationale. If absent, `statement` is used. | | `statement` | string | yes | Natural-language text or `"subject → value"`. Serves as rationale if `subject` and `value` are provided explicitly. | | `subject` | string \| null | — | Explicit subject (snake_case). If absent, extracted from the `statement`. | | `value` | string \| null | — | Explicit value. If absent, extracted from the `statement`. | ### `noezis_codify_corpus` Applies the batch codification on a set of already-indexed documents (without re-ingesting them). Three perimeters: explicit list, thematic community, or documents ingested since a date. Use `dry_run: true` to simulate without modifying the graph. **When to use** — After adding or modifying a knowledge register, to update the codifications on the existing documents. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Optional `Principal` — MCP default `agent:mcp-anonymous`. | | `dry_run` | boolean \| null | — | If `true`, pure simulation (no mutation, no OpEvent). Server default: `false`. | | `force_recodify` | boolean \| null | — | If `true`, overwrites the existing codifications for `(chunk_source, register, slot)` and cascade-purges the linked Tensions (INV_N11 preserved). Server default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `max_documents` | integer \| null | — | Server ceiling (default 1000, hard cap 10000, `0` rejected as `invalid_max_documents`). | | `scope` | object | yes | Codification perimeter — `oneOf` with 3 tagged variants (`kind = "documents" | "community" | "since"`). | | `timeout_ms` | integer \| null | — | Timeout in milliseconds for this operation (can be long on a large corpus). Default: no timeout. Recommended: 30000 ms for corpora > 500 documents. | ### `noezis_consolidate_knowledge` Merges or links nodes identified as similar/redundant. 'merge' strategy: creates a new aggregated node with the merged summary. 'link' strategy: lays Inferred edges between the nodes (less destructive). Emits an OpEvent for traceability. Use sparingly. **When to use** — After detecting duplicated or overly fragmented nodes. Prefer 'link' if unsure — 'merge' is irreversible. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Actor. Default: `agent:mcp-anonymous`. | | `dry_run` | boolean | — | R-MCP-04 — `true` → preview `{ dry_run: true, would_affect, affected_lids }` without consolidating nor emitting an OpEvent. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `lids` | array | yes | LIDs of the nodes to consolidate. | | `rationale` | string | yes | Justification of the consolidation. | | `strategy` | string | yes | Strategy: `"merge"` (summary fusion) or `"link"` (Inferred edge). | ### `noezis_doc_update` Updates a section or a documentation file on disk, re-ingests the file into the graph, and emits a `doc_updated` OpEvent for traceability. Can target a specific H2/H3 section or the whole file. Composed: write + ingest + OpEvent in a single atomic operation. **When to use** — To update a doc file (.md, .rs, etc.) and trace why this change was made. Use before proposing a direct edit so the graph stays in sync with the repo. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Actor. Default: `agent:noezis`. | | `content` | string | yes | New Markdown content for the section (or the whole file). | | `dry_run` | boolean | — | R-MCP-04 — `true` → preview `{ dry_run: true, would_affect }` without writing the file, re-ingesting nor emitting an OpEvent. Default: `false`. | | `evidence_lids` | array \| null | — | LIDs of the nodes that justify this change (optional). | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `path` | string | yes | Absolute path of the file to modify. | | `rationale` | string | yes | Justification of the modification — why this change. | | `section` | string \| null | — | Title of the H2/H3 section to replace. `null` = replace the whole file. | ### `noezis_ingest` Ingests a document into the graph. Source: exactly ONE of the fields `text`, `path` or `url`. The deterministic validation pipeline pipeline validates 5/5 or rolls back. Use to memorize a text, a local file or (V2) a URL. **When to use** — To add a new document (text or local file) to the graph, after checking for absence. | Parameter | Type | Required | Description | |---|---|---|---| | `async` | boolean | — | R-MCP-07 — launches the ingestion in a background task and returns immediately `{ job_id, status: "indexing" }`. Track via `noezis_status(job_id)`. **Default: `true`** (ingestion is heavy — Pass3 + SLM relations — and must not hold the JSON-RPC connection; decision `ingest_async_default_mcp`). Pass `async: false` for a synchronous commit that directly returns the LID + the outcome. | | `dry_run` | boolean | — | R-MCP-04 — `true` → does not mutate the store: returns a preview `{ dry_run: true, would_affect, estimated }` (size, source). No OpEvent emitted. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key. If provided and already seen, the cached result is replayed (`idempotent_replay: true`) without re-ingesting. Complements the deduplication by content hash. | | `path` | string \| null | — | Path on the local filesystem. | | `summary` | string \| null | — | Explicit summary — otherwise generated by the pipeline. | | `text` | string \| null | — | Raw UTF-8 text. | | `url` | string \| null | — | HTTP(S) URL — reserved for V2, currently triggers an `Unsupported` error. | ### `noezis_ingest_batch` Ingests up to 50 documents in a single MCP call. Each item is identical to an individual `noezis_ingest` call (text or path). The items are processed in parallel on the server side. Indispensable to bootstrap a corpus without multiplying round-trips. **When to use** — To ingest N texts or files in a single tool call. Use when you have a list of documents to index (N > 1). | Parameter | Type | Required | Description | |---|---|---|---| | `idempotency_key` | string \| null | — | R-MCP-12 (generalized, redesign 2026-06-06) — idempotency key at the whole-batch level: if already seen, replays the cached result without re-ingesting any item. Complements the dedup by content hash. | | `items` | array | yes | List of items to ingest. Each item must provide exactly one of the fields `text` or `path`. Maximum 50 items per call. | ### `noezis_prefs_drop` Drops a preference (moves it to Dormant). The preference is preserved for audit but is no longer injected at front-load. **When to use** — When the user wants to remove a preference that was inferred incorrectly. | Parameter | Type | Required | Description | |---|---|---|---| | `pref_id` | string | yes | Full hex LID of the preference to drop. | ### `noezis_prefs_pin` Pins a preference — prevents the autonomous loop from reverting it to Dormant. Use for preferences you explicitly want to lock in. **When to use** — When the user explicitly wants to lock in a preference that was promoted automatically. | Parameter | Type | Required | Description | |---|---|---|---| | `pref_id` | string | yes | Full hex LID of the preference to pin. | ### `noezis_purge_node` PERMANENTLY deletes a node from the graph by its LID (+ its child passages if it is a Document; the edges are cascaded). Emits a `purged` OpEvent. Refuses the protected founding documents (CLAUDE.md, CONTEXT.md, ROADMAP.md, etc.). Usage: clean up a test pollution or an erroneous node. Irreversible — no dry-run. **When to use** — To remove a parasitic node (test transcript, erroneous doc) without re-indexing the whole store or stopping the daemon. | Parameter | Type | Required | Description | |---|---|---|---| | `idempotency_key` | string \| null | — | R-MCP-12 (generalized, redesign 2026-06-06) — idempotency key: a retry after timeout replays the cached result instead of failing as `unknown_lid` on an already-purged node. | | `lid` | string | yes | Hex LID (64 chars) of the node to delete. If it is a Document, its structural child passages are deleted too (edge cascade included). | ### `noezis_recluster` Rebuilds the store's hierarchical tree: clusters all the Ready passages by topic clustering and materializes multi-level AggregateNodes (topic centers = mean of the children), with inter-aggregate Proximity edges and community summaries (SLM naming if the model is present, otherwise a deterministic label). GLOBAL and idempotent pass: first purges the aggregates of the previous run. Costly — to launch after a large ingestion, not on each addition. ASYNC by default: returns { job_id, status } immediately; track via noezis_status({ job_id }). **When to use** — After a substantial ingestion, to (re)build the hierarchical navigation tree over the whole store. | Parameter | Type | Required | Description | |---|---|---|---| | `async` | boolean | — | R-MCP-07 (generalized, redesign 2026-06-06) — launches the recluster in a background task and returns immediately `{ job_id, status: "indexing" }`. Track via `noezis_status(job_id)`. **Default: `true`** — recluster is the longest verb of the catalog (full topic clustering + network SLM naming) and exceeds the MCP client timeouts on a large store. Pass `async: false` for a synchronous call that directly returns the counters (`aggregates_created`, `levels`, …). | ### `noezis_resolve_tension` Resolves a detected tension (EdgeKind::Tension) with a mandatory rationale and a canonical resolution code: accepted_a | accepted_b | merged | deferred | invalidated. Mutates the resolution None → Some(_) and emits an idempotent TENSION_RESOLVED OpEvent. Idempotent: a second call with an identical (tension_lid, resolution_code) returns `kind: "already_resolved"` without a new OpEvent. If the tension is already resolved with another code → `kind: "conflicting_resolution"` (JSON-RPC success, typed business refusal). Typed errors in INVALID_PARAMS: invalid_lid, unknown_tension, not_a_tension, invalid_resolution_code, empty_rationale, invalid_actor. **When to use** — To close an active tension after human review — typically after listing the tensions via noezis_list_tensions. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Principal identifier. Default `agent:mcp-anonymous` if omitted. | | `dry_run` | boolean | — | R-MCP-04 — `true` → preview `{ dry_run: true, would_affect }` without mutating the tension's resolution nor emitting an OpEvent. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `rationale` | string | yes | Human justification — never auto-generated. | | `resolution_code` | string | yes | Resolution code (closed catalog, strict case). | | `tension_lid` | string | yes | Hex (64) LID of the tension to resolve. | ### `noezis_retract_decision` Retracts a decision: sets it to the reversible Retracted state with a mandatory reason, withdrawing it from every live surface (front-load, search, review queue, contradiction audit). Unlike supersede, no replacement is needed. The audit is preserved (the node survives until `store gc`); the retracted key no longer blocks a fresh assertion. Idempotent on an already-retracted decision. **When to use** — To cancel a mistaken or obsolete ADR that has NO replacement (wrong repo/subject, abandoned choice). If a newer decision replaces it, use noezis_supersede instead. Always provide an explicit reason (never auto-generated). | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string | yes | Who performs this action. Format: `user:alice` or `agent:claude-code/session-xyz`. | | `decision_lid` | string | yes | LID of the decision to retract. Obtained via `noezis_search`, `noezis_briefing` or the front-load. The decision is set to the reversible `Retracted` state and withdrawn from every live surface; it no longer blocks a fresh assertion on its `(subject, predicate)`. | | `dry_run` | boolean | — | R-MCP-04 — `true` → preview without changing the decision's state nor emitting an OpEvent. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `reason` | string | yes | Why this decision is retracted — never generated automatically, always written by the human or the responsible agent. Mandatory (audit). | ### `noezis_subscribe_node` Subscribes to the STALE/UPDATED events of a LID. The server will then emit `notifications/noezis/stale` JSON-RPC notifications. Use to stay notified that an indexed document changed. **When to use** — To be notified when a given node becomes stale or is updated. | Parameter | Type | Required | Description | |---|---|---|---| | `lid` | string | yes | LID to watch (hex 64). | ### `noezis_supersede` Marks a decision as superseded (replaced) by another. Creates the deprecation link and traces the event in the journal. Idempotent. Refuses if the decision to deprecate is already replaced by a third one — then returns the conflict for arbitration. **When to use** — To retract an existing ADR in favor of a more recent decision. Always provide an explicit justification (never auto-generated). | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string | yes | Who performs this action. Format: `user:alice` or `agent:claude-code/session-xyz`. | | `deprecated_decision_lid` | string | yes | LID of the decision to deprecate (the old one). Obtained via `noezis_search` or `noezis_briefing`. | | `dry_run` | boolean | — | R-MCP-04 — `true` → preview `{ dry_run: true, would_create, affected_lids }` without laying the `SUPERSEDED_BY` link nor emitting an OpEvent. Default: `false`. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `rationale` | string | yes | Why this decision replaces the old one — never generated automatically, always written by the human or the responsible agent. | | `replacement_decision_lid` | string | yes | LID of the decision that replaces it (the new one). Must exist in the graph and be different from `deprecated_decision_lid`. | ### `noezis_task_claim` Atomically claims an open Task (compare-and-set). Sets status to 'claimed' and records holder + optional TTL. Returns claimed=false if the task was already taken. **When to use** — Before starting work on a task, to prevent two agents from working on the same item concurrently. | Parameter | Type | Required | Description | |---|---|---|---| | `actor` | string \| null | — | Actor claiming the task. Defaults to "agent". | | `task_id` | string | yes | Full hex LID of the task to claim. | | `ttl_sec` | integer \| null | — | Lease duration in seconds (default 3600). | ### `noezis_task_create` Creates a new Task node in the shared work ledger (A2). Tasks represent units of work shared across sessions and agents. Scope = logical workspace (e.g. repo name, branch, or session id). **When to use** — To record a new task or work item that spans sessions or needs to be picked up by another agent. | Parameter | Type | Required | Description | |---|---|---|---| | `notes` | string \| null | — | Optional free-form notes. | | `scope` | string | yes | Logical scope — e.g. branch name, feature area, session id. | | `title` | string | yes | Short title (≤ 160 chars). | ### `noezis_task_update` Updates the status (and optionally notes) of a Task. Valid transitions: open → claimed → in_progress → done | blocked. **When to use** — To mark a task as in_progress, done, or blocked after claiming it. | Parameter | Type | Required | Description | |---|---|---|---| | `notes` | string \| null | — | Optional notes to append. | | `status` | string | yes | New status: `in_progress`, `done`, `blocked`, or `open` (unclaim). | | `task_id` | string | yes | Full hex LID of the task to update. | ### `noezis_watch_folder` Main entry point to initialize or sync a repo. Call with the repo's root path to (1) immediately ingest all the existing files in a batch and (2) watch for future modifications via incremental SUPERSEDED_BY re-ingestion. This is the first call to make in a not-yet-indexed repo — a single call suffices, no need to ingest the files one by one. ASYNC by default: returns { job_id, status } immediately; track via noezis_status({ job_id }). **When to use** — To initialize a repo's index (first call) or resynchronize after an interruption. Prefer this tool over noezis_ingest repeated on each file. | Parameter | Type | Required | Description | |---|---|---|---| | `async` | boolean | — | R-MCP-07 — `true` → the folder's initial ingest runs in a background task; returns immediately `{ job_id, status: "indexing" }`. **Default: `true`** (aligned on ingest/recluster, redesign 2026-06-06: the initial ingest of a folder is by construction heavier than a single ingest). Pass `async: false` for a synchronous call. | | `idempotency_key` | string \| null | — | R-MCP-12 — explicit idempotency key (replays the cached result). | | `path` | string | yes | Absolute path of a folder (recursive). | --- # file: explanation/contradictions.md # Contradictions : une détection stable, sans spéculation > Explanation — objectif : comprendre pourquoi Noezis détecte de façon fiable les > contradictions **explicites** et **ne spécule pas** sur les liens profonds. Un choix > de stabilité et de confiance, pas une limite subie. Noezis est un système **stable** : il signale ce qui se contredit **explicitement**, de façon reproductible, et il **n'invente pas** de liens profonds qui demanderaient de deviner. Résultat : ce qu'il signale sur les **décisions** est fiable, et il ne fabrique **aucune** alerte tirée d'un raisonnement hasardeux. (Sur la **prose**, c'est un radar qui sur-signale, à trier — voir plus bas.)
Stable par conception : signale l'explicite, ne spécule pas sur le profond✓ CONTRADICTION EXPLICITEtélétravail = 2 j/semremote = 3 j/semmême règle (alias FR/EN) · valeurs ≠⚡ CONTRADICTIONsignalée · l'agent est prévenuValeurs opposées sur la même règle → alerte fiable, reproductible.✗ LIEN PROFOND — NON SPÉCULÉcible = zéro carbone 2030flotte = 100% diesel?pas de spéculation → zéro fausse alerteRelier les deux exige de deviner (diesel → CO2) : Noezis ne spécule pas.
À gauche : valeurs opposées sur la même règle (synonymes unifiés) → alerte fiable. À droite : un lien qui exigerait de deviner — non spéculé.
## Ce qu'il détecte de façon fiable : les décisions structurées Une **décision** dans Noezis est un fait structuré : un *sujet*, un *prédicat*, une *valeur* (par exemple « politique de télétravail → est → 2 jours par semaine »). Quand vous posez une nouvelle décision sur un sujet déjà tranché avec une **valeur différente**, Noezis le voit par **comparaison exacte** et **bloque** : impossible d'avoir deux vérités opposées sur le même point sans s'en rendre compte. C'est fiable parce que c'est **déterministe** : on compare des champs structurés, pas du texte libre. Pas d'interprétation, pas de hasard. C'est le niveau sur lequel vous pouvez vous appuyer. **Plus fin qu'un simple « vrai/faux ».** La détection tient compte de **qui** a décidé. Deux valeurs opposées sur le même sujet **par le même auteur** = un vrai conflit, bloqué. Les mêmes valeurs opposées **par des auteurs différents** = deux *paradigmes* qui coexistent légitimement — signalés comme tels, pas écrasés en une fausse vérité unique. Le désaccord et le temps (versions remplacées) sont donc de première classe, pas juste un booléen. En pratique : posez une décision sur les sujets qui comptent (`noezis_assert_decision`). Là, la détection est nette. Pour remplacer une décision dépassée, `noezis_supersede`. ## Le prérequis : une nomenclature cohérente — et Noezis y veille La comparaison étant **littérale**, deux décisions ne se contredisent que si elles parlent du **même sujet, écrit de la même façon**. Pour que ça marche sans discipline manuelle, Noezis agit à deux niveaux : - **Des skills poussés à l'agent.** Au moment où un agent enregistre une décision, Noezis lui surface une consigne de **format** : nommer le sujet de façon canonique (un concept, une clé). L'agent garde une nomenclature cohérente sans y penser, d'une session à l'autre. - **Un glossaire d'alias.** Les synonymes connus (« télétravail », « remote », « travail à distance »…) sont ramenés à une **forme canonique unique** avant la comparaison. Une contradiction reste donc détectée même si deux personnes l'ont formulée différemment. Résultat : la mémoire respecte une **nomenclature consistante dans la durée**, et la détection ne se fait pas piéger par un simple écart de vocabulaire. ## Ce qu'il signale comme un radar : les documents Pour la **prose** (vos documents), Noezis lève une alerte quand un texte **touche un sujet déjà décidé**. C'est un **radar, pas un juge** : - Il **n'en rate quasiment aucune** : si une vraie contradiction existe sur un sujet suivi, elle remonte. - Mais il **sur-signale** : il alerte aussi quand un document ne fait que *confirmer* ou *mentionner* le sujet, sans le contredire. En pratique, une alerte sur deux à trois est une vraie contradiction — les autres sont du bruit à écarter. Ce choix est assumé : mieux vaut une alerte de trop qu'une contradiction qui passe inaperçue. **C'est à un humain (ou à l'agent) de trancher**, pas au radar. Les alertes se traitent via la file de revue (`noezis_review_queue`). ## Ce qu'il ne détecte PAS Pour ne pas vous tromper, voici les angles morts réels : - **Les contradictions sans vocabulaire commun.** Deux phrases qui se contredisent par le *sens* mais ne partagent aucun mot-clé peuvent passer sous le radar. Il faut un minimum de recoupement de termes. - **Ce qui demande du raisonnement ou des connaissances extérieures.** « Le serveur est en Europe » vs « les données sont hébergées aux États-Unis » se contredisent *si* l'on sait que serveur et données vont ensemble — Noezis ne fait pas ce raisonnement. - **Les termes vraiment inédits.** Les synonymes connus sont ramenés à une clé canonique (cf. *nomenclature cohérente* plus haut), mais un terme **jamais vu ni aliasé** peut encore échapper à la comparaison tant qu'il n'est pas rattaché au bon sujet. - **Les contradictions entre entités** (« X dépend de Y » vs « X ne dépend pas de Y »), ainsi que les contradictions *orientées* sensibles à l'ordre (« Jean a tué Paul » ≠ « Paul a tué Jean »), relèvent du graphe de relations entité↔entité. Ce mécanisme est conçu mais **pas un acquis fiable aujourd'hui** (couche d'extraction d'entités encore trop fragile) — on ne s'appuie pas dessus. ## Pourquoi c'est conçu ainsi La recherche et la détection de Noezis sont **déterministes** : aucun modèle de langage dans la boucle. On y gagne la **reproductibilité** (même base, mêmes alertes, vérifiables) au prix d'une compréhension fine du sens. Le parti pris : être **exact là où c'est structuré** (les décisions), et **honnêtement approximatif là où c'est du texte libre** (un radar à trier), plutôt que de prétendre tout comprendre. ## Aller plus loin - Décision vs document → [Décision ≠ document](registre-vs-prose.md) - Le cycle de vie d'une information → [Le cycle de vie d'une information](knowledge-lifecycle.md) --- # file: explanation/knowledge-lifecycle.md # Le cycle de vie d'une information > Explanation — objectif : comprendre pourquoi une information n'est pas un fichier figé > mais une connaissance qui évolue, et comment Noezis suit ce mouvement. Dans une équipe, une information n'apparaît pas déjà vraie et gravée dans le marbre. Elle **naît, se confirme, est parfois contestée, puis finit remplacée**. Les outils classiques rangent un instantané ; Noezis suit le mouvement. ## Les quatre temps 1. **En discussion** — l'info émerge, incertaine, débattue. Dans Noezis, c'est une connaissance capturée mais pas encore figée en décision : elle attend confirmation. 2. **Actée** — une décision tranche. L'information devient une vérité de référence, avec son auteur, sa date et sa justification. 3. **Contestée** — plus tard, une autre source la remet en cause. Noezis le **signale** au lieu de laisser les deux versions cohabiter en silence. 4. **Périmée** — une version plus fraîche la remplace. L'ancienne ne ressort plus dans les réponses, mais **n'est pas effacée**. ## Le drift : le problème que ça résout Dans une base de données figée, la connaissance **dérive en silence** : une décision change, une règle évolue, et la structure ne le capte pas. Il faut alors des humains pour corriger en continu la désynchronisation à la main — certains secteurs y consacrent des postes entiers, les autres vivent avec une incohérence chronique. Noezis capture ce drift — décision remplacée, document qui ne colle plus, source contredite — et le **remonte activement**, au lieu de le laisser pourrir. ## Rien n'est effacé : vous remontez le fil Chaque état est conservé et chaîné dans le temps. Vous pouvez **retracer l'histoire d'une décision** : ce qu'elle disait avant, ce qui l'a remplacée, et quand. C'est ce qui rend la base **auditable** — précieux dès qu'une réponse fausse coûte cher. ## Deux espaces, une vérité Noezis n'indexe pas que des documents statiques : il indexe **aussi les décisions**, et met les deux en perspective. Un document *affirme* ; une décision *fait autorité*. Si un document contredit une décision, c'est le document qui a tort — et c'est signalé. ## Aller plus loin - Décision vs document → [Décision ≠ document](registre-vs-prose.md) - Ce que la détection de contradictions sait (et ne sait pas) faire → [Contradictions](contradictions.md) - La proprioception de l'agent → [La proprioception de l'agent](proprioception.md) --- # file: explanation/proprioception.md # La proprioception de l'agent > Explanation — la thèse de fond de Noezis : remplacer le contexte *statique* collé > dans le prompt par une mémoire *vivante* dont l'agent connaît l'état. ## Le mal : le contexte statique Un agent IA repart de zéro à chaque session. On lui colle un paquet de documents dans le prompt, figé et aveugle. Deux pathologies en découlent : - **hallucination** — il invente ce qu'il ne sait pas ; - **cécité au changement** — il ne voit pas que le monde a bougé (une décision périmée, un document contredit, un fichier déplacé). ## Le remède : une mémoire dont l'agent sent l'état Noezis donne à l'agent une forme de **proprioception** — le suivi en continu de son propre état de connaissance. À chaque tour, il sait ce qui est : - **su** — l'information présente, retrouvable ; - **contesté** — les contradictions, signalées au lieu d'être masquées ; - **périmé** — ce qui a été remplacé, ou ce qui a dérivé ; - **manquant** — ce que la base ne sait pas, dit clairement. Ce contexte n'est pas réclamé à la demande par l'agent : il lui est **fourni au début de chaque tour**, sélectionné et borné. ## Trois propriétés 1. **Reproductible et traçable** — la recherche ne fait pas appel à un modèle dans sa boucle ; même question, même réponse, avec le chemin suivi. 2. **Le désaccord et le temps comptent** — les contradictions sont signalées, les versions périmées sont conservées et chaînées, pas effacées. 3. **Mémoire ≠ raisonneur** — Noezis est la mémoire, l'agent est le raisonneur. Frontière nette : Noezis ne génère pas, il retrouve. ## Aller plus loin - Décision vs document → [Décision ≠ document](registre-vs-prose.md) - Pourquoi la recherche est reproductible → [Pourquoi la recherche n'utilise pas de LLM](why-no-llm-in-search.md) --- # file: explanation/registre-vs-prose.md # Décision ≠ document > Explanation — pourquoi Noezis traite une décision autrement qu'un document, et > pourquoi ça protège votre agent. ## Deux natures de connaissance - **Les décisions** — des choix structurés (qui décide, sur quel sujet, quelle valeur, et pourquoi). Noezis **garantit leur cohérence** : deux décisions qui se contredisent sur le même sujet ne peuvent pas coexister silencieusement, et l'historique est conservé dans le temps. C'est la **source d'autorité**. - **Les documents** — du texte libre, recherchable, mais **non garanti cohérent**. Un README, une roadmap, un compte-rendu *affirment* des choses ; ils ne *décident* pas. ## Pourquoi la distinction compte Un agent qui ne distingue pas un choix *décidé* d'une phrase *écrite quelque part* mélange l'autorité et l'opinion. Noezis les sépare : - **Préséance** : si un document dit X mais qu'une décision dit Y, **la décision gagne**. - **Le désaccord est visible** : les contradictions ne sont pas masquées, elles sont signalées à l'agent. - **Le temps compte** : une décision remplacée est marquée périmée, pas effacée — l'historique reste consultable. ## Aller plus loin - Tracer une décision en pratique → [Tracer une décision](../how-to/trace-a-decision.md) - La thèse complète → [La proprioception de l'agent](proprioception.md) --- # file: explanation/the-knowledge-tree.md # Un index par sujet > Explanation — pourquoi Noezis range votre savoir par sujet plutôt qu'en simple > liste de fragments, et ce que ça change pour l'agent. ## Le problème d'une recherche à plat La plupart des outils découpent les documents en fragments et les jettent dans un même sac. Pour répondre, ils comparent la question à *tous* les fragments, un par un. Résultat : des extraits sortis de leur contexte, aucune hiérarchie, et une recherche qui ne sait que *comparer* — pas *naviguer*. ## La réponse de Noezis : un index hiérarchique Noezis range les passages **par sujet**, et les sujets se regroupent eux-mêmes en sujets plus larges, jusqu'à votre base entière. On obtient un index à plusieurs niveaux : - **votre base** au sommet ; - des **sujets** en dessous (regroupés automatiquement par proximité de sens, sans liste de catégories fixée d'avance) ; - les **passages** des documents tout en bas. Pour répondre, la recherche vise directement le bon sujet puis descend vers le bon passage, au lieu de tout parcourir. Les réponses sont plus pertinentes, arrivent plus vite, et l'agent reçoit aussi **le chemin** suivi — il sait d'où vient la réponse. ## Quand l'index se met à jour Au moment où vous ajoutez des documents, ils sont d'abord rangés simplement. Le regroupement par sujet se met à jour ensuite, **automatiquement**, quand votre base a assez grandi. Aucune action de votre part n'est nécessaire. ## Ce que Noezis ne fait pas Le retrieval repose sur cet index par sujet et la recherche. Noezis ne s'appuie pas sur un graphe de relations entre entités pour répondre. ## Aller plus loin - Ingérer pour alimenter la base → [Ingérer des documents](../how-to/ingest-and-watch.md) - Pourquoi la recherche est reproductible → [Pourquoi la recherche n'utilise pas de LLM](why-no-llm-in-search.md) --- # file: explanation/why-no-llm-in-search.md # Pourquoi la recherche n'utilise pas de LLM > Explanation — le choix de conception le plus structurant de Noezis, et ce qu'il > vous garantit. ## Le choix La recherche de Noezis ne fait **aucun appel à un modèle de langage**. Un modèle peut intervenir au moment de l'**ajout** d'un document (par exemple pour nommer un sujet), mais ce qu'il produit est alors **figé** une fois pour toutes. La recherche elle-même est purement automatique. ## Pourquoi c'est possible Chercher dans Noezis, c'est **descendre l'index par sujet** vers la bonne réponse. À chaque étape, le choix du bon sujet se calcule directement, sans avoir besoin qu'un modèle « réfléchisse ». Un LLM n'apporterait rien à cette navigation. ## Pourquoi c'est mieux pour vous - **Reproductible** : même question, même réponse. Toujours. - **Traçable** : Noezis renvoie le chemin suivi — on sait *pourquoi* une réponse remonte. - **Pas d'appel à un modèle de langage lors de la recherche** — donc ni coût d'API ni latence réseau à cette étape. - **Pas de réponse inventée** : Noezis ne *génère* pas, il *retrouve* des passages réels de votre base. ## Aller plus loin - Comment votre savoir est rangé → [Un index par sujet](the-knowledge-tree.md) - Choisir le bon mode de recherche → [Choisir le bon mode de recherche](../how-to/search-modes.md)