Skip to content
MMW Docs

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.
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_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. 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 remember is 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. The spool_status tool 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 consent in a terminal, not a single line of your sessions leaves the machine. Details: Session history.

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:

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

    Configs for other clients are on Agent configuration.

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

  4. 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) 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.
CommandWhat it does
mmw-agentStdio MCP server mode. This is how your client launches it; background sync also runs in this mode.
mmw-agent consentAllow session history upload. Works only in an interactive terminal: the agent shows what it found and asks you to type “yes”.
mmw-agent revokeWithdraw consent. Uploads stop immediately; the server is notified if reachable.
mmw-agent statusLocal consent, discovered sessions, server state and the memory queue (JSON). A refused key shows up in the server field.
mmw-agent outbox-retrySend again the memories that did not reach the server (for example after fixing the key). Included in the current agent.
mmw-agent syncRun one sync cycle now and print the result (JSON). Uploads nothing without consent.
VariableDefaultDescription
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_ENDPOINTregional defaultServer address. Set https://mcp.mmwhub.tech; the trailing /mcp is optional.
MMW_LANGby server addressLanguage of agent hints: en or ru.
MMW_AGENT_HOME~/.mmwAgent state directory: agent.json with the device ID and consent receipt (mode 0600).
MMW_SESSIONS_HOMEhome directoryWhere to look for sessions: the agent checks .claude/projects and .codex/sessions under it.
MMW_SYNC_INTERVAL15Pause 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.