@xmemo/client 0.4.129 → 0.4.132

package/LICENSE

@@ -1,7 +1,7 @@
-Copyright (c) Yonro.
-
-All rights reserved.
-
-This package is published as a client distribution artifact for XMemo.
-No license is granted to copy, modify, distribute, sublicense, or use the source
-code except as expressly permitted by Yonro in a separate written agreement.
+Copyright (c) Yonro.
+
+All rights reserved.
+
+This package is published as a client distribution artifact for XMemo.
+No license is granted to copy, modify, distribute, sublicense, or use the source
+code except as expressly permitted by Yonro in a separate written agreement.

package/README.md

@@ -1,313 +1,322 @@
-# XMemo CLI
-
-`@xmemo/client` is the privacy-first command line entry point for XMemo client
-setup. It is intentionally small: the npm package contains only the CLI and
-setup helper code needed on a user's machine.
-
-`@yonro/xmemo-client` is reserved as a Yonro fallback package. The CLI exposes
-`xmemo` as the primary command and keeps `memory-os` as a compatibility alias.
-
-The XMemo server, database, token registry, deployment files, logs, and
-internal scripts are not part of this npm package.
-
-## Install
-
-```bash
-npm install -g @xmemo/client
-```
-
-Upgrade an existing global install:
-
-```bash
-xmemo update
-```
-
-This runs `npm install -g @xmemo/client@latest`. Use `xmemo update --dry-run`
-to print the exact command without changing anything.
-
-## Commands
-
-```bash
-xmemo update
-xmemo setup codex
-xmemo setup codex --yes
-xmemo smoke --client codex
-xmemo doctor
-xmemo discovery show
-xmemo setup
-xmemo login
-xmemo auth status
-xmemo status
-xmemo token status
-xmemo token add --from-stdin
-xmemo env example --shell bash
-xmemo mcp list
-xmemo mcp config --client generic
-xmemo profile status codex
-xmemo mcp add cursor --url "https://your-private-service.example"
-xmemo privacy
-```
-
-## Enterprise privacy and security defaults
-
-- No telemetry or analytics.
-- `xmemo doctor`, `xmemo discovery show`, and `xmemo status` do not send tokens.
-- MCP config generated by the CLI references `XMEMO_KEY`; it does not write
-  token values into project files.
-- The CLI generates one stable non-secret `XMEMO_AGENT_INSTANCE_ID` per local
-  client profile and stores it in user-scoped config outside git.
-- `xmemo login` and `xmemo token add` store tokens only in the user-scoped
-  XMemo CLI credential file outside git; token values are never printed.
-- Legacy `xmemo token set` refuses plaintext credential storage unless
-  `--allow-plaintext` is explicitly provided.
-- The npm package uses a `files` whitelist so only `bin`, `src`, `README.md`,
-  and `LICENSE` are published.
-
-## Token flow
-
-Recommended personal-user flow:
-
-```bash
-xmemo login
-xmemo auth status
-xmemo token status --verify
-```
-
-`xmemo login` uses the hosted device-login flow when the service advertises it:
-the CLI shows a browser URL and one-time code, the user authorizes in XMemo, and
-the CLI stores the issued MCP token in the user-scoped credential file.
-
-Users who already have a token can configure it directly without shell profiles:
-
-```bash
-printf '%s\n' 'your-token' | xmemo token add --from-stdin
-xmemo token status --verify
-```
-
-This is the preferred fallback while a hosted service is rolling out device
-login. It still avoids project files, MCP config files, logs, and chat
-transcripts.
-
-Tokens should be created by the XMemo website or enterprise console, then
-stored with `xmemo login`, `xmemo token add`, a user environment variable, or an
-enterprise secret manager:
-
-```bash
-export XMEMO_KEY="your-token"
-```
-
-PowerShell:
-
-```powershell
-[Environment]::SetEnvironmentVariable("XMEMO_KEY", "your-token", "User")
-```
-
-Do not commit tokens to source control, MCP config files, `.env` files, logs, or
-chat transcripts.
-
-## Hosted discovery setup
-
-Hosted setup uses the XMemo public discovery contracts. The CLI reads
-secret-free discovery and onboarding status documents, then tells the user where
-the API, MCP endpoint, docs, and any server-advertised onboarding links are.
-
-```bash
-xmemo doctor
-xmemo discovery show
-xmemo setup
-```
-
-Discovery requests do not send `XMEMO_KEY` or any Authorization
-header. Token creation still happens in the website or enterprise console; the
-public service discovery document does not return token values.
-
-The hosted default service/base URL is `https://xmemo.dev`, so normal users do
-not need to type a service address. The MCP endpoint is discovered from that
-base URL and written as `https://xmemo.dev/mcp`; `https://mcp.xmemo.dev` is not
-the current canonical setup URL. Use `--url <service-url>` or `XMEMO_URL` only
-for private, enterprise, or self-hosted deployments. `MEMORY_OS_URL` remains
-accepted as a compatibility alias.
-
-Generate and write a client config from discovery:
-
-```bash
-xmemo setup codex --yes
-xmemo setup codex --url "https://your-private-service.example" --yes
-xmemo setup --url "https://your-private-service.example" --client codex --write
-xmemo setup --url "https://your-private-service.example" --client cursor --write
-```
-
-`--write` requires an explicit `--client` so the CLI never performs broad config
-writes implicitly. Generated config references `XMEMO_KEY`; it does not embed
-the token value. Write-capable client configs also include stable non-secret
-agent identity headers where the client format supports them.
-
-`xmemo setup codex` is the recommended Codex path. Without `--yes` it
-previews the Codex MCP config and the project-scoped `AGENTS.md` memory profile.
-With `--yes`, it writes the Codex MCP config and installs the profile into the
-current project's `AGENTS.md` marker block. Use `--profile-target <path>` to
-choose a different project instruction file, or `--no-profile` to configure MCP
-only.
-
-## MCP setup
-
-List supported client generators:
-
-```bash
-xmemo mcp list
-```
-
-Current write-capable clients:
-
-```text
-codex   ~/.codex/config.toml
-cursor  ~/.cursor/mcp.json
-```
-
-For clients without a verified user-scoped write path, generate a read-only
-template and apply it manually after review:
-
-```bash
-xmemo mcp config --client copilot-cli
-xmemo mcp config --client generic --base-url "https://your-private-service.example" --json
-```
-
-Only Codex and Cursor currently have write-capable helpers. Other client writes
-should only be added after their official user-scoped config format is verified.
-
-### Copilot CLI
-
-Copilot CLI has `/mcp` management, but it does not currently document a stable
-cross-platform user config file path/format for third-party tools to edit
-directly. The recommended personal-user path is therefore local proxy mode:
-
-```bash
-xmemo login
-xmemo mcp config --client copilot-cli
-xmemo mcp proxy
-```
-
-The generated Copilot CLI template points at `http://127.0.0.1:8765/mcp` and
-does not include token or identity headers. `xmemo mcp proxy` reads the token
-saved by `xmemo login` or `xmemo token add --from-stdin`, adds the XMemo bearer
-token and local agent identity, then forwards requests to `https://xmemo.dev/mcp`.
-If you specifically want the older environment-variable template, run:
-
-```bash
-xmemo mcp config --client copilot-cli --remote-env
-```
-
-### Codex
-
-Recommended Codex setup:
-
-```bash
-xmemo setup codex
-xmemo setup codex --yes
-xmemo smoke --client codex
-```
-
-`setup codex` is visible and opt-in: the first command previews the writes, and
-`--yes` performs them. The MCP config stays in user-scoped Codex config, while
-the XMemo Codex behavior profile is installed into the current project's
-`AGENTS.md` between these markers:
-
-```html
-<!-- memory-os:codex-profile:start -->
-<!-- memory-os:codex-profile:end -->
-```
-
-Repeat installs update only that marker block. Remove it with:
-
-```bash
-xmemo profile uninstall codex
-```
-
-Advanced: generate a Codex MCP config snippet without touching files:
-
-```bash
-xmemo mcp add codex --url "$XMEMO_URL"
-```
-
-Write it to the default Codex config path:
-
-```bash
-xmemo mcp add codex --url "$XMEMO_URL" --write
-```
-
-The generated config references `XMEMO_KEY` and does not include the token
-value. Codex custom identity headers are not written until the CLI format is
-verified to support them.
-
-Codex MCP-depth checks:
-
-```bash
-xmemo mcp profile codex
-xmemo profile install codex --dry-run
-xmemo profile install codex
-xmemo profile status codex
-xmemo smoke --client codex
-```
-
-`xmemo mcp profile codex` prints the recommended memory behavior profile:
-recall/search at the start of non-trivial tasks, write back high-signal
-decisions and fixes, and never store secrets. `xmemo smoke --client codex`
-checks the local Codex TOML config for the `memory_os` MCP server,
-`bearer_token_env_var = "XMEMO_KEY"`, token presence in the environment, and
-absence of embedded token values.
-
-### Cursor
-
-Generate a Cursor MCP config snippet:
-
-```bash
-xmemo mcp add cursor --url "$XMEMO_URL"
-```
-
-Merge it into the default Cursor user config path:
-
-```bash
-xmemo mcp add cursor --url "$XMEMO_URL" --write
-```
-
-The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
-config manually if you need to rotate the endpoint. Cursor configs include
-`X-Memory-OS-Agent-ID` and `X-Memory-OS-Agent-Instance-ID`; the instance ID is
-non-secret and stored under the user's XMemo CLI config directory.
-
-## Release model
-
-This repository is the source for the `@xmemo/client` npm package. Releases
-should be published from GitHub Actions on tags or GitHub Releases, not from a
-developer workstation.
-
-Recommended flow:
-
-```text
-develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance
-```
-
-## Package boundary
-
-Included in npm:
-
-```text
-bin/
-src/
-README.md
-LICENSE
-```
-
-Excluded from npm:
-
-```text
-.github/
-test/
-coverage/
-server code
-database migrations
-deployment files
-logs
-local state
-secrets
-```
+# XMemo CLI
+
+`@xmemo/client` is the privacy-first command line entry point for XMemo client
+setup. It is intentionally small: the npm package contains only the CLI and
+setup helper code needed on a user's machine.
+
+`@yonro/xmemo-client` is reserved as a Yonro fallback package. The CLI exposes
+`xmemo` as the primary command and keeps `memory-os` as a compatibility alias.
+
+The XMemo server, database, token registry, deployment files, logs, and
+internal scripts are not part of this npm package.
+
+## Install
+
+```bash
+npm install -g @xmemo/client
+```
+
+Upgrade an existing global install:
+
+```bash
+xmemo update
+```
+
+This runs `npm install -g @xmemo/client@latest`. Use `xmemo update --dry-run`
+to print the exact command without changing anything.
+
+## Commands
+
+```bash
+xmemo update
+xmemo setup codex
+xmemo setup codex --yes
+xmemo smoke --client codex
+xmemo doctor
+xmemo discovery show
+xmemo setup
+xmemo login
+xmemo auth status
+xmemo status
+xmemo token status
+xmemo token add --from-stdin
+xmemo env example --shell bash
+xmemo mcp list
+xmemo mcp config --client generic
+xmemo profile status codex
+xmemo mcp add cursor --url "https://your-private-service.example"
+xmemo privacy
+```
+
+## Enterprise privacy and security defaults
+
+- No telemetry or analytics.
+- `xmemo doctor`, `xmemo discovery show`, and `xmemo status` do not send tokens.
+- MCP config generated by the CLI references `XMEMO_KEY`; it does not write
+  token values into project files.
+- The CLI generates one stable non-secret `XMEMO_AGENT_INSTANCE_ID` per local
+  client profile and stores it in user-scoped config outside git.
+- `xmemo login` stores the issued credential in the user-scoped XMemo CLI
+  config directory, shows the approved account when the server provides it,
+  and does not require extra token configuration afterward.
+- `xmemo token add` remains available for existing tokens and still avoids
+  project files, shell history, and printed token values.
+- Legacy `xmemo token set` refuses plaintext credential storage unless
+  `--allow-plaintext` is explicitly provided.
+- The npm package uses a `files` whitelist so only `bin`, `src`, `README.md`,
+  and `LICENSE` are published.
+
+## Token flow
+
+Recommended personal-user flow:
+
+```bash
+xmemo login
+xmemo auth status
+xmemo token status --verify
+```
+
+`xmemo login` uses the hosted device-login flow when the service advertises it:
+the CLI shows a browser URL and one-time code, the user authorizes in XMemo, and
+the CLI stores the issued MCP token in the user-scoped credential file. When the
+service returns approved account metadata, the CLI prints the account label so
+users can confirm which XMemo account was connected. No manual token setup is
+needed after a successful `xmemo login`; `xmemo token status --verify` is only
+an optional connectivity check. The CLI waits for the full browser authorization
+window by default; use `--timeout-ms` only to shorten or extend that approval
+window, and `--http-timeout-ms` only for individual service requests.
+
+Users who already have a token can configure it directly without shell profiles:
+
+```bash
+printf '%s\n' 'your-token' | xmemo token add --from-stdin
+xmemo token status --verify
+```
+
+This is the preferred fallback while a hosted service is rolling out device
+login. It still avoids project files, MCP config files, logs, and chat
+transcripts.
+
+Tokens should be created by the XMemo website or enterprise console, then
+stored with `xmemo login`, `xmemo token add`, a user environment variable, or an
+enterprise secret manager:
+
+```bash
+export XMEMO_KEY="your-token"
+```
+
+PowerShell:
+
+```powershell
+[Environment]::SetEnvironmentVariable("XMEMO_KEY", "your-token", "User")
+```
+
+Do not commit tokens to source control, MCP config files, `.env` files, logs, or
+chat transcripts.
+
+## Hosted discovery setup
+
+Hosted setup uses the XMemo public discovery contracts. The CLI reads
+secret-free discovery and onboarding status documents, then tells the user where
+the API, MCP endpoint, docs, and any server-advertised onboarding links are.
+
+```bash
+xmemo doctor
+xmemo discovery show
+xmemo setup
+```
+
+Discovery requests do not send `XMEMO_KEY` or any Authorization
+header. Token creation still happens in the website or enterprise console; the
+public service discovery document does not return token values.
+
+The hosted default service/base URL is `https://xmemo.dev`, so normal users do
+not need to type a service address. The MCP endpoint is discovered from that
+base URL and written as `https://xmemo.dev/mcp`; `https://mcp.xmemo.dev` is not
+the current canonical setup URL. Use `--url <service-url>` or `XMEMO_URL` only
+for private, enterprise, or self-hosted deployments. `MEMORY_OS_URL` remains
+accepted as a compatibility alias.
+
+Generate and write a client config from discovery:
+
+```bash
+xmemo setup codex --yes
+xmemo setup codex --url "https://your-private-service.example" --yes
+xmemo setup --url "https://your-private-service.example" --client codex --write
+xmemo setup --url "https://your-private-service.example" --client cursor --write
+```
+
+`--write` requires an explicit `--client` so the CLI never performs broad config
+writes implicitly. Generated config references `XMEMO_KEY`; it does not embed
+the token value. Write-capable client configs also include stable non-secret
+agent identity headers where the client format supports them.
+
+`xmemo setup codex` is the recommended Codex path. Without `--yes` it
+previews the Codex MCP config and the project-scoped `AGENTS.md` memory profile.
+With `--yes`, it writes the Codex MCP config and installs the profile into the
+current project's `AGENTS.md` marker block. Use `--profile-target <path>` to
+choose a different project instruction file, or `--no-profile` to configure MCP
+only.
+
+## MCP setup
+
+List supported client generators:
+
+```bash
+xmemo mcp list
+```
+
+Current write-capable clients:
+
+```text
+codex   ~/.codex/config.toml
+cursor  ~/.cursor/mcp.json
+```
+
+For clients without a verified user-scoped write path, generate a read-only
+template and apply it manually after review:
+
+```bash
+xmemo mcp config --client copilot-cli
+xmemo mcp config --client generic --base-url "https://your-private-service.example" --json
+```
+
+Only Codex and Cursor currently have write-capable helpers. Other client writes
+should only be added after their official user-scoped config format is verified.
+
+### Copilot CLI
+
+Copilot CLI has `/mcp` management, but it does not currently document a stable
+cross-platform user config file path/format for third-party tools to edit
+directly. The recommended personal-user path is therefore local proxy mode:
+
+```bash
+xmemo login
+xmemo mcp config --client copilot-cli
+xmemo mcp proxy
+```
+
+The generated Copilot CLI template points at `http://127.0.0.1:8765/mcp` and
+does not include token or identity headers. `xmemo mcp proxy` reads the token
+saved by `xmemo login` or `xmemo token add --from-stdin`, adds the XMemo bearer
+token and local agent identity, then forwards requests to `https://xmemo.dev/mcp`.
+If you specifically want the older environment-variable template, run:
+
+```bash
+xmemo mcp config --client copilot-cli --remote-env
+```
+
+### Codex
+
+Recommended Codex setup:
+
+```bash
+xmemo setup codex
+xmemo setup codex --yes
+xmemo smoke --client codex
+```
+
+`setup codex` is visible and opt-in: the first command previews the writes, and
+`--yes` performs them. The MCP config stays in user-scoped Codex config, while
+the XMemo Codex behavior profile is installed into the current project's
+`AGENTS.md` between these markers:
+
+```html
+<!-- memory-os:codex-profile:start -->
+<!-- memory-os:codex-profile:end -->
+```
+
+Repeat installs update only that marker block. Remove it with:
+
+```bash
+xmemo profile uninstall codex
+```
+
+Advanced: generate a Codex MCP config snippet without touching files:
+
+```bash
+xmemo mcp add codex --url "$XMEMO_URL"
+```
+
+Write it to the default Codex config path:
+
+```bash
+xmemo mcp add codex --url "$XMEMO_URL" --write
+```
+
+The generated config references `XMEMO_KEY` and does not include the token
+value. Codex custom identity headers are not written until the CLI format is
+verified to support them.
+
+Codex MCP-depth checks:
+
+```bash
+xmemo mcp profile codex
+xmemo profile install codex --dry-run
+xmemo profile install codex
+xmemo profile status codex
+xmemo smoke --client codex
+```
+
+`xmemo mcp profile codex` prints the recommended memory behavior profile:
+recall/search at the start of non-trivial tasks, write back high-signal
+decisions and fixes, and never store secrets. `xmemo smoke --client codex`
+checks the local Codex TOML config for the `memory_os` MCP server,
+`bearer_token_env_var = "XMEMO_KEY"`, token presence in the environment, and
+absence of embedded token values.
+
+### Cursor
+
+Generate a Cursor MCP config snippet:
+
+```bash
+xmemo mcp add cursor --url "$XMEMO_URL"
+```
+
+Merge it into the default Cursor user config path:
+
+```bash
+xmemo mcp add cursor --url "$XMEMO_URL" --write
+```
+
+The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
+config manually if you need to rotate the endpoint. Cursor configs include
+`X-Memory-OS-Agent-ID` and `X-Memory-OS-Agent-Instance-ID`; the instance ID is
+non-secret and stored under the user's XMemo CLI config directory.
+
+## Release model
+
+This repository is the source for the `@xmemo/client` npm package. Releases
+should be published from GitHub Actions on tags or GitHub Releases, not from a
+developer workstation.
+
+Recommended flow:
+
+```text
+develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance
+```
+
+## Package boundary
+
+Included in npm:
+
+```text
+bin/
+src/
+README.md
+LICENSE
+```
+
+Excluded from npm:
+
+```text
+.github/
+test/
+coverage/
+server code
+database migrations
+deployment files
+logs
+local state
+secrets
+```