Início rápido

1. Escolha o cliente e o modo de autenticação

Selecione o cliente do seu agente e o caminho de conexão preferencial. Para Claude Code, Codex e agentes compatíveis, use o instalador do Skill independente com 'Peça ao seu agente'. Para clientes sem skills, como o ChatGPT, use MCP hospedado via OAuth. Para executores diretos e headless como Cursor ou VS Code, use MCP direto com XMEMO_KEY. Guias dedicados para clientes estão disponíveis em /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor e /docs/mcp/copilot.

• Caminho 1 (Skill): Peça ao seu agente para instalar o XMemo Skill independente para Claude Code, Codex e OpenClaw (/docs/connect/openclaw).
• Caminho 2 (OAuth MCP): MCP hospedado via OAuth para clientes sem skills, incluindo ChatGPT (/docs/mcp/chatgpt) e Claude Desktop (/docs/mcp/overview).
• Caminho 3 (MCP direto): MCP direto via Streamable HTTP referenciando ${XMEMO_KEY} do seu ambiente local para Cursor (/docs/mcp/cursor) e VS Code (/docs/mcp/copilot).
• Modos de autenticação: OAuth (preferencial, aprovado pelo navegador) versus MCP direto (variável de ambiente XMEMO_KEY).
• Status intermediário: Selecionar um cliente e copiar a configuração é uma etapa intermediária, não a ativação.

2. Configure o cliente sem expor tokens

