Python: Add Foundry Memory Context Provider

[Copilot]

Motivation and Context

Agents need persistent semantic memory capabilities using Azure AI Foundry Memory Store. Existing context providers (Mem0, Redis) don't integrate with Foundry's memory APIs.

Description

Implements FoundryMemoryProvider as a BaseContextProvider that wraps Azure AI Projects SDK memory operations.

Architecture:

• before_run: Retrieves static memories (user profiles) once per session, then searches contextual memories per turn using search_memories API
• after_run: Fires begin_update_memories with configurable delay (default 300s), chains operations via previous_update_id
• Error handling: Non-critical failures logged, agent continues without memory
• State management: All stateful data stored in session.state[source_id] for proper persistence and multi-provider support
• Client lifecycle: Provider does not close externally-provided project_client (follows Mem0ContextProvider pattern with _should_close_client flag)

Key implementation details:

• Uses ItemParam for message formatting, compatible with Foundry memory extraction pipeline
• Session state namespaced under source_id prevents collisions when multiple providers are used
• Memory updates debounced server-side by update_delay parameter
• Async context manager respects client ownership - does not close externally-provided clients
• DEFAULT_SOURCE_ID = "foundry" provides sensible default while allowing customization
• Uses standard logging.getLogger(__name__) for logging

Usage:

from agent_framework.azure import FoundryMemoryProvider
from azure.ai.projects.aio import AIProjectClient

# Uses default source_id="foundry"
memory_provider = FoundryMemoryProvider(
    project_client=project_client,
    memory_store_name="my_store",
    scope="user_123",
    update_delay=60
)

agent = Agent(
    client=chat_client,
    context_providers=[memory_provider]
)

Files:

• Core: _foundry_memory_provider.py (237 lines)
• Tests: 21 test methods covering init, hooks, edge cases, state management, client lifecycle
• Sample: azure_ai_foundry_memory.py demonstrating memory store creation/cleanup with correct environment variable names

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? No

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Python: Add Foundry Memory Context Provider</issue_title>
<issue_description>We should add a Context Provider based on Foundry Memory. This can be done using the foundry project client sdk: https://learn.microsoft.com/en-us/python/api/overview/azure/ai-projects-readme?view=azure-python-preview (.memory_store operations), a snippet that can be used to get started (incomplete, not validated and uses verbs from the SK version of context providers):

class FoundryMemoryProvider(ContextProvider):
  client: AzureChatClient
  memory_store_id: str
  scope: str
  _previous_update_id: str
  _previous_search_id: str

  def __init__(
    self, client: AzureChatClient, 
    memory_store_id: str, 
    scope: str
  ) -> None:
    super().__init__(client, memory_store_id, scope)

  async def thread_created(self, thread_id: str | None = None) -> None:
    # Retrieve/update user profile memories
    self._static_memories = self.client.memory_stores.search_memories(
      self.memory_store_id,
      self.scope
    )

  async def messages_adding(
    self, thread_id: str | None, new_messages: ChatMessage | Sequence[ChatMessage]
  ) -> None:
    messages_list = ( [new_messages] if isinstance(new_messages, ChatMessage) else list(new_messages) )
    messages: list[dict[str, str]] = [
      {"role": message.role.value, "content": message.text}
      for message in messages_list
      if message.role.value in {"user", "assistant", "system"} and message.text and message.text.strip()
    ]
    self._new_search_messages.extend(messages)
    self._new_update_messages.extend(messages)

    # Update memories with delay (fire and forget)
    update_poller = client.memory_stores.update_memories(
      self.memory_store_id, self.scope, new_update_messages, self.previous_update_id, update_delay="5m")
    self.previous_update_id = update_poller.update_id
    self._new_update_messages = []


  async def model_invoking(
      self, messages: ChatMessage | MutableSequence[ChatMessage]
  ) -> Context:
    # Awkward that thread_id is part of messages_adding, but not model_invoking
    search_response = self.client.memory_stores.search_memories(
      self.memory_store_id, self.scope, self._new_search_messages, self._previous_search_id)
    self._previous_search_id = search_response.search_id
    self._new_search_messages = []

    context_memories = self._static_memories.concat(search_response.memories)
    line_separated_memories = "\n".join(memory.content for memory in context_memories)
    context_prompt = "## Memories\nConsider the following memories when answering user questions:"
    content = TextContent(f"{context_prompt}\n{line_separated_memories}")
    return Context(contents=[content])
```</issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

• Fixes Python: Add Foundry Memory Context Provider #2720

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[eavanvalkenburg]

@copilot couple of comments, please address

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/azure-ai/agent_framework_azure_ai
_foundry_memory_provider.py	88	0	100%
TOTAL	22237	3472	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4285	240 💤	0 ❌	0 🔥	1m 15s ⏱️

[Copilot]

Pull request overview

Adds a new Python context provider that integrates Azure AI Foundry Memory Store into Agent Framework’s context-provider pipeline, along with public exports, tests, and documentation/sample usage.

Changes:

• Introduces FoundryMemoryProvider (BaseContextProvider) backed by azure.ai.projects memory store APIs.
• Exposes FoundryMemoryProvider via agent_framework.azure and agent_framework_azure_ai package exports/stubs.
• Adds unit tests and a runnable sample demonstrating memory store creation, usage, and cleanup.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
python/packages/azure-ai/agent_framework_azure_ai/_foundry_memory_provider.py	Implements Foundry memory search + update hooks and session-state namespacing.
python/packages/azure-ai/tests/test_foundry_memory_provider.py	Adds unit tests covering init, hook behavior, state, and async context manager behavior.
python/packages/core/agent_framework/azure/init.py	Adds lazy export for FoundryMemoryProvider from agent_framework_azure_ai.
python/packages/core/agent_framework/azure/init.pyi	Adds typing export for FoundryMemoryProvider.
python/packages/azure-ai/agent_framework_azure_ai/init.py	Re-exports FoundryMemoryProvider from the azure-ai integration package.
python/packages/azure-ai/README.md	Documents the new provider and links to the sample.
python/samples/02-agents/context_providers/azure_ai_foundry_memory.py	Adds an end-to-end sample showing Foundry memory store setup and agent usage.