# Guía de bases de conocimiento Crea bases de conocimiento, sube documentación técnica, publica elementos versionados y permite que los agentes recuperen hechos citados con procedencia. - Canonical: https://docs.xmemo.dev/es/docs/guides/knowledge-bases - Locale: es-ES - Content-Locale: es-ES - Canonical-Content-Digest: 1867d8b68c37e8f52cb96a448217aeea61bf2b42608d8931313472d77f22d9c6 - Edition-Digest: 66cf6cb5f4ff2a1803adcf1fbfc8629c6a9cb3ff801e770115f63cfedff196f6 - Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd ## Objetivo del usuario Mantén bases de conocimiento estructuradas en tu espacio de trabajo personal o de equipo, incorpora documentos en markdown y formatos estructurados, publica revisiones inmutables verificadas y configura agentes autónomos para recuperar hechos citados con atribución de origen. ## Disponibilidad y requisitos previos La creación e inspección de bases de conocimiento están disponibles en la consola web en https://xmemo.dev/me#knowledge (espacio personal) o https://xmemo.dev/me?space=#knowledge (espacio de equipo) si Knowledge está habilitado en tu cuenta. Antes de comenzar, verifica los siguientes requisitos previos: - Requisito de autenticación: se requiere una sesión de usuario activa. Las visitas no autenticadas se redirigen a /login (la página de inicio de sesión). - Permisos de token: el acceso programático requiere knowledge:read para búsquedas y lecturas directas, y knowledge:write para crear o editar elementos. - Formatos de archivo compatibles: el visor de texto y código en el navegador admite .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml y .toml. La extracción de documentos admite .pdf, .docx, .pptx y .xlsx. - Interfaz de arrastrar y soltar: la consola presenta "Drag & drop files here" con el texto de ayuda "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)". ## 1. Crear una base de conocimiento en la consola web Navega a https://xmemo.dev/me#knowledge en tu navegador. Haz clic en "Create Knowledge Base" para abrir el diálogo de creación. Introduce "Engineering Runbooks" en Name y "Operational runbooks and deployment procedures." en Description. Confirma la creación para inicializar la base activa. ```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. Añadir y publicar un elemento de conocimiento sintético Abre la base "Engineering Runbooks" recién creada y haz clic en "Create Knowledge item" para crear una entrada a partir de markdown o de un archivo local. Introduce el título "Deployment Guidelines" y pega las instrucciones sintéticas iniciales. El elemento se inicializa con el estado "draft": ```markdown ## Deployment Guidelines Production deployments require two peer approvals, clean migration dry-runs, and verified canary health. ``` ## 3. Publicar el elemento en borrador para la recuperación por agentes Mientras permanezca en estado "draft", el elemento es visible únicamente para editores humanos. Para hacerlo detectable por los agentes, haz clic en "Publish". La consola muestra la sugerencia "Published content becomes eligible for authorized Knowledge search.". Una vez confirmado, el elemento pasa al estado "published", estableciendo la revisión 1 como la revisión actual con capacidad de búsqueda. - Privacidad de borradores: los elementos en borrador se excluyen del descubrimiento de agentes y de las búsquedas por consulta. - Acción de publicación: publicar actualiza el estado del elemento a "published" y asigna current_revision_id a la revisión 1. - Revisión inmutable: el contenido canónico, el hash y los metadatos de la revisión 1 se conservan de forma inmutable. ## 4. Recuperar conocimiento con citas para el agente Los agentes autorizados en entornos de cliente que exponen search_knowledge (como cursor-plugin o ordinary-full) pueden consultar el runbook publicado. La herramienta devuelve fragmentos clasificados con punteros explícitos de referencia de citas: ```bash # Query knowledge via standalone Skill CLI node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true ``` ## 5. Actualizar el contenido y publicar una nueva revisión inmutable Cuando los procedimientos técnicos cambien, abre "Deployment Guidelines" y haz clic en "Edit Knowledge item". Actualiza el contenido para reflejar los nuevos requisitos operativos. Haz clic en "Save new revision". La consola muestra "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. ``` ## Resultado observable Verifica el elemento publicado y la procedencia de su revisión en la consola web y mediante la búsqueda del agente: - Insignia de la consola: la tarjeta del elemento muestra la insignia de estado "Published" y señala a la revisión activa actual. - Línea temporal de revisiones: al abrir "Revision history" se muestra la revisión 2 como actual y la revisión 1 como histórica, con marcas de tiempo y atribución de autor. - Resultado de búsqueda del agente: las búsquedas por consulta evalúan únicamente la revisión 2. La revisión histórica 1 sigue accesible mediante lecturas directas especificando el knowledge_revision_id exacto. ## A qué pueden acceder los agentes Las bases de conocimiento imponen límites estrictos de acceso y visibilidad para la integración de agentes: - Solo elementos publicados: los agentes no pueden acceder a elementos en borrador. Las búsquedas por consulta evalúan únicamente elementos publicados en bases activas. - Límite de la revisión actual: la búsqueda por consulta resuelve automáticamente en current_revision_id. Las revisiones sustituidas no pueden aparecer en los resultados de búsqueda. - Disponibilidad de perfiles: la herramienta MCP de solo lectura search_knowledge está disponible estrictamente en los perfiles de cliente cursor-plugin y ordinary-full (config/mcp-documentation-contract.json). Otros perfiles de cliente emplean recall_context, que incluye automáticamente Knowledge cuando está habilitado y autorizado. - Comportamiento de recall: MCP recall_context incluye Knowledge automáticamente cuando Knowledge está habilitado en tu cuenta y el token incluye knowledge:read. No todos los recall buscan en Knowledge. ## Límites de uso compartido y almacenamiento Las bases de conocimiento mantienen un aislamiento estricto de espacios y límites de roles administrativos: - Espacio personal frente a espacio de equipo: las bases personales (/me#knowledge) son privadas de la cuenta. Las bases de equipo (?space=#knowledge) aplican el control de acceso por roles del equipo (routes/knowledge.py:129-134). - Capacidades de rol: Owner y Admin poseen derechos de base:admin e item:write (crear, archivar, actualizar y eliminar bases y elementos). Member posee derechos de item:write (crear, editar y publicar elementos). Viewer posee exclusivamente derechos de lectura. - Archivado frente a eliminación definitiva: archivar ("Are you sure you want to archive knowledge base ''? Archived bases will no longer be retrieved by agents.") suspende la recuperación sin pérdida de información. La eliminación permanente ("Are you sure you want to permanently delete knowledge base '' and all its items? This action cannot be undone.") suprime físicamente los datos. - Independencia de la memoria de proyectos: las bases de conocimiento operan de forma independiente de las particiones de memoria de trabajo y conocimiento de proyectos. Desvincular un recuerdo de un proyecto no afecta a los documentos de la base de conocimiento. ## Recuperación ante fallos Resuelve los problemas habituales de acceso y extracción en bases de conocimiento mediante los siguientes pasos de diagnóstico: - Extracción de documentos en curso: al cargar documentos .pdf, .docx, .pptx o .xlsx, espera mientras se muestre: "Extraction is still in progress. Try again when it succeeds.". - Fallo en la extracción de documentos: si el procesamiento falla, la consola muestra "Extraction failed. Retry the Document from its existing Document surface first.". Verifica la integridad del archivo o sube texto simple en markdown. - Elemento no devuelto en la consulta del agente: comprueba que el estado del elemento sea "Published" (no "draft"), que la base esté activa (no archivada) y que el token de cliente incluya el alcance knowledge:read. - Conflicto de actualización concurrente: si otro usuario o agente actualizó el elemento mientras tu edición estaba abierta, la consola muestra "This Knowledge item changed elsewhere. Refresh it and try again.". Actualiza la página y vuelve a aplicar los cambios. - Selección del modo de búsqueda: si la búsqueda híbrida pasa por alto símbolos exactos de runbooks o claves de configuración, cambia al modo léxico (mode="lexical") para una coincidencia exacta de tokens. ## Referencia relacionada Continúa explorando conceptos de bases de conocimiento, herramientas asociadas y gestión de espacios de trabajo: - Conceptos: bases de conocimiento (/docs/concepts/knowledge-bases) — modelo de arquitectura, DAG de revisiones y modos de recuperación. - Herramientas: search_knowledge (/docs/tools/search-knowledge) — referencia de herramienta para lecturas directas y parámetros de búsqueda. - Herramientas: recall_context (/docs/tools/recall-context) — herramienta de empaquetado de contexto con recuperación automática de Knowledge. - Guías: Memory Console (/docs/guides/memory-console) — guía completa de navegación por la consola web. - Conceptos: procedencia y atribución (/docs/concepts/provenance-attribution) — envoltorios de citación y atribución de autor. ## Usuario de ChatGPT Dale a ChatGPT acceso duradero a tus preferencias de XMemo, datos de proyecto, decisiones y TODOs sin pegar fichas bearer en un chat. Conecte el servidor XMemo MCP alojado a través de la aplicación ChatGPT/OpenAI OAuth flow, luego apruebe la subvención de memoria:read y memoria:write para su cuenta XMemo. Guarde una nota de preferencia sintética o de proyecto, inicie un nuevo chat y luego pida a ChatGPT que la recuerde a través de XMemo antes de continuar el trabajo. Si OAuth falla o las herramientas no aparecen, salir del servidor MCP en la aplicación host, volver a conectar la URL del servidor XMemo y volver a probar antes de crear tokens directos. ## Copiloto / Codex desarrollador Lleve decisiones de repo, convenciones de codificación, notas de corrección de errores e historial de tareas entre los agentes IDE y CLI. Use OAuth para VS Code / GitHub Copilot y Gemini CLI cuando esté disponible. Para Copilot CLI, Codex, Cursor u otros clientes MCP directos, mantenga XMEMO_KEY en el entorno local o en el almacén de secretos y establezca un XMEMO_AGENT_INSTANCE_ID estable. Grabe una decisión de base de código o corrección de errores, y luego pida al siguiente agente IDE o CLI que recuerde el contexto XMemo relevante antes de editarlo. Si las memorias están vacías, verifique la ruta de configuración MCP seleccionada, la variable de entorno XMEMO_KEY para clientes directos y cualquier credencial OAuth rancio en la aplicación host. ## Equipo / propietario del piloto de la empresa Evalúe la memoria compartida con controles de cuenta, atribución de origen, flujos de trabajo export/delete y pruebas de configuración seguras para los revisores. Cree o introduzca el espacio de trabajo protegido de XMemo, invite a usuarios aprobados, luego conecte a cada cliente a través de OAuth o una credencial directa con alcance de acuerdo con las insignias de preparación. Haga que un miembro piloto guarde una memoria sintética del equipo, confirme la atribución de origen en XMemo, luego revise delete/export y las rutas de soporte. Si un miembro no puede conectarse, compruebe los permisos de rol, la aprobación de OAuth, el estado de preparación del cliente y la orientación de soporte antes de emitir un nuevo token. ## Operador de agente autónomo Deje que los agentes sin cabeza o programados registren el progreso, recuperen decisiones previas y mantengan una identidad estable de instancia no secreta. Obtener /api/v1/mcp/config/autonomous-agent. Preferir auth_modes.oauth cuando el runner soporta OAuth + cabeceras personalizadas; utilice auth_modes.xmemo_key con XMEMO_KEY de una tienda secreta sólo para runners totalmente sin cabeza. Ejecute una tarea sintética que escriba el progreso a XMemo, reinicie el runner y confirme que recuerda que el progreso usando el mismo XMEMO_AGENT_INSTANCE_ID. Si la atribución cambia o recuerda dividida entre instancias, persistir XMEMO_AGENT_INSTANCE_ID fuera de git y verificar que el runner no lo esté regenerando en cada inicio.