# Início rápido

Conecte um cliente, salve contexto útil, recupere-o mais tarde e mantenha as credenciais fora da configuração pública.

- Canonical: https://docs.xmemo.dev/pt-br/docs/quickstart
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: abd73d03ccf55170c5c85c4eb326e77c66fde0b1654ec463e46bfe8613eed6fd
- Edition-Digest: 762c495484d7860126779421de3f9adde653ec432d83e7b191ee293a0d04383c
- Source-Revision: sha256:cf650121954b22e4cd8c386342083e6a3a903c519472bb4b370f9e3c03b0c8b8

## 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.

```json
{
  "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.

```ts
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.

```ts
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.

```ts
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.

```ts
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'.

## Início rápido do XMemo hospedado

Comece com o serviço gerenciado do XMemo e uma destas opções de conexão. Configurações auto-hospedadas, Docker, Supabase e pacotes Python são referências para desenvolvedores, não a rota inicial para usuários hospedados.

### Pergunte ao seu agente

Cole isto em um agente confiável para seguir suas verificações normais de segurança.

```
Instale a Skill autônoma do XMemo no seu diretório de skills: execute o instalador de https://xmemo.dev/skill/install (no Windows, https://xmemo.dev/skill/install.ps1) com XMEMO_SKILL_DIR definido para o seu diretório de skills mais /xmemo-memory. Execute o comando doctor exibido para verificar a instalação, depois recarregue suas skills e siga as etapas de primeira execução da Skill. Siga suas verificações de segurança normais e não use privilégios elevados.
```

### Clientes OAuth

Use este caminho para ChatGPT, revisão de app da OpenAI, VS Code e GitHub Copilot quando o host suportar OAuth. Adicione a URL hospedada do MCP, aprove memory:read e memory:write, e não cole XMEMO_KEY na configuração do cliente.

```
MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write
```

### MCP direto com XMEMO_KEY

Use este caminho apenas para clientes ou executores headless que não consigam concluir OAuth. Armazene XMEMO_KEY no ambiente local ou cofre de segredos, mantenha a URL hospedada do MCP na configuração e nunca cole o token real em documentos públicos ou chat.

```
MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID
```

### Controles de conta

Após a primeira conexão, use o acesso à conta para revisar o que foi salvo, conferir a atribuição de agentes e localizar caminhos de exclusão/exportação ou suporte antes de expandir um piloto.

```
Account entry: https://xmemo.dev/login
```