Codex

Requisitos previos

Utilice OpenAI Codex CLI o Codex Desktop con soporte para Streamable HTTP MCP y ejecución de Skill:

• Interfaz concreta: Codex CLI y Codex Desktop (codex).
• Requisito de tiempo de ejecución: Node.js versión 22.22.0 o superior para el ejecutor de Skill independiente.
• Cuenta: Cuenta válida de XMemo en https://xmemo.dev.
• Requisito previo de MCP: Soporte para bearer_token_env_var en ~/.codex/config.toml.

Instalación / configuración

La ruta recomendada instala la Skill independiente de XMemo en el directorio de skills de Codex utilizando el aviso seleccionado por el propietario. Pida a su agente en Codex que ejecute la instalación:

• Aviso: 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.
• Ruta de instalación predeterminada: ~/.codex/skills/xmemo-memory.
• Ruta alternativa: Configure el perfil MCP directo en ~/.codex/config.toml usando bearer_token_env_var.

Establecer la credencial

Configure su credencial antes de ejecutar operaciones. Establezca XMEMO_KEY en el entorno utilizado para iniciar Codex. bearer_token_env_var lee el valor sin colocar el token en config.toml. Si utiliza inicio de sesión interactivo de dispositivo con --allow-plaintext, tenga en cuenta que esta bandera almacena credenciales sin cifrar en este equipo:

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

Generar / confirmar XMEMO_AGENT_INSTANCE_ID

La configuración del cliente asigna la identidad de instancia estable para esta instalación. Confirme que env_http_headers asigne XMEMO_AGENT_INSTANCE_ID y reutilice el mismo valor no secreto en todas las sesiones.

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

Conservar el bloque de configuración existente

Utilice el bloque de configuración revisado de Codex. Conserve bearer_token_env_var y la URL de XMemo; nunca pegue secretos directamente en config.toml:

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

Reiniciar el cliente

Reinicie Codex después de escribir archivos de configuración, modificar variables de entorno o instalar la Skill para que se detecten los nuevos componentes.

Probar con una llamada real de recall

Haga que la primera solicitud sea de solo lectura para verificar la conectividad antes de escribir datos. Esta comprobación no modifica el estado de la memoria.

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

Respuesta esperada (forma literal)

Una llamada exitosa devuelve la forma de texto clasificado público a continuación; la referencia y el contenido son valores reales del espacio de memoria autorizado.

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

Primera tarea útil: Ciclo de vida de memoria sintética

Ejercite la tarea completa de memoria sintética a través de guardado, transición de sesión, recall y corrección:

• 1. Guardar hecho sintético: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions" (o herramienta MCP remember).
• 2. Transición sin estado: Abra una nueva sesión de terminal de Codex para verificar la persistencia entre sesiones.
• 3. Recall con atribución de origen: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" (o herramienta MCP recall). Verifique Reference y Location en la salida devuelta.
• 4. Corregir memoria: node scripts/xmemo-skill.mjs update --id <active-memory-id> --content "Demo project timestamps use UTC with ISO 8601 formatting." (o herramienta MCP update_memory).
• 5. Limpieza opcional: node scripts/xmemo-skill.mjs forget --id <active-memory-id> --confirm (o herramienta MCP forget).

Capacidades y herramientas de perfil

Codex tiene acceso a herramientas calificadas por perfil definidas en el contrato de documentación de MCP para el perfil generic-public:

• Herramientas de memoria principales: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context.
• Herramientas de espacio de trabajo: get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger.

Limitaciones y límites

Límites operativos y restricciones para Codex:

• Aislamiento del espacio de trabajo: Las operaciones están estrictamente confinadas al espacio de trabajo del usuario conectado.
• Manejo de secretos: Utilice siempre bearer_token_env_var; nunca codifique tokens directamente en config.toml.
• Ámbito de distribución: Las bifurcaciones no estándar o de terceros de Codex permanecen marcadas como no probadas.

Errores comunes

Solucione problemas comunes de Codex siguiendo estos pasos de recuperación:

• 401 invalid_token — XMEMO_KEY falta, está vencido o no es válido: verifique el entorno que inicia Codex y reinicie.
• 403 insufficient_scope — El token carece del permiso memory:read: genere un token con el ámbito requerido.
• Destino de instalación incorrecto — Verifique que XMEMO_SKILL_DIR esté configurado en ~/.codex/skills/xmemo-memory.
• Se necesita recarga de Skill — Reinicie Codex para asegurarse de que las skills en memoria se recarguen.

Actualización y eliminación

Procedimientos de mantenimiento para Codex:

• Actualización: Vuelva a ejecutar el comando de instalación para obtener la última versión de la Skill o actualice la URL del punto de conexión MCP.
• Eliminación: Elimine el directorio ~/.codex/skills/xmemo-memory o elimine [mcp_servers.xmemo] de ~/.codex/config.toml.