Walliiee/agent-harness

QMD — Moteur de recherche local de connaissances

QMD est le moteur de recherche vectorielle + lexicale local sur les espaces de travail de l'utilisateur. Utilisez-le avant de répondre à des questions qui pourraient déjà être documentées — en particulier pour le contexte concernant les personnes, projets, décisions et travaux antérieurs.

Flux de travail

Le flux de travail est toujours :

1. Rechercher des documents candidats.
2. Récupérer la source complète avec qmd get ou qmd multi-get.
3. Répondre à partir du texte récupéré, en citant les chemins ou les docid.

Ne répondez pas uniquement à partir d'extraits lorsque l'utilisateur a besoin de faits, décisions, citations ou nuances. Les extraits ne sont que des pistes.

Lorsque vous rapportez ce que vous avez récupéré, une note concise suffit ; ne copiez pas des fichiers entiers sauf si nécessaire :

Récupéré : #abc123 wiki/projects/GenAICategorizer.md, #def432 memory/2026-05-26.md

Choisissez le bon mode de recherche

Mode	Commande	Quand l'utiliser
BM25 mots-clés	qmd search	Mots exacts, titres, noms, symboles de code, phrases rares
Hybride + reclassement	qmd query	Formulation indirecte, rappel conceptuel, meilleure qualité
Structuré	qmd query avec champs lex:/vec:/hyde:	Recherches difficiles nécessitant des ancres exactes + rappel sémantique

Recherche simple :

qmd search "statut du projet challenger crew" -n 10
qmd search '"GenAI Categorizer"' -c wiki-main -n 5

Recherche conceptuelle sémantique :

qmd query "la qualité des décisions dépend de la mise en évidence des hypothèses et du contexte" -n 10

Requête structurée (recherches difficiles) :

qmd query $'intent: Trouver la note conceptuelle sur les métriques comme instruments sans laisser les OKR remplacer le jugement.\nlex: instruments cockpit OKR Goodhart metrics jugement\nvec: données informées non pilotées par les métriques jugement produit\nhyde: Une note conceptuelle dit que les métriques sont utiles comme les instruments de cockpit, mais les dirigeants doivent rester informés par les données plutôt que pilotés par les métriques car les OKR et tableaux de bord peuvent Goodhartiser le jugement produit.'

Champs de requête structurée :

• intent: indique ce que vous essayez de trouver et ce qu'il faut éviter.
• lex: termes exacts, alias, titres et mots rares.
• vec: paraphrase l'idée en langage naturel.
• hyde: décrit le document ou la réponse qui satisferait la demande.

Récupérer les sources

qmd get "#abc123"                        # par docid des résultats de recherche
qmd get "wiki/projects/GenAICategorizer.md" --full  # par chemin
qmd multi-get "#abc123,#def432" --md     # par lot de docids
qmd multi-get 'memory/2026-05-*.md' -l 80  # lot par glob

Utilisez multi-get pour comparer plusieurs résultats ou rassembler du contexte entre pages. Utilisez --full lorsque la source exacte est importante.

Collections par agent

Chaque agent a son propre index QMD avec une configuration isolée par XDG. La liste des agents se trouve dans ${OPENCLAW_HOME}/config/agents.map. Lorsque vous effectuez une recherche depuis la CLI, utilisez le wrapper XDG de l'agent :

# agent principal
XDG_CONFIG_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-config XDG_CACHE_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-cache qmd query "..."
# agent dev et tout autre agent — même modèle, changez le nom de l'agent

Collections de l'agent principal

Collection	Contenu
identity-main	Documents principaux — ÂME, IDENTITÉ, OUTILS, AGENTS, RÉSEAU, index de MÉMOIRE
wiki-main	Cortex de connaissances durables. Wiki — comportements d'agents (règles inter-agents), projets, outils, concepts, personnes. Principal référentiel de mémoire durable depuis le 2026-05-28.
memory-main	Fichiers de mémoire quotidiens (YYYY-MM-DD.md) — couche de capture de 7 jours qui promeut le contenu dans wiki-main
workspace-docs-main	Markdown complet de l'espace de travail (références, tâches, passations, apprentissages)
skills-main	Définitions de compétences (fichiers SKILL.md)
agents-*-identity	Documents d'identité/config racine des autres agents (espaces de travail par agent)
agents-*-memory	Fichiers de mémoire quotidiens des autres agents (espaces de travail par agent)
agents-*-wiki	Wikis durables des autres agents (espaces de travail par agent) — l'agent principal peut interroger directement les connaissances durables spécialisées.
handoffs-*	Fichiers de passation par agent (main, dev et tout autre agent)