Instale o Skill independente ou configure seu cliente usando o endpoint de MCP hospedado (https://xmemo.dev/mcp). Para clientes de Skill, forneça o prompt oficial de instalação ao seu agente como ação primária de cópia ou execute o instalador canônico manualmente. Para MCP direto, referencie ${XMEMO_KEY} do seu ambiente local ou cofre de segredos. Nunca codifique tokens bearer em texto simples nos arquivos de configuração do cliente ou no controle de versão.

• Caminho 1 (Peça ao seu agente): Instale o XMemo Skill independente em seu diretório de skills: execute o instalador a partir de https://xmemo.dev/skill/install (no Windows, https://xmemo.dev/skill/install.ps1) com XMEMO_SKILL_DIR definido para o diretório de skills mais /xmemo-memory. Execute o comando doctor exibido para verificar a instalação, recarregue suas skills e siga as etapas de primeira execução do Skill. Siga suas verificações habituais de segurança e não use privilégios elevados.
• Alternativa de cópia manual: Execute 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex') com XMEMO_SKILL_DIR definido explicitamente.
• Clientes OAuth: Configure https://xmemo.dev/mcp e aprove memory:read e memory:write no navegador.
• MCP direto: Referencie ${XMEMO_KEY} na configuração; mantenha o token real em seu ambiente local ou cofre de segredos.
• Zero segredos: Arquivos de configuração nunca devem conter tokens bearer não criptografados.

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

3. Verifique a conexão com uma verificação somente leitura

Sempre verifique a conectividade com uma solicitação somente leitura antes de gravar dados. Instalação, autenticação e ativação são marcos distintos. Para o Skill independente, execute o comando doctor exibido pelo instalador. Antes de entrar, escolha seu caminho de credencial: prefira fornecer XMEMO_KEY de um cofre de segredos ou usar credenciais gerenciadas. Se você usar o login interativo de dispositivo com --allow-plaintext, observe que essa flag armazena a credencial sem criptografia neste computador. Verifique o status após a autenticação. Para clientes MCP, get_mcp_identity confirma que seu cliente pode acessar o servidor e que seu escopo memory:read é válido.

• Comando doctor do Skill: node scripts/xmemo-skill.mjs doctor --anonymous (verifica runtime e conexão).
• Alternativas de credenciais do Skill: Forneça XMEMO_KEY de um cofre de segredos ou use credenciais gerenciadas.
• Login de dispositivo do Skill: node scripts/xmemo-skill.mjs login --allow-plaintext (abre a verificação no navegador; observe que --allow-plaintext armazena a credencial sem criptografia neste computador).
• Verificação de autenticação do Skill: node scripts/xmemo-skill.mjs auth status --verify (confirma a validade das credenciais).
• Ferramenta MCP: get_mcp_identity() (ou recall com limite 1).
• Controle de escopo: memory:read.
• Sinal de sucesso: Os metadados de identidade confirmam que o servidor está acessível e autorizado.

get_mcp_identity()

4. Salve um fato sintético explícito

Registre uma convenção sintética de projeto para verificar a capacidade de gravação em memory:write. Atribua à memória um caminho específico para que consultas posteriores possam encontrá-la dentro do escopo do projeto. Use a sintaxe correta para sua superfície de integração.

• Comando do Skill: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
• Ferramenta MCP: remember com conteúdo sintético explícito.
• Escopo do caminho: projects/demo-onboarding/conventions.
• Sinal de sucesso: O comprovante começa com 'Saved to XMemo.' junto com o ID e Location atribuídos.

remember({
  content: "Demo project timestamps use UTC.",
  path: "projects/demo-onboarding/conventions"
})

5. Abra uma nova sessão do cliente

Inicie um novo tópico de conversa ou reinicie seu cliente para limpar o contexto efêmero na memória. Essa transição sem estado garante que sua próxima recuperação verifique a persistência no lado do servidor, em vez da reprodução do histórico de chat local.

• Ação: Feche ou redefina a sessão de conversa atual no seu cliente.
• Redefinição de contexto: O contexto efêmero do cliente é limpo para garantir testes sem estado.
• Verificação de persistência: As consultas de recuperação subsequentes consultam diretamente o armazenamento remoto.

6. Recupere o fato com atribuição de origem

Consulte a convenção armazenada a partir da nova sessão. A ativação é rigorosamente definida como a conclusão da primeira recuperação de memória verificada com atribuição de origem; copiar a configuração ou inspecionar trechos de código é apenas uma etapa intermediária de configuração.

• Comando do Skill: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
• Ferramenta MCP: recall com a consulta 'demo project timestamp format'.
• Formato do comprovante: Saída textual iniciando com '### XMemo Memory Results:' exibindo Reference, Location, os campos opcionais Created/Updated/Revision e o conteúdo.
• Sinal de sucesso: A primeira recuperação verificada com atribuição de origem marca a verdadeira ativação.

recall({
  query: "demo project timestamp format",
  limit: 1
})

7. Corrija a convenção com update_memory

Quando as convenções do projeto evoluírem ou exigirem esclarecimentos, atualize a memória com o ID de memória ativo exato ou a Reference retornada na recuperação. Para clientes de Skill, use o comando update. Para clientes MCP, use update_memory. A limpeza opcional é direcionada pelo usuário via forget.

• Comando do Skill: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
• Ferramenta MCP: update_memory com um memory_id válido.
• Trilha de revisão: Substitui a revisão anterior enquanto preserva um histórico imutável.
• Limpeza opcional: Para excluir, execute 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) ou chame forget (MCP).
• Sinal de sucesso: O comprovante começa com 'XMemo memory updated.' exibindo Reference e Revision.

update_memory({
  memory_id: "mem_01hxyz...",
  content: "Demo project timestamps use UTC with ISO 8601 formatting."
})

Recuperação: Acesso à área de transferência negado

Se o seu navegador negar o acesso à área de transferência ou as permissões forem bloqueadas, selecione manualmente o texto do trecho dentro do bloco de código e copie com Ctrl+C (ou Cmd+C). Todos os blocos de código fornecem tabIndex=0 para rolagem e seleção pelo teclado.

• Sintoma: O navegador bloqueia a cópia automática para a área de transferência ou a solicitação de permissões falha.
• Ação: Clique ou use a tecla Tab no contêiner de código e pressione Ctrl+C ou Cmd+C.
• Verificação: A configuração colada corresponde exatamente ao trecho exibido.

Recuperação: Autenticação expirada ou insuficiente

Se o seu cliente receber HTTP 401 Unauthorized, HTTP 403 Forbidden ou SetupRequiredMCPError, seu token de autenticação expirou ou não possui os escopos necessários.

• Sintoma: HTTP 401, HTTP 403 ou SetupRequiredMCPError na invocação da ferramenta.
• Ação: Autentique-se novamente via OAuth ou defina XMEMO_KEY em seu ambiente local.
• Verificação: Confirme se o token concede os escopos memory:read e memory:write.

Recuperação: Ferramentas não visíveis no cliente

