XMemo CLI

Единый приватный слой памяти для каждого AI-агента.

Устанавливайте, проходите аутентификацию, диагностируйте и подключайте XMemo в редакторах, CLI и автономных агентах с помощью одной готовой к продакшену командной строки.

Английский · Упрощённый китайский

Быстрый старт · Интеграции · Режимы подключения · Команды · Безопасность

@xmemo/client — официальная плоскость управления для подключения AI-инструментов к XMemo. Она делает настройку воспроизводимой, не допускает попадания учётных данных в проектные файлы и обеспечивает каждому поддерживаемому клиенту единообразный путь к долговременной памяти, принадлежащей пользователю.

Пакет намеренно компактен: среда выполнения CLI, безопасная конфигурация клиентов, профили поведения, навыки XMemo и метаданные маркетплейса. Серверный код, базы данных, файлы развёртывания, логи и внутренние операции остаются за пределами npm-дистрибутива.

Архитектура


Пакет	`@xmemo/client`
Основная команда	`xmemo`
Локальная команда MCP	`xmemo-mcp`
Хостинговый MCP	`https://xmemo.dev/mcp`
Среда выполнения	Node.js 20 или новее
Лицензия	MIT

Почему XMemo CLI

Единая плоскость управления — вход, диагностика, конфигурация, профили, обновления и smoke-проверки используют один предсказуемый интерфейс.
Приватность по умолчанию — сгенерированная конфигурация проекта ссылается на учётные данные, но никогда не встраивает их значение.
Нативность там, где это важно — OpenClaw и Hermes используют выделенные интеграции памяти вместо дублирования той же возможности через MCP.
Переносимость во всех остальных случаях — хостинговый Streamable HTTP MCP и локальный stdio охватывают современные редакторы, терминалы и среды выполнения агентов.
Безопасная автоматизация — поддерживаемые сценарии настройки и удаления предлагают предварительный просмотр, dry-run или явное подтверждение перед внесением изменений.
Малая поверхность цепочки поставок — npm-пакет управляется явным списком разрешённых файлов и происхождением релиза.

Быстрый старт

npm install -g @xmemo/client
xmemo login
xmemo doctor
xmemo setup codex
xmemo status

Замените codex на вашего клиента. Просмотрите конфигурацию перед записью:

xmemo setup cursor --dry-run

Совет

Начните с xmemo login, xmemo doctor и xmemo setup .

Редактируйте конфигурацию MCP вручную только если для клиента нет проверенного пути настройки.

Поддерживаемые интеграции

Клиент	Рекомендуемая команда	Подключение
Codex	`xmemo setup codex`	Хостинговый MCP + профиль поведения
Cursor	`xmemo setup cursor`	Хостинговый MCP + Bearer Token + профиль поведения
Copilot CLI	`xmemo setup copilot`	Локальный аутентифицированный прокси
Gemini CLI	`xmemo setup gemini`	Хостинговый MCP + OAuth
Antigravity	`xmemo setup antigravity`	Хостинговый MCP + OAuth
OpenClaw	`xmemo setup openclaw`	Нативный плагин памяти + Skill
Hermes	`xmemo setup hermes`	Нативный провайдер памяти
Kiro	`xmemo setup kiro`	Нативный HTTP OAuth; `--auth key` для API Key
Grok	`xmemo setup grok`	Хостинговый MCP
Другие MCP-клиенты	`xmemo mcp config --client generic`	Сгенерированный шаблон

Реестр клиентов также охватывает Windsurf, Cline, Continue, Claude Desktop, Claude Code, Kimi Code, Zed, JetBrains, OpenCode, Qwen, Trae и совместимые MCP-хосты. Выполните xmemo mcp list, чтобы получить актуальный машиночитаемый каталог.

Режимы подключения

Хостинговый MCP

Рекомендуемый универсальный путь — конечная точка XMemo Streamable HTTP:

https://xmemo.dev/mcp

Клиенты с поддержкой OAuth проходят аутентификацию в браузере. Остальные клиенты ссылаются на XMEMO_KEY, не копируя его значение в файлы репозитория.

