Codex

Pré-requisitos

Use o OpenAI Codex CLI ou Codex Desktop com Streamable HTTP MCP e suporte para execução de Skill:

• Interface concreta: Codex CLI e Codex Desktop (codex).
• 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: Suporte para bearer_token_env_var em ~/.codex/config.toml.

Instalação / configuração

O caminho recomendado instala a Skill independente do XMemo no diretório skills do Codex usando o prompt selecionado pelo proprietário. Peça ao seu agente no Codex 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: ~/.codex/skills/xmemo-memory.
• Caminho alternativo: Configure o perfil MCP direto em ~/.codex/config.toml usando bearer_token_env_var.

Definir a credencial

Configure sua credencial antes de executar operações. Defina XMEMO_KEY no ambiente usado para iniciar o Codex. bearer_token_env_var lê o valor sem colocar o token em config.toml. Se estiver usando login interativo no dispositivo com --allow-plaintext, observe que esta flag armazena credenciais sem criptografia neste computador:

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

Gerar / confirmar XMEMO_AGENT_INSTANCE_ID

A configuração do cliente mapeia a identidade estável da instância para esta instalação. Confirme se env_http_headers mapeia XMEMO_AGENT_INSTANCE_ID e reutilize o mesmo valor não secreto nas sessões.

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

Use o bloco de configuração revisado do Codex. Preserve bearer_token_env_var e a URL do XMemo; nunca cole segredos diretamente em config.toml:

[mcp_servers.xmemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

Reiniciar o cliente

Reinicie o Codex após gravar arquivos de configuração, modificar variáveis de ambiente ou instalar a Skill para que os novos componentes sejam detectados.

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

Exercite a tarefa completa de memória sintética entre salvamento, transição de sessão, recall 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 Codex 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 Codex tem acesso a ferramentas qualificadas por perfil definidas no contrato de documentação do MCP para o perfil generic-public:

• Ferramentas de memória principais: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• Ferramentas de espaço de trabalho: get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger.

Limitações e limites

Limites operacionais e restrições para o Codex:

• Isolamento do espaço de trabalho: As operações são estritamente confinadas ao espaço de trabalho do usuário conectado.
• Tratamento de segredos: Sempre use bearer_token_env_var; nunca insira tokens codificados em config.toml.
• Escopo de distribuição: Bifurcações não padrão ou de terceiros do Codex permanecem marcadas como não testadas.

Erros comuns

Solucione problemas comuns do Codex usando estas etapas de recuperação:

• 401 invalid_token — XMEMO_KEY está ausente, expirado ou inválido: verifique o ambiente que inicia o Codex e reinicie.
• 403 insufficient_scope — O token não possui permissão memory:read: gere um token com o escopo necessário.
• Destino de instalação incorreto — Verifique se XMEMO_SKILL_DIR foi definido como ~/.codex/skills/xmemo-memory.
• Recarregamento de Skill necessário — Reinicie o Codex para garantir que as skills na memória sejam recarregadas.

Atualização e remoção

Procedimentos de manutenção para o Codex:

• Atualização: Execute novamente o comando do instalador para obter a versão mais recente da Skill ou atualize a URL do endpoint MCP.
• Remoção: Exclua o diretório ~/.codex/skills/xmemo-memory ou remova [mcp_servers.xmemo] de ~/.codex/config.toml.