EmpezarGuíasSolución de problemas

Guide

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.

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.

curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'X-API-Key: <your-assigned-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.

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.
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.
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Authorization: Bearer <your-token>' \
  '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.
curl -s -H 'Authorization: Bearer <your-token>' \
  '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.
curl -s -X POST 'https://xmemo.dev/v1/memories' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <generate-a-uuid-v4>' \
  -d '{"content":"Durable convention fact","path":"projects/demo/conventions"}'

Preguntas frecuentes / Solución de problemas

Empieza por las respuestas para usuarios de asistentes de IA y después consulta las respuestas para desarrolladores e integradores sobre los detalles de conexión y operaciones. Cada respuesta incluye un paso de acción y un límite de seguridad.

Para usuarios de asistentes de IA

Respuestas cotidianas para quienes usan XMemo a través de un asistente de IA sin configurar la conexión por su cuenta.

  1. ¿Por qué mi asistente de IA no recuerda algo que le conté antes?

    Síntoma
    Guardé una preferencia o un detalle importante, pero en un chat posterior mi asistente de IA actúa como si nunca lo hubiera visto.
    Causa
    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.
    Acción:
    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.
    Verificación
    Inicia un chat nuevo con el mismo asistente y pregúntale por el dato de prueba; elimínalo al terminar.
    Seguridad:
    Usa un dato de prueba inventado; no uses información privada de otra persona.

  2. ¿Por qué mi asistente de IA mezcla mis proyectos o conversaciones?

    Síntoma
    Un detalle de un proyecto aparece en otro, o el asistente responde como si dos conversaciones estuvieran relacionadas.
    Causa
    Es posible que el asistente esté usando un proyecto o contexto de cuenta distinto de aquel donde se guardó la memoria.
    Acción:
    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.
    Verificación
    Comprueba el proyecto y el origen de la memoria en Memory Console y confirma que un proyecto no relacionado no pueda ver ese dato de prueba.
    Seguridad:
    No muevas información privada entre proyectos solo para hacer que aparezca.

  3. ¿Cómo puedo hacer que mi asistente de IA olvide algo por completo?

    Síntoma
    Quiero eliminar una memoria y necesito saber si ya desapareció.
    Causa
    Ver una memoria, quitarla de forma recuperable, eliminarla permanentemente y exportarla son acciones distintas de la cuenta.
    Acción:
    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.
    Verificación
    Vuelve a buscar la memoria y confirma el estado que muestra Memory Console; comprueba que cualquier exportación solo contenga datos de tu cuenta.
    Seguridad:
    Elimina solo la memoria prevista y nunca incluyas contenido privado en un mensaje de soporte.

  4. ¿XMemo seguirá recordándome si cambio de ordenador o de asistente de IA?

    Síntoma
    Mis memorias antiguas parecen separadas de las nuevas después de cambiar de dispositivo, reiniciar un asistente o cambiar de host.
    Causa
    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.
    Acción:
    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.
    Verificación
    Guarda un dato de prueba inventado, inicia un chat nuevo en el mismo asistente y confirma que aparece sin cambiar de cuenta.
    Seguridad:
    Comprueba la cuenta antes de guardar información personal en un ordenador compartido.

  5. ¿Por qué mi asistente de IA guardó lo mismo dos veces?

    Síntoma
    Veo dos copias de lo que parece la misma memoria después de un reintento o una reconexión.
    Causa
    El primer guardado puede haber tenido éxito aunque el asistente no mostrara el resultado; al repetir la solicitud se creó otra copia.
    Acción:
    Abre Memory Console, compara las dos entradas y elimina solo el duplicado después de confirmar sus fechas y su origen.
    Verificación
    Pide al asistente que guarde una vez un dato de prueba nuevo y claramente etiquetado, y confirma que solo aparezca una entrada nueva.
    Seguridad:
    No elimines todas las memorias coincidentes hasta identificar la copia que quieres conservar.

  6. ¿Por qué mi asistente de IA me da demasiado o muy poco contexto del pasado?

    Síntoma
    El asistente recupera detalles no relacionados, omite la decisión que necesito o responde con una cantidad de información excesiva.
    Causa
    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.
    Acción:
    Pide un tema, proyecto o periodo más concreto e indica al asistente qué decisión o detalle es el más importante.
    Verificación
    Compara la respuesta con el tema solicitado y elimina de la conversación los detalles no relacionados antes de continuar.
    Seguridad:
    No pidas al asistente que revele memorias privadas no relacionadas solo para llenar la conversación.

  7. He desconectado XMemo; ¿cómo compruebo que el asistente antiguo no pueda usarlo?

    Síntoma
    Quité la conexión de un asistente, pero no sé si aún puede acceder a mis memorias.
    Causa
    Quitar una conexión en la aplicación puede no cancelar el permiso de conexión de la cuenta.
    Acción:
    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.
    Verificación
    Prueba la conexión antigua solo si es seguro hacerlo y confirma que sea rechazada antes de usar la nueva conexión.
    Seguridad:
    Revoca solo la conexión que quieras quitar y no compartas los datos de inicio de sesión de la cuenta.

  8. ¿Por qué mi asistente de IA ya no puede usar XMemo?

    Síntoma
    XMemo estaba disponible en mi asistente, pero sus acciones de memoria ya no aparecen o el asistente dice que no puede usarlas.
    Causa
    Es posible que el asistente necesite actualizar su conexión de XMemo o que haya iniciado sesión en otra cuenta.
    Acción:
    Abre la configuración de aplicaciones conectadas del asistente, desconecta y vuelve a conectar XMemo, y después inicia un chat nuevo.
    Verificación
    Pide al asistente que muestre si XMemo está conectado y prueba una lectura inocua antes de guardar nada.
    Seguridad:
    Nunca pegues datos secretos de la cuenta ni memorias privadas en un chat o una solicitud de soporte.

  9. ¿Qué conexión de XMemo debo usar en mi asistente de IA?

    Síntoma
    No sé qué página o conexión de XMemo corresponde a la configuración de mi asistente.
    Causa
    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.
    Acción:
    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.
    Verificación
    Antes de guardar un dato personal, confirma que la página usa la cuenta de XMemo y el servicio alojado que pretendes utilizar.
    Seguridad:
    No uses direcciones de desarrollo local ni pegues credenciales privadas en un chat público.

  10. ¿Qué hago si mi asistente de IA todavía no puede conectarse a XMemo?

    Síntoma
    Repetí los pasos de conexión, pero el asistente sigue sin poder usar XMemo.
    Causa
    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.
    Acción:
    Contacta con Support indicando el nombre del asistente, una hora aproximada y una descripción breve de lo que viste; incluye únicamente detalles redactados.
    Verificación
    Asegúrate de que el informe se pueda reproducir sin enviar memorias privadas ni secretos de la cuenta.
    Seguridad:
    Nunca envíes datos de inicio de sesión, códigos de un solo uso, cookies ni texto de memorias privadas.

