Python: Separate mem0 storage and search scopes

[westey-m]

Motivation & Context

E.g. Allow users to stamp memories with both the agent and user id, but only retrieve for a user

Description & Review Guide

• What are the major changes?
• What is the impact of these changes?
• What do you want reviewers to focus on?

Related Issue

Fixes #

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/mem0/agent_framework_mem0
_context_provider.py	141	9	93%	179, 190, 193–194, 199, 209, 217, 220, 228
TOTAL	44733	4104	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9147	34 💤	0 ❌	0 🔥	2m 6s ⏱️

[Copilot]

Pull request overview

This PR updates the Python Mem0 context provider to explicitly separate storage scoping (how memories are stamped when written) from retrieval scoping (which memories are searched and injected), preventing accidental cross-user memory retrieval when an agent_id is shared across users.

Changes:

• Add explicit retrieval-scope parameters (search_user_id, search_agent_id, search_application_id) and make retrieval opt-in (warn + retrieve nothing if no search_* configured).
• Update samples and package documentation to demonstrate explicit retrieval scoping.
• Expand unit tests to cover non-inheritance of retrieval scope and cross-user isolation behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/samples/02-agents/context_providers/mem0/README.md	Documents the storage vs retrieval scoping model for the Mem0 sample.
python/samples/02-agents/context_providers/mem0/mem0_sessions.py	Updates sample sessions to set explicit retrieval scope via search_*.
python/samples/02-agents/context_providers/mem0/mem0_oss.py	Updates OSS sample provider construction to use explicit retrieval scope.
python/samples/02-agents/context_providers/mem0/mem0_basic.py	Updates basic sample to set search_user_id explicitly.
python/packages/mem0/tests/test_mem0_context_provider.py	Adds/updates tests to ensure retrieval scope is explicit and prevent cross-user leakage.
python/packages/mem0/README.md	Adds user-facing docs describing separate storage vs retrieval scope.
python/packages/mem0/AGENTS.md	Updates package guidance to include explicit retrieval scoping and behavior.
python/packages/mem0/agent_framework_mem0/_context_provider.py	Implements separate retrieval scope, warning-on-missing-retrieval, and new search_* parameters.

Suppressed comments (1)

python/packages/mem0/agent_framework_mem0/_context_provider.py:285

• The OSS-client validation error message is now triggered by either application_id or search_application_id, but the message still only mentions application_id. This makes the exception misleading when a caller sets search_application_id.

        if isinstance(self.mem0_client, AsyncMemory) and (self.application_id or self.search_application_id):
            raise ValueError(
                "application_id is not supported by the OSS AsyncMemory client, which scopes "
                "memories only by user_id/agent_id. Remove application_id or use AsyncMemoryClient."
            )

[github-actions]

Automated Code Review

Reviewers: 2 | Confidence: 93% | Result: All clear

Reviewed: Correctness, Test Coverage

---

Automated review by westey-m's agents