[BREAKING] Python: Preserve Redis context scope identity

[Jose Alvarez (jpalvarezl)]

Motivation & Context

Redis context retrieval uses application, agent, user, and session identifiers as isolation boundaries. Redis TAG defaults and query formatting do not preserve every opaque identifier exactly, so distinct application identities can be treated as equivalent. This change makes scope matching deterministic and exact while retaining the original identifiers as document metadata.

Description & Review Guide

• What are the major changes? Index versioned, domain-separated scope tokens in dedicated case-sensitive TAG fields; keep raw scope values unindexed; make provider configuration authoritative over document-supplied scope fields; scope search_all() consistently; and add a resumable, bounded migration that backfills tokens before rebuilding an existing index.
• What is the impact of these changes? Scope comparisons now preserve case and punctuation across text and hybrid retrieval. Existing context indexes fail closed until their migration completes. Migration progress is persisted outside the indexed namespace, scans only the exact RedisVL key namespace, pipelines the required scope reads and token writes, and preserves stored hashes and memory content.
• What do you want reviewers to focus on? The token-field schema, the fail-closed migration state machine, authoritative scope assignment on writes, and the live Redis coverage for exact identity, session scoping, hybrid retrieval, and resumable legacy-index migration.

Related Issue

N/A - maintainer-directed correctness change with no competing public issue or pull request.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Implementation, tests, documentation, migration design, and PR description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• 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) — workflows keep the label and title prefix in sync automatically.

[github-code-quality]

Code coverage overview

Languages: Python

Python / code-coverage/python

main 9127b89	fix-redis-context-sc... afffd53	+/-
92%	92%	0%

View coverage of the 1 most impacted file.

File	main 9127b89	fix-redis-context-sc... afffd53	+/-
packages/redis/...ext_provider.py	96%	94%	-2%

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

---

_{Updated October 19, 2026 08:20 UTC}

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): ec2198f0d81f
Model: gpt-5.6-sol

Overview

The PR replaces raw TAG filters with domain-separated scope tokens, makes provider scopes authoritative on writes, and adds strong unit and live Redis coverage for exact identity and migration. Those guards address case, punctuation, and caller-supplied scope spoofing. The rebuild path still has three medium-risk lifecycle defects: incomplete migrations can appear complete, migration work is unbounded, and raw prefix matching can mutate unrelated hashes.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (3 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/redis/agent_framework_redis/_context_provider.py

[Copilot]

Note

Copilot was unable to run its full agentic suite in this review.

Copilot review overview

4 open findings

• _migrate_scope_tokens() currently scans all HASH keys in Redis and then filters in Python. This… · New
• The migration loop performs an HGETALL per key serially, which can be slow for large datasets… · New
• The completion check uses FT.INFO num_docs >= migrated_documents, but num_docs reflects total… · New
• This unconditionally overwrites any caller-supplied scope metadata in data *even when the… · New

What changed in this PR

Introduces deterministic, identity-preserving scoping for RedisContextProvider by indexing versioned scope tokens (instead of raw scope identifiers), including an opt-in migration path for existing indexes and added integration coverage.

Changes:

• Replace indexed scope TAG fields (application_id, agent_id, user_id, thread_id, conversation_id) with versioned token TAG fields derived from those identifiers.
• Add overwrite_index=True coordinated migration flow that rebuilds the index and backfills token fields into preserved hashes.
• Expand test coverage (unit + live Redis integration) and wire integration tests into CI workflows.

File	Description
python/​packages/​redis/​agent_framework_redis/​_context_provider.py	Implements tokenized scope fields, schema changes, migration/backfill logic, and updates filtering/search_all behavior.
python/​packages/​redis/​tests/​test_providers.py	Updates schema expectations to reflect tokenized scope fields.
python/​packages/​redis/​tests/​test_context_provider_sdk.py	Verifies SDK-level records include scope token fields derived from stored scope metadata.
python/​packages/​redis/​tests/​test_context_provider_integration.py	Adds live Redis integration tests for scope isolation and migration behavior.
python/​packages/​redis/​tests/​test_context_provider_edges.py	Adds edge-case coverage for token generation, schema tagging behavior, migration, and query filtering.
python/​packages/​redis/​README.md	Documents new isolation model and the coordinated migration procedure.
python/​packages/​redis/​AGENTS.md	Summarizes tokenized scoping and migration behavior for agents.
.github/​workflows/​python-merge-tests.yml	Runs Redis integration tests including the new context provider integration suite.
.github/​workflows/​python-integration-tests.yml	Runs Redis integration tests including the new context provider integration suite.

🧠 Review effort: Lite

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.