# The mmw-agent local agent

> What mmw-agent does, how to run it with uvx, and its commands and environment variables.

**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

```text
  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](/agent/session-history/).

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](/clients/other-mcp/). 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](https://docs.astral.sh/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](https://app.mmwhub.tech). Keys start with `mmw_`.

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

   ```bash
   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](/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:

   ```bash
   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
   ```

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:

```json
{
  "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. |

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](/agent/configuration/).

## Where next