Bases de connaissances

Architecture de base, élément et révision

Une base de connaissances (Knowledge Base) est une collection de documents de référence, de spécifications et de runbooks définie au niveau du propriétaire ou de l'équipe. Elle organise les connaissances techniques en trois entités hiérarchiques distinctes :

• Knowledge Base : Le conteneur de premier niveau (comme "Engineering Runbooks"). Une base possède un nom, une description, un état (active ou archived) et une appartenance d'espace (Personal ou Team).
• Knowledge Item : Un document ou une directive distincte au sein d'une base (comme "Deployment Guidelines"). Un élément possède un titre, un localisateur, un état (draft, published ou archived), un type de source (user_created ou file) et un pointeur current_revision_id.
• Knowledge Revision : Un instantané immuable contenant le contenu canonique, le numéro de révision, le format du contenu (comme markdown), le hachage du contenu, les métadonnées sources et la provenance.
• Cycle de vie de publication : Un élément commence avec le statut draft. Une fois publié, sa révision actuelle devient découvrable par les agents. Les modifications ultérieures créent de nouvelles révisions immuables et font avancer le pointeur actuel sans altérer les révisions historiques.

Frontières de publication et visibilité des agents

Les bases de connaissances appliquent des frontières de publication strictes entre la rédaction humaine et la récupération par les agents autonomes. Les appelants choisissent entre recherche par requête (query search) et lecture adressée (addressed read). Les recherches par requête protègent la fraîcheur en évaluant uniquement les éléments publiés à leurs révisions actives actuelles :

• Bases actives uniquement : Les bases archivées sont exclues de la découverte par les agents. L'archivage suspend la récupération sur tous les éléments contenus sans détruire le contenu.
• Éléments publiés uniquement : Les éléments à l'état de projet (draft) restent privés pour l'auteur et les éditeurs de l'équipe jusqu'à leur publication explicite. Les agents ne peuvent ni découvrir ni citer d'éléments brouillons dans une recherche par requête.
• Révision actuelle par défaut : La recherche par requête évalue uniquement la révision référencée par current_revision_id. Les révisions historiques remplacées ne peuvent pas apparaître comme résultats de recherche.
• Lecture adressée : Une lecture adressée peut inspecter une révision historique exacte en fournissant knowledge_revision_id aux côtés de knowledge_item_id, préservant ainsi des citations reproductibles.

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

Modes de récupération : Hybrid, RRF, Semantic et Lexical

Le runtime de recherche prend en charge quatre modes de récupération pour équilibrer précision lexicale et compréhension sémantique :

• hybrid (par défaut) : Combinaison linéaire des scores lexicaux et sémantiques normalisés à l'aide du paramètre alpha (0.5 par défaut). Un alpha proche de 1 privilégie le chevauchement lexical exact, tandis qu'un alpha proche de 0 favorise la similarité sémantique conceptuelle. Bascule sur lexical lorsque les scores vectoriels sont indisponibles.
• rrf (Reciprocal Rank Fusion) : Fusionne des listes classées lexicales et sémantiques indépendantes à l'aide de la constante de rang k (60 par défaut), garantissant un ordonnancement équilibré sans nécessiter d'étalonnage des scores.
• semantic : Classement par similarité vectorielle basé sur des représentations d'embeddings, basculant sur la correspondance lexicale lorsque les embeddings ne sont pas configurés.
• lexical : Correspondance normalisée de jetons et d'expressions optimisée pour les symboles exacts, les noms de fonctions, les codes d'erreur et les clés de configuration.

Types de fichiers pris en charge et pipelines de téléversement

Les éléments de connaissances peuvent être rédigés directement en markdown ou importés à partir de fichiers locaux via deux mécanismes d'ingestion distincts :

