Python: Fix Cosmos memory retrieval with Toolkit 0.3

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

agent-framework-azure-cosmos-memory supports Agent Memory Toolkit 0.3.0b2, but its generic retrieval call silently omits selected episodic memories and bypasses the Toolkit's task-aware procedural projection. This prevents configured episode and procedure context from reaching agent runs.

The provider must support the newer retrieval contract without dropping users on the existing 0.2.0b3 compatibility floor.

Description & Review Guide

• What are the major changes? Detect the Toolkit retrieval capabilities, keep facts and selected episodes in one ranked search with explicit episode opt-in, compile selected procedures separately for the current task, and isolate generic, procedural, and user-summary retrieval failures. Preserve older generic retrieval and write fallbacks, cap the prerelease dependency below 0.4, and add focused contract coverage and documentation.
• What is the impact of these changes? Toolkit 0.3.0b2 installations now retrieve configured episodic and procedural memory correctly, while supported 0.2.x and 0.3.0b1 clients retain their existing call shapes.
• What do you want reviewers to focus on? The capability boundary between the legacy generic path and the 0.3.0b2 task-aware path, including failure isolation and dependency bounds.

Related Issue

Fixes #7923

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]

MAF Automated Review — Iteration 1

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

Overview

The review found 3 verified inline finding(s).

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

Affected areas: python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py

[Copilot]

🟡 Changes recommended

Procedural context must be routed through instruction extensions rather than included in the user-role memory message.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates Cosmos memory retrieval for Agent Memory Toolkit 0.3.0b2 while preserving older-client compatibility.

Changes:

• Adds capability-aware episodic and procedural retrieval.
• Preserves legacy fallbacks and isolates retrieval failures.
• Updates dependencies, tests, lockfile, and documentation.

File summaries

File	Summary
python/uv.lock	Locks Toolkit 0.3.0b2.
python/packages/azure-cosmos-memory/tests/test_emulator.py	Supports both write API names.
python/packages/azure-cosmos-memory/tests/test_context_provider.py	Adds retrieval contract and failure-isolation tests.
python/packages/azure-cosmos-memory/README.md	Documents updated retrieval behavior.
python/packages/azure-cosmos-memory/pyproject.toml	Bounds the Toolkit dependency below 0.4.
python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py	Implements compatible retrieval paths; procedural context requires instruction-priority handling.

Review details

• Files reviewed: 5/6 changed files
• Comments generated: 1
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

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