Skip to main content
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.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:
EndpointPurpose
POST /v1/uui/registerCreate a Memory Passport account and send OTP
POST /v1/uui/otp/sendSend a login code
POST /v1/uui/otp/verifyVerify OTP and return session token
GET /v1/uui/meResolve current Memory Passport session
GET /v1/uui/me/grantsList active grants
POST /v1/uui/me/grantsCreate or update a grant
DELETE /v1/uui/me/grants/{grant_id}Revoke a grant
GET /v1/uui/organisationsList public connector directory entries
GET /v1/uui/me/connectionsList the user’s connected services
DELETE /v1/uui/me/connections/{connection_id}Disconnect a service
DELETE /v1/uui/meDelete Memory Passport data

​
Related pages