Démarrage rapide

1. Choisissez le client et le mode d'authentification

Sélectionnez le client de votre agent et le chemin de connexion préféré. Pour Claude Code, Codex et les agents compatibles, utilisez le programme d'installation autonome du Skill avec 'Demandez à votre agent'. Pour les clients sans skills comme ChatGPT, utilisez le MCP hébergé sur OAuth. Pour les exécuteurs directs et sans interface graphique comme Cursor ou VS Code, utilisez le MCP direct avec XMEMO_KEY. Des guides clients dédiés sont disponibles sous /docs/mcp/claude-code, /docs/mcp/codex, /docs/connect/openclaw, /docs/mcp/chatgpt, /docs/mcp/cursor et /docs/mcp/copilot.

• Chemin 1 (Skill) : Demandez à votre agent d'installer le XMemo Skill autonome pour Claude Code, Codex et OpenClaw (/docs/connect/openclaw).
• Chemin 2 (OAuth MCP) : MCP hébergé sur OAuth pour les clients sans skills, y compris ChatGPT (/docs/mcp/chatgpt) et Claude Desktop (/docs/mcp/overview).
• Chemin 3 (MCP direct) : MCP direct via Streamable HTTP référençant ${XMEMO_KEY} depuis votre environnement local pour Cursor (/docs/mcp/cursor) et VS Code (/docs/mcp/copilot).
• Modes d'authentification : OAuth (préféré, approuvé par le navigateur) ou MCP direct (variable d'environnement XMEMO_KEY).
• Statut intermédiaire : Sélectionner un client et copier la configuration est une étape intermédiaire, pas l'activation.

2. Configurez le client sans exposer de tokens

Installez le Skill autonome ou configurez votre client en utilisant le point de terminaison MCP hébergé (https://xmemo.dev/mcp). Pour les clients de type Skill, fournissez l'invite d'installation officielle à votre agent comme action principale de copie, ou exécutez le programme d'installation canonique manuellement. Pour le MCP direct, référencez ${XMEMO_KEY} depuis votre environnement local ou votre magasin de secrets. N'intégrez jamais de jetons porteurs en texte brut dans les fichiers de configuration du client ou dans le contrôle de version.

• Chemin 1 (Demandez à votre agent) : Installez le XMemo Skill autonome dans votre répertoire de skills : exécutez le programme d'installation depuis https://xmemo.dev/skill/install (sous Windows, https://xmemo.dev/skill/install.ps1) avec XMEMO_SKILL_DIR configuré vers votre répertoire de skills plus /xmemo-memory. Exécutez la commande doctor qu'il affiche pour vérifier l'installation, puis rechargez vos skills et suivez les étapes de première exécution du Skill. Suivez vos contrôles de sécurité habituels et n'utilisez pas de privilèges élevés.
• Solution de repli manuelle : Exécutez 'curl -fsSL https://xmemo.dev/skill/install | sh' (Windows PowerShell : 'irm https://xmemo.dev/skill/install.ps1 | iex') avec XMEMO_SKILL_DIR défini explicitement.
• Clients OAuth : Configurez https://xmemo.dev/mcp et approuvez memory:read et memory:write dans le navigateur.
• MCP direct : Référencez ${XMEMO_KEY} dans la configuration ; conservez le véritable jeton dans votre environnement local ou votre magasin de secrets.
• Zéro secret : Les fichiers de configuration ne doivent jamais contenir de jetons porteurs non chiffrés.

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

3. Vérifiez la connexion avec une vérification en lecture seule

Vérifiez toujours la connectivité avec une requête en lecture seule avant d'écrire des données. L'installation, l'authentification et l'activation sont des étapes distinctes. Pour le Skill autonome, exécutez la commande doctor affichée par le programme d'installation. Avant de vous connecter, choisissez votre méthode d'identification : préférez fournir XMEMO_KEY à partir d'un magasin de secrets ou utiliser des identifiants gérés. Si vous utilisez la connexion interactive sur l'appareil avec --allow-plaintext, notez que cet indicateur stocke l'identifiant non chiffré sur cet ordinateur. Vérifiez le statut après l'authentification. Pour les clients MCP, get_mcp_identity confirme que votre client peut joindre le serveur et que votre portée memory:read est valide.

• Commande doctor du Skill : node scripts/xmemo-skill.mjs doctor --anonymous (vérifie le runtime et la connexion).
• Alternatives d'identifiants du Skill : Fournissez XMEMO_KEY depuis un magasin de secrets ou utilisez des identifiants gérés.
• Connexion de l'appareil du Skill : node scripts/xmemo-skill.mjs login --allow-plaintext (ouvre la vérification dans le navigateur ; notez que --allow-plaintext stocke l'identifiant non chiffré sur cet ordinateur).
• Vérification d'authentification du Skill : node scripts/xmemo-skill.mjs auth status --verify (confirme la validité des identifiants).
• Outil MCP : get_mcp_identity() (ou recall avec limite à 1).
• Portée requise : memory:read.
• Signal de succès : Les métadonnées d'identité confirment que le serveur est accessible et autorisé.

