Lifecycle and diagnostics

\n\n```bash\nxmemo --version\nxmemo update\nxmemo update --dry-run\nxmemo doctor\nxmemo discovery show\nxmemo status\nxmemo privacy\nxmemo skill install\nxmemo skill install --version \nxmemo skill install --from \n```\n\n

\n\n

Authentication

\n\n```bash\nxmemo login\nxmemo auth status\nxmemo auth-status --verify\nxmemo token status --verify\nxmemo token add --from-stdin --allow-plaintext\nxmemo env example --shell bash\n```\n\n

\n\n

Client setup

\n\n```bash\nxmemo setup \nxmemo setup --dry-run\nxmemo setup --all\nxmemo setup openclaw [--with-mcp|--mcp-only]\nxmemo setup hermes [--with-mcp|--mcp-only]\n```\n\n

\n\n

Direct XMemo service client

\n\n```bash\nxmemo memory add --content \"Remember this\" --path notes/example --json\nxmemo memory search \"example\" --json\nxmemo context recall \"resume this task\" --include-knowledge --json\nxmemo state save --current-task \"ship the client\" --next-action \"run tests\" --json\nxmemo state restore --json\nxmemo restart snapshot --json\nxmemo restart restore --snapshot-id --json\n\nxmemo knowledge add --base --file ./guide.pdf --title \"Guide\" --json\nxmemo knowledge search \"setup\" --base --json\nxmemo knowledge read --json > knowledge-view.json\nxmemo knowledge update --text \"Updated\" --from knowledge-view.json --publish --yes --json\n\nxmemo dream preview --wait --json\nxmemo dream show --json > dream-view.json\nxmemo dream apply --item --from dream-view.json --yes --json\n\nxmemo cloud-skill list --json\nxmemo cloud-skill add --file ./SKILL.md --json\nxmemo cloud-skill show --json > skill-view.json\nxmemo cloud-skill update --from skill-view.json --file ./SKILL.md --json\nxmemo cloud-skill run --input ./args.json --from skill-view.json --yes --json\n```\n\nAll direct service commands support a single machine-readable JSON envelope.\nKnowledge update, Dream apply, and Cloud Skill run use the `readReceipt` from a\nsaved read/show result so the CLI never silently substitutes a newer revision.\nSet `XMEMO_KNOWLEDGE_BASE_ID` for a non-interactive default knowledge base.\nFor a long knowledge item, continue the same fixed revision with\n`xmemo knowledge read --from knowledge-view.json --offset `.\nRun `xmemo doctor --services --json` for read-only Knowledge, Dream, and Cloud\nSkill diagnostics; it deliberately does not claim write or production readiness.\n\nCloud Skill add/update already target the safe create-only and content-CAS\ncontracts. They fail with `SERVER_CONTRACT_REQUIRED` on older services and do\nnot fall back to legacy upsert routes. Binary Knowledge item updates similarly\nrequire a new version of the same server Document; use `--document` and\n`--document-version` after that version has been uploaded.\n\nThe normal login scopes remain unchanged. Request additional service scopes\nexplicitly when needed, for example:\n\n```bash\nxmemo login --scopes memory:read,memory:write,memory:restore,knowledge:read,knowledge:write\n```\n\n

\n\n

MCP and behavior profiles

\n\n```bash\nxmemo mcp serve\nxmemo mcp list\nxmemo mcp config --client generic\nxmemo mcp add --write\nxmemo mcp proxy\nxmemo profile install \nxmemo profile status \nxmemo profile uninstall \nxmemo smoke --client codex\n```\n\n

\n\n

Safe removal

\n\n```bash\nxmemo uninstall --dry-run\nxmemo uninstall --yes\nxmemo uninstall --all --dry-run\nxmemo uninstall --all --yes --profiles\n```\n\nOnly XMemo-owned entries and marker-scoped behavior profiles are removed.\nUnrelated MCP servers, credentials, and device identity remain intact.\n\n

\n\nRun `xmemo help` or `xmemo --help` for complete, version-matched\noptions.\n\n## Client notes\n\n

Codex and Cursor

\n\n```bash\nxmemo setup codex\nxmemo smoke --client codex\n\nxmemo setup cursor\n```\n\nBoth setup paths write a user-scoped MCP entry and can install a marker-scoped\nmemory behavior profile. Use `--no-profile` to configure MCP only. Cursor's\npublic marketplace plugin remains OAuth-first and contains no bearer-token\nconfiguration.\n\n

\n\n

Gemini CLI and Antigravity

