@yonro/memory-os

Memory OS CLI

@yonro/memory-os is the privacy-first command line entry point for Memory OS client setup. It is intentionally small: the npm package contains only the CLI and setup helper code needed on a user's machine.

The Memory OS server, database, token registry, DevFlow state, deployment files, logs, and internal scripts are not part of this npm package.

Install

npm install -g @yonro/memory-os

Commands

export MEMORY_OS_URL="https://xmemo.dev"

memory-os doctor --base-url "$MEMORY_OS_URL"
memory-os discovery show --base-url "$MEMORY_OS_URL"
memory-os setup --url "$MEMORY_OS_URL"
memory-os status --url "$MEMORY_OS_URL"
memory-os token status
memory-os env example --shell bash --base-url "$MEMORY_OS_URL"
memory-os mcp list
memory-os mcp config --client generic --base-url "$MEMORY_OS_URL"
memory-os mcp add codex --url "$MEMORY_OS_URL"
memory-os mcp add cursor --url "$MEMORY_OS_URL"
memory-os privacy

Enterprise privacy and security defaults

• No telemetry or analytics.
• memory-os doctor, memory-os discovery show, and memory-os 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.
• memory-os 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

Tokens should be created by the Memory OS website or enterprise console, then stored in a user environment variable or enterprise secret manager:

export XMEMO_KEY="your-token"

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 Memory OS 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.

memory-os doctor --base-url "$MEMORY_OS_URL"
memory-os discovery show --base-url "$MEMORY_OS_URL"
memory-os setup --url "$MEMORY_OS_URL"

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.

Generate and write a client config from discovery:

memory-os setup --url "$MEMORY_OS_URL" --client codex --write
memory-os setup --url "$MEMORY_OS_URL" --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.

MCP setup

List supported client generators:

memory-os mcp list

Current write-capable clients:

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:

memory-os mcp config --client copilot-cli --base-url "$MEMORY_OS_URL"
memory-os mcp config --client generic --base-url "$MEMORY_OS_URL" --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.

Codex

Generate a Codex MCP config snippet:

memory-os mcp add codex --url "$MEMORY_OS_URL"

Write it to the default Codex config path:

memory-os mcp add codex --url "$MEMORY_OS_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.

Cursor

Generate a Cursor MCP config snippet:

memory-os mcp add cursor --url "$MEMORY_OS_URL"

Merge it into the default Cursor user config path:

memory-os mcp add cursor --url "$MEMORY_OS_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 Memory OS CLI config directory.

Release model

This repository is the source for the @yonro/memory-os npm package. Releases should be published from GitHub Actions on tags or GitHub Releases, not from a developer workstation.

Recommended flow:

develop -> test -> tag/release -> GitHub Actions -> npm publish --provenance

Package boundary

Included in npm:

bin/
src/
README.md
LICENSE

Excluded from npm:

.github/
test/
coverage/
server code
database migrations
deployment files
logs
local state
secrets