yonro/memory-os-cli

XMemo is a user-owned Memory OS for AI agents: persistent memory, project context and session continuity with agent identity, provenance and governed access, shared across AI clients through MCP, the CLI and a public REST API surface.
English · 简体中文 | Documentation · Hosted MCP
Quick start · What this repo contains · Beyond MCP · Integrations · Connection modes · Plugins · Commands · Versioning · Security
---
What this repository contains
- **@xmemo/client**: the official xmemo CLI for setup, diagnostics, behavior profiles, and memory commands.
- **MCP distribution**: hosted Streamable HTTP configuration (https://xmemo.dev/mcp) and the local xmemo-mcp stdio server.
- **XMemo Skill & native integrations**: skills/xmemo for agent platforms and the native plugin index (src/plugins/index.json).
- **Marketplace and registry metadata**: canonical descriptors for MCP Registry (server.json), LobeHub (lhm.plugin.json), and AI agents (context7.json).
The hosted service implementation is private.
Beyond MCP
MCP is one access surface of XMemo, not the product boundary. XMemo provides a persistent, governed memory operating layer across AI tools and agents:
- **Persistent Memory**: store, search, list, and soft-delete durable facts, preferences, and operational knowledge across sessions.
- **Context Recall**: retrieve focused, relevant context on demand with token-budget controls and document expansions.
- **Session Continuity & Working State**: restart snapshots and state save/restore so agents resume context across process restarts.
- **Project Context & Decisions**: track project-scoped facts, TODOs, and durable decisions across agent workflows.
- **Agent Identity & Provenance**: track authorship and origin per memory record via agent instance attribution without conflating credentials.
- **Governed Access**: scoped tokens, OAuth where the client supports it, soft/hard deletion and sensitive-memory handling (governance details).
- **Native Integrations & Skill**: dedicated integration for OpenClaw, Hermes, XMemo Skill (ClawHub), and DeepSeek DSH (available, released and pilot-tested; integration maturity Preview).
- **Access Surfaces**: unified via Model Context Protocol, the local CLI (xmemo), and the public REST API.
*Preview: Cloud Skills; Dream (off by default); Teams (Business plan not yet available). Knowledge Bases are available where enabled for the account.*
XMemo CLI
@xmemo/client is the official control plane for connecting AI tools to XMemo. It makes setup repeatable, keeps credentials out of project files, and gives every supported client a consistent path to durable, user-owned memory.
The package is deliberately small: the CLI runtime, safe client configuration, behavior profiles, XMemo skills, and marketplace metadata. Server code, databases, deployment files, logs, and internal operations remain outside the npm distribution.
Architecture
| | |
| --- | --- |
| **Package** | @xmemo/client |
| **Primary command** | xmemo (alias: client) |
| **Local MCP command** | xmemo-mcp |
| **Hosted MCP** | https://xmemo.dev/mcp |
| **Runtime** | Node.js 20 or later |
| **License** | MIT |
Why XMemo CLI
- **One control plane** — login, diagnostics, configuration, profiles, updates,
and smoke checks share one predictable interface.
- **Private by design** — generated project configuration references a
credential; it never embeds the credential value.
- **Native where it matters** — OpenClaw and Hermes use dedicated memory
integrations instead of duplicating the same capability through MCP.
- **Portable everywhere else** — hosted Streamable HTTP MCP and local stdio
cover modern editors, terminals, and agent runtimes.
- **Safe automation** — supported setup and removal paths offer preview,
dry-run, or explicit confirmation before making changes.
- **Small supply-chain surface** — the npm package is governed by an explicit
file allowlist and release provenance.
Quick start
Guided onboarding (xmemo init)
For an interactive first-run experience across account authentication, detected clients, agent behavior instructions, MCP server setup, skills, and plugins, run:
Flags and options:
- xmemo init --dry-run: View the full onboarding plan without performing network calls or disk writes.
- xmemo init --yes: Automatically accept and apply all onboarding steps without interactive prompts.
- xmemo init --json: Emit structured JSON for the plan or result envelope.
- xmemo init --client ...: Restrict onboarding to specific clients (e.g., cursor, codex, claude-code).