Python: Add agent-framework-azure-cosmos-memory context provider

[TheovanKraay]

Motivation & Context

Right now there's no first-party way to give agents long-term, per-user memory backed by Azure Cosmos DB. This PR adds an optional package, agent-framework-azure-cosmos-memory, that plugs Cosmos-backed memory into the standard ContextProvider extension point. On each run it pulls the user's relevant past memories and running summary into the agent's context, then saves new memories after the run. So you get the "agent that remembers the user across sessions" scenario without coupling core to Cosmos.

It builds on the azure-cosmos-agent-memory toolkit for storage, embeddings, and reconciliation, and installs as a standalone, opt-in package.

Heads up: this is a draft for you to review the approach and packaging before I polish it further. The emulator-based integration tests depend on an upstream toolkit change, so they're not turned on in CI yet.

Description & Review Guide

• What are the major changes?

  • New package python/packages/azure-cosmos-memory/ with CosmosMemoryContextProvider, implementing the framework's ContextProvider contract.
  • before_run retrieves per-user memories (semantic search) plus a user summary, injecting memories as context messages and the summary as instructions. Search and summary failures are handled separately so one doesn't block the other, and it warns once if there's no user_id.
  • after_run persists new memories from the turn.
  • README, AGENTS.md, two runnable samples (basic_usage.py, interactive_chat.py), 32 unit tests, and an integration test scaffold.
  • The package is excluded from the shared uv workspace (see below for why).

• What is the impact of these changes?

  • Additive only. No changes to existing packages or public APIs.
  • The package is excluded from the uv workspace in python/pyproject.toml via [tool.uv.workspace] exclude. That's needed because its dependency azure-cosmos-agent-memory requires Python >=3.11 and a prompty prerelease (>=2.0.0a9), both of which are unsatisfiable against the monorepo's >=3.10 floor and if-necessary-or-explicit prerelease policy. Excluding it keeps root uv sync resolvable and leaves the committed uv.lock untouched, while the package is built and tested standalone.
  • The trade-off: it won't be built or tested by the monorepo CI matrix. If you'd rather have it as a full workspace member, that would mean raising the workspace floor to 3.11 and enabling the prompty prerelease. Happy to go whichever way you prefer.

• What do you want reviewers to focus on?

  • The exclude decision in python/pyproject.toml, and whether you want this standalone or as a workspace member.
  • The ContextProvider integration semantics (how memories vs. summary are injected, and the independent failure handling).

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.

[Copilot]

Pull request overview

Adds a new Python integration package, agent-framework-azure-cosmos-memory, introducing a CosmosMemoryContextProvider that persists and recalls long-term memories via Azure Cosmos DB using the azure-cosmos-agent-memory toolkit (including user-summary injection and retrieval-time context augmentation).

Changes:

• Introduces CosmosMemoryContextProvider (async context manager + before_run/after_run hooks) plus package exports.
• Adds documentation and samples demonstrating basic usage and an interactive Foundry-backed chat experience.
• Adds unit tests (mocked client) and live-Azure integration tests (pytest markers).

Reviewed changes

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

Show a summary per file

File	Description
python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/_context_provider.py	Implements the Cosmos-backed memory context provider (retrieval + storage + user-summary injection + flush).
python/packages/azure-cosmos-memory/agent_framework_azure_cosmos_memory/init.py	Exports CosmosMemoryContextProvider and package version.
python/packages/azure-cosmos-memory/pyproject.toml	Defines the new package, dependencies, and pytest/tooling configuration (Python >=3.11).
python/packages/azure-cosmos-memory/README.md	End-user documentation, configuration guidance, and usage examples.
python/packages/azure-cosmos-memory/AGENTS.md	Package-level developer guidance and key behaviors (user_id/thread_id, flush).
python/packages/azure-cosmos-memory/LICENSE	Package license.
python/packages/azure-cosmos-memory/samples/basic_usage.py	Minimal “raw hooks” sample calling before_run()/after_run() directly.
python/packages/azure-cosmos-memory/samples/interactive_chat.py	Interactive CLI sample demonstrating an agent wired with Foundry + Cosmos memory provider.
python/packages/azure-cosmos-memory/tests/test_context_provider.py	Unit tests for provider behavior with a mocked memory client (incl. context manager + flush).
python/packages/azure-cosmos-memory/tests/test_integration.py	Live-Azure integration tests gated by env vars and markers.
python/packages/azure-cosmos-memory/tests/conftest.py	Pytest marker registration for the package’s tests.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	42829	5099	88%

report-only-changed-files is enabled. No files were changed during this commit :)

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
8445	37 💤	0 ❌	0 🔥	2m 11s ⏱️