# mmw_sync_status

> The mmw-agent local tool — consent state and the result of the last session history sync cycle.

On this page you will learn what `mmw_sync_status` shows, how to read each sync state, and what to do when session history upload stops.

The running example: a developer has consented to uploading Claude Code sessions and asks the agent "are my sessions being uploaded to MMW?".

## Purpose

`mmw_sync_status` is the only tool that answers **locally**, without contacting the MMW server. The local agent [mmw-agent](/agent/overview/) (version 0.1.4) adds it to the server's tool list. It shows:

- whether a person consented to uploading local AI session history;
- this device's identifier;
- the result of the last sync cycle.

The tool only reads. **It cannot grant consent**: consent is given by a person in a terminal with `mmw-agent consent`. Clients without the agent (claude.ai, ChatGPT, direct HTTP) do not have this tool.

Annotations: `readOnlyHint: true`, `idempotentHint: true`.

## Parameters

None. The input schema is an empty object.

## Response

A text block with JSON:

| Field | Description |
| --- | --- |
| `consent` | `null` if there is no consent. Otherwise an object: `granted` (`true`), `clients` (for example `["claude-code", "codex"]`), `granted_at` (consent time). |
| `device_id` | This computer's identifier, `dev-…`; `null` if not created yet. |
| `last_cycle` | Result of the last sync cycle (see below). |

### `last_cycle.state` values

| State | Meaning | What to do |
| --- | --- | --- |
| `idle` | The agent just started; no cycle has run yet. | Wait: a cycle runs every 15 seconds by default. |
| `consent_required` | No consent. `discovered` shows how many sessions were found on the computer, `hint` gives a tip. | Run `mmw-agent consent` in a terminal if you want history uploaded. |
| `ok` | The cycle succeeded. | Nothing. |
| `quota_exceeded` | Plan storage for session history is full; includes `used_bytes` and `max_bytes`. | Upgrade the plan. Full history is on Enterprise. |
| `server_busy` | The server is temporarily not accepting history (low on space). Nothing is lost. | Nothing: the agent retries later on its own. |
| `offline` | The server is unreachable; `error` gives the reason. | Check the network. The agent catches up once the server is back. |
| `unsupported` | The server has no session sync. | Check `MMW_ENDPOINT`. |
| `error` | Unexpected cycle error; `error` gives type and text. | Check `mmw-agent status` and contact support. |

Fields of a successful (`ok`) cycle: `sources` (sessions processed), `chunks` and `bytes` (what was sent), `local_redactions` (secrets removed on the computer), `skipped_by_plan_history` (sessions older than the plan's retention), `conflicts`, `truncated`, `plan`, `history_days`, `at` (cycle time).

## Example

A call with no arguments:

```json title="arguments"
{}
```

```json
{
  "consent": {
    "granted": true,
    "clients": ["claude-code"],
    "granted_at": "2026-10-05T08:30:12.004512+00:00"
  },
  "device_id": "dev-5c0e9b7f3a2d4e1f8b6a0c9d7e5f4a3b",
  "last_cycle": {
    "state": "ok",
    "sources": 4,
    "chunks": 2,
    "bytes": 183422,
    "local_redactions": 1,
    "skipped_by_plan_history": 0,
    "conflicts": [],
    "truncated": [],
    "plan": "pro",
    "history_days": 90,
    "at": "2026-10-05T09:15:44.871003+00:00"
  }
}
```

## Errors

The tool itself returns no errors: anything that went wrong shows up in `last_cycle`. Agent errors when calling **other** tools:

| Text | Cause |
| --- | --- |
| `MMW rejected the API key (check MMW_API_KEY in the MCP config)` | The server answered 401 or 403 to the key. |
| `MMW server unreachable: … Session sync will catch up automatically.` | No connection to the server. While it is unreachable, the tool list contains only `mmw_sync_status`. |
| `Empty reply from MMW server` | The server returned an empty response. |

With the mmwhub.tech endpoint, agent messages are in English; `MMW_LANG=en` forces English explicitly.

## Notes

- Uploaded sessions are stored compressed, but searching them and extracting facts into memory are not built yet: they do not appear in `search`.
- To withdraw consent: `mmw-agent revoke`; uploads stop immediately.

If `mmw_sync_status` is missing in your client, the client is connected to the server directly, without the agent. Check the agent from a terminal with `mmw-agent status`.

## Next steps