# Inicio rápido

Conecte un cliente, guarde contexto útil, recupérelo más tarde y mantenga las credenciales fuera de la configuración pública.

- Canonical: https://docs.xmemo.dev/es/docs/quickstart
- Locale: es-ES
- Content-Locale: es-ES
- Canonical-Content-Digest: abd73d03ccf55170c5c85c4eb326e77c66fde0b1654ec463e46bfe8613eed6fd
- Edition-Digest: f2f07c701fbcf8cd29a18e7c4ed2864b1d49588685dd61c7f4fb73ebb1ccb171
- Source-Revision: sha256:cf650121954b22e4cd8c386342083e6a3a903c519472bb4b370f9e3c03b0c8b8

## 1. Elija cliente y modo de autenticación

Seleccione el cliente de su agente y la ruta de conexión preferida. Para Claude Code, Codex y agentes compatibles, use el instalador de Skill independiente con 'Preguntar a su agente'. Para clientes sin skills como ChatGPT, use MCP alojado sobre OAuth. Para ejecutores directos y headless como Cursor o VS Code, use MCP directo con XMEMO_KEY. Las guías dedicadas para clientes están disponibles en /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor y /docs/mcp/copilot.

- Ruta 1 (Skill): Pida a su agente que instale el XMemo Skill independiente para Claude Code, Codex y OpenClaw (/docs/connect/openclaw).
- Ruta 2 (OAuth MCP): MCP alojado sobre OAuth para clientes sin skills, incluidos ChatGPT (/docs/mcp/chatgpt) y Claude Desktop (/docs/mcp/overview).
- Ruta 3 (MCP directo): MCP directo mediante Streamable HTTP haciendo referencia a ${XMEMO_KEY} desde su entorno local para Cursor (/docs/mcp/cursor) y VS Code (/docs/mcp/copilot).
- Modos de autenticación: OAuth (preferido, aprobado en navegador) frente a MCP directo (variable de entorno XMEMO_KEY).
- Estado intermedio: Seleccionar un cliente y copiar la configuración es un paso intermedio, no la activación.

## 2. Configure el cliente sin exponer tokens

Instale el Skill independiente o configure su cliente utilizando el endpoint de MCP alojado (https://xmemo.dev/mcp). Para clientes de Skill, proporcione el prompt de instalación oficial a su agente como la acción principal de copia, o ejecute el instalador canónico manualmente. Para MCP directo, haga referencia a ${XMEMO_KEY} desde su entorno local o almacén de secretos. Nunca incruste tokens bearer de texto sin formato en archivos de configuración del cliente o en el control de versiones.

- Ruta 1 (Preguntar a su agente): Instale el XMemo Skill independiente en su directorio de skills: ejecute el instalador desde https://xmemo.dev/skill/install (en Windows, https://xmemo.dev/skill/install.ps1) con XMEMO_SKILL_DIR configurado en su directorio de skills más /xmemo-memory. Ejecute el comando doctor que imprime para verificar la instalación, luego recargue sus skills y siga los pasos de primera ejecución del Skill. Siga sus controles de seguridad habituales y no use privilegios elevados.
- Alternativa de copia manual: Ejecute 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell: 'irm https://xmemo.dev/skill/install.ps1 | iex') con XMEMO_SKILL_DIR configurado explícitamente.
- Clientes OAuth: Configure https://xmemo.dev/mcp y apruebe memory:read y memory:write en el navegador.
- MCP directo: Haga referencia a ${XMEMO_KEY} en la configuración; mantenga el token real en su entorno local o almacén de secretos.
- Cero secretos: Los archivos de configuración nunca deben contener tokens bearer sin cifrar.

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

## 3. Verifique la conexión con una comprobación de solo lectura

Verifique siempre la conectividad con una solicitud de solo lectura antes de escribir datos. La instalación, la autenticación y la activación son hitos distintos. Para el Skill independiente, ejecute el comando doctor impreso por el instalador. Antes de iniciar sesión, elija su ruta de credenciales: prefiera proporcionar XMEMO_KEY desde un almacén de secretos o usar credenciales administradas. Si usa el inicio de sesión interactivo de dispositivo con --allow-plaintext, tenga en cuenta que esta bandera almacena la credencial sin cifrar en esta computadora. Verifique el estado después de la autenticación. Para clientes MCP, get_mcp_identity confirma que su cliente puede comunicarse con el servidor y que su ámbito memory:read es válido.

- Comando doctor de Skill: node scripts/xmemo-skill.mjs doctor --anonymous (comprueba el runtime y la conexión).
- Alternativas de credenciales de Skill: Proporcione XMEMO_KEY desde un almacén de secretos o use credenciales administradas.
- Inicio de sesión de dispositivo de Skill: node scripts/xmemo-skill.mjs login --allow-plaintext (abre la verificación en el navegador; tenga en cuenta que --allow-plaintext almacena la credencial sin cifrar en esta computadora).
- Verificación de autenticación de Skill: node scripts/xmemo-skill.mjs auth status --verify (confirma la validez de las credenciales).
- Herramienta MCP: get_mcp_identity() (o recall con límite 1).
- Control de ámbito: memory:read.
- Señal de éxito: Los metadatos de identidad confirman que el servidor es accesible y está autorizado.

