MMRY AI Public API

Memory infrastructure for AI assistants. Four operations, OAuth 2.0, designed for ChatGPT, Copilot, Gemini, Cursor, and MCP-compatible platforms.

Overview

The MMRY AI Public API lets external AI platforms maintain persistent memory for their users across sessions. A user grants your platform access through a standard OAuth 2.0 consent screen on mmryai.com. After that, your platform can load context at the start of a conversation, search memories during a conversation, save new memories worth remembering, and set or change who can see a memory — all on the user's behalf, scoped to their account.

The surface is intentionally narrow:

• Four operations. Load, search, save, and set who can see a memory. Nothing else.
• OAuth 2.0 authorization code flow with PKCE. The standard. Refresh tokens rotate on every use.
• Stable shape. Memory lifecycle — how long memories last, how they age, how they're classified — is handled by MMRY AI internally. Your platform never sees those mechanics and never has to manage them.
• Visibility is yours to set, and is always reported back. Every memory says whether it is private to the person, shared with one of their memory groups, or open to their whole organization. Omit it on save and the person's own default applies.

The machine-readable spec lives at https://mmryai.com/openapi/v1.json. Like the rest of these docs, the spec is gated to authenticated MMRY AI users — fetch it with your JWT or API key. Use the download button below to save it as mmry-openapi-v1.json, for use with OpenAPI-aware tooling. Connecting an AI assistant such as ChatGPT? You do not need the spec at all: use the MCP connector below.

Download OpenAPI spec (v1.json)

Connect an AI tool (MCP)

The easiest way to use MMRY AI is as a Model Context Protocol (MCP) connector. Most AI assistants can connect to a remote MCP server by URL. MMRY AI lives at:

https://mmryai.com/mcp

Add that as a custom connector in your AI tool. It registers itself automatically and walks you through signing in to your MMRY AI account. There are no client IDs, secrets, or settings to manage. Once connected, your assistant can load, search, and save memories on your behalf, choose whether each one is private, shared with a memory group, or open to your organization, and change that later. The same memories are available in every tool you connect.

ChatGPT

Open Settings, then Connectors (turn on Developer mode first if prompted), then add a custom connector. Enter https://mmryai.com/mcp and authorize.

Claude (Desktop or Team)

Open Settings, then Connectors, then add a custom connector. Enter https://mmryai.com/mcp and authorize. Team owners can add it once for the whole workspace; each member still signs in to their own account, and memories stay private to each person.

Cursor, Copilot, and other MCP clients

Any MCP-capable client that accepts a remote server URL can connect. Point it at https://mmryai.com/mcp.

The rest of this page documents the underlying OAuth 2.0 and REST API, for platforms that integrate MMRY AI directly rather than through the MCP connector.

Authentication — OAuth 2.0

