ComeçarGuiasSolução de problemas

Guide

Solução de problemas

Use orientações sobre sintoma, causa, ação e segurança quando OAuth, descoberta MCP ou recall não funcionar como esperado.

Verificar uma conexão sem gravar memory

Cada caminho de solução de problemas abaixo termina com uma etapa de verification. Comece com uma leitura: ela comprova credential e transport sem alterar 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'

Lendo o status code

O status separa um problema de credential de um memory store vazio.

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.

Erros de conexão do cliente

Quando um cliente de IA ou executor não conseguir alcançar o servidor MCP, isole a negociação do protocolo de transporte e o roteamento antes de alternar tokens.

  • Verifique a integridade do servidor com um GET direto para /health ou OPTIONS para /mcp.
  • Verifique a compatibilidade do transporte: clientes hospedados usam Streamable HTTP (/mcp); ferramentas CLI locais usam stdio.
  • Certifique-se de que proxies ou firewalls corporativos permitam respostas SSE em streaming sem truncamento de pacotes.
curl -I -s 'https://xmemo.dev/mcp'

Falhas de autenticação

Falhas de autenticação diferenciam credenciais ausentes (401 Unauthorized) de permissões insuficientes ou violações de limite de locatário (403 Forbidden).

  • Clientes OAuth: Reconecte por meio do aplicativo host e conceda permissões memory:read e memory:write.
  • Clientes Direct MCP: Verifique se XMEMO_KEY está configurada no ambiente do processo sem expor segredos no git.
  • 403 Forbidden: Confirme se o token pertence ao locatário e project scope ativos.
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 recuperação vazios

Uma recuperação retornando zero resultados indica incompatibilidade de escopo ou consulta, e não falha no mecanismo. As leituras retornam 200 OK quando não há correspondências.

  • Incompatibilidade de project scope: Verifique se o agente que faz a consulta opera no mesmo project da memória salva.
  • Limite de instância do agente: Clientes Direct que filtram por XMEMO_AGENT_INSTANCE_ID não podem ler memórias salvas com identificadores de instância diferentes.
  • Verificação de status: Verifique no Memory Console se a memória foi confirmada e tem status active, não excluída ou obsoleta.
curl -s -H 'Authorization: Bearer <your-token>' \
  'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo'

Tempos limite de bloqueio de gravação

Gravações simultâneas de múltiplos executores ou execuções de ferramentas paralelas podem causar contenção de bloqueio em memory paths compartilhados.

  • Implemente recuo exponencial com variação aleatória quando as solicitações de gravação retornarem contenção de bloqueio.
  • Forneça uma chave de idempotência (idempotency key) do lado do cliente em tentativas de repetição para evitar duplicatas.
  • Serialize mutações de memória para fluxos de trabalho de alta frequência usando filas de tarefas ou APIs em lote.
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"}'

Perguntas frequentes / Solução de problemas

Comece pelas respostas para usuários de assistentes de IA e depois consulte as respostas para desenvolvedores e integradores sobre detalhes de conexão e operações. Cada resposta inclui uma ação e um limite de segurança.

Para usuários de assistentes de IA