```ts
get_mcp_identity()
```

## 4. Guarde un hecho sintético explícito

Registre una convención sintética de proyecto para verificar la capacidad de escritura bajo memory:write. Asigne a la memoria una ruta específica para que las consultas posteriores puedan encontrarla dentro del ámbito del proyecto. Utilice la sintaxis correcta para su superficie de integración.

- Comando de Skill: node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
- Herramienta MCP: remember con contenido sintético explícito.
- Ámbito de ruta: projects/demo-onboarding/conventions.
- Señal de éxito: El recibo comienza con 'Saved to XMemo.' junto con el ID y Location asignados.

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

## 5. Abra una nueva sesión de cliente

Inicie un nuevo hilo de conversación o reinicie su cliente para borrar el contexto efímero en memoria. Esta transición sin estado garantiza que su próxima recuperación verifique la persistencia del lado del servidor en lugar de reproducir el historial de chat local.

- Acción: Cierre o restablezca la sesión de chat actual en su cliente.
- Reinicio de contexto: El contexto efímero del cliente se borra para garantizar pruebas sin estado.
- Verificación de persistencia: Las consultas de recuperación posteriores consultan directamente el almacén remoto.

## 6. Recupere el hecho con atribución de fuente

Consulte la convención almacenada desde la nueva sesión. La activación se define estrictamente como completar la primera recuperación de memoria verificada con atribución de fuente; copiar la configuración o inspeccionar fragmentos de código es solo un paso intermedio de configuración.

- Comando de Skill: node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
- Herramienta MCP: recall con la consulta 'demo project timestamp format'.
- Formato de recibo: Salida de texto que comienza con '### XMemo Memory Results:' mostrando Reference, Location, Created/Updated/Revision opcionales y el contenido.
- Señal de éxito: La primera recuperación verificada con atribución de fuente marca la verdadera activación.

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

## 7. Corrija la convención con update_memory

Cuando las convenciones del proyecto evolucionen o requieran aclaraciones, actualice la memoria con el ID de memoria activo exacto o la Referencia devuelta por la recuperación. Para clientes de Skill, use el comando update. Para clientes MCP, use update_memory. La limpieza opcional es dirigida por el usuario mediante forget.

- Comando de Skill: node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
- Herramienta MCP: update_memory con un memory_id válido.
- Rastro de revisiones: Reemplaza la revisión anterior mientras preserva un historial inmutable.
- Limpieza opcional: Para eliminar, ejecute 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) o llame a forget (MCP).
- Señal de éxito: El recibo comienza con 'XMemo memory updated.' mostrando Reference y Revision.

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

## Recuperación: Acceso al portapapeles denegado

Si su navegador deniega el acceso al portapapeles o los permisos están bloqueados, seleccione manualmente el texto del fragmento dentro del bloque de código y cópielo con Ctrl+C (o Cmd+C). Todos los bloques de código proporcionan tabIndex=0 para desplazamiento y selección por teclado.

- Síntoma: El navegador bloquea la copia automática al portapapeles o falla la solicitud de permisos.
- Acción: Haga clic o use el tabulador en el contenedor de código y presione Ctrl+C o Cmd+C.
- Verificación: La configuración pegada coincide exactamente con el fragmento mostrado.

## Recuperación: Autenticación caducada o insuficiente

Si su cliente recibe HTTP 401 Unauthorized, HTTP 403 Forbidden o SetupRequiredMCPError, su token de autenticación ha caducado o carece de los ámbitos necesarios.

- Síntoma: HTTP 401, HTTP 403 o SetupRequiredMCPError en la invocación de herramientas.
- Acción: Vuelva a autenticarse mediante OAuth o configure XMEMO_KEY en su entorno local.
- Verificación: Confirme que el token otorgue tanto el ámbito memory:read como memory:write.

## Recuperación: Herramientas no visibles en el cliente

Si las herramientas de XMemo no aparecen en la paleta de su cliente después de la configuración, el archivo de configuración puede contener errores de sintaxis o el proceso de conexión MCP puede requerir un reinicio.

- Síntoma: El cliente muestra 0 herramientas o no reconoce el servidor MCP de XMemo.
- Acción: Revise los registros de desarrollador del cliente, valide la sintaxis JSON y reinicie el cliente.
- Verificación: Los registros del cliente muestran una inicialización de MCP y un descubrimiento de herramientas exitosos.

## Recuperación: Resultados de recuperación vacíos

Si recall no devuelve memorias coincidentes ('No matching memories found' o 'No strong memory match'), verifique que la escritura en el Paso 4 se haya completado correctamente y compruebe su consulta de búsqueda.