Общий вид конфигурации:

{
  "mcpServers": {
    "XMemo": {
      "type": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

Ключи конфигурации клиентов различаются; предпочитайте xmemo setup вместо прямого копирования этого общего примера.

Локальный stdio MCP

xmemo-mcp — это выделенная точка входа stdio для маркетплейсов и клиентов, запускающих локальный процесс. Безопасное обнаружение предоставляет 20 инструментов, три промпта и два ресурса документации без токена. Для выполнения инструментов по-прежнему требуется аутентификация.

После глобальной установки:

xmemo-mcp

Конфигурация MCP без установки:

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@xmemo/client@latest",
        "xmemo-mcp"
      ]
    }
  }
}

xmemo mcp serve — эквивалентная команда, если CLI уже установлен.

Нативные интеграции

У OpenClaw и Hermes есть выделенные провайдеры памяти. Их настройка по умолчанию не устанавливает вторую дублирующую поверхность инструментов XMemo.

# Native OpenClaw plugin + XMemo Skill
xmemo setup openclaw

# Native Hermes memory provider
xmemo setup hermes

Добавляйте хостинговый MCP только когда нужен явный резервный вариант:

xmemo setup openclaw --with-mcp
xmemo setup hermes --with-mcp

Используйте --mcp-only, чтобы пропустить нативную интеграцию и установить только резервный хостинговый MCP.

Аутентификация

Вход через браузер

Рекомендуется для личных аккаунтов:

xmemo login
xmemo auth status

CLI использует хостинговый поток входа через устройство, ожидает подтверждения в браузере и один раз запрашивает согласие перед сохранением выданных учётных данных без шифрования в каталоге конфигурации XMemo текущего пользователя. Точный путь показывается до подтверждения; права на файл ограничиваются там, где это поддерживает операционная система; значение учётных данных никогда не выводится. В общих системах предпочитайте XMEMO_KEY или управляемое хранилище секретов.

Для неинтерактивной автоматизации явно зафиксируйте то же решение:

xmemo login --allow-plaintext

Существующий токен

Передайте существующий токен через stdin, чтобы он не попал в историю команд:

printf '%s\n' 'your-token' | xmemo token add --from-stdin --allow-plaintext
xmemo token status --verify

PowerShell:

$xmemoToken = Read-Host "XMemo token"
$xmemoToken | xmemo token add --from-stdin --allow-plaintext
Remove-Variable xmemoToken

Для CI и управляемых рабочих станций предоставляйте XMEMO_KEY через менеджер секретов платформы. Не добавляйте его в .env, конфигурацию MCP, логи, отчёты об ошибках или стенограммы чатов.

Справочник команд

Жизненный цикл и диагностика

xmemo --version
xmemo update
xmemo update --dry-run
xmemo doctor
xmemo discovery show
xmemo status
xmemo privacy

Аутентификация

xmemo login
xmemo auth status
xmemo auth-status --verify
xmemo token status --verify
xmemo token add --from-stdin --allow-plaintext
xmemo env example --shell bash

Настройка клиентов

xmemo setup <client>
xmemo setup <client> --dry-run
xmemo setup --all
xmemo setup openclaw [--with-mcp|--mcp-only]
xmemo setup hermes [--with-mcp|--mcp-only]

Прямой клиент сервиса XMemo

xmemo memory add --content "Remember this" --path notes/example --json
xmemo memory search "example" --json
xmemo context recall "resume this task" --include-knowledge --json
xmemo state save --current-task "ship the client" --next-action "run tests" --json
xmemo state restore --json
xmemo restart snapshot --json
xmemo restart restore --snapshot-id <snapshot-id> --json

xmemo knowledge add --base <base-id> --file ./guide.pdf --title "Guide" --json
xmemo knowledge search "setup" --base <base-id> --json
xmemo knowledge read <item-id> --json > knowledge-view.json
xmemo knowledge update <item-id> --text "Updated" --from knowledge-view.json --publish --yes --json

xmemo dream preview --wait --json
xmemo dream show <run-id> --json > dream-view.json
xmemo dream apply <run-id> --item <candidate-id> --from dream-view.json --yes --json

