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

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.

Example response:

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

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

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
• Cross-agent memory sharing
• Authentication