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.

​
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

Create a global agent once per app or AI agent that will request Memory Passport access. The tenant creates this agent from their backend or tenant dashboard. End users do not create global agents; they only approve or deny access on the consent page. 
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": ""
}
default_categories_requested sets the default checkboxes when a consent URL does not pass categories. It does not limit what the user can approve. A consent link can preselect a different subset with ?categories=preference,goal, and the final grant stores only the categories the user approves. 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 the agent_sk_... value used for universal memory calls and should be treated like a backend secret.

​
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_status": "no_grant",
  "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"]
}

​
Consent and manage endpoints

Human users interact through the consent app: 
https://consent.memoryos.io/consent
https://consent.memoryos.io/manage
Backend endpoints include:
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
DELETE /v1/uui/meDelete Memory Passport data

​
Related pages