Skills quickstart

When to choose the Skill instead of MCP

The standalone Skill is an agent connector runtime for hosts that cannot mount a hosted MCP server, communicating over direct HTTPS with XMemo. It is distinct from user-authored Cloud Skills (reusable procedural SOPs stored in XMemo).

• Use hosted MCP when the agent host natively mounts remote MCP servers.
• Use the standalone Skill runtime when the host executes local CLI tools or skill scripts instead.
• Runtime requirement: Node.js 22.22.0 or higher (Node.js >= 22.22.0) with built-in ESM support.
• Zero external dependencies: The bundled skill script uses only standard Node.js built-in modules.
• Direct HTTPS communication: Outbound requests talk directly to https://xmemo.dev/v1/skill/operations.

Installation by prompt and by client

Install the standalone Skill into your agent skills directory. You can provide the official installation prompt to your agent, use the XMemo CLI, or run the canonical HTTPS installer directly.

• Ask your agent 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.
• Claude Code global: ~/.claude/skills/xmemo-memory (project-level: .claude/skills/xmemo-memory).
• Codex: ~/.codex/skills/xmemo-memory (or ${CODEX_HOME:-$HOME/.codex}/skills/xmemo-memory).
• OpenClaw: ~/.openclaw/skills/xmemo-memory or install via ClawHub (https://clawhub.ai/xmemo/skills/xmemo).
• XMemo CLI: xmemo skill install --client <id> (supports claude-code, codex, and openclaw) or xmemo skill install --all.
• Manual installer fallback: POSIX 'curl -fsSL https://xmemo.dev/skill/install | sh' or PowerShell 'irm https://xmemo.dev/skill/install.ps1 | iex'.
• Service release notice: Automated parent-directory creation and the printed post-install doctor line take effect after the next service release; in pre-release environments, ensure the parent directory exists before running the installer.

# Ask your agent to run the installer, or run it directly:
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_DIR="$HOME/.claude/skills/xmemo-memory" sh

# Or install via XMemo CLI:
xmemo skill install --client claude-code

First run and authentication

Run connectivity and authentication checks from the installed skill directory before initiating memory operations. Installation, authentication, and activation are distinct milestones.

• Check reachability: Run doctor --anonymous to verify network and service reachability without credentials.
• Choose credential source: Prefer an XMEMO_KEY supplied by a managed secret store (Doppler, 1Password, or environment).
• Interactive sign-in: Run login --allow-plaintext to start browser-based device sign-in. The --allow-plaintext flag explicitly confirms storing the token unencrypted in ~/.xmemo/skill-credentials.json with 0600 POSIX permissions.
• Verify authentication: Run auth status --verify to validate that your credential carries the required memory scopes.

node scripts/xmemo-skill.mjs doctor --anonymous
node scripts/xmemo-skill.mjs login --allow-plaintext
node scripts/xmemo-skill.mjs auth status --verify

First useful memory task

Complete a full memory lifecycle: save a synthetic project fact, recall it with source attribution, update it when details evolve, and optionally soft-delete it with confirmation.

• 1. Save synthetic fact: node scripts/xmemo-skill.mjs remember --content "Project convention: all timestamps use UTC." --path "projects/onboarding/conventions".
• 2. Recall fact: node scripts/xmemo-skill.mjs recall --query "project timestamp convention". Check that the returned memory matches your saved content.
• 3. Update memory: node scripts/xmemo-skill.mjs update --id <id> --content "Project convention: all timestamps use UTC with ISO 8601 formatting.".
• 4. Optional cleanup: node scripts/xmemo-skill.mjs forget --id <id> --confirm. Deletion strictly requires --confirm.

node scripts/xmemo-skill.mjs remember --content "Project convention: all timestamps use UTC." --path "projects/onboarding/conventions"
node scripts/xmemo-skill.mjs recall --query "project timestamp convention"
node scripts/xmemo-skill.mjs update --id mem_01hxyz... --content "Project convention: all timestamps use UTC with ISO 8601 formatting."
node scripts/xmemo-skill.mjs forget --id mem_01hxyz... --confirm

Project profile and AGENTS.md offer

When first-run sign-in completes, the agent can offer to add an XMemo memory section to your project's AGENTS.md. This offer requires separate explicit user consent.

• Separately consented offer: If the project lacks an XMemo section, the agent asks once: 'Want XMemo used automatically in every session of this project? I can add a short XMemo section to AGENTS.md (yes / later / don't ask again).'
• Print instructions: node scripts/xmemo-skill.mjs profile prints recommended prompt instructions for project agent configuration.
• Record user preference: node scripts/xmemo-skill.mjs profile --status later or node scripts/xmemo-skill.mjs profile --status never records the answer so the agent does not prompt repeatedly.
• Ecosystem registries: Verified Skill listing is available on ClawHub at https://clawhub.ai/xmemo/skills/xmemo; OpenClaw companion plugin at https://clawhub.ai/xmemo/plugins/openclaw-memory.

# Inspect agent profile instructions:
node scripts/xmemo-skill.mjs profile

# Record deferred or declined offer:
node scripts/xmemo-skill.mjs profile --status later
node scripts/xmemo-skill.mjs profile --status never