Para desarrolladores e integradores

Respuestas sobre conexión, límites de cuenta, clientes y operaciones para quienes integran XMemo.

  1. OAuth falla o la ventana de consentimiento nunca termina.

    Síntoma
    El cliente muestra 401, el navegador de OAuth no se abre o el consentimiento devuelve el control al cliente sin una conexión utilizable.
    Causa
    La concesión alojada puede estar obsoleta, el traspaso al navegador puede estar bloqueado o el cliente puede usar un registro de servidor antiguo.
    Acción:
    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.
    Verificación
    Vuelve a conectar hasta que el cliente informe de una autorización activa y ejecuta una recuperación inocua antes de escribir memoria.
    Seguridad:
    No cambies a XMEMO_KEY dentro de clientes OAuth solo para evitar una sesión OAuth obsoleta.

  2. La solicitud devuelve 403 Forbidden.

    Síntoma
    El servidor es accesible y reconoce la credencial, pero rechaza el proyecto, la herramienta o la acción de memoria solicitados.
    Causa
    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.
    Acción:
    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.
    Verificación
    Confirma que una solicitud de solo lectura en el proyecto previsto funciona antes de repetir una operación de escritura o eliminación.
    Seguridad:
    No amplíes los ámbitos ni copies el token de otro usuario para hacer desaparecer un 403.

  3. El servidor MCP se conecta, pero no aparecen herramientas.

    Síntoma
    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.
    Causa
    El cliente no ha actualizado el descubrimiento, usa el perfil MCP equivocado o está conectado a una URL o un registro obsoletos.
    Acción:
    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.
    Verificación
    Confirma que aparecen al menos remember, recall y search_memory antes de iniciar una escritura o una demostración de marketplace.
    Seguridad:
    No pegues tokens bearer en capturas de pantalla, tickets de soporte ni notas de revisión de marketplace.

  4. Un cliente MCP directo dice que falta el token.

    Síntoma
    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.
    Causa
    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.
    Acción:
    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.
    Verificación
    Inspecciona solo los metadatos de presencia de la variable, reinicia el cliente y confirma una recuperación autenticada inocua; nunca muestres el valor del token.
    Seguridad:
    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.

  5. El ID de instancia del agente cambia después de cada reinicio.

    Síntoma
    El mismo ejecutor local aparece como varios agentes o las recuperaciones se separan entre instancias después de un reinicio o un nuevo despliegue.
    Causa
    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.
    Acción:
    Genera una etiqueta de instancia no secreta por ejecutor, persístela fuera de git y envíala con cada conexión MCP directa.
    Verificación
    Reinicia el ejecutor dos veces y confirma que la misma etiqueta de instancia aparece en la atribución de origen sin exponer credenciales.
    Seguridad:
    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.

  6. La recuperación devuelve una memoria vacía.

    Síntoma
    Una recuperación o búsqueda tiene éxito, pero no devuelve registros relevantes después de que el usuario haya guardado contexto.
    Causa
    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ó.
    Acción:
    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.
    Verificación
    Vuelve a leer el registro sintético recién creado con el mismo proyecto y ámbito y después elimínalo mediante la ruta de eliminación prevista.
    Seguridad:
    Usa datos sintéticos de revisión; no uses memoria privada de clientes en una demostración de marketplace.

  7. La recuperación o la escritura usa el ámbito de proyecto equivocado.

    Síntoma
    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.
    Causa
    El cliente reutilizó un identificador de proyecto de otro entorno, omitió el límite del proyecto o conservó una sesión de cuenta obsoleta.
    Acción:
    Selecciona explícitamente la cuenta y el proyecto correctos, actualiza el contexto del cliente y repite la operación con un registro sintético.
    Verificación
    Confirma la atribución de proyecto y origen del registro en Memory Console y verifica que un proyecto no relacionado no pueda leerlo.
    Seguridad:
    Nunca resuelvas un desajuste de ámbito concediendo un token más amplio o copiando datos entre proyectos.

  8. La misma memoria se guarda dos veces.

    Síntoma
    Un reintento o una reconexión produce registros duplicados en lugar de una sola memoria duradera.
    Causa
    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.
    Acción:
    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.
    Verificación
    Repite una sola vez la misma captura controlada y confirma un registro nuevo y una lectura de vuelta, no dos registros nuevos.
    Seguridad:
    No elimines en bloque las memorias coincidentes hasta confirmar el registro previsto y el ámbito de la cuenta.

  9. El contexto de recuperación es demasiado grande o demasiado pequeño.

    Síntoma
    El agente recibe contexto irrelevante, omite la decisión necesaria o supera el presupuesto de contexto útil del host.
    Causa
    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.
    Acción:
    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.
    Verificación
    Compara el contexto devuelto con la pregunta objetivo y confirma que cada registro incluido está autorizado y resulta útil.
    Seguridad:
    No amplíes el ámbito ni exportes memoria no relacionada solo para llenar una ventana de contexto.

  10. ¿Cómo elimino o exporto una memoria?

    Síntoma
    El operador necesita quitar un registro, confirmar una acción de olvido u obtener una exportación limitada a la cuenta.
    Causa
    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.
    Acció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.
    Verificación
    Después de olvidar o eliminar, busca por la referencia del registro y confirma el estado recuperable o permanente esperado; verifica que las exportaciones solo contengan el ámbito de la cuenta.
    Seguridad:
    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.

  11. ¿Cómo revoco el acceso después de desconectar un cliente?

    Síntoma
    Se quitó un cliente localmente, pero el operador necesita invalidar su concesión OAuth o su credencial directa.
    Causa
    Desconectar una configuración de cliente no revoca necesariamente la concesión del servidor ni rota un token directo.
    Acción:
    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.
    Verificación
    Reintenta una lectura autenticada con la conexión antigua y confirma que sea rechazada; después vuelve a conectar solo mediante la ruta prevista de consentimiento o almacén de secretos.
    Seguridad:
    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.

  12. ¿XMemo está en disponibilidad general (GA), certificado o listado en un marketplace?

    Síntoma
    Un listado o documento pregunta si una configuración funcional demuestra disponibilidad general, certificación o aprobación para un marketplace.
    Causa
    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.
    Acción:
    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.
    Verificación
    Comprueba la matriz canónica de capacidades del cliente y el artefacto de aprobación indicado antes de publicar una afirmación de estado.
    Seguridad:
    No afirmes que está en GA, certificado, estable o listado basándote solo en una configuración funcional.

  13. ¿Qué URL debo usar?

    Síntoma
    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.
    Causa
    La incorporación alojada y la ruta autogestionada o heredada tienen URL, credenciales y límites de datos diferentes.
    Acción:
    Los usuarios alojados deben empezar con https://xmemo.dev/mcp para clientes MCP y https://xmemo.dev/product/docs para la configuración guiada.
    Verificación
    Confirma que la URL del host, el modo de autenticación y el límite de la cuenta coinciden con el despliegue alojado o autogestionado previsto antes de conectarte.
    Seguridad:
    No uses localhost, Supabase, Docker ni instrucciones Python autogestionadas como primera ruta para usuarios del servicio público alojado.

  14. La memoria aparece bajo el agente o dispositivo equivocado.

    Síntoma
    Una memoria se atribuye a otro ejecutor o aparece separada entre dispositivos después de una actualización o un reinicio del cliente.
    Causa
    El cliente cambió sus cabeceras de agente o instancia no secretas, o varias instancias comparten una misma credencial.
    Acción:
    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.
    Verificación
    Escribe un registro sintético desde el ejecutor previsto y confirma que su atribución de origen permanece estable después de reconectar.
    Seguridad:
    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.

  15. Sigo sin poder conectarme después de seguir los pasos.

    Síntoma
    La conexión sigue sin estar disponible después de repetir la ruta OAuth o de secreto directo específica del cliente.
    Causa
    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.
    Acción:
    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.
    Verificación
    Confirma que el informe de soporte contiene un síntoma reproducible y metadatos redactados; después espera el diagnóstico limitado a la cuenta.
    Seguridad:
    Comparte solo diagnósticos redactados; nunca envíes tokens bearer, códigos OAuth, cookies ni contenido de memorias de clientes.

Fuente: Preguntas frecuentes / Solución de problemas