Universal Memory APIs

These endpoints are frozen in private beta and disabled by default. They return 404 memory_passport_not_available unless MemoryOS explicitly enables MEMORY_PASSPORT_ENABLED for an approved deployment. Do not use this API for a standard production integration.

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. This page is only the API reference.

Authentication

Universal memory calls require two headers:

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.

POST /v1/agents/global
Authorization: ApiKey mem_...
Content-Type: application/json

Request:

{
  "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:

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

POST /v1/universal/memories/add

Request

{
  "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:

{
  "error": "write_not_permitted",
  "code": "UAT_002"
}

POST /v1/universal/memories/retrieve

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

POST /v1/universal/memories/retrieve

Request

{
  "query": "How should I personalize this answer?",
  "limit": 5,
  "format": "bullets",
  "context_max_tokens": 500
}

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:

{
  "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:

GET /v1/agents/global/{agent_id}

This endpoint does not return tenant ownership or agent API keys. agent_id must be the UUID returned by agent registration. Malformed IDs return 422; a valid UUID with no active public agent returns 404. Example response:

{
  "data": {
    "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"]
  },
  "request_id": "c3d4fd63-77ff-48b6-9316-6bcbadf9476b",
  "timestamp": "2026-09-11T17:32:37Z"
}

Secure-link connector token

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

POST /v1/tenant/memory-passport/link-token
Authorization: ApiKey mem_...
Content-Type: application/json

Request:

{
  "agent_id": "aa535a7e-b0d6-44df-8e17-8438f6098836",
  "external_user_id": "cust_8a72"
}

Response:

{
  "data": {
    "link_token": "plink_...",
    "expires_in_seconds": 900
  }
}

Build the user redirect URL:

https://consent.memoryo.dev/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

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

Memory APIs

Domain APIs

Reference

Universal Memory APIs

Authentication

Create a global agent

POST /v1/universal/memories/add

Request

Behavior

POST /v1/universal/memories/retrieve

Request

Behavior

Public agent profile

Secure-link connector token

​Authentication

​Create a global agent

​POST /v1/universal/memories/add

​Request

​Behavior

​POST /v1/universal/memories/retrieve

​Request

​Behavior

​Public agent profile

​Secure-link connector token

​Consent and manage endpoints

​Related pages

Authentication

Create a global agent

POST /v1/universal/memories/add

Request

Behavior

POST /v1/universal/memories/retrieve

Request

Behavior

Public agent profile

Secure-link connector token

Consent and manage endpoints

Related pages