Se as ferramentas do XMemo não aparecerem na paleta do seu cliente após a configuração, o arquivo de configuração pode conter erros de sintaxe ou o processo de conexão MCP pode precisar de uma reinicialização.

• Sintoma: O cliente exibe 0 ferramentas ou falha ao reconhecer o servidor MCP do XMemo.
• Ação: Verifique os logs de desenvolvedor do cliente, valide a sintaxe JSON e reinicie o cliente.
• Verificação: Os logs do cliente mostram inicialização bem-sucedida do MCP e descoberta de ferramentas.

Recuperação: Resultados de recuperação vazios

Se recall não retornar memórias correspondentes ('No matching memories found' ou 'No strong memory match'), verifique se a gravação na Etapa 4 foi concluída com sucesso e verifique sua consulta de pesquisa.

• Sintoma: recall retorna uma mensagem de texto indicando que nenhuma memória correspondente foi encontrada.
• Ação: Verifique as palavras-chave da consulta ('timestamp', 'UTC') e confirme o escopo do caminho.
• Verificação: Confirme se remember retornou um comprovante começando com 'Saved to XMemo' antes de realizar o recall.

Recuperação: ID de memória desconhecido na atualização

Se update_memory rejeitar sua chamada porque o memory_id é desconhecido ou inválido, não tente adivinhar os identificadores.

• Sintoma: update_memory retorna um erro indicando que memory_id não foi encontrado.
• Ação: Chame recall primeiro para recuperar a Referência de memória ativa e passe-a como memory_id.
• Verificação: Passe a Referência de memória ativa obtida no recall para update_memory.

Recuperação: Destino de instalação incorreto

Se o instalador salvou scripts diretamente no diretório raiz de skills do seu agente, em vez de um subdiretório de skill isolado, o agente não conseguirá localizar scripts/xmemo-skill.mjs ou carregará arquivos brutos de instalação.

• Sintoma: Erro ao localizar scripts/xmemo-skill.mjs ou arquivos extraídos diretamente na raiz de skills.
• Ação: Defina XMEMO_SKILL_DIR explicitamente para o diretório de skills mais /xmemo-memory (por exemplo, export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
• Verificação: SKILL.md e scripts/xmemo-skill.mjs residem diretamente dentro da pasta xmemo-memory.

Recuperação: Runtime do Node 22.22.0 ausente

O Skill independente requer Node.js >= 22.22.0. Se o node estiver ausente ou uma versão mais antiga estiver ativa, as operações de doctor e do skill falharão.

• Sintoma: 'command not found: node', erros de runtime na inicialização ou node -v relata versão inferior a 22.22.0.
• Ação: Instale ou mude para o Node.js 22.22.0 ou superior usando nvm (nvm install 22.22.0 && nvm use 22.22.0) ou o gerenciador de pacotes do seu sistema operacional.
• Verificação: Execute 'node -v' e confirme que a saída seja v22.22.0 ou superior.

Recuperação: Recarregamento do Skill necessário

Se o Skill estiver instalado e doctor passar, mas o seu agente não listar as ferramentas ou operações do XMemo na sessão ativa, o cache de skills na memória do agente deverá ser recarregado.

• Sintoma: O agente relata desconhecimento dos skills do XMemo após a instalação.
• Ação: Reinicie a sessão do agente para recarregar os skills na memória.
• Verificação: Pergunte ao agente 'what skills are available?' e verifique se xmemo-memory está listado.

Recuperação: Login interrompido

Se o login do dispositivo foi interrompido, atingiu o tempo limite ou foi fechado antes de inserir o código de verificação, as credenciais não serão gravadas no disco.

• Sintoma: O navegador foi fechado antes da aprovação, o código de uso único expirou ou 'auth status --verify' relata auth_valid: false.
• Ação: Se você não estiver usando XMEMO_KEY em cofre de segredos nem credenciais gerenciadas, execute novamente 'node scripts/xmemo-skill.mjs login --allow-plaintext' (o que armazena a credencial sem criptografia neste computador), abra o URL exibido e digite o código antes da expiração.
• Verificação: Execute 'node scripts/xmemo-skill.mjs auth status --verify' e confirme 'status: ok' com 'auth_valid: true'.