XMemo Memory

XMemo Memory

Give your agent durable memory that survives across sessions, projects, and tools.

Runtime Selection

XMemo supports two parallel integration paths:

1. Bundled Skill script at scripts/xmemo-skill.mjs (primary standalone direct REST API integration, fully self-contained and zero-dependency).
2. XMemo MCP tools (when running in environments that natively host the XMemo MCP server).

Run bundled commands from the Skill root with Node.js 20 or newer.

Hosted Discovery Boundary

The public agent-discovery field standalone_skill.operations describes the generic commands accepted by POST /v1/skill/operations; it is not the full standalone command catalogue. restart-snapshot and restart-restore use the separate direct endpoints /v1/restart/snapshot and /v1/restart/restore, so they are deliberately absent from that operations list.

Do not infer that a restart command is available merely because a discovery document mentions a memory scope. It requires a formal account credential and the service must authorize the specific request. The temporary-agent manifest intentionally omits restart continuity: temporary access stays limited to remember, recall, and search in its isolated sandbox.

Credential lookup always prefers the XMEMO_KEY environment variable. When it is present, the script does not copy its value into a local credential file.

If no credential is available, use formal account login (recommended):

node scripts/xmemo-skill.mjs login --allow-plaintext

New users should create or sign in to an XMemo account at https://xmemo.dev. The login command opens the hosted device-login page and shows a one-time code; approve that code in the browser account session to issue the Skill's scoped skill_token.

The standalone zero-dependency script has no cross-platform operating-system keychain integration. --allow-plaintext is therefore an explicit decision to store the issued token unencrypted in the current user's XMemo directory so later commands can use it. The script prints the exact path, restricts POSIX permissions where supported, never prints the token, and never writes it into the project. Prefer XMEMO_KEY or a managed secret store when plaintext local storage is not acceptable.

Formal registration/login is the default and recommended path. It gives the user account-backed memory and the full command set.

Only when no human can complete login (unattended) or the human explicitly declines registration for now (declined), use the explicit temporary fallback:

node scripts/xmemo-skill.mjs register --reason unattended --allow-plaintext

Temporary access is an isolated, limited memory sandbox. It only supports remember, recall, and search. The script reads the current public policy before registration and immediately discloses its item cap, inactivity expiry, and maximum lifetime (currently 100 items, 14 days of inactivity, and 30 days from registration). Show the returned bind URL to the user and do not share that URL publicly. Run node scripts/xmemo-skill.mjs auth claim-confirm after they claim it. Temporary and pending-confirmation values inherit the same explicit plaintext-storage consent and are replaced or cleared during formal-token handoff.

or, if you already have a token, pipe it without putting the value in the command line. POSIX shell:

printf '%s' "$XMEMO_KEY" | node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext

PowerShell:

$env:XMEMO_KEY | node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext

Never ask the user to paste a raw token into chat, logs, or project files.

Core Workflows

• Recall before non-trivial work. Call recall or search with the repo, project, task, and subsystem before making decisions.
• Remember durable facts. Store decisions, conventions, preferences, architecture notes, release procedures, and verified troubleshooting steps.
• Preserve handoffs. Use save-state / restore-state for one active task slot. Use restart-snapshot / restart-restore when a restart needs the broader continuity pack: active state, recent events, TODOs, and pending decisions.
• Record concrete expenses. Use expense-add when the user states a concrete purchase or income.
• Confirm destructive actions. The bundled script does not expose memory deletion or overwrite commands. Use an authorized product surface with an explicit target and user confirmation if such an operation is required.
• Read provenance correctly. agent_id, agent_instance_id, and agent_boundary are attribution signals, not authorization boundaries.

Bundled Script Commands

node scripts/xmemo-skill.mjs remember --content "..." --path "..."
node scripts/xmemo-skill.mjs recall --query "..." --compact
node scripts/xmemo-skill.mjs search --query "..." --limit 5 --compact
node scripts/xmemo-skill.mjs save-state --key active_task
node scripts/xmemo-skill.mjs restore-state --key active_task
node scripts/xmemo-skill.mjs restart-snapshot
node scripts/xmemo-skill.mjs restart-restore
node scripts/xmemo-skill.mjs todo-add --content "..."
node scripts/xmemo-skill.mjs todo-list
node scripts/xmemo-skill.mjs todo-done --id 
node scripts/xmemo-skill.mjs expense-add --item "..." --amount 12.5 --currency USD
node scripts/xmemo-skill.mjs doctor
node scripts/xmemo-skill.mjs doctor --anonymous
node scripts/xmemo-skill.mjs register --reason  --allow-plaintext

