@xmemo/client 0.0.0 → 0.4.127

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,4 +1,301 @@
-# @xmemo/client
-
-Reserved client package name for XMemo by Memory OS. Official client package is coming soon.
+# 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
+```
+
+## Commands
+
+```bash
+xmemo setup codex
+xmemo setup codex --yes
+xmemo smoke --client codex
+xmemo doctor
+xmemo discovery show
+xmemo setup
+xmemo login
+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 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
+```

package/bin/memory-os.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+const exitCode = await run(process.argv.slice(2), {
+  env: process.env,
+  stdin: process.stdin,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  fetch: globalThis.fetch
+});
+
+process.exitCode = exitCode;

package/package.json

@@ -1,24 +1,46 @@
-{
-  "name": "@xmemo/client",
-  "version": "0.0.0",
-  "description": "Reserved client package name for XMemo by Memory OS.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "MIT",
-  "type": "module",
-  "homepage": "https://xmemo.dev",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yonro/memory-os.git"
-  },
-  "bugs": {
-    "url": "https://github.com/yonro/memory-os/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@xmemo/client",
+  "version": "0.4.127",
+  "description": "Privacy-first CLI and MCP setup helper for XMemo.",
+  "type": "module",
+  "bin": {
+    "xmemo": "bin/memory-os.js",
+    "memory-os": "bin/memory-os.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "node --check bin/memory-os.js && node --check src/cli.js && node --check test/cli.test.js",
+    "test": "node --test",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm run lint && npm test && npm run pack:dry-run"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yonro/memory-os-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yonro/memory-os-cli/issues"
+  },
+  "homepage": "https://github.com/yonro/memory-os-cli#readme",
+  "keywords": [
+    "xmemo",
+    "memory-os",
+    "mcp",
+    "agent",
+    "cli",
+    "privacy"
+  ],
+  "license": "UNLICENSED"
+}