{"id":5809,"date":"2026-09-04T06:00:07","date_gmt":"2026-09-04T13:00:07","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/agent-framework\/?p=5809"},"modified":"2026-09-04T06:00:07","modified_gmt":"2026-09-04T13:00:07","slug":"native-memory-for-microsoft-agent-framework-with-azure-cosmos-db","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/native-memory-for-microsoft-agent-framework-with-azure-cosmos-db\/","title":{"rendered":"Native memory for Microsoft Agent Framework with Azure Cosmos DB"},"content":{"rendered":"<p>Agents are more useful when they can remember what matters beyond the current conversation. Today, we&#8217;re announcing a new preview integration that gives <strong>Microsoft Agent Framework<\/strong> agents durable, cross-session memory backed by <strong>Azure Cosmos DB<\/strong>.<\/p>\n<p>The new Python package, <code>agent-framework-azure-cosmos-memory<\/code>, provides <code>CosmosMemoryContextProvider<\/code>. Attach it to an agent once and it can automatically store conversation turns, extract durable memories, and recall relevant facts, summaries, and user profiles in later conversations.<\/p>\n<p>This integration was introduced by the Azure Cosmos DB team in <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/native-agent-memory-for-microsoft-agent-framework-powered-by-azure-cosmos-db\/\"><em>Native Agent Memory for Microsoft Agent Framework, Powered by Azure Cosmos DB<\/em><\/a>. Here, we&#8217;ll focus on what it means for Agent Framework developers and how naturally it fits the framework&#8217;s context-provider model.<\/p>\n<blockquote><p><strong>Preview:<\/strong> <code>agent-framework-azure-cosmos-memory<\/code> is currently available for <strong>Python only<\/strong>. The package and its APIs may change before general availability.<\/p><\/blockquote>\n<h2 id=\"memory-that-participates-in-the-agent-lifecycle\">Memory that participates in the agent lifecycle<\/h2>\n<p>In Agent Framework, a <a href=\"https:\/\/learn.microsoft.com\/agent-framework\/concepts\/agents\/conversations\/context-providers\"><code>ContextProvider<\/code><\/a> runs around every agent invocation. It can contribute information before the model runs and react to the completed run afterwards. That makes context providers a natural extension point for memory: the agent loop stays in Agent Framework, while a provider handles storage, retrieval, and memory processing.<\/p>\n<p><code>CosmosMemoryContextProvider<\/code> uses both sides of that lifecycle:<\/p>\n<ul>\n<li><strong>Before a run<\/strong>, it searches for memories relevant to the incoming message and adds them to the model&#8217;s context.<\/li>\n<li><strong>After a run<\/strong>, it stores the new conversation turns. The Azure Cosmos DB Agent Memory Toolkit then extracts facts, produces summaries, and updates the user&#8217;s profile in the background.<\/li>\n<\/ul>\n<p>The agent doesn&#8217;t need to decide to call a memory tool, and your application doesn&#8217;t need to orchestrate a separate retrieval pipeline. Memory is part of every run.<\/p>\n<h2 id=\"how-it-fits-together\">How it fits together<\/h2>\n<p>Agent Framework owns the agent loop and invokes the provider. The provider adapts that lifecycle to the <a href=\"https:\/\/aka.ms\/AgentMemoryToolkit\">Azure Cosmos DB Agent Memory Toolkit<\/a>, which owns the storage model and the processing pipeline. Azure Cosmos DB for NoSQL stores the turns and derived memories, then supports vector, full-text, and hybrid retrieval from the same database.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2.webp\"><img decoding=\"async\" class=\"aligncenter wp-image-5812 size-full\" src=\"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2.webp\" alt=\"Architecture diagram showing Microsoft Agent Framework using CosmosMemoryContextProvider and Agent Memory Toolkit to retrieve context and store conversation turns, facts, summaries, and profiles in Azure Cosmos DB for NoSQL.\" width=\"1536\" height=\"890\" srcset=\"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2.webp 1536w, https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2-300x174.webp 300w, https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2-1024x593.webp 1024w, https:\/\/devblogs.microsoft.com\/agent-framework\/wp-content\/uploads\/sites\/78\/2026\/08\/MAF-memory-2-768x445.webp 768w\" sizes=\"(max-width: 1536px) 100vw, 1536px\" \/><\/a><\/p>\n<p><em>Architecture diagram courtesy of the Azure Cosmos DB team. See the <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/native-agent-memory-for-microsoft-agent-framework-powered-by-azure-cosmos-db\/\">original announcement<\/a> for a deeper look at the memory pipeline.<\/em><\/p>\n<h2 id=\"add-durable-memory-to-a-python-agent\">Add durable memory to a Python agent<\/h2>\n<p>Install the preview integration alongside the Agent Framework Foundry provider:<\/p>\n<pre><code class=\"language-bash\">pip install --pre agent-framework-azure-cosmos-memory agent-framework-foundry<\/code><\/pre>\n<p>Set <code>COSMOS_ENDPOINT<\/code>, <code>FOUNDRY_ENDPOINT<\/code>, <code>EMBEDDING_MODEL<\/code>, and <code>CHAT_MODEL<\/code> for your Azure resources. Then create the provider and add it to the agent&#8217;s <code>context_providers<\/code> collection. A stable <code>user_id<\/code> lets a new session recall memories learned in an earlier one:<\/p>\n<pre><code class=\"language-python\">import asyncio\r\nimport os\r\n\r\nfrom agent_framework import Agent\r\nfrom agent_framework.foundry import FoundryChatClient\r\nfrom agent_framework_azure_cosmos_memory import CosmosMemoryContextProvider\r\nfrom azure.identity.aio import DefaultAzureCredential\r\n\r\n\r\nasync def main() -&gt; None:\r\n    credential = DefaultAzureCredential()\r\n    memory = CosmosMemoryContextProvider(\r\n        cosmos_endpoint=os.environ[\"COSMOS_ENDPOINT\"],\r\n        cosmos_database=os.getenv(\"COSMOS_DATABASE\", \"ai_memory\"),\r\n        foundry_endpoint=os.environ[\"FOUNDRY_ENDPOINT\"],\r\n        embedding_model=os.environ[\"EMBEDDING_MODEL\"],\r\n        chat_model=os.environ[\"CHAT_MODEL\"],\r\n        credential=credential,\r\n    )\r\n\r\n    agent = Agent(\r\n        client=FoundryChatClient(\r\n            project_endpoint=os.environ[\"FOUNDRY_ENDPOINT\"],\r\n            model=os.environ[\"CHAT_MODEL\"],\r\n            credential=credential,\r\n        ),\r\n        instructions=\"You are a helpful assistant with long-term memory.\",\r\n        context_providers=[memory],\r\n    )\r\n\r\n    async with credential, memory:\r\n        first_session = agent.create_session()\r\n        first_session.state.setdefault(memory.source_id, {})[\"user_id\"] = \"alice\"\r\n        await agent.run(\r\n            \"I love hiking and I'm allergic to peanuts.\",\r\n            session=first_session,\r\n        )\r\n\r\n        # Wait for background extraction so this immediate demo is deterministic.\r\n        await memory.flush()\r\n\r\n        # A new session for the same user can recall memories from the first one.\r\n        second_session = agent.create_session()\r\n        second_session.state.setdefault(memory.source_id, {})[\"user_id\"] = \"alice\"\r\n        reply = await agent.run(\r\n            \"What should I pack for a trail lunch?\",\r\n            session=second_session,\r\n        )\r\n        print(reply.text)\r\n\r\n\r\nasyncio.run(main())<\/code><\/pre>\n<p>The provider&#8217;s async context drains in-flight background extraction before shutdown. In a real application, derive <code>user_id<\/code> from your authenticated user rather than accepting an arbitrary value from a request. If you don&#8217;t supply a stable user ID, the provider falls back to session-scoped memory instead of carrying knowledge across sessions.<\/p>\n<p>The Foundry endpoint powers the toolkit&#8217;s extraction and embedding models as well as the chat agent in this example. <code>DefaultAzureCredential<\/code> supports local development through <code>az login<\/code> and production deployment through managed identity, so you don&#8217;t need to put keys in your code.<\/p>\n<h2 id=\"what-your-agent-gains\">What your agent gains<\/h2>\n<p>This integration gives Agent Framework developers a single composable provider for:<\/p>\n<ul>\n<li><strong>Cross-session recall<\/strong> scoped to a stable user.<\/li>\n<li><strong>Derived memory<\/strong>, including facts, procedural and episodic memories, thread summaries, and user profiles.<\/li>\n<li><strong>Hybrid retrieval<\/strong> using the vector and full-text capabilities built into Azure Cosmos DB.<\/li>\n<li><strong>Background extraction<\/strong>, so memory processing doesn&#8217;t block the agent&#8217;s response path.<\/li>\n<li><strong>Domain-specific extraction<\/strong>, using custom Prompty templates when the default memory rubric isn&#8217;t specific enough for your agent.<\/li>\n<\/ul>\n<p>It also keeps responsibilities clean: Agent Framework runs the agent and composes its context; Azure Cosmos DB stores, processes, and retrieves the long-term memory.<\/p>\n<h2 id=\"get-started\">Get started<\/h2>\n<ul>\n<li>Read the Azure Cosmos DB team&#8217;s <a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/native-agent-memory-for-microsoft-agent-framework-powered-by-azure-cosmos-db\/\">full announcement and walkthrough<\/a>.<\/li>\n<li>Run the <a href=\"https:\/\/github.com\/microsoft\/agent-framework\/blob\/main\/python\/packages\/azure-cosmos-memory\/samples\/basic_usage.py\"><code>basic_usage.py<\/code><\/a> or <a href=\"https:\/\/github.com\/microsoft\/agent-framework\/blob\/main\/python\/packages\/azure-cosmos-memory\/samples\/interactive_chat.py\"><code>interactive_chat.py<\/code><\/a> sample.<\/li>\n<li>Explore the <a href=\"https:\/\/github.com\/microsoft\/agent-framework\/tree\/main\/python\/packages\/azure-cosmos-memory\"><code>agent-framework-azure-cosmos-memory<\/code> package<\/a> and the <a href=\"https:\/\/aka.ms\/AgentMemoryToolkit\">Agent Memory Toolkit<\/a>.<\/li>\n<li>Learn more about <a href=\"https:\/\/learn.microsoft.com\/agent-framework\/concepts\/agents\/conversations\/context-providers\">context providers in Agent Framework<\/a> and browse the available <a href=\"https:\/\/learn.microsoft.com\/agent-framework\/integrations\/by-component\/context-providers\/\">context-provider integrations<\/a>.<\/li>\n<\/ul>\n<p>With <code>CosmosMemoryContextProvider<\/code>, durable memory becomes another composable part of your Agent Framework agent: attach the provider, scope it to the user, and let the framework lifecycle do the rest.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Agents are more useful when they can remember what matters beyond the current conversation. Today, we&#8217;re announcing a new preview integration that gives Microsoft Agent Framework agents durable, cross-session memory backed by Azure Cosmos DB. The new Python package, agent-framework-azure-cosmos-memory, provides CosmosMemoryContextProvider. Attach it to an agent once and it can automatically store conversation turns, [&hellip;]<\/p>\n","protected":false},"author":162052,"featured_media":5811,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143,34],"tags":[],"class_list":["post-5809","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-agent-framework","category-python-2"],"acf":[],"blog_post_summary":"<p>Agents are more useful when they can remember what matters beyond the current conversation. Today, we&#8217;re announcing a new preview integration that gives Microsoft Agent Framework agents durable, cross-session memory backed by Azure Cosmos DB. The new Python package, agent-framework-azure-cosmos-memory, provides CosmosMemoryContextProvider. Attach it to an agent once and it can automatically store conversation turns, [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/posts\/5809","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/users\/162052"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/comments?post=5809"}],"version-history":[{"count":1,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/posts\/5809\/revisions"}],"predecessor-version":[{"id":5813,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/posts\/5809\/revisions\/5813"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/media\/5811"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/media?parent=5809"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/categories?post=5809"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/agent-framework\/wp-json\/wp\/v2\/tags?post=5809"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}