Respostas cotidianas para pessoas que usam o XMemo por meio de um assistente de IA sem configurar a conexão por conta própria.

  1. Por que meu assistente de IA não se lembra de algo que eu contei antes?

    Sintoma
    Salvei uma preferência ou um detalhe importante, mas, em um chat posterior, meu assistente de IA age como se nunca tivesse visto isso.
    Causa
    O assistente pode estar conectado a outra conta, projeto ou contexto de dispositivo do XMemo, ou a memória original pode não ter sido salva.
    Ação:
    Peça ao assistente para salvar um pequeno detalhe de teste não sensível; depois abra o Memory Console e verifique se ele aparece na conta e no projeto que você usa.
    Verificação
    Inicie um chat novo com o mesmo assistente e pergunte sobre o detalhe de teste; remova a entrada quando terminar.
    Segurança:
    Use um detalhe de teste inventado; não use informações privadas de outra pessoa.

  2. Por que meu assistente de IA está misturando meus projetos ou conversas?

    Sintoma
    Um detalhe de um projeto aparece em outro, ou o assistente responde como se duas conversas fizessem parte do mesmo contexto.
    Causa
    O assistente pode estar usando um projeto ou contexto de conta diferente daquele em que a memória foi salva.
    Ação:
    No assistente, escolha a conta e o projeto XMemo corretos, reconecte-o se necessário e tente novamente com um detalhe de teste claramente identificado.
    Verificação
    Confira o projeto e a origem da memória no Memory Console e confirme que um projeto não relacionado não consegue ver esse detalhe de teste.
    Segurança:
    Não mova informações privadas entre projetos apenas para fazê-las aparecer.

  3. Como faço para que meu assistente de IA esqueça algo completamente?

    Sintoma
    Quero remover uma memória e preciso saber se ela foi apagada.
    Causa
    Visualizar, remover de forma recuperável, excluir permanentemente e exportar memória são ações diferentes na conta.
    Ação:
    Abra o Memory Console, encontre a memória e use o controle de excluir ou esquecer; se não encontrar o controle, entre em contato com o Suporte informando a referência da memória.
    Verificação
    Pesquise a memória novamente e confirme o estado mostrado pelo Memory Console; verifique se qualquer exportação contém apenas dados da sua conta.
    Segurança:
    Exclua somente a memória pretendida e nunca inclua conteúdo privado em uma mensagem ao Suporte.

  4. Troquei de computador ou de assistente de IA; o XMemo ainda vai se lembrar de mim?

    Sintoma
    Minhas memórias antigas parecem separadas das novas depois que troquei de dispositivo, reiniciei um assistente ou mudei de host.
    Causa
    A nova conexão do assistente pode identificar o dispositivo ou assistente como uma nova origem, ou pode estar conectada a outra conta.
    Ação:
    Reconecte o XMemo no assistente que você quer usar, entre na mesma conta e mantenha estável o rótulo do dispositivo da conexão quando o aplicativo oferecer essa opção.
    Verificação
    Salve um detalhe de teste inventado, inicie um chat novo no mesmo assistente e confirme que o detalhe aparece sem trocar de conta.
    Segurança:
    Confira a conta antes de salvar qualquer dado pessoal em um computador compartilhado.

  5. Por que meu assistente de IA salvou a mesma coisa duas vezes?

    Sintoma
    Vejo duas cópias que parecem ser a mesma memória depois de uma nova tentativa ou reconexão.
    Causa
    O primeiro salvamento pode ter sido concluído mesmo que o assistente não tenha mostrado o resultado; repetir a solicitação criou outra cópia.
    Ação:
    Abra o Memory Console, compare as duas entradas e remova apenas a duplicata depois de confirmar as datas e a origem.
    Verificação
    Peça ao assistente para salvar uma vez um novo detalhe de teste claramente identificado e confirme que apenas uma nova entrada aparece.
    Segurança:
    Não exclua todas as memórias correspondentes até identificar a cópia que quer manter.

  6. Por que meu assistente de IA está trazendo contexto demais ou de menos do meu histórico?

    Sintoma
    O assistente traz detalhes sem relação, não encontra a decisão de que preciso ou dá uma resposta sobrecarregada.
    Causa
    A solicitação abrange um tema ou período amplo demais, ou o assistente está tentando usar mais contexto salvo do que a conversa precisa.
    Ação:
    Peça um tema, projeto ou período mais específico e diga ao assistente qual decisão ou detalhe é mais importante.
    Verificação
    Compare a resposta com o tema solicitado e remova da conversa qualquer detalhe sem relação antes de continuar.
    Segurança:
    Não peça ao assistente para revelar memórias privadas sem relação apenas para preencher a conversa.

  7. Desconectei o XMemo; como garanto que o assistente antigo não possa mais usá-lo?

    Sintoma
    Removi a conexão de um assistente, mas não sei se ele ainda consegue acessar minhas memórias.
    Causa
    Remover uma conexão no aplicativo pode não cancelar a permissão da conexão na conta.
    Ação:
    Abra os controles de aplicativos conectados ou de segurança da sua conta XMemo, revogue a conexão do assistente antigo e reconecte somente a que você considera confiável.
    Verificação
    Tente a conexão antiga apenas se for seguro e confirme que ela é recusada antes de usar a nova conexão.
    Segurança:
    Revogue apenas a conexão que pretende remover e não compartilhe dados de login da conta.

  8. Por que meu assistente de IA não consegue mais usar o XMemo?

    Sintoma
    O XMemo costumava estar disponível no meu assistente, mas as ações de memória não aparecem mais ou o assistente diz que não pode usá-las.
    Causa
    O assistente pode precisar atualizar a conexão com o XMemo ou pode estar conectado a outra conta.
    Ação:
    Abra as configurações de aplicativos conectados do assistente, desconecte e reconecte o XMemo e inicie um chat novo.
    Verificação
    Peça ao assistente para mostrar se o XMemo está conectado e faça uma leitura inofensiva antes de salvar qualquer coisa.
    Segurança:
    Nunca cole dados secretos da conta ou memórias privadas em um chat ou solicitação de suporte.

  9. Qual conexão do XMemo devo usar no meu assistente de IA?

    Sintoma
    Não sei qual página ou conexão do XMemo deve ser usada nas configurações do meu assistente.
    Causa
    A página de configuração guiada e a conexão do assistente têm finalidades diferentes, e configurações hospedadas e autogerenciadas têm limites diferentes.
    Ação:
    Para o serviço hospedado, comece em https://xmemo.dev/product/docs e siga o link de conexão mostrado para seu assistente; pergunte ao Suporte se sua organização forneceu uma página de configuração diferente.
    Verificação
    Antes de salvar um dado pessoal, confirme que a página usa a conta XMemo e o serviço hospedado pretendidos.
    Segurança:
    Não use endereços de desenvolvimento local nem cole credenciais privadas em um chat público.

  10. O que faço se meu assistente de IA ainda não conseguir se conectar ao XMemo?

    Sintoma
    Tentei novamente os passos de conexão, mas o assistente ainda não consegue usar o XMemo.
    Causa
    O problema pode estar no aplicativo do assistente, na minha conta ou em uma conexão antiga que as instruções públicas não conseguem inspecionar.
    Ação:
    Entre em contato com o Suporte informando o nome do assistente, o horário aproximado e uma breve descrição do que você viu; inclua somente dados redigidos.
    Verificação
    Garanta que o relato possa ser reproduzido sem enviar memórias privadas ou segredos da conta.
    Segurança:
    Nunca envie dados de login, códigos de uso único, cookies ou texto de memória privada.

