Python: Cosmos memory provider misses Toolkit 0.3 episodic and procedural retrieval APIs

[coding-totoro]

What happened

agent-framework-azure-cosmos-memory allows azure-cosmos-agent-memory>=0.2.0b3 with no upper bound. Its CosmosMemoryContextProvider also accepts fact, procedural, and episodic memory types, but before_run() sends all selected types through this call:

await self.memory_client.search_cosmos(
    search_terms=query_text,
    user_id=user_id,
    top_k=self.top_k,
    memory_types=[str(t) for t in self.memory_types],
    min_confidence=self.min_confidence,
)

That no longer implements the public retrieval contract in Agent Memory Toolkit 0.3.0b2:

• search_cosmos() removes episodic from memory_types unless include_episodes=True, so episodes configured on the MAF provider are silently omitted.
• Procedural memory is now an atomic procedure library. The Toolkit's supported projection is build_procedural_context(user_id, task=...), which selects and compiles active, applicable procedures. The MAF provider never calls it and instead formats generic search results.

Why this matters

A fresh installation can legally resolve Toolkit 0.3.0b2, appear healthy, and still miss configured episodes. Procedural context also bypasses the Toolkit's active/in-scope compilation path.

This is the retrieval counterpart to #7633: the provider's open-ended Toolkit dependency moved past another beta API boundary.

Verified versions

• agent-framework-core==1.15.0
• agent-framework-azure-cosmos-memory==1.0.0a260813
• azure-cosmos-agent-memory==0.3.0b2

The provider code is unchanged on current main as of 2026-08-27.

Expected behavior

The provider and its declared dependency range should agree. For Toolkit 0.3.0b2, the provider should:

1. use include_episodes=True when episodic memory is selected, preserving the single shared fact/episode ranking budget;
2. exclude procedural records from generic search; and
3. obtain procedural context through build_procedural_context(user_id, task=query_text).

Alternatively, constrain the Toolkit upper bound until that provider support ships.

Public references

• Toolkit 0.3.0b2 release notes: https://github.com/AzureCosmosDB/AgentMemoryToolkit/blob/main/CHANGELOG.md#030b2-2026-08-17
• Episodic retrieval contract: Episodic memory: boundary-based segmentation, facts/episode retrieval separation, and v2 extraction default AzureCosmosDB/AgentMemoryToolkit#37
• Atomic procedural contract: Atomic procedural memory + durable episodic extraction (dedup simplification, API renames, hardening) AzureCosmosDB/AgentMemoryToolkit#38

[linhongyu510]

I reproduced this on current main and prepared a focused implementation for review of the direction before opening a PR:

main...linhongyu510:fix/7923-cosmos-memory-retrieval

The patch:

• keeps facts and optional episodes in one ranked search_cosmos() call, setting include_episodes from the provider configuration;
• excludes procedural records from generic search and obtains task-aware instructions through build_procedural_context();
• isolates fact/episode, procedural, and user-summary retrieval failures; and
• raises the Toolkit floor to 0.3.0b2, removing the obsolete add_cosmos fallback.

Verification:

• the four new contract tests fail on main and pass with the patch;
• Cosmos memory unit suite: 46 passed, 12 integration tests deselected, 100% package coverage;
• Pyright, MyPy, Ruff, formatting, and git diff --check pass;
• uv sync --frozen consumes the updated lock successfully.

I did not run the live Azure integration tests. Could a maintainer confirm that adapting the provider to the 0.3 APIs is preferred over temporarily constraining the dependency upper bound?

[linhongyu510]

I reproduced this against Toolkit 0.3.0b2 and have a local contract-test patch covering:

• episodic retrieval with include_episodes=True;
• procedural retrieval through build_procedural_context(user_id, task=...);
• isolation between procedural, fact/episode, and user-summary failures; and
• the emulator write path using upsert_memory().

Before opening a PR, could a maintainer confirm the desired compatibility boundary?

1. Preserve the current >=0.2.0b3 range by capability-detecting the Toolkit 0.3 procedural API and retaining the 0.2 generic-search / add_cosmos fallback; or
2. Raise the dependency floor to >=0.3.0b2 and implement the 0.3 retrieval/write contracts directly.

Given the compatibility approach accepted in #7633/#7635, I would prefer option 1 unless the package is intentionally moving its minimum Toolkit version. I will hold the PR until that ownership decision is clear.

The current 0.3-only local prototype passes the package's full poe check, including 46 tests and all configured type/lint checks.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

Repro: python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py::CosmosMemoryContextProvider.before_run lines 365-371 mishandles Toolkit 0.3.0b2 when memory_types includes episodic or procedural: episodic is sent without include_episodes=True, while procedural is sent to generic search_cosmos(). Minimal repro: supply an AsyncMock client, invoke before_run() with episodic or procedural configuration and a user message, then assert the Toolkit 0.3 call shapes from tests/test_issue_7923.py.

• Failing test: python/packages/azure-cosmos-memory/tests/test_issue_7923.py
• Files examined: python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py, python/packages/azure-cosmos-memory/tests/test_context_provider.py, python/packages/azure-cosmos-memory/pyproject.toml, python/uv.lock
• Tests run: tests/test_context_provider.py::TestBeforeRun::test_retrieves_and_injects_memories, tests/test_issue_7923.py::test_episodic_retrieval_enables_toolkit_episodes, tests/test_issue_7923.py::test_procedural_retrieval_uses_task_aware_projection
• Reported version: 1.0.0a260813
• Current version: 1.0.0a260813