The script supports JSON output with --json, command-specific usage with --help, --version, per-request timeouts with --timeout-ms, and compact recall/search output with --compact. doctor --json adds a bounded clientDiagnostics object: a read-only discovery summary and a nextAction command for the next credential check or formal sign-in. The summary includes the advertised service version, MCP URL, supported clients, and standalone Skill operations so compatibility can be checked without inspecting the raw discovery document. If discovery is unavailable, clientDiagnostics.discovery.status is unavailable; a successful doctor health check still succeeds. It never prints token values or prefixes.

When native XMemo MCP tools are present, use create_restart_snapshot and restore_restart_snapshot for the same full-continuity workflow. The bundled commands keep that capability available to standalone Skill hosts. These restart commands require a formal account credential; temporary sandboxes remain limited to remember, recall, and search.

Direct CLI Commands

The Skill script handles all operations directly, including status checks and token management:

node scripts/xmemo-skill.mjs auth status [--verify]
node scripts/xmemo-skill.mjs auth add --from-stdin --allow-plaintext
node scripts/xmemo-skill.mjs auth claim-status [--allow-plaintext]
node scripts/xmemo-skill.mjs auth claim-confirm [--allow-plaintext]
node scripts/xmemo-skill.mjs auth claim-deny [--allow-plaintext]
node scripts/xmemo-skill.mjs logout [--revoke-environment-token]
node scripts/xmemo-skill.mjs doctor

logout revokes and removes a user credential file. When XMEMO_KEY supplies the active credential, logout leaves that externally managed token unchanged unless --revoke-environment-token is explicitly passed; unset the environment variable in the launching environment to stop using it.

Setup And Repair

If the bundled script reports auth or service errors, use the canonical commands above: doctor, doctor --anonymous, auth status --verify, and auth claim-status. The auth-status spelling remains a compatibility alias, but it is intentionally not repeated in this reference.

doctor retains authenticated diagnosis when a credential is available. doctor --anonymous performs the same service-health check without sending an Authorization header. Both forms use only an unauthenticated, read-only discovery request for their JSON capability summary; discovery failure does not block an otherwise successful health check. In terminal output, an explicit anonymous check says authentication was not checked; a normal no-credential check instead prints the formal-login next command.

For detailed examples, read references/operations.md. For auth, network, and service diagnosis, read references/troubleshooting.md.

Good Memory Candidates

• Repository conventions, build/test/deploy commands, and verified troubleshooting steps.
• Architecture decisions, product decisions, release procedures, and their rationale.
• User-approved preferences for code review, testing, documentation, or UX.
• Project TODOs, blockers, risks, and handoff summaries for future sessions.
• Bug fix context that might recur.

Never Save

• Secrets, tokens, API keys, OAuth codes, cookies, authentication session IDs, or private keys. Optional restart session_id values must be non-secret correlation labels, never login/session credentials.
• Private customer data or sensitive personal data unless the user explicitly asks and the memory tool supports the required privacy policy.
• Temporary debugging output that will not help future work.
• Large code blocks; link to files, commits, or concise summaries instead.

Safety

• Keep XMemo credentials private. Do not paste them into public prompts, screenshots, repositories, issue comments, marketplace metadata, or shared logs.
• Prefer XMEMO_KEY or a managed secret store. Use --allow-plaintext only after accepting that processes running as the same operating-system user may read the local credential file.
• The default service is https://xmemo.dev. Custom HTTPS origins are supported but receive credentials when an authenticated command runs; use only trusted hosts. Plain HTTP is rejected except for localhost/loopback development.
• Use synthetic data for marketplace demos and screenshots.
• Do not claim a marketplace integration is certified unless there is explicit approval evidence for that marketplace.
• Do not simulate a successful memory read or write when no runtime path is available. Report the exact failing check and the next repair command.