Bases de conocimiento

Arquitectura de base, elemento y revisión

Una Knowledge Base es una colección de documentos de referencia, especificaciones y runbooks con alcance de propietario o de equipo. Organiza el conocimiento técnico en tres entidades jerárquicas distintas:

• Knowledge Base: El contenedor de nivel superior (como "Engineering Runbooks"). Una base tiene un nombre, descripción, estado (active o archived) y propiedad del espacio (Personal o Team).
• Knowledge Item: Un documento o directriz individual dentro de una base (como "Deployment Guidelines"). Un elemento tiene un título, localizador, estado (draft, published o archived), tipo de origen (user_created o file) y un puntero current_revision_id.
• Knowledge Revision: Una instantánea inmutable que contiene contenido canónico, número de revisión, formato de contenido (como markdown), hash de contenido, metadatos de origen y procedencia (provenance).
• Ciclo de vida de publicación: Un elemento comienza en estado draft. Cuando se publica, su revisión actual se vuelve detectable para los agentes. Las ediciones posteriores crean revisiones nuevas inmutables y avanzan el puntero actual sin alterar las revisiones históricas.

Límites de publicación y visibilidad de los agentes

Las Knowledge Bases aplican límites estrictos de publicación entre la autoría humana y la recuperación por parte de agentes autónomos. Quienes invocan el servicio eligen entre búsqueda por consulta (query search) y lectura direccionada (addressed read). Las búsquedas por consulta protegen la frescura evaluando únicamente los elementos publicados en sus revisiones activas actuales:

• Solo bases activas: Las bases archivadas se excluyen del descubrimiento de agentes. El archivado suspende la recuperación en todos los elementos contenidos sin destruir el contenido.
• Solo elementos publicados: Los elementos en borrador (draft) permanecen privados para el autor y los editores del equipo hasta que se publican explícitamente. Los agentes no pueden descubrir ni citar elementos en borrador en la búsqueda por consulta.
• Revisión actual por defecto: La búsqueda por consulta evalúa únicamente la revisión a la que hace referencia current_revision_id. Las revisiones históricas sustituidas no pueden aparecer como resultados de búsqueda.
• Lectura direccionada: Una lectura direccionada puede inspeccionar una revisión histórica exacta proporcionando knowledge_revision_id junto con knowledge_item_id, conservando citas reproducibles.

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>)

Modos de recuperación: Hybrid, RRF, Semantic y Lexical

El runtime de búsqueda admite cuatro modos de recuperación para equilibrar la precisión léxica y la comprensión semántica:

• hybrid (predeterminado): Combinación lineal de puntuaciones léxicas y semánticas normalizadas utilizando el parámetro alpha (predeterminado 0.5). Un valor de alpha cercano a 1 favorece la superposición léxica exacta, mientras que un valor cercano a 0 favorece la similitud semántica conceptual. Recurre a lexical cuando las puntuaciones vectoriales no están disponibles.
• rrf (Reciprocal Rank Fusion): Fusiona listas clasificadas léxicas y semánticas independientes utilizando la constante de rango k (predeterminada 60), garantizando un orden equilibrado sin requerir calibración de puntuaciones.
• semantic: Clasificación por similitud vectorial basada en representaciones de incrustación (embeddings), recurriendo a coincidencia léxica cuando las incrustaciones no están configuradas.
• lexical: Coincidencia normalizada de tokens y frases optimizada para símbolos exactos, nombres de funciones, códigos de error y claves de configuración.

Tipos de archivos admitidos y canalizaciones de subida

Los elementos de conocimiento se pueden redactar directamente en markdown o importar desde archivos locales mediante dos mecanismos de ingesta independientes:

• Archivos de texto y código leídos por el navegador: Los archivos de texto sin formato y código (.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml) se leen directamente en el navegador y se guardan como contenido canónico en markdown.
• Canalización de extracción de documentos: Los documentos formateados (.pdf, .docx, .pptx, .xlsx) se suben a través de la API Documents, se procesan mediante workers de extracción de texto y se convierten en instantáneas como elementos de Knowledge una vez que la extracción tiene éxito.
• Límites de archivos: Los límites de ingesta se aplican en entornos de cliente y servidor. Para un procesamiento fiable, organice el conocimiento en documentos modulares y enfocados en lugar de volcados de archivos monolíticos.

Superficies de acceso de agentes y perfiles de cliente

Los agentes autorizados acceden a Knowledge a través de herramientas MCP dedicadas y comandos de Skill independientes:

• MCP search_knowledge: Herramienta de búsqueda dedicada de solo lectura que requiere el alcance de token knowledge:read. Expuesta específicamente en los perfiles de cliente cursor-plugin y ordinary-full (config/mcp-documentation-contract.json); no expuesta en los perfiles chatgpt-public o generic-public.
• MCP recall_context: Incluye automáticamente elementos de Knowledge relevantes junto con la memoria episódica cuando Knowledge está habilitado para su cuenta y el token incluye knowledge:read.
• XMemo Skill independiente: Ejecuta recall-context con inclusión explícita de conocimiento: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• Cumplimiento del alcance: No todas las operaciones de recall consultan Knowledge automáticamente; la recuperación solo se produce cuando está configurada, permitida por el alcance del token y admitida por el perfil de cliente activo.
• Complemento REST: El endpoint complementario autenticado POST /api/v1/knowledge/search proporciona acceso programático directo a la búsqueda de conocimiento para servicios backend y herramientas personalizadas.

{
  "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
    }
  ]
}

Roles de equipo, espacios y operaciones de ciclo de vida

Las Knowledge Bases admiten espacios de trabajo personales y colaborativos con control de acceso basado en roles:

• Capacidades de los roles: Owner y Admin poseen permisos de base:admin y de item:write (crear, archivar, actualizar y eliminar bases y elementos). Member posee permisos de item:write (crear, editar y publicar elementos, pero no puede eliminar ni archivar bases). Viewer solo posee permisos de lectura.
• Límites de los espacios: El espacio personal (/me#knowledge) es privado para el propietario. El espacio de equipo (?space=<team_id>#knowledge) comparte la documentación publicada entre los miembros autenticados del equipo.
• Archivado frente a eliminación permanente: Archivar una base establece el estado en archived, excluyendo instantáneamente todos los elementos de las consultas de agentes y permitiendo al mismo tiempo una restauración completa. La eliminación permanente destruye físicamente la base y todas las revisiones asociadas de forma irreversible.

Diferencia con la memoria de proyecto

Las Knowledge Bases proporcionan documentación de referencia seleccionada, que opera bajo garantías diferentes a las de la memoria de proyecto conversacional:

• Elementos de Knowledge Base: Documentos de referencia seleccionados y versionados (como runbooks, documentos de diseño y estándares de código) con historial multirrevisión y referencias de citas exactas (knowledge:<item-id>@<revision-id>).
• Memoria de Knowledge/Working de proyecto: Registros de memoria conversacional categorizados dentro de un espacio de trabajo de proyecto como contexto duradero (knowledge) frente a estado de tarea transitorio (working memory).
• Independencia: Eliminar un registro de memoria o desvincular un documento de un proyecto no modifica, archiva ni elimina los elementos subyacentes de la Knowledge Base.

Disponibilidad y habilitación en tiempo de ejecución

Knowledge Base está documentada como una capacidad principal, no como Preview. La disponibilidad está activa si Knowledge está habilitado para su cuenta. Cuando el runtime de conocimiento del backend no está configurado o está deshabilitado, las solicitudes devuelven HTTP 503 con el código knowledge_runtime_disabled. Las designaciones de planes de catálogo (como las asignaciones del nivel Plus) representan límites de plan y no mecanismos de aplicación en tiempo de ejecución; ninguna ruta de API impone niveles de plan.