mmw-agent is a small Python program that your MCP client (Claude Code, Claude Desktop, Cursor, Codex) runs on your machine. It connects the client to the MMW memory server and, only if you explicitly allow it, uploads your Claude Code and Codex session history.
On this page you will learn:
- what the agent does and how it differs from a direct HTTP connection;
- how to run and check it;
- its commands and environment variables.
What the agent does
Section titled “What the agent does” MCP client mmw-agent (your machine) MMW server ────────── ──────────────────────── ────────── tools/list ── stdio ──▶ forwards the request ── HTTPS ──▶ remember, search, forget, tools/call + adds mmw_sync_status, validate_memory spool_status (local) (+ connected integrations) remember: disk first, then the server
background sync ── HTTPS ──▶ session history (only after consent) (with your consent)- A proxy to every server tool. The agent is a local stdio MCP server that forwards each client request to the MMW server. The client sees exactly the tool list the server returns, not a subset hard-coded into the agent.
- Says which app started it. The current agent the agent passes the server the app’s name and version from its handshake (for example
Cursor/1.7.2), for the “Connected clients” table in the account. Nothing else about the app or the computer is sent. - A local
mmw_sync_statustool. Read-only: it shows whether you consented to session upload and how the last sync cycle went. It cannot grant consent. - Survives a server outage at start-up. If the server does not answer when the client starts, the agent completes the handshake itself (server name “MMW (offline, local agent)”) so the client does not fail. Search returns a clear error in the meantime, and the agent tries to reconnect on the next call.
- A local outbox for memories (since 0.1.9). Every
rememberis first written to your disk, in~/.mmw/outbox.db, and only then sent to the server. If the server is unreachable or overloaded, the assistant gets a “saved locally” answer instead of an error, and the memory is delivered in the background as soon as the server answers. Memories are delivered in the order they were made and never twice: each carries its own idempotency key. A refusal on the merits (for example, the Memory Guard fired) is not retried: the assistant sees the server’s answer. Thespool_statustool shows the queue. - One connection for all calls (since 0.1.9). The agent keeps its connection to the server open between calls instead of paying for a new TLS handshake every time.
- Session history only with consent. Until you run
mmw-agent consentin a terminal, not a single line of your sessions leaves the machine. Details: Session history.
Install and run
Section titled “Install and run”There is nothing to install separately: uvx downloads the agent the first time your client starts it. Requirements: Python 3.11+ and uv. The agent ships as a wheel from the MMW site; it is not published on PyPI.
-
Get an API key in your account at app.mmwhub.tech. Keys start with
mmw_. -
Add the agent to your client config. Claude Code example:
Terminal window claude mcp add mmw \-e MMW_API_KEY=mmw_your_key \-e MMW_ENDPOINT=https://mcp.mmwhub.tech \-- uvx --from https://app.mmwhub.tech/downloads/mmw-agent/mmw_agent-0.1.14-py3-none-any.whl mmw-agentConfigs for other clients are on Agent configuration.
-
Restart the client. The tool list should now include
remember,search,search_history,forget,validate_memory,mmw_sync_statusandspool_status. -
Check the connection from a terminal:
Terminal window MMW_API_KEY=mmw_your_key MMW_ENDPOINT=https://mcp.mmwhub.tech \uvx --from https://app.mmwhub.tech/downloads/mmw-agent/mmw_agent-0.1.14-py3-none-any.whl mmw-agent status
status prints JSON. Before consent it looks roughly like this:
{ "consent": null, "device_id": null, "discovered": { "claude-code": 42, "codex": 7 }, "server": { "registered": false, "sources": 0 }}consent— the consent receipt (clients and time) ornull;device_id— this machine’s identifier, created the first time the agent talks to the server or on consent;discovered— how many session files the agent found on disk (it lists files only and does not read them);server— whether the device is registered on the server and how many sources (session files) are already there. If the server is unreachable, you geterrorwith the reason.
Commands
Section titled “Commands”| Command | What it does |
|---|---|
mmw-agent | Stdio MCP server mode. This is how your client launches it; background sync also runs in this mode. |
mmw-agent consent | Allow session history upload. Works only in an interactive terminal: the agent shows what it found and asks you to type “yes”. |
mmw-agent revoke | Withdraw consent. Uploads stop immediately; the server is notified if reachable. |
mmw-agent status | Local consent, discovered sessions, server state and the memory queue (JSON). A refused key shows up in the server field. |
mmw-agent outbox-retry | Send again the memories that did not reach the server (for example after fixing the key). Included in the current agent. |
mmw-agent sync | Run one sync cycle now and print the result (JSON). Uploads nothing without consent. |
Environment variables
Section titled “Environment variables”| Variable | Default | Description |
|---|---|---|
MMW_API_KEY | — | API key from your account. Required for server mode, status and sync; without it the agent exits with a hint. |
MMW_CREDENTIAL | — | Fallback name for the key, read only when MMW_API_KEY is not set. |
MMW_ENDPOINT | regional default | Server address. Set https://mcp.mmwhub.tech; the trailing /mcp is optional. |
MMW_LANG | by server address | Language of agent hints: en or ru. |
MMW_AGENT_HOME | ~/.mmw | Agent state directory: agent.json with the device ID and consent receipt (mode 0600). |
MMW_SESSIONS_HOME | home directory | Where to look for sessions: the agent checks .claude/projects and .codex/sessions under it. |
MMW_SYNC_INTERVAL | 15 | Pause between sync cycles, in seconds. On network errors the pause grows up to 5 minutes. |
MMW_SPOOL_MODE | — | async: every remember answers “saved locally” at once and is sent to the server in the background. By default the agent first tries to deliver the memory right away and returns the server’s answer. |
Per-client examples are on Agent configuration.