# Локальный агент mmw-agent

> Что делает mmw-agent, как его запустить через uvx, какие у него команды и переменные окружения.

**mmw-agent** — небольшая программа на Python, которую ваш MCP-клиент (Claude Code, Claude Desktop, Cursor, Codex) запускает у вас на компьютере. Она соединяет клиента с сервером памяти MMW и, только если вы явно разрешите, загружает историю ваших сессий Claude Code и Codex.

Из этой страницы вы узнаете:

1. что именно делает агент и чем он отличается от прямого подключения по HTTP;
2. как его запустить и проверить;
3. какие у него команды и переменные окружения.

## Что делает агент

```text
  MCP-клиент                mmw-agent (ваш компьютер)                 Сервер MMW
  ──────────                ─────────────────────────                 ──────────
  tools/list   ── stdio ──▶  пересылает запрос         ── HTTPS ──▶   remember, search, forget,
  tools/call                 + добавляет mmw_sync_status               validate_memory, gateway_call
                             (локальный, только чтение)                 (+ подключённые интеграции)

                             фоновая синхронизация      ── HTTPS ──▶   история сессий
                             (только после consent)                    (с вашего согласия)
```

- **Прокси ко всем инструментам сервера.** Агент работает как локальный MCP-сервер по stdio и пересылает каждый запрос клиента на сервер MMW. Клиент видит ровно тот список инструментов, который отдаёт сервер, — без урезанного набора, зашитого в агент.
- **Локальный инструмент `mmw_sync_status`.** Только чтение: показывает, дано ли согласие на загрузку истории и чем закончился последний цикл синхронизации. Выдать согласие этот инструмент не может.
- **Устойчивость к недоступности сервера.** Если при запуске сервер не отвечает, агент сам отвечает клиенту на рукопожатие (имя сервера «MMW (офлайн, локальный агент)»), и клиент не падает. Вызовы инструментов в это время возвращают понятную ошибку, а при следующем вызове агент снова пробует подключиться.
- **История сессий — по согласию.** Пока вы не выполнили `mmw-agent consent` в терминале, с компьютера не уходит ни одной строки ваших сессий. Подробно — в разделе [История сессий](/agent/session-history/).

Агент нужен не всегда. Если вам не нужна история сессий, можно подключиться к `https://mcp.mmwhub.ru/mcp` напрямую по HTTP с заголовком `Authorization: Bearer mmw_…` — см. [Другие MCP-клиенты](/clients/other-mcp/). В веб-версии claude.ai агент не запускается: там работает коннектор по OAuth.

## Установка и запуск

Отдельно ставить агент не нужно: `uvx` скачивает его при первом запуске прямо из конфигурации клиента. Требования: **Python 3.11+** и [uv](https://docs.astral.sh/uv/). Агент распространяется как колесо (wheel) с сайта MMW, в PyPI он не опубликован.

1. Получите API-ключ в кабинете [app.mmwhub.ru](https://app.mmwhub.ru). Ключ начинается с `mmw_`.

2. Добавьте агент в конфигурацию клиента. Пример для Claude Code:

   ```bash
   claude mcp add mmw \
     -e MMW_API_KEY=mmw_ваш_ключ \
     -- uvx --from https://app.mmwhub.ru/downloads/mmw-agent/mmw_agent-0.1.4-py3-none-any.whl mmw-agent
   ```

   Конфигурации для остальных клиентов — на странице [Настройка агента](/agent/configuration/).

3. Перезапустите клиента. В списке инструментов появятся `remember`, `search`, `forget`, `validate_memory`, `gateway_call` и `mmw_sync_status`.

4. Проверьте подключение из терминала:

   ```bash
   MMW_API_KEY=mmw_ваш_ключ \
     uvx --from https://app.mmwhub.ru/downloads/mmw-agent/mmw_agent-0.1.4-py3-none-any.whl mmw-agent status
   ```

Команда `status` печатает JSON. Пока согласие не дано, он выглядит примерно так:

```json
{
  "consent": null,
  "device_id": null,
  "discovered": { "claude-code": 42, "codex": 7 },
  "server": { "registered": false, "sources": 0 }
}
```

- `consent` — квитанция согласия (список клиентов и время) или `null`;
- `device_id` — идентификатор этого компьютера, создаётся при первом обращении агента к серверу или при согласии;
- `discovered` — сколько файлов сессий агент нашёл на диске (только список файлов, содержимое не читается);
- `server` — зарегистрировано ли устройство на сервере и сколько источников (файлов сессий) там уже есть. Если сервер недоступен, здесь будет `error` с причиной.

## Команды

| Команда | Что делает |
| --- | --- |
| `mmw-agent` | Режим MCP-сервера по stdio. Так агент запускает ваш клиент; в этом же режиме работает фоновая синхронизация. |
| `mmw-agent consent` | Разрешить загрузку истории сессий. Работает только в интерактивном терминале: агент покажет, сколько сессий нашёл, и попросит ввести «да». |
| `mmw-agent revoke` | Отозвать согласие. Загрузка останавливается сразу; сервер получает уведомление, если доступен. |
| `mmw-agent status` | Локальное согласие, найденные сессии и состояние на сервере (JSON). |
| `mmw-agent sync` | Выполнить один цикл синхронизации сейчас и напечатать итог (JSON). Без согласия ничего не загружает. |

Согласие даёт только человек. `mmw-agent consent` отказывается работать, если его запускают не из интерактивного терминала, а инструмент `mmw_sync_status` доступен модели только на чтение. Если ассистент предлагает «дать согласие за вас» — такой возможности у модели нет специально, выполните команду сами.

## Переменные окружения

| Переменная | По умолчанию | Описание |
| --- | --- | --- |
| `MMW_API_KEY` | — | API-ключ из кабинета. Обязателен для режима сервера, `status`, `sync`. Без него агент завершится с подсказкой. |
| `MMW_CREDENTIAL` | — | Запасное имя для ключа: читается, только если `MMW_API_KEY` не задан. |
| `MMW_ENDPOINT` | `https://mcp.mmwhub.ru` | Адрес сервера. Можно указывать с `/mcp` на конце или без. |
| `MMW_LANG` | по адресу сервера | Язык подсказок агента: `ru` или `en`. Для `mmwhub.ru` по умолчанию русский, для остальных адресов — английский. |
| `MMW_AGENT_HOME` | `~/.mmw` | Каталог состояния агента: файл `agent.json` с идентификатором устройства и квитанцией согласия (права 0600). |
| `MMW_SESSIONS_HOME` | домашний каталог | Где искать сессии: агент смотрит в `.claude/projects` и `.codex/sessions` внутри этого каталога. |
| `MMW_SYNC_INTERVAL` | `15` | Пауза между циклами синхронизации, в секундах. При ошибках сети пауза растёт до 5 минут. |

Подробные примеры для каждого клиента — на странице [Настройка агента](/agent/configuration/).

## Что дальше