The mmw-agent local agent

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:

1. what the agent does and how it differs from a direct HTTP connection;
2. how to run and check it;
3. its commands and environment variables.

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, gateway_call
                             (local, read-only)                         (+ connected integrations)

                             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.
• A local mmw_sync_status tool. 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. Tool calls return a clear error in the meantime, and the agent tries to reconnect on the next call.
• Session history only with consent. Until you run mmw-agent consent in a terminal, not a single line of your sessions leaves the machine. Details: Session history.

Note

You do not always need the agent. If you do not want session history, connect to https://mcp.mmwhub.tech/mcp directly over HTTP with an Authorization: Bearer mmw_… header — see Other MCP clients. The agent does not run in claude.ai on the web; there you use the OAuth connector.

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.

1. Get an API key in your account at app.mmwhub.tech. Keys start with mmw_.

2. Add the agent to your client config. Claude Code example:

   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.4-py3-none-any.whl mmw-agent

   Configs for other clients are on Agent configuration.

3. Restart the client. The tool list should now include remember, search, forget, validate_memory, gateway_call and mmw_sync_status.

4. Check the connection from a terminal:

   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.4-py3-none-any.whl mmw-agent status

Caution

Always set MMW_ENDPOINT=https://mcp.mmwhub.tech. The agent’s built-in default is a different regional address, and its hints would then appear in another language.

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) or null;
• 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 get error with the reason.

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 and server-side state (JSON).
mmw-agent sync	Run one sync cycle now and print the result (JSON). Uploads nothing without consent.

Caution

Only a person can give consent. mmw-agent consent refuses to run outside an interactive terminal, and the mmw_sync_status tool the model sees is read-only. If an assistant offers to “consent for you”, it cannot — that is deliberate. Run the command yourself.

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.

Per-client examples are on Agent configuration.

Where next

Agent configuration Ready configs for Claude Code, Claude Desktop, Cursor and Codex.

Session history What is uploaded, what never leaves your machine, quotas and revoking.

Agent troubleshooting Symptom, cause, fix — based on how the agent actually behaves.

mmw_sync_status tool Response fields and sync states.