Cross-agent Memory Sharing

This guide covers Memory Passport, the user-controlled cross-agent memory flow in MemoryOS. Use this flow when:

the same person uses multiple AI agents or apps
agents should not automatically share everything
the user must approve, review, and revoke access themselves

For the standard one-app pattern, use tenant-scoped Quickstart instead.

Production flow at a glance

Memory Passport has four moving parts:

Part	Owned by	Purpose
Global agent	Your workspace	Public agent profile plus `agent_sk_...` key
Consent page	MemoryOS	User signs in, chooses categories, approves duration
Permission grant	MemoryOS	Records which agent can access which categories
Universal API call	Your backend/agent	Uses `agent_sk_...` plus `uui_...` after consent

Universal memory API calls require both credentials:

Authorization: ApiKey agent_sk_...
X-MemoryOS-UUI: uui_...

The agent key identifies which app is asking. The UUI token identifies which Memory Passport user is being accessed.

Step 0: Register a global agent

Before you send users to consent, register the AI agent that is requesting access.

Recommended: use the tenant dashboard

Open Tenant Dashboard -> Memory Passport
Click Create Global Agent
Add the agent name, website, logo, and description
Choose default requested categories
Copy the public agent_id
Copy the one-time agent_sk_... secret into your backend secret manager
Use the Consent URL Builder to generate and preview a test link

The same page shows verification status. New agents appear as Pending MemoryOS review until the MemoryOS operator team verifies them. Production rules:

agent_id is public and can be copied into consent links
agent_sk_... is secret and is shown only once
store agent_sk_... server-side, never in browser code
default categories are only a starting selection, not a hard maximum
users can add or remove categories before approval

Optional: create agents from your backend

Use the API when you want to automate setup from an internal admin tool, CI workflow, or customer provisioning flow.

curl -X POST https://api.memoryos.io/v1/agents/global \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey mem_..." \
  -d '{
    "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": ""
  }'

MemoryOS returns two important values:

{
  "data": {
    "id": "aa535a7e-b0d6-44df-8e17-8438f6098836",
    "raw_agent_api_key": "agent_sk_..."
  }
}

id is the public agent_id used in consent URLs
raw_agent_api_key is shown once and must be stored server-side

default_categories_requested are only the default checkboxes shown on consent links that do not pass a categories parameter. They are not a hard maximum. The end user always makes the final choice before a grant is created. The user sees this profile on the consent page:

app / agent name
description
verification status
requested memory categories
website or logo, if configured

Fetch the public profile to preview what the user will see:

curl https://api.memoryos.io/v1/agents/global/your_global_agent_id

Step 1: Explain shared memory in your app

Do not surprise users with a consent screen. Add a clear button such as:

Connect shared memory

Optional: app-owned callback

Use an app-owned callback only when your app must automatically update its own UI after consent.

consent_url = UniversalMemory.consent_url(
    agent_id="your_global_agent_id",
    redirect_uri="https://yourapp.com/integrations/memoryos/callback",
    state="secure_random_state_token",
    categories=["preference", "fact"],
)

If you provide redirect_uri, your route must exist and must verify state server-side. Otherwise users can approve access and land on a 404. Copy-paste callback examples are available in:

examples/production-memoryos-callbacks/

Step 3: Let MemoryOS create the grant

When the user approves access, MemoryOS creates or updates the grant. Your app normally does not call /v1/uui/me/grants directly. The consent page handles:

new user account creation
email OTP login
category selection
duration selection
grant creation
grant notification
revoke/manage link

Grant rules:

access type may be read_only or read_write
grants are category-scoped
users can revoke access any time at https://consent.memoryos.io/manage
revoked grants return empty retrieve results instead of leaking metadata

Step 4: Use universal memory from your agent

Once your agent has a valid agent_sk_... and the user’s uui_... token, it can retrieve only the categories the user approved.

from memoryos.universal import UniversalMemory

with UniversalMemory(
    agent_api_key="agent_sk_...",
    uui_token="uui_...",
) as memory:
    result = memory.get(
        query="How should I tailor the response?",
        limit=5,
    )

    if result.has_context:
        system_prompt = BASE_PROMPT + "\n\n" + result.system_prompt_addition

If the grant is read_write, the agent can also add universal memories:

result = memory.add(
    messages=[
        {
            "role": "user",
            "content": "Please remember that I prefer short, structured explanations and Python examples.",
        }
    ],
    metadata={"source": "learning-agent"},
)

If the grant is read_only, write attempts return:

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

Integration note

The hosted completion page removes the need for every customer to build a callback route. However, universal API calls still require a uui_... token. For production apps, the clean long-term pattern is an app-owned account-linking flow where your backend can securely associate your logged-in user with their Memory Passport identity. Until a server-side token exchange flow is available, use hosted completion for:

demos
pilots
local agents
manual testing
user-facing permission confirmation

Use app-owned callback mode when:

your app needs to update its UI immediately after consent
your backend already has a secure way to associate the app user with the Memory Passport user
you are building a full production cross-agent integration

Supported categories

Current Memory Passport categories are:

preference
fact
goal
procedure
relationship
expertise

REST API examples

Retrieve universal memory:

curl -X POST https://api.memoryos.io/v1/universal/memories/retrieve \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey agent_sk_..." \
  -H "X-MemoryOS-UUI: uui_..." \
  -d '{
    "query": "How should I tailor the response?",
    "limit": 5,
    "format": "bullets"
  }'

Add universal memory:

curl -X POST https://api.memoryos.io/v1/universal/memories/add \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey agent_sk_..." \
  -H "X-MemoryOS-UUI: uui_..." \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please remember that I prefer short, structured explanations and Python examples."
      }
    ],
    "metadata": {
      "source": "learning-agent"
    }
  }'

User management

Users manage active grants at:

https://consent.memoryos.io/manage

The manage page lets users:

see which agents have access
revoke access
review memories
answer pending questions when MemoryOS needs the user to resolve a personal memory conflict
flag or correct memories
delete their Memory Passport data

Privacy guarantees

Memory Passport is designed so that:

one agent cannot see which other agents were granted access
denied or revoked grants return empty results
universal memories are stored separately from tenant-scoped memory
grants are category-scoped and revocable

​Production flow at a glance

​Step 0: Register a global agent

​Recommended: use the tenant dashboard

​Optional: create agents from your backend

​Step 1: Explain shared memory in your app

​Step 2: Send the user to MemoryOS consent

​Optional: app-owned callback

​Step 3: Let MemoryOS create the grant

​Step 4: Use universal memory from your agent

​Integration note

​Supported categories

​REST API examples

​User management

​Privacy guarantees

​Related pages