get_mcp_identity()

4. Enregistrez un fait synthétique explicite

Enregistrez une convention de projet synthétique pour vérifier la capacité d'écriture sous memory:write. Donnez à la mémoire un chemin spécifique afin que les requêtes ultérieures puissent la retrouver dans la portée du projet. Utilisez la syntaxe appropriée pour votre surface d'intégration.

• Commande du Skill : node scripts/xmemo-skill.mjs remember --content "Demo project timestamps use UTC." --path "projects/demo-onboarding/conventions".
• Outil MCP : remember avec un contenu synthétique explicite.
• Portée du chemin : projects/demo-onboarding/conventions.
• Signal de succès : Le reçu commence par 'Saved to XMemo.' avec l'identifiant et l'emplacement attribués.

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

5. Ouvrez une nouvelle session client

Démarrez un nouveau fil de discussion ou redémarrez votre client pour effacer le contexte éphémère en mémoire. Cette transition sans état garantit que votre prochain rappel vérifiera la persistance côté serveur plutôt que la relecture de l'historique de discussion local.

• Action : Fermez ou réinitialisez la session de discussion actuelle dans votre client.
• Réinitialisation du contexte : Le contexte éphémère du client est effacé pour garantir un test sans état.
• Vérification de la persistance : Le rappel ultérieur interroge directement le stockage distant.

6. Rappelez le fait avec attribution de source

Interrogez la convention enregistrée depuis la nouvelle session. L'activation est strictement définie comme l'achèvement du premier rappel de mémoire vérifié avec attribution de source ; copier la configuration ou inspecter des extraits de code ne constitue qu'une étape intermédiaire de configuration.

• Commande du Skill : node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1.
• Outil MCP : recall avec la requête 'demo project timestamp format'.
• Format du reçu : Sortie textuelle commençant par '### XMemo Memory Results:' indiquant Reference, Location, les mentions facultatives Created/Updated/Revision et le contenu.
• Signal de succès : Le premier rappel vérifié avec attribution de source marque la véritable activation.

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

7. Corrigez la convention avec update_memory

Lorsque les conventions du projet évoluent ou nécessitent des clarifications, mettez à jour la mémoire avec l'identifiant de mémoire actif exact ou la référence renvoyée par le rappel. Pour les clients de type Skill, utilisez la commande update. Pour les clients MCP, utilisez update_memory. Le nettoyage facultatif est géré par l'utilisateur via forget.

• Commande du Skill : node scripts/xmemo-skill.mjs update --id "mem_01hxyz..." --content "Demo project timestamps use UTC with ISO 8601 formatting.".
• Outil MCP : update_memory avec un memory_id valide.
• Piste de révision : Remplace la révision précédente tout en préservant un historique immuable.
• Nettoyage facultatif : Pour supprimer, exécutez 'node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm' (Skill) ou appelez forget (MCP).
• Signal de succès : Le reçu commence par 'XMemo memory updated.' indiquant Reference et Revision.

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

Récupération : Accès au presse-papiers refusé

Si votre navigateur refuse l'accès au presse-papiers ou si les autorisations sont bloquées, sélectionnez manuellement le texte du fragment à l'intérieur du bloc de code et copiez-le avec Ctrl+C (ou Cmd+C). Tous les blocs de code fournissent tabIndex=0 pour le défilement et la sélection au clavier.

• Symptôme : Le navigateur bloque la copie automatique dans le presse-papiers ou l'invite d'autorisation échoue.
• Action : Cliquez ou utilisez la touche tabulation pour entrer dans le conteneur de code et utilisez Ctrl+C ou Cmd+C.
• Vérification : La configuration collée correspond exactement à l'extrait affiché.

Récupération : Authentification expirée ou insuffisante

Si votre client reçoit HTTP 401 Unauthorized, HTTP 403 Forbidden ou SetupRequiredMCPError, votre jeton d'authentification a expiré ou ne dispose pas des portées requises.

