Claude Code

Pré-requisitos

Use o Claude Code CLI (claude) em seu terminal local. Ambientes de execução e pré-requisitos:

• Interface concreta: Claude Code CLI (claude).
• Requisito de tempo de execução: Node.js versão 22.22.0 ou superior para o executor de Skill independente.
• Conta: Conta válida do XMemo em https://xmemo.dev.
• Pré-requisito MCP alternativo: Suporte a transporte Streamable HTTP com token de portador no ambiente local.

Instalação / configuração

O caminho recomendado instala a Skill independente do XMemo no diretório skills do Claude Code usando o prompt selecionado pelo proprietário. Peça ao seu agente no Claude Code para executar a instalação:

• Prompt: Install the standalone XMemo Skill into your skills directory: run the installer from https://xmemo.dev/skill/install (on Windows, https://xmemo.dev/skill/install.ps1) with XMEMO_SKILL_DIR set to your skills directory plus /xmemo-memory. Run the doctor command it prints to verify the installation, then reload your skills and follow the Skill's first-run steps. Follow your normal safety checks and do not use elevated privileges.
• Caminho de instalação padrão: ~/.claude/skills/xmemo-memory.
• Caminho alternativo: Registre o MCP Streamable HTTP direto via claude mcp add ou .mcp.json com https://xmemo.dev/mcp.

Definir a credencial

Antes de executar comandos, configure seu caminho de armazenamento de credenciais. Prefira definir XMEMO_KEY a partir de um cofre de segredos ou ambiente de shell local. Se estiver usando login interativo no dispositivo com --allow-plaintext, observe que esta flag armazena a credencial sem criptografia neste computador:

export XMEMO_KEY='<your-xmemo-token>'
# Interactive alternative (stores credential unencrypted on this machine):
# node ~/.claude/skills/xmemo-memory/scripts/xmemo-skill.mjs login --allow-plaintext

Gerar / confirmar XMEMO_AGENT_INSTANCE_ID

Gere um valor não secreto por instalação local do Claude Code, mantenha-o fora do git e reutilize-o nas sessões para que a atribuição de instância permaneça estável.

export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'
# Persist and reuse this value for the same local install

Preservar o bloco de configuração existente

Para ambientes MCP diretos, use o bloco de configuração revisado do Claude Code. Preserve a referência de variável Authorization; nunca substitua o espaço reservado do token por um segredo real:

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

Reiniciar o cliente

Reinicie o Claude Code após alterar variáveis de ambiente, arquivos de configuração ou instalar a Skill para que todos os componentes sejam carregados de forma limpa na memória.

Testar com uma chamada real de recall

Faça a primeira solicitação somente leitura para verificar a conectividade antes de gravar dados. Esta verificação não modifica o estado da memória.

recall({ query: "connection check", limit: 1 })

Resposta esperada (formato literal)

Uma chamada bem-sucedida retorna o formato de texto classificado público abaixo; a referência e o conteúdo são valores reais do espaço de memória autorizado.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

Primeira tarefa útil: Ciclo de vida de memória sintética

Verifique a persistência da memória, transição de sessão sem estado, recall atribuído à fonte e correção:

• 1. Salvar fato sintético: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (ou ferramenta MCP remember).
• 2. Transição sem estado: Abra uma nova sessão de terminal do Claude Code para verificar a persistência entre sessões.
• 3. Recall com atribuição de fonte: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (ou ferramenta MCP recall). Verifique Reference e Location na saída retornada.
• 4. Corrigir memória: node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (ou ferramenta MCP update_memory).
• 5. Limpeza opcional: node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (ou ferramenta MCP forget).

Recursos e ferramentas de perfil

O Claude Code tem acesso a ferramentas qualificadas por perfil definidas no contrato de documentação do MCP para os perfis claude-plugin e claude-public:

• Ferramentas de memória principais: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• Ferramentas de projeto e contexto: get_mcp_identity, get_project_context, project, todo, update_state.
• Continuidade de sessão: create_restart_snapshot, restore_restart_snapshot, record_event, create_pending_decision, resolve_decision.

Limitações e limites

Limites operacionais e restrições para o Claude Code:

• Limite do espaço de trabalho: O acesso à memória é estritamente limitado ao espaço de trabalho do usuário autorizado.
• Separação de desktop: A configuração do Claude Code CLI é independente das configurações do Claude Desktop Cowork.
• Claude no claude.ai e Claude Desktop: conecte pelo conector personalizado com OAuth; consulte [Claude (claude.ai)](/docs/mcp/claude).
• Tratamento de segredos: Nunca envie tokens em texto não criptografado para o git nem cole segredos em arquivos de configuração confirmados.

Erros comuns

Solucione problemas comuns de conexão e autorização com estas etapas:

• 401 invalid_token — XMEMO_KEY está ausente, expirado ou inválido: verifique o token de ambiente ou execute novamente o login no dispositivo.
• 403 insufficient_scope — O token não possui o escopo memory:read ou memory:write: emita um token com as permissões necessárias.
• Destino de instalação incorreto — Verifique se XMEMO_SKILL_DIR foi definido como ~/.claude/skills/xmemo-memory.
• Recarregamento de Skill necessário — Saia do Claude Code (/exit) e reinicie para recarregar as skills na memória.

Atualização e remoção

Procedimentos para atualizar ou desinstalar a integração:

• Atualização: Execute novamente o prompt do instalador para obter a versão mais recente do pacote de Skill.
• Remoção: Exclua ~/.claude/skills/xmemo-memory ou execute claude mcp remove xmemo para remover a configuração direta de MCP.