Entity-Scoped Memory

Mem0’s Platform API lets you separate memories for different users, agents, and apps. By tagging each write and query with the right identifiers, you can prevent data from mixing between them, maintain clear audit trails, and control data retention.

Entity IDs vs. graph entities. This page covers the user_id / agent_id / app_id / run_id identifiers used to scope memories. These are different from the graph entities (the people, places, and concepts surfaced in Graph Memory).

Want the long-form tutorial? The Partition Memories by Entity cookbook walks through multi-agent storage, debugging, and cleanup step by step.

You’ll use this when…

You run assistants for multiple customers who each need private memory spaces
Different agents (like a planner and a critic) need separate context for the same user
Sessions should expire on their own schedule, making debugging and data removal more precise

Configure access

from mem0 import MemoryClient

client = MemoryClient(api_key="m0-...")

Call client.project.get() to verify your connection. It should return your project details including org_id and project_id. If you get a 401 error, generate a new API key in the Mem0 dashboard.

Feature anatomy

Dimension	Field	When to use it	Example value
User	`user_id`	Persistent persona or account	`"customer_6412"`
Agent	`agent_id`	Distinct agent persona or tool	`"meal_planner"`
Application	`app_id`	White-label app or product surface	`"ios_retail_demo"`
Run	`run_id`	Short-lived flow, ticket, or session thread	`"ticket-9241"`

Writes (client.add) accept any combination of these fields. app_id and run_id are stored on every memory the call produces. user_id and agent_id behave differently on the default extraction path: each extracted fact is attributed to whoever stated it, so a record carries user_id or agent_id, not both. Absent fields default to null.
Reads (client.search, client.get_all, exports) accept the same identifiers inside the filters JSON object. Deletes (client.delete_all) scope via query parameters instead; the SDK builds these for you when you pass user_id=..., run_id=..., and so on.
Unmentioned entities are not constrained: Passing only {"user_id": "alice"} matches on user_id alone. It does not require agent_id, app_id, or run_id to be null, so records that also have those fields set are still returned.

Common Pitfall: If you create a memory with user_id="alice" but the other fields default to null, then search with {"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]} will return nothing because you’re looking for a memory where agent_id="bot", not null.

Choose the right identifier

Identifier	Purpose	Example Use Cases
`user_id`	Store preferences, profile details, and historical actions that follow a person everywhere	Dietary restrictions, seat preferences, meeting habits
`agent_id`	Keep an agent’s personality, operating modes, or brand voice in one place	Travel agent vs concierge vs customer support personas
`app_id`	Tag every write from a partner app or deployment for tenant separation	White-label deployments, partner integrations
`run_id`	Isolate temporary flows that should reset or expire independently	Support tickets, chat sessions, experiments

For more detailed examples, see the Partition Memories by Entity cookbook.

Configure it

The example below adds memories with entity tags:

messages = [
    {"role": "user", "content": "I teach ninth-grade algebra."},
    {"role": "assistant", "content": "I'll tailor study plans to algebra topics."}
]

client.add(
    messages,
    user_id="teacher_872",
    agent_id="study_planner",
    app_id="district_dashboard",
    run_id="prep-period-2025-09-02"
)

The response will include one or more memory IDs. Check the dashboard → Memories to confirm the entry appears under the correct user, agent, app, and run.

Passing both user_id and agent_id to client.add does not produce records with both fields set. On the default extraction path, each extracted fact is attributed to the speaker who stated it: facts from user messages are stored with user_id set and agent_id null, facts from assistant messages with agent_id set and user_id null. app_id and run_id are carried on every record either way.As a result, {"AND": [{"user_id": ...}, {"agent_id": ...}]} returns nothing for memories created this way. Use OR to match either scope. Records with both fields populated only come from Direct Import (infer=False), which writes your text verbatim without attribution splitting.

The HTTP equivalent uses POST /v3/memories/add/ with the same identifiers in the JSON body. See the Add Memories API reference for REST details.

See it in action

1. Store scoped memories

traveler_messages = [
    {"role": "user", "content": "I prefer boutique hotels and avoid shellfish."},
    {"role": "assistant", "content": "Logged your travel preferences for future itineraries."}
]

client.add(
    traveler_messages,
    user_id="customer_6412",
    agent_id="travel_planner",
    app_id="concierge_portal",
    run_id="itinerary-2025-apr",
    metadata={"category": "preferences"}
)

2. Retrieve by user scope

user_scope = {
    "AND": [
        {"user_id": "customer_6412"},
        {"app_id": "concierge_portal"},
        {"run_id": "itinerary-2025-apr"}
    ]
}

user_results = client.search("Any dietary flags?", filters=user_scope)
print(user_results)

3. Retrieve by agent scope

agent_scope = {
    "AND": [
        {"agent_id": "travel_planner"},
        {"app_id": "concierge_portal"}
    ]
}

agent_results = client.search("Any dietary flags?", filters=agent_scope)
print(agent_results)

A search that ANDs user_id and agent_id only matches records that have both fields set, which the default extraction path never produces. Use OR when you want either scope to match on its own.

Want to experiment with AND/OR logic, nested operators, or wildcards? The Memory Filters v2 guide walks through every filter pattern with working examples.

4. Audit everything for an app

app_scope = {
    "AND": [
        {"app_id": "concierge_portal"},
        {"OR": [
            {"user_id": "*"},
            {"agent_id": "*"}
        ]}
    ]
}

page = client.get_all(filters=app_scope, page=1, page_size=20)

Wildcards ("*") include only non-null values. Use them when you want “any agent” or “any user” without limiting results to null-only records.

5. Clean up a session

client.delete_all(
    user_id="customer_6412",
    run_id="itinerary-2025-apr"
)

A successful delete returns {"message": "Memories deleted successfully!"}. Run the previous get_all call again to confirm the session memories were removed.

Verify the feature is working

Run client.search with your filters and confirm only expected memories appear. Mismatched identifiers usually mean a typo in your scoping.
Check the Mem0 dashboard filter pills. User, agent, app, and run should all show populated values for your memory entry.
Call client.delete_all with a unique run_id and confirm other sessions remain intact (the count in get_all should only drop for that run).

Best practices

Use consistent identifier formats (like team-alpha or app-ios-retail) so you can query or delete entire groups later
When debugging, print your filters before each call to verify wildcards ("*"), lists, and run IDs are spelled correctly
Combine entity filters with metadata filters (categories, created_at) for precise exports or audits
Use run_id for temporary sessions like support tickets or experiments, then schedule cleanup jobs to delete them

For a complete walkthrough, see the Partition Memories by Entity cookbook.

Getting Started

Core Concepts

Features

Support

Migration

Entity-Scoped Memory

Configure access

Feature anatomy

Choose the right identifier

Configure it

See it in action

Verify the feature is working

Best practices

Master Memory Filters

Partition Memories in Practice

​Configure access

​Feature anatomy

​Choose the right identifier

​Configure it

​See it in action

​Verify the feature is working

​Best practices

Master Memory Filters

Partition Memories in Practice

Configure access

Feature anatomy

Choose the right identifier

Configure it

See it in action

Verify the feature is working

Best practices