xmemo cloud-skill list --json
xmemo cloud-skill add --file ./SKILL.md --json
xmemo cloud-skill show <skill-id> --json > skill-view.json
xmemo cloud-skill update <skill-id> --from skill-view.json --file ./SKILL.md --json
xmemo cloud-skill run <skill-id> --input ./args.json --from skill-view.json --yes --json

Все команды прямого доступа к сервису поддерживают единый машиночитаемый JSON-конверт.

Операции Knowledge update, Dream apply и Cloud Skill run используют readReceipt из сохранённого результата read/show, поэтому CLI никогда не подменяет ревизию на более новую молча.

Задайте XMEMO_KNOWLEDGE_BASE_ID для базы знаний по умолчанию в неинтерактивном режиме.

Для длинного элемента Knowledge продолжайте работу с той же фиксированной ревизией с помощью xmemo knowledge read --from knowledge-view.json --offset .

Запустите xmemo doctor --services --json для диагностики Knowledge, Dream и Cloud Skill в режиме только чтения; она намеренно не заявляет о готовности к записи или продакшену.

Cloud Skill add/update уже нацелены на безопасные контракты create-only и content-CAS. На старых сервисах они завершаются ошибкой SERVER_CONTRACT_REQUIRED и не откатываются к устаревшим маршрутам upsert. Обновления бинарных элементов Knowledge аналогично требуют новой версии того же серверного Document; используйте --document и --document-version после загрузки этой версии.

Обычные области доступа (scopes) при входе остаются без изменений. При необходимости явно запрашивайте дополнительные области доступа к сервисам, например:

xmemo login --scopes memory:read,memory:write,memory:restore,knowledge:read,knowledge:write

MCP и профили поведения

xmemo mcp serve
xmemo mcp list
xmemo mcp config --client generic
xmemo mcp add <client> --write
xmemo mcp proxy
xmemo profile install <client>
xmemo profile status <client>
xmemo profile uninstall <client>
xmemo smoke --client codex

Безопасное удаление

xmemo uninstall <client> --dry-run
xmemo uninstall <client> --yes
xmemo uninstall --all --dry-run
xmemo uninstall --all --yes --profiles

Удаляются только записи, принадлежащие XMemo, и профили поведения с областью действия маркера. Несвязанные MCP-серверы, учётные данные и идентичность устройства остаются нетронутыми.

Запустите xmemo help или xmemo --help, чтобы получить полный набор опций, соответствующих версии.

Заметки о клиентах

Codex и Cursor

xmemo setup codex
xmemo smoke --client codex

xmemo setup cursor

Оба пути настройки создают MCP-запись уровня пользователя и могут установить профиль поведения памяти с областью действия маркера. Используйте --no-profile, чтобы настроить только MCP. Публичный плагин Cursor из маркетплейса по-прежнему использует OAuth в первую очередь и не содержит конфигурации bearer-токена.

Gemini CLI и Antigravity

xmemo setup gemini
xmemo setup antigravity

Эти клиенты используют OAuth размещённого MCP. В создаваемой конфигурации нет значения токена; перезапустите клиент и при первом использовании завершите вход в браузере.

OpenClaw

xmemo login
xmemo setup openclaw
openclaw xmemo status

Команда setup устанавливает или обновляет @xmemo/openclaw-memory, устанавливает XMemo Skill, повторно использует общие учётные данные XMemo и проверяет статус плагина.

Hermes

xmemo login
xmemo setup hermes

Команда setup устанавливает или обновляет hermes-xmemo, настраивает нативный провайдер и синхронизирует пользовательские учётные данные XMemo с Hermes.

Copilot CLI

xmemo login
xmemo setup copilot
xmemo mcp proxy

Copilot CLI получает запись локального прокси. Прокси читает учётные данные из пользовательского хранилища, добавляет метаданные идентификации и перенаправляет запросы в размещённый MCP, не записывая секреты в конфигурацию Copilot.

Безопасность по умолчанию

