> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Universal Memory APIs

> Cross-agent Memory Passport endpoints for consented universal memory.

Universal memory APIs are used by global agents after a user grants access through Memory Passport.

These endpoints are separate from tenant-scoped `/v1/memories/*` APIs.

For the full product flow, use [Cross-agent memory sharing](/guides/cross-agent-sharing). This page is only the API reference.

## Authentication

Universal memory calls require two headers:

```http theme={null}
Authorization: ApiKey agent_sk_...
X-MemoryOS-UUI: uui_...
```

The agent API key identifies the requesting agent.

The UUI token identifies the Memory Passport user whose grant is being checked.

## Create a global agent

Creates an agent identity that can request Memory Passport access.

```http theme={null}
POST /v1/agents/global
Authorization: ApiKey mem_...
Content-Type: application/json
```

Request:

```json theme={null}
{
  "name": "Support Copilot",
  "description": "Customer support agent with access to approved user context.",
  "website_url": "https://yourapp.com",
  "logo_url": "https://yourapp.com/logo.png",
  "default_categories_requested": ["preference", "fact", "goal"],
  "redirect_uri": ""
}
```

Response:

```json theme={null}
{
  "data": {
    "id": "aa535a7e-b0d6-44df-8e17-8438f6098836",
    "name": "Support Copilot",
    "default_categories_requested": ["preference", "fact", "goal"],
    "raw_agent_api_key": "agent_sk_..."
  }
}
```

Store `raw_agent_api_key` immediately. It is shown once.

Notes

* tenants create global agents; end users do not
* `id` is the public `agent_id` used in consent and connector URLs
* `raw>_agent_api_key` is the backend-only `agent_sk_...`
* `default_categories_requested` only preselects consent checkboxes; the user makes the final choice

## POST /v1/universal/memories/add

Queues a universal memory extraction job.

```http theme={null}
POST /v1/universal/memories/add
```

### Request

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "content": "Please remember that I prefer Python-first examples."
    }
  ],
  "metadata": {
    "source": "learning-app"
  },
  "idempotency_key": "optional-client-key"
}
```

### Behavior

* requires an active grant for the user and agent
* requires `access_type = read_write`
* writes to the universal memory table and `universal_memories` vector collection
* never writes to the tenant-scoped `memories` table

If the grant is read-only, MemoryOS returns:

```json theme={null}
{
  "error": "write_not_permitted",
  "code": "UAT_002"
}
```

## POST /v1/universal/memories/retrieve

Retrieves universal memories that the user allowed this agent to access.

```http theme={null}
POST /v1/universal/memories/retrieve
```

### Request

```json theme={null}
{
  "query": "How should I personalize this answer?",
  "limit": 5,
  "format": "bullets"
}
```

### Behavior

* filters by `user_uui_id`
* filters by categories in the active permission grant
* searches only the `universal_memories` collection
* never exposes other agents' grants
* returns an empty result when no grant exists

No-grant response:

```json theme={null}
{
  "data": [],
  "system_prompt_addition": "",
  "is_passthrough": false,
  "permission_error": "no_grant_for_user",
  "categories_available": []
}
```

## Public agent profile

The consent app and tenant apps can fetch a public global-agent profile before consent:

```http theme={null}
GET /v1/agents/global/{agent_id}
```

This endpoint does not return tenant ownership or agent API keys.

Example response:

```json theme={null}
{
  "id": "2beab5d0-741d-4ff8-9475-c29d9ea5a57e",
  "name": "Learning Coach",
  "description": "Personalizes explanations using approved learning memories.",
  "logo_url": "https://example.com/logo.png",
  "website_url": "https://example.com",
  "is_verified": false,
  "default_categories_requested": ["preference", "expertise"]
}
```

## Secure-link connector token

Creates a one-time connector token for a signed-in app user.

```http theme={null}
POST /v1/tenant/memory-passport/link-token
Authorization: ApiKey mem_...
Content-Type: application/json
```

Request:

```json theme={null}
{
  "agent_id": "aa535a7e-b0d6-44df-8e17-8438f6098836",
  "external_user_id": "cust_8a72"
}
```

Response:

```json theme={null}
{
  "data": {
    "link_token": "plink_...",
    "expires_in_seconds": 900
  }
}
```

Build the user redirect URL:

```text theme={null}
https://consent.memoryos.io/connect?agent_id=aa535a7e-b0d6-44df-8e17-8438f6098836&link_token=plink_...
```

Rules:

* generate the token only after the user is signed in to your app
* the token is single-use
* the token expires automatically
* do not ask the user to type their own app user ID
* do not expose your tenant API key in frontend code

## Consent and manage endpoints

The consent/manage app uses these user-scoped endpoints:

| Endpoint                                        | Purpose                                       |
| ----------------------------------------------- | --------------------------------------------- |
| `POST /v1/uui/register`                         | Create a Memory Passport account and send OTP |
| `POST /v1/uui/otp/send`                         | Send a login code                             |
| `POST /v1/uui/otp/verify`                       | Verify OTP and return session token           |
| `GET /v1/uui/me`                                | Resolve current Memory Passport session       |
| `GET /v1/uui/me/grants`                         | List active grants                            |
| `POST /v1/uui/me/grants`                        | Create or update a grant                      |
| `DELETE /v1/uui/me/grants/{grant_id}`           | Revoke a grant                                |
| `GET /v1/uui/organisations`                     | List public connector directory entries       |
| `GET /v1/uui/me/connections`                    | List the user's connected services            |
| `DELETE /v1/uui/me/connections/{connection_id}` | Disconnect a service                          |
| `DELETE /v1/uui/me`                             | Delete Memory Passport data                   |

## Related pages

* [Memory Passport](/concepts/memory-passport)
* [Cross-agent memory sharing](/guides/cross-agent-sharing)
* [Authentication](/authentication)