ReferenceSkillsSkill updates and lifecycle

Skill

Skill updates and lifecycle

Inspect versions, update releases, handle backups, and safely remove the local standalone Skill runtime.

Distinct Skill and CLI versions

The standalone Skill runtime and the XMemo CLI are independent packages with separate version numbers and release lifecycles. Updating one does not automatically mutate the other.

  • Standalone Skill package: Version 1.1.35 (@xmemo/skill@1.1.35), inspectable via node scripts/xmemo-skill.mjs --version or doctor.
  • XMemo CLI package: Version 0.4.x / 1.x (@xmemo/client@0.4.187), inspectable via xmemo --version.
  • Independent updates: Updating @xmemo/client through npm updates the CLI orchestrator, but does not alter existing installed skill directories until xmemo skill update is run.
  • Subresource Integrity (SRI): The CLI verifies package tarballs using sha512 SRI before extracting files into agent skill directories.
# Inspect standalone Skill version:
node scripts/xmemo-skill.mjs --version

# Inspect XMemo CLI version:
xmemo --version

# Inspect detailed runtime health and discovery status:
node scripts/xmemo-skill.mjs doctor

CLI skill lifecycle commands

The XMemo CLI provides dedicated commands to inspect installation status, install across agent clients, update to newer releases, and safely remove skills.

  • Status: xmemo skill status [--client <id>|--all] [--json] inspects installed skills and reports version, client ID, and target path.
  • Install: xmemo skill install [--client <id>|--all] [--project] [--global] [--dir <path>] [--dry-run] [--yes] [--force] [--json].
  • Update: xmemo skill update [--client <id>|--all] [--dry-run] [--yes] [--json] updates installed skills to the latest pinned release.
  • Remove: xmemo skill remove --client <id> [--project] [--yes] [--json] safely removes verified skill folders.
# Check status across all detected clients:
xmemo skill status --all

# Update an installed skill with preview:
xmemo skill update --client codex --dry-run
xmemo skill update --client codex --yes

# Install to a specific client:
xmemo skill install --client claude-code --yes

Existing-install handling, backups, and recovery

To prevent accidental overwrites or lost customizations, the installer refuses to overwrite an existing directory without explicit confirmation and automatically preserves backups.

  • Overwrite refusal: Re-running install against an existing skill directory stops and reports an existing installation unless --force (or XMEMO_SKILL_FORCE=1) is passed.
  • Automated backup location: When --force or skill update replaces an installation, the previous version is moved to ~/.xmemo/backups/skills/<client_id>/<name>-<timestamp> (or ~/.xmemo/backups/skills/custom/<basename>-<timestamp> for custom directories).
  • Isolation from agent loading: Backups reside safely in ~/.xmemo/backups/, outside the agent's active skills search paths, preventing duplicate tool registrations.
  • Recovery: To roll back an update, restore the preserved backup directory from ~/.xmemo/backups/skills/<client_id>/ back into the active agent skills folder.
# Force re-install with automatic backup creation:
xmemo skill install --client codex --force --yes

# Inspect preserved backups:
ls -la ~/.xmemo/backups/skills/codex/

What removal leaves behind

Removing a skill is a local filesystem operation that unlinks the skill directory. It does not erase your credentials, local configuration, or remote memories.

  • Local skill directory removed: xmemo skill remove deletes only the verified xmemo-memory directory and refuses foreign folders.
  • Credentials remain intact: ~/.xmemo/skill-credentials.json and environment XMEMO_KEY remain untouched.
  • Configuration remains intact: Local settings under ~/.xmemo/ remain intact.
  • Remote memories remain intact: Stored memories, Knowledge items, and TODOs on xmemo.dev are not deleted by skill removal.
  • Complete credential cleanup: Run node scripts/xmemo-skill.mjs logout before removal to revoke the active session token, or manually delete ~/.xmemo/skill-credentials.json.
  • Memory purging: Remote memories remain accessible until soft-deleted via node scripts/xmemo-skill.mjs forget --id <id> --confirm or purged through the Memory Console.
# Step 1: Revoke active session credentials (optional):
node scripts/xmemo-skill.mjs logout

# Step 2: Remove the installed skill directory:
xmemo skill remove --client codex --yes

Skill updates and lifecycle

Skills are the instruction-and-command lane for agents that do not mount a hosted MCP server directly.

Open XMemo Skills

Source: XMemo Skills