Контроль	Поведение по умолчанию
Телеметрия	Нет аналитики CLI или телеметрии использования
Вывод учётных данных	Значения токенов никогда не выводятся
Файлы проекта	Сгенерированная конфигурация ссылается на секреты, но не встраивает их
Обнаружение	`doctor`, `discovery show` и публичное обнаружение возможностей не отправляют токен
Идентификация	Один стабильный несекретный ID экземпляра агента хранится вне git
Запись	Настройка поддерживает предварительный просмотр/dry-run; массовое удаление требует подтверждения
Локальное хранение учётных данных	Интерактивный вход сначала запрашивает подтверждение; неинтерактивная запись требует `--allow-plaintext`; сохранённые токены не шифруются
Содержимое пакета	Список разрешённых файлов npm `files` исключает тесты, операции, логи и серверный код

Приоритет учётных данных и алиасы совместимости документируются с помощью:

xmemo env example --shell bash
xmemo privacy

Для приватных или самостоятельно размещённых развёртываний задайте XMEMO_URL или передайте --url . MEMORY_OS_URL остаётся алиасом совместимости.

Границы пакета

Публикуется в npm:

bin/
docs/assets/
src/
skills/
plugins/xmemo/
README.md
LICENSE

Не публикуется:

.github/
docs/analysis/
docs/architecture/
docs/design/
test/
coverage/
server code
database migrations
deployment files
logs and local state

Разработка

npm install
npm run release:check
npm run lint
npm test
npm run pack:dry-run

Перед предложением релиза запустите полную проверку пакета:

npm run prepublishOnly

Локальный stdio-сервер можно проверить напрямую:

node bin/mcp-stdio.js

Модель релизов

Обычные релизы создаются в GitHub Actions из точного коммита с тегом, а не из изменяемой ветки или рабочей станции разработчика:

develop → CLI version sync → test → cli-v tag → GitHub Actions → npm publish --provenance

Пакет CLI и размещённый сервис MCP намеренно имеют отдельные потоки версий:

Версия CLI/npm: package.json, package-lock.json и запись npm-пакета в server.json.
Версия размещённого MCP/Registry: верхнеуровневый server.json.version и lhm.plugin.json. Эта версия соответствует развёрнутому сервису XMemo.

node scripts/check-release-version.mjs проверяет оба контракта. Тег cli-vX.Y.Z должен совпадать с версией CLI/npm и публикует только npm. MCP Registry публикуется отдельно с помощью рабочего процесса Publish MCP Registry metadata с тегом mcp-vX.Y.Z, который должен совпадать с версией размещённого MCP/Registry. Отдельный рабочий процесс публикации npm предназначен только для ручного восстановления, поэтому создание GitHub Release не может привести к двойной публикации.

Документация и поддержка

Каноническая документация сервиса доступна по адресу xmemo.dev/docs.

В этом репозитории описан клиент; страницы ниже посвящены облачному сервису, к которому он подключается.


Быстрый старт	xmemo.dev/docs/quickstart
Обзор MCP и настройка для каждого клиента	xmemo.dev/docs/mcp/overview
Справочник инструментов (`remember`, `recall`, `search`, …)	xmemo.dev/docs/tools/remember
REST API	xmemo.dev/docs/api/authentication
Устранение неполадок	xmemo.dev/docs/troubleshooting
Машинночитаемый индекс	xmemo.dev/llms.txt

Лицензия

Исправление существующей конфигурации MCP для Kiro

Для проверки локальной конфигурации без сетевых запросов выполните xmemo doctor --client kiro --json. Команда xmemo doctor --client kiro --fix переносит распознанные устаревшие прокси-конфигурации на нативный HTTP с OAuth; добавьте --auth key, чтобы использовать нативный HTTP с Bearer ${XMEMO_KEY}. При исправлении создаётся резервная копия, сохраняются не связанные с ним серверы и настройки клиента, а учётные данные никогда не копируются в новую конфигурацию. После этого перезапустите Kiro и проверьте работу на реальном вызове инструмента: успешная проверка конфигурации ещё не означает, что аутентификация пройдена или токен обновлён. Для новых установок используйте xmemo setup kiro [--auth oauth|key].