# Guide des bases de connaissances Créez des bases de connaissances, téléversez de la documentation technique, publiez des éléments versionnés et permettez aux agents de récupérer des faits cités avec provenance. - Canonical: https://docs.xmemo.dev/fr/docs/guides/knowledge-bases - Locale: fr-FR - Content-Locale: fr-FR - Canonical-Content-Digest: 1867d8b68c37e8f52cb96a448217aeea61bf2b42608d8931313472d77f22d9c6 - Edition-Digest: d9cca004d55a2b9afab6b00f837a50054b7abaa8a21c7ce40479587a1e84587a - Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd ## Objectif de l'utilisateur Gérez des bases de connaissances structurées dans votre espace de travail personnel ou d'équipe, ingérez des documents en markdown et aux formats structurés, publiez des révisions immuables vérifiées et configurez des agents autonomes pour récupérer des faits cités avec attribution de la source. ## Disponibilité et prérequis La création et l'inspection de bases de connaissances sont disponibles dans la console web sur https://xmemo.dev/me#knowledge (espace personnel) ou https://xmemo.dev/me?space=#knowledge (espace d'équipe) si Knowledge est activé pour votre compte. Avant de commencer, vérifiez les prérequis suivants : - Exigence d'authentification : une session utilisateur active est requise. Les visites non authentifiées sont redirigées vers /login (la page de connexion). - Portées de jeton : l'accès programmatique nécessite knowledge:read pour la recherche et les lectures ciblées, et knowledge:write pour créer ou modifier des éléments. - Formats de fichiers pris en charge : le lecteur de texte et de code intégré au navigateur prend en charge .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml et .toml. L'extraction de documents prend en charge .pdf, .docx, .pptx et .xlsx. - Interface de glisser-déposer : la console affiche "Drag & drop files here" avec le texte d'aide "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)". ## 1. Créer une base de connaissances dans la console web Rendez-vous sur https://xmemo.dev/me#knowledge dans votre navigateur. Cliquez sur "Create Knowledge Base" pour ouvrir la boîte de dialogue de création. Saisissez "Engineering Runbooks" dans Name et "Operational runbooks and deployment procedures." dans Description. Confirmez la création pour initialiser la base active. ```bash # Access personal knowledge workspace https://xmemo.dev/me#knowledge # Access team knowledge workspace with explicit space parameter https://xmemo.dev/me?space=#knowledge ``` ## 2. Ajouter et publier un élément de connaissances synthétique Ouvrez la base "Engineering Runbooks" nouvellement créée et cliquez sur "Create Knowledge item" pour créer une entrée à partir de markdown ou d'un fichier local. Saisissez le titre "Deployment Guidelines" et collez les instructions synthétiques initiales. L'élément commence avec le statut "draft" : ```markdown ## Deployment Guidelines Production deployments require two peer approvals, clean migration dry-runs, and verified canary health. ``` ## 3. Publier l'élément en brouillon pour la récupération par les agents Tant qu'il est au statut "draft", l'élément reste visible uniquement par les éditeurs humains. Pour le rendre accessible aux agents, cliquez sur "Publish". La console affiche l'indication "Published content becomes eligible for authorized Knowledge search.". Une fois confirmée, l'entrée passe au statut "published", établissant la révision 1 comme révision actuelle consultable. - Confidentialité des brouillons : les éléments en brouillon sont exclus de la découverte et de la recherche par requête des agents. - Action de publication : la publication met à jour le statut de l'élément vers "published" et définit current_revision_id sur la révision 1. - Révision immuable : le contenu canonique, le hachage et les métadonnées de la révision 1 sont conservés de manière immuable. ## 4. Récupérer des connaissances avec citation d'agent Les agents autorisés dans des environnements clients exposant search_knowledge (comme cursor-plugin ou ordinary-full) peuvent interroger le runbook publié. L'outil renvoie des extraits classés accompagnés de pointeurs explicites de référence de citation : ```bash # Query knowledge via standalone Skill CLI node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true ``` ## 5. Mettre à jour le contenu et publier une nouvelle révision immuable Lorsque les procédures techniques évoluent, ouvrez "Deployment Guidelines" et cliquez sur "Edit Knowledge item". Mettez à jour le contenu pour refléter les nouvelles exigences opérationnelles. Cliquez sur "Save new revision". La console affiche : "Saving content creates an immutable new revision. Metadata changes do not create a revision." : ```markdown ## Deployment Guidelines Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification. ``` ## Résultat observable Vérifiez l'élément publié et la traçabilité de sa révision dans la console web et via la recherche d'agent : - Badge de console : la carte de l'élément affiche le badge de statut "Published" et renvoie vers la révision active actuelle. - Lignée des révisions : l'ouverture de "Revision history" présente la révision 2 comme actuelle et la révision 1 comme historique, avec horodatages et attribution de l'auteur. - Résultat de recherche d'agent : les recherches par requête évaluent uniquement la révision 2. La révision historique 1 reste accessible par des lectures ciblées spécifiant le knowledge_revision_id exact. ## Ce à quoi les agents peuvent accéder Les bases de connaissances imposent des frontières strictes d'accès et de visibilité pour l'intégration des agents : - Éléments publiés uniquement : les agents ne peuvent pas accéder aux brouillons. Les recherches par requête évaluent uniquement les éléments publiés dans les bases actives. - Frontière de révision actuelle : la recherche par requête résout automatiquement current_revision_id. Les révisions remplacées ne peuvent pas apparaître dans les résultats de recherche. - Disponibilité selon le profil : l'outil MCP en lecture seule search_knowledge est strictement disponible dans les profils clients cursor-plugin et ordinary-full (config/mcp-documentation-contract.json). Les autres profils clients emploient recall_context, qui inclut automatiquement Knowledge s'il est activé et autorisé. - Comportement de rappel : MCP recall_context inclut automatiquement Knowledge lorsque Knowledge est activé sur votre compte et que le jeton contient knowledge:read. Les appels à recall ne consultent pas tous Knowledge. ## Frontières de partage et de stockage Les bases de connaissances maintiennent un cloisonnement strict des espaces et des limites de rôles administratifs : - Espace personnel vs espace d'équipe : les bases personnelles (/me#knowledge) sont privées pour le compte. Les bases d'équipe (?space=#knowledge) appliquent le contrôle d'accès basé sur les rôles d'équipe (routes/knowledge.py:129-134). - Capacités des rôles : Owner et Admin détiennent les droits base:admin et item:write (créer, archiver, mettre à jour et supprimer des bases et des éléments). Member détient les droits item:write (créer, modifier et publier des éléments). Viewer dispose uniquement de droits de lecture. - Archivage vs suppression définitive : l'archivage ("Are you sure you want to archive knowledge base ''? Archived bases will no longer be retrieved by agents.") suspend la récupération sans perte. La suppression définitive ("Are you sure you want to permanently delete knowledge base '' and all its items? This action cannot be undone.") efface physiquement les données. - Indépendance de la mémoire des projets : les bases de connaissances fonctionnent indépendamment des partitions de mémoire de travail et de connaissances des projets. Dissocier une mémoire d'un projet ne modifie pas les documents de la base de connaissances. ## Dépannage Résolvez les problèmes courants d'accès et d'extraction dans les bases de connaissances à l'aide des étapes de diagnostic suivantes : - Extraction de document en cours : lors du téléversement de documents .pdf, .docx, .pptx ou .xlsx, patientez pendant l'affichage de "Extraction is still in progress. Try again when it succeeds.". - Échec de l'extraction de document : si le traitement échoue, la console indique "Extraction failed. Retry the Document from its existing Document surface first.". Vérifiez l'intégrité du fichier ou téléversez du texte brut en markdown. - Élément non renvoyé dans la requête de l'agent : assurez-vous que le statut de l'élément est "Published" (et non "draft"), que la base est active (non archivée) et que le jeton client détient la portée knowledge:read. - Conflit de mise à jour simultanée : si un autre utilisateur ou agent a modifié l'élément alors que votre édition était ouverte, la console affiche "This Knowledge item changed elsewhere. Refresh it and try again.". Actualisez la page et appliquez à nouveau vos modifications. - Sélection du mode de recherche : si des symboles de runbook ou des clés de configuration exacts sont ignorés par la recherche hybride, basculez en mode lexical (mode="lexical") pour une correspondance exacte des jetons. ## Références associées Poursuivez l'exploration des concepts des bases de connaissances, des outils associés et de la gestion des espaces : - Concepts : bases de connaissances (/docs/concepts/knowledge-bases) — Modèle architectural, DAG de révision et modes de récupération. - Outils : search_knowledge (/docs/tools/search-knowledge) — Référence de l'outil pour les lectures ciblées et paramètres de recherche. - Outils : recall_context (/docs/tools/recall-context) — Outil de structuration de contexte avec extraction automatique de Knowledge. - Guides : Memory Console (/docs/guides/memory-console) — Guide complet de navigation dans la console web. - Concepts : provenance et attribution (/docs/concepts/provenance-attribution) — Enveloppes de citation et attribution de l'auteur. ## Utilisateur de ChatGPT Donnez à ChatGPT un accès durable à vos préférences XMemo, faits de projet, décisions et TODOs sans coller de jetons bearer dans un chat. Connectez le serveur MCP XMemo hébergé via le flux OAuth de l'application ChatGPT/OpenAI, puis approuvez les autorisations memory:read et memory:write pour votre compte XMemo. Enregistrez une préférence synthétique ou une note de projet, démarrez un nouveau chat, puis demandez à ChatGPT de la rappeler via XMemo avant de poursuivre le travail. Si OAuth échoue ou si les outils n'apparaissent pas, déconnectez-vous du serveur MCP dans l'application hôte, reconnectez l'URL du serveur XMemo et réessayez avant de créer des jetons directs. ## Développeur Copilot / Codex Transmettez les décisions du dépôt, les conventions de codage, les notes de correctifs et l'historique des tâches entre les agents IDE et CLI. Utilisez OAuth pour VS Code / GitHub Copilot et Gemini CLI lorsqu'il est disponible. Pour Copilot CLI, Codex, Cursor ou d'autres clients MCP directs, conservez XMEMO_KEY dans l'environnement local ou le gestionnaire de secrets et définissez un identifiant XMEMO_AGENT_INSTANCE_ID stable. Enregistrez une décision relative au code ou un correctif, puis demandez au prochain agent de l'IDE ou de la CLI de rappeler le contexte XMemo pertinent avant toute modification. Si les rappels sont vides, vérifiez le chemin de configuration MCP sélectionné, la variable d'environnement XMEMO_KEY pour les clients directs et tout identifiant OAuth obsolète dans l'application hôte. ## Responsable de projet pilote d'équipe / entreprise Évaluez la mémoire partagée avec les contrôles de compte, l'attribution des sources, les flux d'exportation/suppression et des preuves de configuration sécurisées pour les évaluateurs. Créez ou rejoignez l'espace de travail sécurisé XMemo, invitez les utilisateurs approuvés, puis connectez chaque client via OAuth ou un identifiant direct délimité selon les badges de disponibilité. Demandez à un membre du projet pilote d'enregistrer une mémoire d'équipe synthétique, confirmez l'attribution de la source dans XMemo, puis examinez les chemins de suppression/exportation et de support. Si un membre ne parvient pas à se connecter, vérifiez les permissions de rôle, l'approbation OAuth, l'état de disponibilité du client et les conseils du support avant d'émettre un nouveau jeton. ## Opérateur d'agents autonomes Permettez aux agents autonomes ou planifiés d'enregistrer leur progression, de récupérer les décisions antérieures et de conserver une identité d'instance stable et non secrète. Récupérez /api/v1/mcp/config/autonomous-agent. Privilégiez auth_modes.oauth lorsque l'exécuteur prend en charge OAuth + en-têtes personnalisés ; utilisez auth_modes.xmemo_key avec XMEMO_KEY issu d'un gestionnaire de secrets uniquement pour les exécuteurs entièrement autonomes. Exécutez une tâche synthétique qui consigne la progression dans XMemo, redémarrez l'exécuteur et confirmez qu'il rappelle cette progression à l'aide du même XMEMO_AGENT_INSTANCE_ID. Si l'attribution change ou si les rappels se scindent entre instances, conservez XMEMO_AGENT_INSTANCE_ID hors de git et vérifiez que l'exécuteur ne le régénère pas à chaque démarrage.