# Solución de problemas Usa las indicaciones de síntoma, causa, acción y seguridad cuando OAuth, el descubrimiento MCP o la recuperación no funcionen como esperas. - Canonical: https://docs.xmemo.dev/es/docs/troubleshooting - Locale: es-ES - Content-Locale: es-ES - Canonical-Content-Digest: 78719b9cecfa970434f8f31e363e6e5cca1f6171a945b7c98cd4db05a669dc4b - Edition-Digest: e12aee94811654401e5a567dae7d5741bad8ce6aa553371b89cfb02e8c12e565 - Source-Revision: sha256:888cdc62dd33778dae5cd658cec828efa3504abd545d98fc35af9f3fbd35157a ## Verificar una conexión sin escribir memory Cada ruta de resolución de problemas a continuación finaliza con un paso de verification. Comience con una lectura: prueba credential y transport sin cambiar nada. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'X-API-Key: ' \ 'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1' ``` ## Leer el status code El status separa un problema de credential de un memory store vacío. ```text 200 — authorized; an empty results array just means nothing matched. 401 — the credential is missing or not valid. 403 — the credential is valid but lacks the required scope. ``` ## Errores de conexión del cliente Cuando un cliente de IA o ejecutor no pueda comunicarse con el servidor MCP, aísle la negociación del protocolo de transporte y el enrutamiento antes de rotar tokens. - Verifique el estado del servidor con un GET directo a /health o OPTIONS a /mcp. - Compruebe la compatibilidad del transporte: los clientes alojados usan Streamable HTTP (/mcp); las herramientas locales de CLI usan stdio. - Asegúrese de que los servidores proxy o firewalls corporativos permitan respuestas SSE en streaming sin truncamiento de fragmentos. ```bash curl -I -s 'https://xmemo.dev/mcp' ``` ## Fallos de autenticación Los fallos de autenticación distinguen credenciales ausentes (401 Unauthorized) de permisos insuficientes o violaciones de límites de inquilinos (403 Forbidden). - Clientes OAuth: Vuelva a conectarse a través de la aplicación host y otorgue memory:read y memory:write. - Clientes Direct MCP: Verifique que XMEMO_KEY esté configurada en el entorno del proceso sin exponer secretos en git. - 403 Forbidden: Confirme que el token pertenezca al inquilino y project scope activos. ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=auth%20check&limit=1' ``` ## Resultados de recuperación vacíos Una recuperación que no devuelve ningún resultado indica un desajuste de ámbito o de consulta más que un fallo del motor. Las lecturas devuelven 200 OK si no coinciden memorias. - Desajuste de project scope: Verifique que el agente consultor opere dentro del mismo project que la memoria guardada. - Límite de instancia del agente: Los clientes Direct que filtran por XMEMO_AGENT_INSTANCE_ID no pueden leer memorias guardadas con diferentes identificadores de instancia. - Comprobación de estado: Verifique en Memory Console que la memoria esté confirmada y tenga estado active, no eliminada ni reemplazada. ```bash curl -s -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo' ``` ## Tiempos de espera de bloqueo de escritura Las escrituras concurrentes desde múltiples ejecutores o invocaciones de herramientas paralelas pueden causar contención de bloqueo en memory paths compartidos. - Implemente retroceso exponencial con fluctuación aleatoria cuando las solicitudes de escritura devuelvan contención de bloqueo. - Proporcione una clave de idempotencia (idempotency key) del cliente en los reintentos de escritura para evitar duplicados. - Serialice las mutaciones de memoria para flujos de trabajo de alta frecuencia mediante colas de tareas o APIs por lotes. ```bash curl -s -X POST 'https://xmemo.dev/v1/memories' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{"content":"Durable convention fact","path":"projects/demo/conventions"}' ``` ## ¿Por qué mi asistente de IA no recuerda algo que le conté antes? Guardé una preferencia o un detalle importante, pero en un chat posterior mi asistente de IA actúa como si nunca lo hubiera visto. Es posible que el asistente esté conectado a otra cuenta de XMemo, otro proyecto o el contexto de otro dispositivo, o que la memoria original no se haya guardado. Pide al asistente que guarde un pequeño dato de prueba no sensible; después abre Memory Console y comprueba que aparezca en la cuenta y el proyecto que utilizas. Usa un dato de prueba inventado; no uses información privada de otra persona. ## ¿Por qué mi asistente de IA mezcla mis proyectos o conversaciones? Un detalle de un proyecto aparece en otro, o el asistente responde como si dos conversaciones estuvieran relacionadas. Es posible que el asistente esté usando un proyecto o contexto de cuenta distinto de aquel donde se guardó la memoria. En el asistente, selecciona la cuenta y el proyecto de XMemo correctos, vuelve a conectarlo si hace falta y repite la prueba con un dato claramente etiquetado. No muevas información privada entre proyectos solo para hacer que aparezca. ## ¿Cómo puedo hacer que mi asistente de IA olvide algo por completo? Quiero eliminar una memoria y necesito saber si ya desapareció. Ver una memoria, quitarla de forma recuperable, eliminarla permanentemente y exportarla son acciones distintas de la cuenta. Abre Memory Console, busca la memoria y usa el control para eliminarla u olvidarla; si no encuentras el control, contacta con Support e indica la referencia de la memoria. Elimina solo la memoria prevista y nunca incluyas contenido privado en un mensaje de soporte. ## ¿XMemo seguirá recordándome si cambio de ordenador o de asistente de IA? Mis memorias antiguas parecen separadas de las nuevas después de cambiar de dispositivo, reiniciar un asistente o cambiar de host. La nueva conexión del asistente puede identificar el dispositivo o el asistente como una fuente nueva, o puede haber iniciado sesión en otra cuenta. Vuelve a conectar XMemo en el asistente que quieras usar, inicia sesión en la misma cuenta y mantén estable la etiqueta del dispositivo de la conexión cuando la aplicación ofrezca esa opción. Comprueba la cuenta antes de guardar información personal en un ordenador compartido. ## ¿Por qué mi asistente de IA guardó lo mismo dos veces? Veo dos copias de lo que parece la misma memoria después de un reintento o una reconexión. El primer guardado puede haber tenido éxito aunque el asistente no mostrara el resultado; al repetir la solicitud se creó otra copia. Abre Memory Console, compara las dos entradas y elimina solo el duplicado después de confirmar sus fechas y su origen. No elimines todas las memorias coincidentes hasta identificar la copia que quieres conservar. ## ¿Por qué mi asistente de IA me da demasiado o muy poco contexto del pasado? El asistente recupera detalles no relacionados, omite la decisión que necesito o responde con una cantidad de información excesiva. El tema o el periodo de la solicitud son demasiado amplios, o el asistente intenta usar más contexto guardado del que necesita la conversación. Pide un tema, proyecto o periodo más concreto e indica al asistente qué decisión o detalle es el más importante. No pidas al asistente que revele memorias privadas no relacionadas solo para llenar la conversación. ## He desconectado XMemo; ¿cómo compruebo que el asistente antiguo no pueda usarlo? Quité la conexión de un asistente, pero no sé si aún puede acceder a mis memorias. Quitar una conexión en la aplicación puede no cancelar el permiso de conexión de la cuenta. Abre los controles de aplicaciones conectadas o de seguridad de tu cuenta de XMemo, revoca la conexión del asistente antiguo y vuelve a conectar solo la que consideres de confianza. Revoca solo la conexión que quieras quitar y no compartas los datos de inicio de sesión de la cuenta. ## ¿Por qué mi asistente de IA ya no puede usar XMemo? XMemo estaba disponible en mi asistente, pero sus acciones de memoria ya no aparecen o el asistente dice que no puede usarlas. Es posible que el asistente necesite actualizar su conexión de XMemo o que haya iniciado sesión en otra cuenta. Abre la configuración de aplicaciones conectadas del asistente, desconecta y vuelve a conectar XMemo, y después inicia un chat nuevo. Nunca pegues datos secretos de la cuenta ni memorias privadas en un chat o una solicitud de soporte. ## ¿Qué conexión de XMemo debo usar en mi asistente de IA? No sé qué página o conexión de XMemo corresponde a la configuración de mi asistente. La página de configuración guiada y la conexión del asistente tienen fines distintos, y las configuraciones alojadas y autogestionadas tienen límites diferentes. Para el servicio alojado, empieza en https://xmemo.dev/product/docs y sigue el enlace de conexión que aparece para tu asistente; pregunta a Support si tu organización te dio otra página de configuración. No uses direcciones de desarrollo local ni pegues credenciales privadas en un chat público. ## ¿Qué hago si mi asistente de IA todavía no puede conectarse a XMemo? Repetí los pasos de conexión, pero el asistente sigue sin poder usar XMemo. El problema puede pertenecer a la aplicación del asistente, a mi cuenta o a una conexión obsoleta que las instrucciones públicas no pueden inspeccionar. Contacta con Support indicando el nombre del asistente, una hora aproximada y una descripción breve de lo que viste; incluye únicamente detalles redactados. Nunca envíes datos de inicio de sesión, códigos de un solo uso, cookies ni texto de memorias privadas. ## OAuth falla o la ventana de consentimiento nunca termina. El cliente muestra 401, el navegador de OAuth no se abre o el consentimiento devuelve el control al cliente sin una conexión utilizable. La concesión alojada puede estar obsoleta, el traspaso al navegador puede estar bloqueado o el cliente puede usar un registro de servidor antiguo. Cierra la sesión del servidor MCP de XMemo en la aplicación anfitriona, vuelve a conectar la URL MCP alojada y aprueba de nuevo memory:read y memory:write. No cambies a XMEMO_KEY dentro de clientes OAuth solo para evitar una sesión OAuth obsoleta. ## La solicitud devuelve 403 Forbidden. El servidor es accesible y reconoce la credencial, pero rechaza el proyecto, la herramienta o la acción de memoria solicitados. A la concesión le falta el ámbito necesario, la cuenta está fuera del límite del proyecto seleccionado o el recurso pertenece a otro tenant. Comprueba la cuenta y el proyecto seleccionados, vuelve a conectar OAuth o solicita el ámbito previsto y repite la misma operación sin cambiar el recurso. No amplíes los ámbitos ni copies el token de otro usuario para hacer desaparecer un 403. ## El servidor MCP se conecta, pero no aparecen herramientas. El host muestra un servidor conectado, pero tools/list está vacío o las herramientas de XMemo faltan en el selector de herramientas del modelo. El cliente no ha actualizado el descubrimiento, usa el perfil MCP equivocado o está conectado a una URL o un registro obsoletos. Vuelve a conectar el servidor, verifica que el cliente use el perfil MCP compatible y ejecuta de nuevo el descubrimiento de herramientas antes de cambiar las credenciales. No pegues tokens bearer en capturas de pantalla, tickets de soporte ni notas de revisión de marketplace. ## Un cliente MCP directo dice que falta el token. Un cliente directo informa de que XMEMO_KEY no está definida, está vacía o no está disponible aunque la variable se haya añadido en algún lugar del equipo. El proceso del cliente no heredó el entorno, la variable se añadió a otro shell o la configuración espera en su lugar una referencia a un almacén de secretos. Define XMEMO_KEY en el entorno local o en el almacén de secretos, reinicia el cliente y mantén estable XMEMO_AGENT_INSTANCE_ID cuando importe la atribución. Mantén el token real fuera de los archivos de configuración confirmados en git; los ejemplos públicos deben referirse solo a variables de entorno. ## El ID de instancia del agente cambia después de cada reinicio. El mismo ejecutor local aparece como varios agentes o las recuperaciones se separan entre instancias después de un reinicio o un nuevo despliegue. XMEMO_AGENT_INSTANCE_ID se genera al iniciar el proceso en lugar de persistirse en el secreto local o la configuración de entorno del ejecutor. Genera una etiqueta de instancia no secreta por ejecutor, persístela fuera de git y envíala con cada conexión MCP directa. La etiqueta de instancia es metadatos de atribución, no una credencial de autorización; la cuenta y los límites del token siguen controlando el acceso. ## La recuperación devuelve una memoria vacía. Una recuperación o búsqueda tiene éxito, pero no devuelve registros relevantes después de que el usuario haya guardado contexto. La lectura usa otra cuenta, proyecto, ámbito, límite de agente o tipo de memoria distinto del usado al escribir, o el registro de prueba nunca se confirmó. Crea una memoria de prueba sintética, verifica la ruta y el tipo de memoria en Memory Console y vuelve a intentar la recuperación desde el mismo límite de cuenta o tenant. Usa datos sintéticos de revisión; no uses memoria privada de clientes en una demostración de marketplace. ## La recuperación o la escritura usa el ámbito de proyecto equivocado. Un registro es visible en un proyecto pero no en otro, o una escritura aparece bajo un proyecto que el operador no pretendía usar. El cliente reutilizó un identificador de proyecto de otro entorno, omitió el límite del proyecto o conservó una sesión de cuenta obsoleta. Selecciona explícitamente la cuenta y el proyecto correctos, actualiza el contexto del cliente y repite la operación con un registro sintético. Nunca resuelvas un desajuste de ámbito concediendo un token más amplio o copiando datos entre proyectos. ## La misma memoria se guarda dos veces. Un reintento o una reconexión produce registros duplicados en lugar de una sola memoria duradera. El cliente reintentó después de un tiempo de espera sin un límite de idempotencia, o el flujo de captura escribe antes de confirmar la primera respuesta. Inspecciona primero el registro existente y la atribución de origen; después usa la política de reintentos del cliente o una clave de idempotencia estable antes de volver a escribir. No elimines en bloque las memorias coincidentes hasta confirmar el registro previsto y el ámbito de la cuenta. ## El contexto de recuperación es demasiado grande o demasiado pequeño. El agente recibe contexto irrelevante, omite la decisión necesaria o supera el presupuesto de contexto útil del host. La consulta es demasiado amplia, falta el ámbito o la ventana temporal, o el llamador solicitó un límite de resultados inadecuado para la tarea. Acota la consulta con límites de proyecto, agente, tiempo o tema y solicita un conjunto pequeño y relevante antes de ampliar el límite. No amplíes el ámbito ni exportes memoria no relacionada solo para llenar una ventana de contexto. ## ¿Cómo elimino o exporto una memoria? El operador necesita quitar un registro, confirmar una acción de olvido u obtener una exportación limitada a la cuenta. La eliminación, el olvido recuperable, la eliminación permanente y la exportación son flujos distintos con semánticas diferentes de confirmación y recuperación. Usa primero Memory Console o los flujos de la cuenta; si no hay una ruta de autoservicio, contacta con Support para que la solicitud siga limitada a la cuenta. Las exportaciones y los paquetes de soporte deben excluir hashes de tokens, claves de API, secretos de sesión, credenciales de proveedores y datos de otros tenants. ## ¿Cómo revoco el acceso después de desconectar un cliente? Se quitó un cliente localmente, pero el operador necesita invalidar su concesión OAuth o su credencial directa. Desconectar una configuración de cliente no revoca necesariamente la concesión del servidor ni rota un token directo. Abre los controles de seguridad de la cuenta o de clientes conectados, revoca la concesión OAuth indicada y rota la credencial directa si se expuso o dejó de ser de confianza. Revoca únicamente el cliente o la concesión previstos; no publiques tokens antiguos, códigos OAuth ni datos de sesión mientras diagnosticas el acceso. ## ¿XMemo está en disponibilidad general (GA), certificado o listado en un marketplace? Un listado o documento pregunta si una configuración funcional demuestra disponibilidad general, certificación o aprobación para un marketplace. La compatibilidad de configuración, la preparación para OAuth, la evidencia de un piloto y la aprobación de un marketplace son afirmaciones distintas. Trata el texto público como beta o como compatible con la configuración, salvo que exista un artefacto específico de aprobación de marketplace o certificación. No afirmes que está en GA, certificado, estable o listado basándote solo en una configuración funcional. ## ¿Qué URL debo usar? Un usuario del servicio alojado no sabe si debe seguir el inicio rápido público, el endpoint MCP o las instrucciones para desarrolladores autogestionados. La incorporación alojada y la ruta autogestionada o heredada tienen URL, credenciales y límites de datos diferentes. Los usuarios alojados deben empezar con https://xmemo.dev/mcp para clientes MCP y https://xmemo.dev/product/docs para la configuración guiada. No uses localhost, Supabase, Docker ni instrucciones Python autogestionadas como primera ruta para usuarios del servicio público alojado. ## La memoria aparece bajo el agente o dispositivo equivocado. Una memoria se atribuye a otro ejecutor o aparece separada entre dispositivos después de una actualización o un reinicio del cliente. El cliente cambió sus cabeceras de agente o instancia no secretas, o varias instancias comparten una misma credencial. Comprueba las cabeceras no secretas del agente o dispositivo o el perfil del cliente y persiste el ID de instancia local en lugar de regenerarlo. Las etiquetas de atribución ayudan a revisar el origen, pero no son un límite de seguridad; las credenciales de la cuenta siguen decidiendo el acceso. ## Sigo sin poder conectarme después de seguir los pasos. La conexión sigue sin estar disponible después de repetir la ruta OAuth o de secreto directo específica del cliente. El problema restante puede ser específico del cliente, de la cuenta o de un registro obsoleto o límite del entorno que la documentación local no puede inspeccionar. Abre una solicitud en Support con el nombre del cliente, la ruta de configuración, la hora aproximada y si usa OAuth o XMEMO_KEY. Comparte solo diagnósticos redactados; nunca envíes tokens bearer, códigos OAuth, cookies ni contenido de memorias de clientes.