Threads & Memory

Before you start: this is a billed Azure service

• Cost and account. An Azure subscription, a Foundry project, and a model deployment. The BYO-storage path provisions an Azure Cosmos DB for NoSQL account, which bills while it exists. Clean up at the end.
• Authored against the docs, not executed live. Code is written against the official docs and syntax-checked, not run during authoring. Threads/memory APIs move — pin your SDK version and verify.
• Two languages. Python-primary with .NET noted.

About this series

This is Part 5 of the twelve-part Microsoft Foundry series. Your agent can reason, ground (Lab 3), and use tools (Lab 4) — but its memory is only as long as a single thread. This lab gives it durable context: threads for a conversation, managed memory across conversations, and the option to keep all of it in your own store.

What you'll build

You'll give the Acme Orders assistant a memory:

1. Threads: the managed short-term conversation (you met these in Lab 2) — revisited as the unit of continuity.
2. Managed memory: persistent context the agent carries across conversations, so a returning customer isn't a stranger.
3. Bring-your-own storage: point thread storage at your own Azure Cosmos DB so conversation data lives in your resources.

Why this matters (the 5-minute business case)

Read this before handing the lab to your team.

An agent that forgets is a worse experience than the form it replaced. If a returning customer re-explains who they are every time, the agent feels broken — worse than a site that at least remembered their login. Memory is what turns a stateless Q&A bot into something that feels like it knows you.

Three reasons this is a leadership-level concern:

1. Personalization is the difference between useful and generic. An agent that recalls a customer's past orders and preferences answers in one turn instead of an interrogation. That continuity is most of the perceived quality of an assistant.
2. Managed memory means you don't run a memory system. Doing it yourself is a database, an extraction pipeline, embeddings for recall, and privacy controls over all of it. Foundry's managed memory and threads handle the persistence and recall; you decide what's worth remembering.
3. BYO storage is a data-control lever. Pointing thread storage at your own Cosmos DB keeps conversation history in your resources, under your residency, retention, and access policies — important for regulated data and a clean answer to "where does our customer data live?"

The honest caveats:

• Memory is data about people — govern it. Persistent context means storing facts about users. Decide what's appropriate to keep, scope per user, and have a deletion story. "Remember everything" is a liability, not a feature.
• It's not free. Persistence (and BYO Cosmos DB) is a running resource with cost; memory operations add latency. Use them where they earn their keep.
• APIs are moving. Threads/memory and the BYO-storage setup shift across versions. Pin and verify.

A framing for a non-technical stakeholder: "This gives our agent memory — within a conversation and across them — as a managed service, with the option to keep all conversation data in our own database. Returning customers don't start from scratch, and we control where their data lives."

Concepts you'll use (2-minute primer)

• Thread — the managed conversation: messages + the run history for one interaction, referenced by thread.id. Short-term continuity.
• Managed memory — persistent context the agent can carry across threads/conversations, so it remembers a user over time.
• BYO thread storage — the Standard Agent Setup option to store all thread messages and history in your own Azure Cosmos DB for NoSQL account instead of Microsoft-managed storage.
• Scope — keep memory per user so each person's context is theirs and isolated.

One sentence: threads remember a conversation, managed memory remembers the person, and BYO storage keeps both in your own database.

Prerequisites

Step 1 — Threads: short-term continuity (recap)

A thread holds one conversation. Create it, add turns, and the service keeps the history:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

thread = project.agents.threads.create()
project.agents.messages.create(
    thread_id=thread.id, role="user",
    content="Hi, I'm Dana. I always want expedited shipping on my orders.",
)
project.agents.runs.create_and_process(
    thread_id=thread.id, agent_name="acme-orders-assistant"
)

The fact Dana prefers expedited shipping lives in this thread. Send more turns against the same thread.id and they stay in context — until the conversation ends. Carrying it beyond this thread is what memory is for.

Step 2 — Managed memory: remember across conversations

Enable the agent's managed memory so durable facts persist across threads, scoped to the user. Conceptually: as a conversation completes, the meaningful, durable facts (the customer's name, a standing preference) are retained and recalled in future conversations for that user.

# Memory is configured on the agent / project (portal or SDK). Once on, the
# agent retains durable, per-user facts across threads and recalls them.
# The exact memory configuration surface varies by SDK version — set it in the
# portal or per the docs for your pinned version, then verify recall:
thread2 = project.agents.threads.create()  # a NEW conversation, same user
project.agents.messages.create(
    thread_id=thread2.id, role="user",
    content="Place my usual — what shipping will you use?",
)
project.agents.runs.create_and_process(
    thread_id=thread2.id, agent_name="acme-orders-assistant"
)
# A memory-enabled agent should answer "expedited" without being re-told.

Recalling a preference the user never repeated — in a brand-new conversation — is the whole point. Configure what is remembered deliberately; this is data about people.

The managed-memory configuration API is evolving and partly portal-driven. Set it where the docs for your version indicate, and treat the code above as the behavior to verify, not a fixed API.

Step 3 — Bring your own thread storage (Cosmos DB)

For data control, use the Standard Agent Setup with bring-your-own thread storage: all thread messages and conversation history are stored in your Azure Cosmos DB for NoSQL account.

1. Create (or choose) an Azure Cosmos DB for NoSQL account in your subscription.
2. In the project's Standard Agent Setup, select BYO thread storage and point it at that Cosmos DB account (grant the project access).
3. From then on, threads and history persist to your database — under your residency, retention, and access controls.

This is the difference between "our conversation data lives in our governed database" and "it lives somewhere managed we don't control" — often the deciding factor for regulated workloads.

.NET note: threads/runs use the same Azure.AI.Agents surface in C#; BYO storage is a project-setup choice, identical regardless of SDK language.

Cost & cleanup

• Managed memory persists data about users — delete test users' memory; it's privacy hygiene as much as cleanup.
• If you created a Cosmos DB account for the BYO path, delete it (or the resource group) — it bills while it exists.
• Delete the test agent/threads if they were only for this lab.
• Confirm in Cost Management that nothing is still accruing.

If a lab created it and you're done, delete it today.

Verified against

• Microsoft Foundry threads/memory and Standard Agent Setup BYO thread storage (Azure Cosmos DB for NoSQL) docs, and the `azure-ai-projects` SDK, June 2026.
• The managed-memory configuration surface and thread APIs vary by SDK version and are partly portal-driven; code is syntax-checked against the docs but not executed during authoring. Pin your version.

What's next

Your agent now remembers — within and across conversations, in your own store if you choose. Next:

• Lab 6 — Evaluations: measure agent quality with managed evaluators, gate ship/no-ship, and debug failures from the linked trace.
• Memory makes the agent feel better; evaluation is how you prove it's actually better.