Indices de collections spécialisées

Les noms de collections ci-dessous proviennent de la configuration QMD propre à chaque agent spécialisé. Depuis l'agent principal, utilisez les équivalents inter-agents (agents-<agent>-wiki, agents-<agent>-memory).

Ce que vous cherchez	Agent	Collections clés (au sein de cet agent)	Depuis l'agent principal
Projets code, configurations de build, décisions d'ingénierie	dev	projects-dev, identity-dev, wiki-dev	agents-dev-wiki, agents-dev-memory

Contexte et délimitation des collections

Les métadonnées context: de QMD (définies dans index.yml ou via qmd context add) améliorent la pertinence de la recherche en décrivant le contenu de chaque collection. Elles sont renvoyées avec les résultats.

Délimitez les recherches avec -c lorsque des requêtes larges dérivent dans le mauvais corpus :

qmd search "notes de point hebdomadaire" -c agents-dev-memory -n 10
qmd query "statut du projet GenAI" -c wiki-main -c projects-dev -n 10

Omettez -c pour tout rechercher.

Diagnostic

qmd status     # comptages des collections et plongements en attente
qmd update     # ré-indexation (à utiliser après ajout/édition de fichiers dans les chemins indexés)
qmd embed      # générer/reconstruire les vecteurs après mise à jour

Si qmd query ou qmd vsearch échouent (modèle/GPU indisponible), revenez à qmd search avec des termes lexicaux plus forts.

Remarque : les anciennes docs référençaient qmd doctor — cette sous-commande n'est pas présente dans la version actuelle de la CLI. Utilisez qmd status pour la santé, et qmd update/qmd embed pour la réparation.

Outils MCP

Lorsque vous utilisez MCP (par défaut pour les agents OpenClaw), préférez les requêtes structurées :

{
  "searches": [
    { "type": "lex", "query": "statut équipage challenger" },
    { "type": "vec", "query": "quel est l'état actuel du projet d'équipage challenger" }
  ],
  "intent": "Trouver le statut du projet, pas des concepts généraux sur l'équipage.",
  "limit": 10
}

Pièges à éviter

• Ne vous arrêtez pas aux extraits. Récupérez les documents avant de faire des affirmations.
• N'abusez pas de la recherche sémantique. Si vous connaissez les titres ou termes exacts, BM25 est plus rapide et souvent meilleur.
• Ne modifiez pas les index à la légère. qmd collection add, qmd update et qmd embed modifient l'état local et peuvent être coûteux.
• Les commandes basées sur des modèles peuvent être sensibles à l'environnement. Si qmd query ou le reclassement échouent, revenez à qmd search avec des termes lexicaux plus forts.
• Un libellé ambigu nécessite une intention. Ajoutez intent: plutôt que d'espérer que l'expansion de requête devine le bon domaine.
• Les noms de collections sont importants. Délimitez avec -c lorsque la requête pourrait correspondre à plusieurs domaines.
• Actualité : QMD ne déprécie pas les anciens résultats. Pour les mémoires temporelles, vérifiez les noms de fichiers — YYYY-MM-DD plus proche d'aujourd'hui est plus récent.

Configuration et maintenance

Ne les exécutez que lorsque cela vous est demandé. Chercher et récupérer sont sûrs ; la mutation d'index n'est pas anodine.

qmd collection add ~/notes --name notes   # alternative CLI à l'édition de index.yml
qmd context add qmd://notes "Description"  # alternative CLI à context: dans index.yml
qmd update                                # ré-indexer les collections
qmd embed                                 # générer/reconstruire les vecteurs
qmd status                                # vérification de santé après les changements