@xmemo/client 0.4.135 → 0.4.137

package/README.md

@@ -1,329 +1,422 @@
-# 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 --dry-run
-xmemo setup cursor
-xmemo setup cursor --dry-run
-xmemo setup copilot
-xmemo setup copilot --dry-run
-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 smoke --client codex
-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
-xmemo setup codex --url "https://your-private-service.example"
-xmemo setup cursor
-xmemo setup copilot
-```
-
-`xmemo setup <client>` is the unified setup entry point. For write-capable
-clients, it applies the user-scoped config directly; use `--dry-run` to preview
-without writing. 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. `--yes` remains accepted
-for Codex and Cursor as a compatibility no-op.
-
-`xmemo setup codex` is the recommended Codex path. It writes the Codex MCP
-config and installs the profile into the current project's `AGENTS.md` marker
-block. Use `--dry-run` to preview, `--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
-copilot ~/.copilot/mcp-config.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 generic --base-url "https://your-private-service.example" --json
-```
-
-Codex, Cursor, and Copilot CLI have write-capable setup helpers. Other client
-writes should only be added after their official user-scoped config format is
-verified.
-
-### Copilot CLI
-
-Copilot CLI has `/mcp` management and reads user MCP configuration from
-`~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json`). XMemo writes
-a local proxy server entry there:
-
-```bash
-xmemo login
-xmemo setup copilot
-xmemo mcp proxy
-```
-
-`xmemo setup copilot` writes `memory-os` to Copilot CLI's user MCP config and
-does not include token or identity headers. Use `xmemo setup copilot --dry-run`
-to preview without writing. `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
-Copilot CLI is already open, reload MCP config or restart Copilot CLI after
-setup.
-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 smoke --client codex
-```
-
-`setup codex` writes the MCP config to user-scoped Codex config and installs the
-XMemo Codex behavior profile into the current project's `AGENTS.md` between
-these markers. Use `xmemo setup codex --dry-run` to preview without writing.
-
-```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
-
-Recommended Cursor setup:
-
-```bash
-xmemo setup cursor
-```
-
-`setup cursor` merges the Cursor MCP config into the default Cursor user config
-path. Use `xmemo setup cursor --dry-run` to preview without writing. The
-lower-level equivalent remains:
-
-```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 --dry-run
+xmemo setup cursor
+xmemo setup cursor --dry-run
+xmemo setup copilot
+xmemo setup copilot --dry-run
+xmemo setup gemini
+xmemo setup gemini --dry-run
+xmemo setup antigravity
+xmemo setup antigravity --dry-run
+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 mcp config --client antigravity
+xmemo mcp add antigravity --write
+xmemo profile status codex
+xmemo profile install gemini
+xmemo profile install antigravity
+xmemo smoke --client codex
+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` or uses the client's
+  MCP OAuth flow; 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 setup <client>` can install a marker-scoped XMemo memory behavior
+  profile for the selected agent. The profile contains instructions only; it
+  never embeds token values.
+- `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
+xmemo setup codex --url "https://your-private-service.example"
+xmemo setup cursor
+xmemo setup copilot
+xmemo setup gemini
+xmemo setup antigravity
+```
+
+`xmemo setup <client>` is the unified setup entry point. For write-capable
+clients, it applies the user-scoped config directly; use `--dry-run` to preview
+without writing. Codex/Cursor configs reference `XMEMO_KEY`; OAuth-native
+clients such as Gemini CLI and Antigravity use the client's MCP OAuth flow
+instead. No generated config embeds a token value. Write-capable client configs
+also include stable non-secret agent identity headers where the client format
+supports them. `--yes` remains accepted for Codex and Cursor as a compatibility
+no-op.
+
+After writing MCP config, `xmemo setup <client>` prompts:
+
+```text
+Write XMemo memory behavior profile to <path>? [Y/n]
+```
+
+The default is `Y`, so pressing Enter writes a marker-scoped profile that nudges
+the agent to recall/search XMemo at the start of non-trivial work and remember
+high-signal decisions after meaningful changes. Use `n` or `--no-profile` to
+configure MCP only. Use `--dry-run` to preview without writing config or profile
+files, and `--profile-target <path>` to choose a different behavior profile
+target.
+
+Default behavior profile targets:
+
+```text
+codex       ./AGENTS.md
+cursor      ~/.cursor/memory-profile.md
+gemini      ~/.gemini/GEMINI.md
+antigravity ~/.gemini/antigravity/MEMORY.md
+```
+
+## MCP setup
+
+List supported client generators:
+
+```bash
+xmemo mcp list
+```
+
+Current write-capable clients:
+
+```text
+codex       ~/.codex/config.toml
+cursor      ~/.cursor/mcp.json
+copilot     ~/.copilot/mcp-config.json
+gemini      ~/.gemini/settings.json
+antigravity ~/.gemini/antigravity/mcp_config.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 generic --base-url "https://your-private-service.example" --json
+```
+
+Codex, Cursor, Copilot CLI, Gemini CLI, and Antigravity have write-capable setup
+helpers.
+Other client writes should only be added after their official user-scoped config
+format is verified.
+
+### Copilot CLI
+
+Copilot CLI has `/mcp` management and reads user MCP configuration from
+`~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json`). XMemo writes
+a local proxy server entry there:
+
+```bash
+xmemo login
+xmemo setup copilot
+xmemo mcp proxy
+```
+
+`xmemo setup copilot` writes `memory-os` to Copilot CLI's user MCP config and
+does not include token or identity headers. Use `xmemo setup copilot --dry-run`
+to preview without writing. `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
+Copilot CLI is already open, reload MCP config or restart Copilot CLI after
+setup.
+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 smoke --client codex
+```
+
+`setup codex` writes the MCP config to user-scoped Codex config and, by default,
+installs the XMemo Codex behavior profile into the current project's `AGENTS.md`
+between these markers. Use `xmemo setup codex --dry-run` to preview without
+writing or `xmemo setup codex --no-profile` to skip the behavior profile.
+
+```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
+
+Recommended Cursor setup:
+
+```bash
+xmemo setup cursor
+```
+
+`setup cursor` merges the Cursor MCP config into the default Cursor user config
+path. Use `xmemo setup cursor --dry-run` to preview without writing. The
+lower-level equivalent remains:
+
+```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. By default,
+the setup prompt also installs a Cursor behavior profile at
+`~/.cursor/memory-profile.md`; answer `n` or pass `--no-profile` to skip it.
+
+### Gemini CLI
+
+Recommended Gemini CLI setup:
+
+```bash
+xmemo setup gemini
+```
+
+`setup gemini` merges an XMemo MCP server into Gemini CLI's user settings at
+`~/.gemini/settings.json`. It writes a remote HTTP server using Gemini's
+`httpUrl` key plus `X-Memory-OS-Agent-ID` and `X-Memory-OS-Agent-Instance-ID`
+headers. Use `xmemo setup gemini --dry-run` to preview without writing.
+
+Unlike Codex/Cursor, the Gemini config carries **no token**: authentication uses
+Gemini CLI's built-in MCP OAuth flow (a one-time browser login on first use).
+This is deliberate — Gemini redacts environment variables matching
+`*KEY*`/`*TOKEN*`/`*AUTH*` during header expansion, so an `${XMEMO_KEY}`
+reference would not survive. OAuth avoids storing any secret in the config and
+still grants the full XMemo tool profile. After setup, restart Gemini CLI and
+run `/mcp` (or the first XMemo tool call) to complete the OAuth login. By
+default, the setup prompt also installs a Gemini behavior profile at
+`~/.gemini/GEMINI.md`; answer `n` or pass `--no-profile` to skip it.
+
+The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
+config manually if you need to rotate the endpoint.
+
+### Antigravity
+
+Recommended Antigravity setup:
+
+```bash
+xmemo setup antigravity
+```
+
+`setup antigravity` merges an XMemo MCP server into Antigravity's user MCP config
+at `~/.gemini/antigravity/mcp_config.json`. It writes Antigravity's
+`serverUrl` shape plus `X-Memory-OS-Agent-ID` and
+`X-Memory-OS-Agent-Instance-ID` headers. Like Gemini CLI, the config carries
+**no token**: restart Antigravity and complete the MCP OAuth flow on first use.
+By default, the setup prompt also installs an Antigravity behavior profile at
+`~/.gemini/antigravity/MEMORY.md`; answer `n` or pass `--no-profile` to skip it.
+
+The lower-level equivalent is:
+
+```bash
+xmemo mcp add antigravity --write
+```
+
+Use `xmemo setup antigravity` for normal installs because it performs discovery
+and chooses the recommended Antigravity path automatically. Use
+`xmemo mcp add antigravity --write` when you want the generic MCP writer
+directly, for example with `--url` or `--config` in advanced/multi-client setup.
+The CLI refuses to overwrite an existing `memory_os` MCP server entry. Edit the
+config manually if you need to rotate the endpoint.
+
+## 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
+```