{
  "markdown": "<div align=\"center\">\n  <a href=\"https://xmemo.dev\">\n    <img src=\"./plugins/xmemo/assets/logo.png\" width=\"132\" alt=\"XMemo logo\">\n  </a>\n\n  <h1>XMemo CLI</h1>\n\n  <p><strong>One private memory layer for every AI agent.</strong></p>\n  <p>\n    Install, authenticate, diagnose, and connect XMemo across editors,\n    CLIs, and autonomous agents from one production-ready command line.\n  </p>\n\n  <p>\n    <a href=\"https://github.com/yonro/memory-os-cli/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/yonro/memory-os-cli/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI\"></a>\n    <a href=\"https://www.npmjs.com/package/@xmemo/client\"><img alt=\"npm version\" src=\"https://img.shields.io/npm/v/@xmemo/client?style=flat-square&logo=npm&logoColor=white&label=npm\"></a>\n    <a href=\"https://www.npmjs.com/package/@xmemo/client\"><img alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/@xmemo/client?style=flat-square&logo=npm&logoColor=white&label=downloads\"></a>\n    <a href=\"https://www.npmjs.com/package/@xmemo/client\"><img alt=\"Node.js version\" src=\"https://img.shields.io/node/v/@xmemo/client?style=flat-square&logo=nodedotjs&logoColor=white&label=node\"></a>\n    <a href=\"./LICENSE\"><img alt=\"MIT license\" src=\"https://img.shields.io/npm/l/@xmemo/client?style=flat-square&label=license\"></a>\n    <a href=\"https://github.com/yonro/memory-os-cli/stargazers\"><img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/yonro/memory-os-cli?style=flat-square&logo=github&label=stars\"></a>\n  </p>\n\n  <p>\n    <a href=\"https://modelcontextprotocol.io/\"><img alt=\"MCP compatible\" src=\"https://img.shields.io/badge/MCP-compatible-2563eb?style=flat-square\"></a>\n    <a href=\"https://xmemo.dev\"><img alt=\"XMemo Cloud\" src=\"https://img.shields.io/badge/XMemo-Cloud-7c3aed?style=flat-square\"></a>\n    <a href=\"#security-by-default\"><img alt=\"Privacy first\" src=\"https://img.shields.io/badge/privacy-first-334155?style=flat-square&logo=shield&logoColor=white\"></a>\n    <a href=\"https://lobehub.com/mcp/yonro-memory-os-cli\"><img alt=\"MCP Badge\" src=\"https://lobehub.com/badge/mcp/yonro-memory-os-cli?style=flat\"></a>\n    <a href=\"https://glama.ai/mcp/servers/yonro/memory-os-cli\"><img alt=\"Glama quality score\" src=\"https://glama.ai/mcp/servers/yonro/memory-os-cli/badges/score.svg\"></a>\n  </p>\n\n  <p>\n    <a href=\"#quick-start\">Quick start</a> ·\n    <a href=\"#supported-integrations\">Integrations</a> ·\n    <a href=\"#connection-modes\">Connection modes</a> ·\n    <a href=\"#command-reference\">Commands</a> ·\n    <a href=\"#security-by-default\">Security</a>\n  </p>\n</div>\n\n---\n\n`@xmemo/client` is the official control plane for connecting AI tools to\n[XMemo](https://xmemo.dev). It makes setup repeatable, keeps credentials out of\nproject files, and gives every supported client a consistent path to durable,\nuser-owned memory.\n\nThe package is deliberately small: the CLI runtime, safe client configuration,\nbehavior profiles, XMemo skills, and marketplace metadata. Server code,\ndatabases, deployment files, logs, and internal operations remain outside the\nnpm distribution.\n\n## Architecture\n\n<p align=\"center\">\n  <img src=\"./docs/assets/xmemo-cli-architecture.svg\" width=\"100%\" alt=\"XMemo CLI architecture\">\n</p>\n\n| | |\n| --- | --- |\n| **Package** | [`@xmemo/client`](https://www.npmjs.com/package/@xmemo/client) |\n| **Primary command** | `xmemo` |\n| **Local MCP command** | `xmemo-mcp` |\n| **Hosted MCP** | `https://xmemo.dev/mcp` |\n| **Runtime** | Node.js 20 or later |\n| **License** | MIT |\n\n## Why XMemo CLI\n\n- **One control plane** — login, diagnostics, configuration, profiles, updates,\n  and smoke checks share one predictable interface.\n- **Private by design** — generated project configuration references a\n  credential; it never embeds the credential value.\n- **Native where it matters** — OpenClaw and Hermes use dedicated memory\n  integrations instead of duplicating the same capability through MCP.\n- **Portable everywhere else** — hosted Streamable HTTP MCP and local stdio\n  cover modern editors, terminals, and agent runtimes.\n- **Safe automation** — supported setup and removal paths offer preview,\n  dry-run, or explicit confirmation before making changes.\n- **Small supply-chain surface** — the npm package is governed by an explicit\n  file allowlist and release provenance.\n\n## Quick start\n\n```bash\nnpm install -g @xmemo/client\nxmemo login\nxmemo doctor\nxmemo setup codex\nxmemo status\n```\n\nReplace `codex` with your client. Preview a configuration before writing it:\n\n```bash\nxmemo setup cursor --dry-run\n```\n\n<p align=\"center\">\n  <img src=\"./docs/assets/xmemo-cli-workflow.svg\" width=\"100%\" alt=\"XMemo CLI setup workflow\">\n</p>\n\n> [!TIP]\n> Start with `xmemo login`, `xmemo doctor`, and `xmemo setup <client>`.\n> Hand-edit MCP configuration only when a client has no verified setup path.\n\n## Supported integrations\n\n| Client | Recommended command | Connection |\n| --- | --- | --- |\n| **Codex** | `xmemo setup codex` | Hosted MCP + behavior profile |\n| **Cursor** | `xmemo setup cursor` | Hosted MCP + Bearer Token + behavior profile |\n| **Copilot CLI** | `xmemo setup copilot` | Local authenticated proxy |\n| **Gemini CLI** | `xmemo setup gemini` | Hosted MCP + OAuth |\n| **Antigravity** | `xmemo setup antigravity` | Hosted MCP + OAuth |\n| **OpenClaw** | `xmemo setup openclaw` | Native memory plugin + Skill |\n| **Hermes** | `xmemo setup hermes` | Native memory provider |\n| **Kiro** | `xmemo setup kiro` | Hosted MCP + Bearer Token |\n| **Grok** | `xmemo setup grok` | Hosted MCP |\n| **Other MCP clients** | `xmemo mcp config --client generic` | Generated template |\n\nThe client registry also covers Windsurf, Cline, Continue, Claude Desktop,\nClaude Code, Kimi Code, Zed, JetBrains, OpenCode, Qwen, Trae, and compatible\nMCP hosts. Run `xmemo mcp list` for the current machine-readable catalog.\n\n## Connection modes\n\n### Hosted MCP\n\nThe recommended universal path is the XMemo Streamable HTTP endpoint:\n\n```text\nhttps://xmemo.dev/mcp\n```\n\nOAuth-capable clients complete authentication in the browser. Other clients\nreference `XMEMO_KEY` without copying its value into repository files.\n\nGeneric configuration shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"XMemo\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://xmemo.dev/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${XMEMO_KEY}\"\n      }\n    }\n  }\n}\n```\n\nClient configuration keys differ; prefer `xmemo setup <client>` over copying\nthis generic example directly.\n\n### Local stdio MCP\n\n`xmemo-mcp` is the dedicated stdio entry point for marketplaces and clients\nthat launch a local process. Safe discovery exposes 20 tools, three prompts,\nand two documentation resources without a token. Tool execution still requires\nauthentication.\n\nAfter a global installation:\n\n```bash\nxmemo-mcp\n```\n\nInstall-free MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"XMemo\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"--package\",\n        \"@xmemo/client@latest\",\n        \"xmemo-mcp\"\n      ]\n    }\n  }\n}\n```\n\n`xmemo mcp serve` is equivalent when the CLI is already installed.\n\n### Native integrations\n\nOpenClaw and Hermes have dedicated memory providers. Their default setup avoids\ninstalling a second, duplicate XMemo tool surface.\n\n```bash\n# Native OpenClaw plugin + XMemo Skill\nxmemo setup openclaw\n\n# Native Hermes memory provider\nxmemo setup hermes\n```\n\nAdd hosted MCP only when an explicit fallback is desired:\n\n```bash\nxmemo setup openclaw --with-mcp\nxmemo setup hermes --with-mcp\n```\n\nUse `--mcp-only` to skip the native integration and install only the hosted MCP\nfallback.\n\n## Authentication\n\n### Browser login\n\nRecommended for personal accounts:\n\n```bash\nxmemo login\nxmemo auth status\n```\n\nThe CLI uses the hosted device-login flow, waits for browser approval, and\nasks once before storing the issued credential unencrypted in the current\nuser's XMemo config directory. The exact path is shown before approval, file\npermissions are restricted where the operating system supports it, and the\ncredential value is never printed. Prefer `XMEMO_KEY` or a managed secret store\non shared systems.\n\nFor non-interactive automation, record the same decision explicitly:\n\n```bash\nxmemo login --allow-plaintext\n```\n\n### Existing token\n\nPipe an existing token through stdin so it does not appear in command history:\n\n```bash\nprintf '%s\\n' 'your-token' | xmemo token add --from-stdin --allow-plaintext\nxmemo token status --verify\n```\n\nPowerShell:\n\n```powershell\n$xmemoToken = Read-Host \"XMemo token\"\n$xmemoToken | xmemo token add --from-stdin --allow-plaintext\nRemove-Variable xmemoToken\n```\n\nFor CI and managed workstations, expose `XMEMO_KEY` through the platform's\nsecret manager. Do not commit it to `.env`, MCP configuration, logs, issue\nreports, or chat transcripts.\n\n## Command reference\n\n<details>\n<summary><strong>Lifecycle and diagnostics</strong></summary>\n\n```bash\nxmemo --version\nxmemo update\nxmemo update --dry-run\nxmemo doctor\nxmemo discovery show\nxmemo status\nxmemo privacy\n```\n\n</details>\n\n<details>\n<summary><strong>Authentication</strong></summary>\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</details>\n\n<details>\n<summary><strong>Client setup</strong></summary>\n\n```bash\nxmemo setup <client>\nxmemo setup <client> --dry-run\nxmemo setup --all\nxmemo setup openclaw [--with-mcp|--mcp-only]\nxmemo setup hermes [--with-mcp|--mcp-only]\n```\n\n</details>\n\n<details>\n<summary><strong>Direct XMemo service client</strong></summary>\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 <snapshot-id> --json\n\nxmemo knowledge add --base <base-id> --file ./guide.pdf --title \"Guide\" --json\nxmemo knowledge search \"setup\" --base <base-id> --json\nxmemo knowledge read <item-id> --json > knowledge-view.json\nxmemo knowledge update <item-id> --text \"Updated\" --from knowledge-view.json --publish --yes --json\n\nxmemo dream preview --wait --json\nxmemo dream show <run-id> --json > dream-view.json\nxmemo dream apply <run-id> --item <candidate-id> --from dream-view.json --yes --json\n\nxmemo cloud-skill list --json\nxmemo cloud-skill add --file ./SKILL.md --json\nxmemo cloud-skill show <skill-id> --json > skill-view.json\nxmemo cloud-skill update <skill-id> --from skill-view.json --file ./SKILL.md --json\nxmemo cloud-skill run <skill-id> --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 <item-id> --from knowledge-view.json --offset <n>`.\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</details>\n\n<details>\n<summary><strong>MCP and behavior profiles</strong></summary>\n\n```bash\nxmemo mcp serve\nxmemo mcp list\nxmemo mcp config --client generic\nxmemo mcp add <client> --write\nxmemo mcp proxy\nxmemo profile install <client>\nxmemo profile status <client>\nxmemo profile uninstall <client>\nxmemo smoke --client codex\n```\n\n</details>\n\n<details>\n<summary><strong>Safe removal</strong></summary>\n\n```bash\nxmemo uninstall <client> --dry-run\nxmemo uninstall <client> --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</details>\n\nRun `xmemo help` or `xmemo <command> --help` for complete, version-matched\noptions.\n\n## Client notes\n\n<details>\n<summary><strong>Codex and Cursor</strong></summary>\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</details>\n\n<details>\n<summary><strong>Gemini CLI and Antigravity</strong></summary>\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</details>\n\n<details>\n<summary><strong>OpenClaw</strong></summary>\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</details>\n\n<details>\n<summary><strong>Hermes</strong></summary>\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</details>\n\n<details>\n<summary><strong>Copilot CLI</strong></summary>\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</details>\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 <service-url>`. `MEMORY_OS_URL` remains a compatibility alias.\n\n## Package boundary\n\nPublished to npm:\n\n```text\nbin/\ndocs/assets/\nsrc/\nskills/\nplugins/kiro/\nplugins/xmemo/\nREADME.md\nLICENSE\n```\n\nNot published:\n\n```text\n.github/\ndocs/analysis/\ndocs/architecture/\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## 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](./MCP-README.md)\n- [Adding a new client](./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](./LICENSE) © 2025–2026 Yonro\n",
  "bytes": 18150,
  "sha": "a8b0ba0dda4e969b9228e0811adbec842df2022d76d6238029f3740c28231fb9",
  "repo_slug": "yonro/memory-os-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yonro_xmemo_1ffb675e/readme"
}