• Symptôme : HTTP 401, HTTP 403 ou SetupRequiredMCPError lors de l'appel de l'outil.
• Action : Réauthentifiez-vous via OAuth, ou définissez XMEMO_KEY dans votre environnement local.
• Vérification : Confirmez que le jeton accorde à la fois les portées memory:read et memory:write.

Récupération : Outils non visibles dans le client

Si les outils XMemo n'apparaissent pas dans la palette de votre client après la configuration, le fichier de configuration peut contenir des erreurs de syntaxe ou le processus de connexion MCP peut nécessiter un redémarrage.

• Symptôme : Le client affiche 0 outil ou ne parvient pas à reconnaître le serveur MCP de XMemo.
• Action : Consultez les journaux de développement du client, validez la syntaxe JSON et redémarrez le client.
• Vérification : Les journaux du client confirment l'initialisation réussie du MCP et la découverte des outils.

Récupération : Résultats de rappel vides

Si recall ne renvoie aucune mémoire correspondante ('No matching memories found' ou 'No strong memory match'), vérifiez que l'écriture à l'Étape 4 a réussi et vérifiez votre requête de recherche.

• Symptôme : recall renvoie un message texte indiquant qu'aucune mémoire correspondante n'a été trouvée.
• Action : Vérifiez les mots-clés de la requête ('timestamp', 'UTC') et vérifiez la portée du chemin.
• Vérification : Confirmez que remember a renvoyé un reçu commençant par 'Saved to XMemo' avant d'effectuer le rappel.

Récupération : Identifiant de mémoire inconnu lors de la mise à jour

Si update_memory rejette votre appel parce que memory_id est inconnu ou invalide, ne devinez pas les identifiants.

• Symptôme : update_memory renvoie une erreur indiquant que memory_id est introuvable.
• Action : Appelez d'abord recall pour récupérer la référence de mémoire active et transmettez-la comme memory_id.
• Vérification : Transmettez la référence de mémoire active obtenue via recall à update_memory.

Récupération : Cible d'installation incorrecte

Si le programme d'installation a enregistré les scripts directement dans le répertoire racine des skills de votre agent plutôt que dans un sous-répertoire isolé, l'agent ne peut pas localiser scripts/xmemo-skill.mjs ou charge des fichiers d'installation bruts.

• Symptôme : Erreur lors de la recherche de scripts/xmemo-skill.mjs ou fichiers extraits directement dans la racine des skills.
• Action : Définissez XMEMO_SKILL_DIR explicitement vers votre répertoire de skills plus /xmemo-memory (par exemple, export XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory").
• Vérification : SKILL.md et scripts/xmemo-skill.mjs se trouvent directement dans le dossier xmemo-memory.

Récupération : Runtime Node 22.22.0 manquant

Le Skill autonome requiert Node.js >= 22.22.0. Si node est absent ou qu'une version plus ancienne est active, les opérations doctor et du skill échouent.

• Symptôme : 'command not found: node', ou erreurs de runtime au démarrage, ou node -v indique une version inférieure à 22.22.0.
• Action : Installez ou basculez vers Node.js 22.22.0 ou supérieur à l'aide de nvm (nvm install 22.22.0 && nvm use 22.22.0) ou du gestionnaire de paquets de votre système d'exploitation.
• Vérification : Exécutez 'node -v' et confirmez que la sortie est v22.22.0 ou supérieure.

Récupération : Rechargement du Skill nécessaire

Si le Skill est installé et que doctor réussit, mais que votre agent ne liste pas les outils ou opérations XMemo dans sa session active, le cache des skills en mémoire de l'agent doit être rechargé.

• Symptôme : L'agent indique n'avoir aucune connaissance des skills XMemo après l'installation.
• Action : Redémarrez la session de l'agent pour recharger les skills en mémoire.
• Vérification : Demandez à l'agent 'what skills are available?' et vérifiez que xmemo-memory est listé.

Récupération : Connexion interrompue

Si la connexion de l'appareil a été interrompue, a expiré ou a été fermée avant la saisie du code de vérification, les identifiants ne sont pas enregistrés sur le disque.

• Symptôme : Le navigateur a été fermé avant approbation, le code à usage unique a expiré ou 'auth status --verify' signale auth_valid: false.
• Action : Si vous n'utilisez pas de secret-store XMEMO_KEY ou d'identifiants gérés, réexécutez 'node scripts/xmemo-skill.mjs login --allow-plaintext' (ce qui stocke l'identifiant non chiffré sur cet ordinateur), ouvrez l'URL affichée et saisissez le code avant son expiration.
• Vérification : Exécutez 'node scripts/xmemo-skill.mjs auth status --verify' et confirmez 'status: ok' avec 'auth_valid: true'.