Every request to /v1/* requires an OAuth 2.0 bearer access token. The authorization code flow is standard:

Authorization request

Redirect the user's browser to:

GET https://mmryai.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://your-platform.example.com/callback
    &response_type=code
    &state=OPAQUE_STATE_FOR_CSRF
    &code_challenge=SHA256_OF_VERIFIER_BASE64URL
    &code_challenge_method=S256

The redirect_uri must match one of the redirect URIs registered for your client. PKCE is optional but recommended; we accept S256 or plain.

Token exchange

POST https://mmryai.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=THE_CODE_FROM_REDIRECT
&redirect_uri=https://your-platform.example.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code_verifier=YOUR_PKCE_VERIFIER

Response (200):

{
  "access_token": "<64-char hex>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<64-char hex>"
}

Access tokens are valid for 1 hour. Refresh tokens are valid for 30 days, single-use, and rotated on every refresh.

Refresh

POST https://mmryai.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Revoke

POST https://mmryai.com/oauth/revoke
Content-Type: application/json

{ "token": "<access_token or refresh_token>" }

Revoking a refresh token cascades to every access token derived from it.

Discovery

The OIDC discovery document is at https://mmryai.com/.well-known/openid-configuration and lists the canonical endpoint URLs above.

The four operations

All four endpoints live under /v1/ and require the Authorization: Bearer <access_token> header.

Load memories

Returns the memories visible to the authenticated user, newest first, in pages of 100. Pass page to walk through additional pages, and optionally filter by scope:

GET /v1/memories?scope=payments&page=1 HTTP/1.1
Authorization: Bearer <access_token>

Query parameters:

• page: page number starting at 1. Defaults to 1. Each page returns up to 100 memories.
• scope: optional scope filter.

Response (200):

{
  "items": [
    {
      "id": 42,
      "topic": "Refund Provider",
      "content": "Use Stripe for all refund processing.",
      "scope": "payments",
      "category": "Decision",
      "createdAt": "2026-02-22T10:00:00Z"
    }
  ],
  "total": 342,
  "page": 1,
  "pageSize": 100,
  "hasMore": true
}

To retrieve everything, request page=1, then increment page until hasMore is false. total is the full count across all pages.

Search memories

Keyword search across topic + content. The q parameter is required (1-200 chars). Optional scope filter.

GET /v1/memories/search?q=refund HTTP/1.1
Authorization: Bearer <access_token>

Save a memory

POST /v1/memories HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "topic": "Refund Provider",
  "content": "Use Stripe for all refund processing.",
  "scope": "payments",
  "visibility": "organization"
}

Response (201):

{
  "id": 42,
  "topic": "Refund Provider",
  "content": "Use Stripe for all refund processing.",
  "scope": "payments",
  "category": "Decision",
  "createdAt": "2026-02-22T10:00:00Z",
  "visibility": "Global",
  "group": null
}

Fields:

• topic (required, 1-200 chars) — short label
• content (required, 1-8000 chars) — the memory itself
• scope (optional, ≤100 chars) — context or project scope. Defaults to "general".
• visibility (optional) — private, group, or organization. Omit it and the user's own default applies, which is how someone who chose private in their account settings stays protected even when your platform says nothing about visibility.
• group (required when visibility is group) — the memory group's name. It must be one the user belongs to. If it is not, the error names the groups that would work.

Category is determined by MMRY AI — your platform never has to think about it.

The response always states the visibility that was applied, so you can tell the user what actually happened rather than assuming.

Set who can see a memory

Changes who can see a memory the user already saved. Use it when they ask to make something private, share it with one of their memory groups, or open it to their organization.

PUT /v1/memories/42/visibility HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "visibility": "private"
}

Response (200):

{
  "id": 42,
  "topic": "Refund Provider",
  "content": "Use Stripe for all refund processing.",
  "scope": "payments",
  "category": "Decision",
  "createdAt": "2026-02-22T10:00:00Z",
  "visibility": "Private",
  "group": null
}

Only the person who saved a memory can change who sees it. This fails for anyone else, including account administrators. That is deliberate, not a limitation.

Errors & rate limiting

Error response shape

4xx and 5xx responses return either an OAuth-style error or an RFC 7807 problem document, always as JSON with a non-empty body:

{
  "error": "invalid_grant",
  "error_description": "Refresh token expired."
}

or for validation failures:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "content": ["Content must not exceed 8000 characters."] }
}

Authentication failures (401)

A /v1/* request returns 401 when the bearer token is missing, expired, or no longer valid. A token can stop working before its normal expiry if it was revoked or if MMRY AI deactivates your platform's OAuth client; in that case the token is rejected immediately. Treat any 401 as a signal to obtain a fresh token through the authorization flow (or refresh), and if that also fails, re-connect your platform.

Rate limits

Per-platform requests to /v1/* are limited to 200 requests per 60-second window by default. Specific platforms may have higher limits configured by MMRY AI.

When you exceed the limit you receive HTTP 429 with:

{ "error": "Too many requests", "retryAfterSeconds": 60 }

The Retry-After response header carries the same value. Always respect it; back off and retry after the window elapses.

Registering a platform

MMRY supports RFC 7591 Dynamic Client Registration, so most platforms need no manual setup. MCP clients such as Claude, ChatGPT, and Cursor register themselves automatically the first time a user connects. The user simply adds the connector URL https://mmryai.com/mcp and approves the consent screen.

To register a client directly, POST to the registration endpoint. No authentication is required, and the endpoint is rate-limited:

POST https://mmryai.com/oauth/register
Content-Type: application/json

{
  "client_name": "Your Platform",
  "redirect_uris": ["https://yourplatform.example/oauth/callback"]
}

By default the client is registered as a public client (PKCE, token_endpoint_auth_method: "none") and no client secret is issued. To register a confidential client, set "token_endpoint_auth_method": "client_secret_post"; the response then includes a client_secret that is returned exactly once. A successful call returns 201 Created:

{
  "client_id": "mcp_a1b2c3...",
  "client_id_issued_at": 1752566400,
  "token_endpoint_auth_method": "none",
  "redirect_uris": ["https://yourplatform.example/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Endpoint URLs are discoverable without registration. https://mmryai.com/.well-known/oauth-authorization-server (RFC 8414) advertises the authorization, token, and registration endpoints and the supported token endpoint auth methods client_secret_post and none. https://mmryai.com/.well-known/oauth-protected-resource (RFC 9728) advertises the protected resource and its authorization server. The OIDC document at /.well-known/openid-configuration remains available.

FAQ

Do my users need a MMRY AI account?

Yes. The OAuth consent screen is the place where a new user can create an account inline; the flow lands them back at your platform with a working connection. If they cancel the consent screen, your platform receives error=access_denied at the redirect URI.

What memories can my platform see?

Only memories belonging to the authenticated user. Multi-tenant isolation is enforced by MMRY AI at every layer; cross-account leakage is impossible.

Can my platform classify memories?

No. Classification (category, scope semantics, retention) is handled internally and stays stable across MMRY AI releases. The intent is that your platform never has to manage memory lifecycle — just save what's worth remembering and read what's relevant.

What happens if a user revokes my platform's access?

The user can revoke at https://mmryai.com/account. Your existing access and refresh tokens are immediately invalidated. The next request returns 401; your platform should handle this by prompting the user to reconnect.

How do I rotate my client secret?

Public (PKCE) clients have no secret, so there is nothing to rotate. They are safe by design. If you registered a confidential client and need to roll its secret, register a fresh client via POST /oauth/register and cut over to it, or email platforms@mmryai.com for help. When a confidential client's secret changes, that client's existing tokens stop working, so plan for a brief reconnection window.

Where can I see what my platform is doing?

Each call to /v1/* is logged on the MMRY AI side with platform attribution, the user, the operation, and timestamp. Per-platform usage reports are available on request.