• Fichiers texte et code lus par le navigateur : Les fichiers texte brut et de code (.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml) sont lus directement dans le navigateur et enregistrés en tant que contenu markdown canonique.
• Pipeline d'extraction de documents : Les documents formatés (.pdf, .docx, .pptx, .xlsx) sont téléversés via l'API Documents, traités par des workers d'extraction de texte et enregistrés sous forme d'instantanés dans des éléments de connaissances dès que l'extraction réussit.
• Frontières de fichiers : Les frontières d'ingestion s'appliquent sur les environnements client et serveur. Pour un traitement fiable, organisez les connaissances en documents modulaires et ciblés plutôt qu'en vidages de fichiers monolithiques.

Surfaces d'accès des agents et profils clients

Les agents autorisés accèdent aux connaissances par le biais d'outils MCP dédiés et de commandes Skill autonomes :

• MCP search_knowledge : Outil de recherche dédié en lecture seule nécessitant la portée de jeton knowledge:read. Exposé spécifiquement dans les profils clients cursor-plugin et ordinary-full (config/mcp-documentation-contract.json) ; non exposé dans les profils chatgpt-public ou generic-public.
• MCP recall_context : Inclut automatiquement les éléments de connaissances pertinents aux côtés de la mémoire épisodique lorsque Knowledge est activé pour votre compte et que le jeton comprend knowledge:read.
• Skill XMemo autonome : Exécute recall-context avec inclusion explicite des connaissances : node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• Application de la portée : Les opérations de recall n'interrogent pas toutes Knowledge automatiquement ; la récupération ne se produit que lorsqu'elle est configurée, autorisée par la portée du jeton et prise en charge par le profil client actif.
• Compagnon REST : Le point de terminaison compagnon authentifié POST /api/v1/knowledge/search fournit un accès programmatique direct à la recherche de connaissances pour les services backend et les outils personnalisés.

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

Rôles d'équipe, espaces et opérations de cycle de vie

Les bases de connaissances prennent en charge les espaces de travail personnels et collaboratifs avec contrôle d'accès basé sur les rôles :

• 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, mais ne peut ni supprimer ni archiver de bases). Viewer ne détient que des droits de lecture.
• Frontières des espaces : L'espace personnel (/me#knowledge) est privé pour le propriétaire. L'espace d'équipe (?space=<team_id>#knowledge) partage la documentation publiée entre les membres authentifiés de l'équipe.
• Archivage vs suppression définitive : L'archivage d'une base définit son statut sur archived, excluant instantanément tous les éléments des requêtes d'agents tout en permettant une restauration complète. La suppression définitive détruit physiquement la base et toutes les révisions associées de manière irréversible.

Distinction par rapport à la mémoire de projet

Les bases de connaissances fournissent une documentation de référence organisée, qui fonctionne sous des garanties différentes de la mémoire de projet conversationnelle :

• Éléments de base de connaissances : Documents de référence organisés et versionnés (tels que des runbooks, des documents de conception et des normes de codage) avec un historique multi-révisions et des références de citation exactes (knowledge:<item-id>@<revision-id>).
• Mémoire de projet Knowledge/Working : Enregistrements de mémoire conversationnelle catégorisés au sein d'un espace de travail de projet en tant que contexte durable (knowledge) par opposition à un état de tâche temporaire (working memory).
• Indépendance : La suppression d'un enregistrement de mémoire ou la dissociation d'un document d'un projet ne modifie, n'archive ni ne supprime les éléments sous-jacents de la base de connaissances.

Disponibilité et activation au runtime

La base de connaissances est documentée en tant que fonctionnalité centrale, et non en tant que Preview. La disponibilité est active si Knowledge est activé pour votre compte. Lorsque le runtime de connaissances du backend n'est pas configuré ou est désactivé, les requêtes renvoient HTTP 503 avec le code knowledge_runtime_disabled. Les désignations de plan du catalogue (telles que les allocations du niveau Plus) représentent des quotas de plan et non des mécanismes d'application au runtime ; aucune route d'API n'impose de niveaux de plan.