- Síntoma: recall devuelve un mensaje de texto indicando que no se encontraron memorias coincidentes.
- Acción: Verifique las palabras clave de la consulta ('timestamp', 'UTC') y compruebe el ámbito de la ruta.
- Verificación: Confirme que remember haya devuelto un recibo que comience con 'Saved to XMemo' antes de realizar el recall.

## Recuperación: ID de memoria desconocido en la actualización

Si update_memory rechaza su llamada porque memory_id es desconocido o no válido, no adivine los identificadores.

- Síntoma: update_memory devuelve un error indicando que memory_id no fue encontrado.
- Acción: Llame primero a recall para obtener la Referencia de memoria activa y pásela como memory_id.
- Verificación: Pase la Referencia de memoria activa de recall a update_memory.

## Recuperación: Destino de instalación incorrecto

Si el instalador guardó los scripts directamente en el directorio raíz de skills de su agente en lugar de un subdirectorio de skill aislado, el agente no puede localizar scripts/xmemo-skill.mjs o carga archivos de instalación sin procesar.

- Síntoma: Error al buscar scripts/xmemo-skill.mjs o archivos extraídos directamente en la raíz de skills.
- Acción: Configure XMEMO_SKILL_DIR explícitamente a su directorio de skills más /xmemo-memory (por ejemplo, export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
- Verificación: SKILL.md y scripts/xmemo-skill.mjs residen directamente dentro de la carpeta xmemo-memory.

## Recuperación: Falta el runtime de Node 22.22.0

El Skill independiente requiere Node.js >= 22.22.0. Si falta node o está activa una versión anterior, las operaciones de doctor y del skill fallarán.

- Síntoma: 'command not found: node', o errores de runtime al inicio, o node -v informa una versión inferior a 22.22.0.
- Acción: Instale o cambie a Node.js 22.22.0 o superior usando nvm (nvm install 22.22.0 && nvm use 22.22.0) o el administrador de paquetes de su sistema operativo.
- Verificación: Ejecute 'node -v' y confirme que la salida sea v22.22.0 o superior.

## Recuperación: Se necesita recargar el Skill

Si el Skill está instalado y doctor aprueba, pero su agente no enumera las herramientas u operaciones de XMemo en su sesión activa, se debe recargar la caché de skills en memoria del agente.

- Síntoma: El agente informa que no tiene conocimiento de los skills de XMemo después de la instalación.
- Acción: Reinicie la sesión del agente para recargar los skills en memoria.
- Verificación: Pregunte al agente 'what skills are available?' y compruebe que xmemo-memory esté listado.

## Recuperación: Inicio de sesión interrumpido

Si el inicio de sesión del dispositivo se interrumpió, se agotó el tiempo de espera o se cerró antes de ingresar el código de verificación, las credenciales no se escriben en el disco.

- Síntoma: El navegador se cerró antes de la aprobación, el código de un solo uso caducó o 'auth status --verify' informa auth_valid: false.
- Acción: Si no utiliza XMEMO_KEY de almacén de secretos ni credenciales administradas, vuelva a ejecutar 'node scripts/xmemo-skill.mjs login --allow-plaintext' (lo que almacena la credencial sin cifrar en esta computadora), abra la URL mostrada e ingrese el código antes de que caduque.
- Verificación: Ejecute 'node scripts/xmemo-skill.mjs auth status --verify' y confirme 'status: ok' con 'auth_valid: true'.

## Guía rápida de XMemo alojado

Comience con el servicio XMemo administrado y una de estas rutas de conexión. Auto-acogida, Docker, Supabase y Python configuración de paquetes son referencias de desarrolladores, no la primera ruta para usuarios alojados.

### Pregunte a su agente

Pegue esto en un agente de confianza para seguir sus controles de seguridad normales.

```
Instale la habilidad XMemo independiente en su directorio de habilidades: ejecute el instalador desde https://xmemo.dev/skill/install (en Windows, https://xmemo.dev/skill/install.ps1) con XMEMO_SKILL_DIR configurado en su directorio de habilidades más /xmemo-memory. Ejecute el comando doctor que imprime para verificar la instalación, luego recargue sus habilidades y siga los pasos de primera ejecución de la habilidad. Siga sus controles de seguridad habituales y no utilice privilegios elevados.
```

### Clientes de OAuth

Use esta ruta para ChatGPT, OpenAI app review, VS Code, y GitHub Copilot cuando el host soporte OAuth. Añada la URL MCP alojada, apruebe memoria:read y memoria:write, y no pegue XMEMO_KEY en la configuración del cliente.

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

### MCP directo con XMEMO_KEY

Utilice esta ruta solo para clientes o runners sin cabeza que no puedan completar OAuth. Almacene XMEMO_KEY en el entorno local o en la tienda secreta, mantenga la URL MCP alojada en configuración y nunca pegue el token real en documentos públicos o chat.

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

### Controles de cuentas

Después de la primera conexión, utilice la entrada de la cuenta para revisar lo que se guardó, comprobar la atribución del agente y encontrar delete/export o rutas de soporte antes de expandir un piloto.

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