\n\n```bash\nxmemo setup gemini\nxmemo setup antigravity\n```\n\nThese clients use hosted MCP OAuth. Their generated configuration carries no\ntoken value; restart the client and complete the browser login on first use.\n\n

\n\n

OpenClaw

\n\n```bash\nxmemo login\nxmemo setup openclaw\nopenclaw xmemo status\n```\n\nThe setup command installs or updates `@xmemo/openclaw-memory`, installs the\nXMemo Skill, reuses the shared XMemo credential, and checks plugin status.\n\n

\n\n

Hermes

\n\n```bash\nxmemo login\nxmemo setup hermes\n```\n\nThe setup command installs or updates `hermes-xmemo`, configures the native\nprovider, and synchronizes the user-scoped XMemo credential with Hermes.\n\n

\n\n

Copilot CLI

\n\n```bash\nxmemo login\nxmemo setup copilot\nxmemo mcp proxy\n```\n\nCopilot CLI receives a local proxy entry. The proxy reads the credential from\nuser-scoped storage, adds identity metadata, and forwards requests to hosted\nMCP without writing secrets into Copilot configuration.\n\n

\n\n## Security by default\n\n| Control | Default behavior |\n| --- | --- |\n| **Telemetry** | No CLI analytics or usage telemetry |\n| **Credential output** | Token values are never printed |\n| **Project files** | Generated configuration references secrets; it does not embed them |\n| **Discovery** | `doctor`, `discovery show`, and public capability discovery send no token |\n| **Identity** | One stable, non-secret agent-instance ID is stored outside git |\n| **Writes** | Setup supports preview/dry-run; broad removal requires confirmation |\n| **Local credential storage** | Interactive login asks first; non-interactive writes require `--allow-plaintext`; stored tokens are unencrypted |\n| **Package contents** | An npm `files` allowlist excludes tests, operations, logs, and server code |\n\nCredential precedence and compatibility aliases are documented by:\n\n```bash\nxmemo env example --shell bash\nxmemo privacy\n```\n\nFor private or self-hosted deployments, set `XMEMO_URL` or pass\n`--url `. `MEMORY_OS_URL` remains a compatibility alias.\n\n## Package boundary\n\nPublished to npm:\n\n```text\nbin/\ndocs/assets/\nsrc/\nplugins/xmemo/\nREADME.md\nLICENSE\n```\n\nNot published:\n\n```text\n.github/\ndocs/analysis/\ndocs/architecture/\ndocs/design/\ntest/\ncoverage/\nserver code\ndatabase migrations\ndeployment files\nlogs and local state\n```\n\n## Development\n\n```bash\nnpm install\nnpm run release:check\nnpm run lint\nnpm test\nnpm run pack:dry-run\n```\n\nBefore proposing a release, run the complete package gate:\n\n```bash\nnpm run prepublishOnly\n```\n\nThe local stdio server can be inspected directly:\n\n```bash\nnode bin/mcp-stdio.js\n```\n\n## Versioning\n\nThis repository distributes two independent products with decoupled version tracks:\n\n- **CLI (`@xmemo/client`)**: Published to [npm](https://www.npmjs.com/package/@xmemo/client).\n - Version source: `package.json`.\n - Tag convention: `cli-v*` (legacy tags through version 0.4.181 used `v0.4.xxx`).\n - View versions on [npm (@xmemo/client)](https://www.npmjs.com/package/@xmemo/client).\n- **Skill (`xmemo`)**: Published to [ClawHub](https://clawhub.ai/skill/xmemo) and distributed via [xmemo.dev](https://xmemo.dev/v1/skill/package).\n - Version source: `skills/xmemo/scripts/xmemo-skill.mjs` (`SKILL_VERSION`).\n - Tag convention: `skill-v*`.\n - View versions on [ClawHub (xmemo)](https://clawhub.ai/skill/xmemo). GitHub Releases for skill releases explicitly carry the `Latest` release badge to support automated installer and server fallback downloads.\n\n## Release model\n\nNormal releases are produced by GitHub Actions from the exact tagged commit,\nnot from a mutable branch checkout or a developer workstation:\n\n```text\ndevelop → CLI version sync → test → cli-v tag → GitHub Actions → npm publish --provenance\n```\n\nThe CLI package and hosted MCP service intentionally have separate version\nstreams:\n\n- CLI/npm version: `package.json`, `package-lock.json`, and the npm package\n entry in `server.json`.\n- Hosted MCP/Registry version: the top-level `server.json.version` and\n `lhm.plugin.json`. This version follows the deployed XMemo service.\n\n`node scripts/check-release-version.mjs` verifies both contracts. A\n`cli-vX.Y.Z` tag must equal the CLI/npm version and publishes only npm. The\nMCP Registry is published separately with the `Publish MCP Registry metadata`\nworkflow using `mcp-vX.Y.Z`, which must equal the hosted MCP/Registry version.\nThe separate npm publish workflow is manual recovery only, so creating a\nGitHub Release cannot publish twice.\n\n## Documentation and support\n\nCanonical service documentation lives at [xmemo.dev/docs](https://xmemo.dev/docs/quickstart).\nThis repository documents the client; the pages below document the hosted service\nit connects to.\n\n| | |\n| --- | --- |\n| **Quickstart** | [xmemo.dev/docs/quickstart](https://xmemo.dev/docs/quickstart) |\n| **MCP overview and per-client setup** | [xmemo.dev/docs/mcp/overview](https://xmemo.dev/docs/mcp/overview) |\n| **Tool reference** (`remember`, `recall`, `search`, …) | [xmemo.dev/docs/tools/remember](https://xmemo.dev/docs/tools/remember) |\n| **REST API** | [xmemo.dev/docs/api/authentication](https://xmemo.dev/docs/api/authentication) |\n| **Troubleshooting** | [xmemo.dev/docs/troubleshooting](https://xmemo.dev/docs/troubleshooting) |\n| **Machine-readable index** | [xmemo.dev/llms.txt](https://xmemo.dev/llms.txt) |\n\n- [XMemo](https://xmemo.dev)\n- [MCP server reference](https://github.com/yonro/memory-os-cli/blob/main/MCP-README.md)\n- [Adding a new client](https://github.com/yonro/memory-os-cli/blob/main/ADDING_CLIENTS.md)\n- [Issues](https://github.com/yonro/memory-os-cli/issues)\n- [Releases](https://github.com/yonro/memory-os-cli/releases)\n\n## License\n\n[MIT](https://github.com/yonro/memory-os-cli/blob/main/LICENSE) © 2025–2026 Yonro\n\n### Repairing an existing Kiro MCP configuration\n\nRun `xmemo doctor --client kiro --json` to inspect local configuration without network requests.\nUse `xmemo doctor --client kiro --fix` to migrate recognized legacy proxy configurations to native\nHTTP OAuth, or add `--auth key` for native HTTP with `Bearer ${XMEMO_KEY}`. Repairs create a\nbackup, retain unrelated servers and client preferences, and never copy credentials into the\nreplacement. Reload Kiro and verify a real tool call afterwards; a configuration pass is not an\nauthentication or token-refresh result. Fresh installs use `xmemo setup kiro [--auth oauth|key]`.\n","changelogMarkdown","videoKey","requiredSecretsJson","[{\"name\":\"X-Memory-OS-Agent-ID\",\"scope\":\"per-user\",\"header\":\"X-Memory-OS-Agent-ID\"},{\"name\":\"X-Memory-OS-Agent-Instance-ID\",\"scope\":\"per-user\",\"header\":\"X-Memory-OS-Agent-Instance-ID\"},{\"name\":\"X-Memory-OS-Device-ID\",\"scope\":\"per-user\",\"header\":\"X-Memory-OS-Device-ID\"},{\"name\":\"X-Memory-OS-Device-Label\",\"scope\":\"per-user\",\"header\":\"X-Memory-OS-Device-Label\"}]","publishedAt",1790355300000,"priceCents","trialDays","iconType","image","upstream",{"_117":118,"_119":120,"_121":122,"_123":124,"_125":126,"_127":128},"requiredSecrets",[105,106,107,108],"tags",[104,65],"assets",[],"stats",{"_102":45,"_103":45},"ratingAvg","reviewCount","ai-memory",{"_109":116,"_111":112,"_113":116},{"_109":115,"_111":112,"_113":115},{"_109":114,"_111":112,"_113":114},{"_109":110,"_111":112,"_113":110},"name","X-Memory-OS-Device-Label","scope","per-user","header","X-Memory-OS-Device-ID","X-Memory-OS-Agent-Instance-ID","X-Memory-OS-Agent-ID","topics",[104,135,136,137,65],"license","MIT","language","JavaScript","registryName","io.github.yonro/xmemo","homepage","https://xmemo.dev/product/mcp","packages",[129],{"_130":131,"_132":133,"_78":134},"registryType","npm","identifier","@xmemo/client","0.4.186","mcp","mcp-server","model-context-protocol","ENV",{"_140":141,"_142":143,"_144":145,"_146":-7},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272","SENTRY_ENABLE_LOCAL"]