Para desenvolvedores e integradores

Respostas sobre conexão, limites de conta, clientes e operações para quem integra o XMemo.

  1. O OAuth falhou ou a janela de consentimento nunca termina.

    Sintoma
    O cliente mostra 401, o navegador do OAuth não abre ou o consentimento retorna ao cliente sem uma conexão utilizável.
    Causa
    A concessão hospedada pode estar desatualizada, a transferência para o navegador pode estar bloqueada ou o cliente pode estar usando um registro antigo do servidor.
    Ação:
    Saia do servidor MCP do XMemo no aplicativo host, reconecte a URL do MCP hospedado e aprove novamente memory:read e memory:write.
    Verificação
    Reconecte até o cliente informar uma autorização ativa e depois execute um recall inofensivo antes de gravar memória.
    Segurança:
    Não troque para XMEMO_KEY dentro de clientes OAuth apenas para contornar uma sessão OAuth desatualizada.

  2. A solicitação retorna 403 Forbidden.

    Sintoma
    O servidor está acessível e a credencial é reconhecida, mas o projeto, a ferramenta ou a ação de memória solicitada é recusada.
    Causa
    A concessão não tem o escopo necessário, a conta está fora do limite do projeto selecionado ou o recurso pertence a outro tenant.
    Ação:
    Verifique a conta e o projeto selecionados, reconecte o OAuth ou solicite o escopo pretendido e repita a mesma operação sem alterar o recurso.
    Verificação
    Confirme que uma solicitação somente leitura no projeto pretendido funciona antes de tentar uma operação de gravação ou exclusão.
    Segurança:
    Não amplie escopos nem copie o token de outro usuário para fazer um 403 desaparecer.

  3. O servidor MCP conecta, mas nenhuma ferramenta aparece.

    Sintoma
    O host mostra um servidor conectado, mas tools/list está vazio ou as ferramentas do XMemo não aparecem no seletor de ferramentas do modelo.
    Causa
    O cliente ainda não atualizou a descoberta, está usando o perfil MCP errado ou está conectado a uma URL ou registro desatualizado.
    Ação:
    Reconecte o servidor, verifique se o cliente está usando o perfil MCP compatível e execute a descoberta de ferramentas novamente antes de alterar credenciais.
    Verificação
    Confirme que pelo menos remember, recall e search_memory aparecem antes de iniciar uma gravação ou demonstração para marketplace.
    Segurança:
    Não cole tokens bearer em capturas de tela, chamados de suporte ou notas de revisão de marketplace.

  4. Um cliente MCP direto informa que o token está ausente.

    Sintoma
    Um cliente direto informa que XMEMO_KEY não está definida, está vazia ou indisponível, embora a variável tenha sido adicionada em algum lugar da máquina.
    Causa
    O processo do cliente não herdou o ambiente, a variável foi adicionada a outro shell ou a configuração espera, em vez disso, uma referência a um armazenamento de segredos.
    Ação:
    Defina XMEMO_KEY no ambiente local ou no armazenamento de segredos, reinicie o cliente e mantenha XMEMO_AGENT_INSTANCE_ID estável quando a atribuição for importante.
    Verificação
    Inspecione somente os metadados de presença da variável, reinicie o cliente e confirme um recall autenticado inofensivo; nunca imprima o valor do token.
    Segurança:
    Mantenha o token real fora de arquivos de configuração versionados no git; exemplos públicos devem referenciar apenas variáveis de ambiente.

  5. O ID da instância do agente muda a cada reinicialização.

    Sintoma
    O mesmo executor local aparece como vários agentes ou o recall fica separado entre instâncias depois de uma reinicialização ou reimplantação.
    Causa
    XMEMO_AGENT_INSTANCE_ID é gerado na inicialização do processo, em vez de ser persistido no segredo local do executor ou na configuração do ambiente.
    Ação:
    Gere um rótulo de instância não secreto por executor, persista-o fora do git e envie-o em toda conexão MCP direta.
    Verificação
    Reinicie o executor duas vezes e confirme que o mesmo rótulo de instância aparece na atribuição da origem sem expor credenciais.
    Segurança:
    O rótulo da instância é metadado de atribuição, não uma credencial de autorização; os limites de conta e token continuam controlando o acesso.

  6. O recall retorna memória vazia.

    Sintoma
    Uma operação de recall ou busca é bem-sucedida, mas não retorna registros relevantes depois que o usuário salvou contexto.
    Causa
    A leitura usa uma conta, projeto, escopo, limite de agente ou tipo de memória diferente da gravação, ou o registro de teste nunca foi confirmado.
    Ação:
    Crie uma memória de teste sintética, verifique o caminho e o tipo de memória no Memory Console e tente o recall novamente na mesma conta ou no mesmo limite de tenant.
    Verificação
    Leia de volta o registro sintético recém-criado com o mesmo projeto e escopo e depois remova-o pelo caminho de exclusão pretendido.
    Segurança:
    Use dados sintéticos de revisão; não use memória privada de cliente como demonstração de marketplace.

  7. A operação de recall ou gravação usa o escopo de projeto errado.

    Sintoma
    Um registro fica visível em um projeto, mas não em outro, ou uma gravação aparece em um projeto que o operador não pretendia usar.
    Causa
    O cliente reutilizou um identificador de projeto de outro ambiente, omitiu o limite do projeto ou manteve uma sessão de conta desatualizada.
    Ação:
    Selecione explicitamente a conta e o projeto pretendidos, atualize o contexto do cliente e repita a operação com um registro sintético.
    Verificação
    Confirme o projeto e a atribuição de origem do registro no Memory Console e verifique que um projeto não relacionado não consiga lê-lo.
    Segurança:
    Nunca resolva uma divergência de escopo concedendo um token mais amplo ou copiando dados entre projetos.

  8. O mesmo registro de memória é salvo duas vezes.

    Sintoma
    Uma nova tentativa ou reconexão cria registros duplicados em vez de uma única memória duradoura.
    Causa
    O cliente tentou novamente após um timeout sem uma barreira de idempotência, ou o fluxo de captura grava antes de confirmar a primeira resposta.
    Ação:
    Inspecione primeiro o registro existente e sua atribuição de origem; depois use a política de nova tentativa do cliente ou uma chave de idempotência estável antes de gravar novamente.
    Verificação
    Repita uma captura controlada uma vez e confirme um novo registro e uma leitura de retorno, não dois novos registros.
    Segurança:
    Não exclua em massa memórias correspondentes até confirmar o registro pretendido e o escopo da conta.

  9. O contexto de recall é grande ou pequeno demais.

    Sintoma
    O agente recebe contexto irrelevante, não encontra a decisão necessária ou ultrapassa o orçamento de contexto útil do host.
    Causa
    A consulta é ampla demais, falta um escopo ou janela de tempo, ou o chamador solicitou um limite de resultados inadequado para a tarefa.
    Ação:
    Restrinja a consulta com limites de projeto, agente, tempo ou tema e peça primeiro um conjunto pequeno e relevante antes de aumentar o limite.
    Verificação
    Compare o contexto retornado com a pergunta-alvo e confirme que todo registro incluído está autorizado e é útil.
    Segurança:
    Não amplie o escopo nem exporte memória sem relação apenas para preencher uma janela de contexto.

  10. Como excluo ou exporto uma memória?

    Sintoma
    O operador precisa remover um registro, confirmar uma ação de esquecimento ou obter uma exportação limitada à conta.
    Causa
    Excluir, esquecer de modo recuperável, excluir permanentemente e exportar são fluxos distintos, com semânticas diferentes de confirmação e recuperação.
    Ação:
    Use primeiro o Memory Console ou os fluxos da conta; se não houver uma opção de autoatendimento, entre em contato com o Suporte para manter a solicitação limitada à conta.
    Verificação
    Depois de esquecer ou excluir, pesquise pela referência do registro e confirme o estado recuperável ou permanente esperado; verifique se as exportações contêm somente o escopo da conta.
    Segurança:
    Exportações e pacotes de suporte devem excluir hashes de token, chaves de API, segredos de sessão, credenciais de provedor e dados de outros tenants.

  11. Como revogo o acesso depois que um cliente foi desconectado?

    Sintoma
    Um cliente foi removido localmente, mas o operador precisa invalidar sua concessão OAuth ou credencial direta.
    Causa
    Desconectar uma configuração de cliente não revoga necessariamente a concessão no servidor nem faz a rotação de um token direto.
    Ação:
    Abra os controles de segurança da conta ou de clientes conectados, revogue a concessão OAuth nomeada e faça a rotação da credencial direta se ela foi exposta ou deixou de ser confiável.
    Verificação
    Tente uma leitura autenticada com a conexão antiga e confirme que ela é rejeitada; depois reconecte somente pelo fluxo de consentimento ou armazenamento de segredos pretendido.
    Segurança:
    Revogue apenas o cliente ou a concessão pretendida; não publique tokens antigos, códigos OAuth ou detalhes de sessão enquanto diagnostica o acesso.

  12. O XMemo é GA, certificado ou está listado em marketplace?

    Sintoma
    Uma listagem ou documento pergunta se uma configuração funcional comprova GA, certificação ou aprovação em marketplace.
    Causa
    Suporte à configuração, prontidão do OAuth, evidências de piloto e aprovação em marketplace são afirmações distintas.
    Ação:
    Considere a redação pública como beta/com suporte à configuração, a menos que exista um artefato específico de aprovação ou certificação em marketplace.
    Verificação
    Confira a matriz canônica de capacidades do cliente e o artefato de aprovação nomeado antes de publicar uma afirmação de status.
    Segurança:
    Não afirme status GA, certificado, estável ou listado apenas com base em uma configuração funcional.

  13. Qual URL devo usar?

    Sintoma
    Um usuário do serviço hospedado não sabe se deve seguir o guia rápido público, o endpoint MCP ou as instruções para desenvolvedores autogerenciados.
    Causa
    Onboarding hospedado e caminhos autogerenciados ou legados têm URLs, credenciais e limites de dados diferentes.
    Ação:
    Usuários hospedados devem começar em https://xmemo.dev/mcp para clientes MCP e https://xmemo.dev/product/docs para a configuração guiada.
    Verificação
    Confirme que a URL do host, o modo de autenticação e o limite da conta correspondem à implantação hospedada ou autogerenciada pretendida antes de conectar.
    Segurança:
    Não use localhost, Supabase, Docker ou instruções Python autogerenciadas como primeiro caminho para usuários públicos do serviço hospedado.

  14. A memória aparece sob o agente ou dispositivo errado.

    Sintoma
    Uma memória é atribuída a outro executor ou parece separada entre dispositivos depois de uma atualização ou reinicialização do cliente.
    Causa
    O cliente alterou seus cabeçalhos não secretos de agente ou instância, ou uma credencial compartilhada está sendo usada por vários executores.
    Ação:
    Verifique os cabeçalhos não secretos de agente/dispositivo ou o perfil do cliente e persista o ID da instância local em vez de gerá-lo novamente.
    Verificação
    Grave um registro sintético pelo executor pretendido e confirme que a atribuição da origem permanece estável após a reconexão.
    Segurança:
    Rótulos de atribuição ajudam na revisão, mas não são um limite de segurança; as credenciais da conta continuam decidindo o acesso.

  15. Ainda não consigo me conectar depois de seguir os passos.

    Sintoma
    A conexão continua indisponível depois que o caminho OAuth específico do cliente ou o caminho de segredo direto foi tentado novamente.
    Causa
    O problema restante pode ser específico do cliente, da conta ou causado por um registro desatualizado ou limite de ambiente que os documentos locais não conseguem inspecionar.
    Ação:
    Abra um chamado no Suporte com o nome do cliente, o caminho da configuração, o horário aproximado e se o cliente usa OAuth ou XMEMO_KEY.
    Verificação
    Confirme que o relato de suporte contém um sintoma reproduzível e metadados redigidos; depois aguarde o diagnóstico limitado à conta.
    Segurança:
    Compartilhe somente diagnósticos redigidos; nunca envie tokens bearer, códigos OAuth, cookies ou conteúdo de memória de clientes.

Origem: FAQ / Solução de problemas