CSharp | The .NET Blog

Where Does Your Agent Remember Things? A Practical Guide to Chat History Storage

Emiliano Montesdeoca — Sat, 25 Apr 2026 00:00:00 +0000

When you build an AI agent, you spend most of your energy on the model, the tools, and the prompts. The question of where the conversation history lives feels like an implementation detail — but it’s actually one of the most important architectural decisions you’ll make.

It determines whether users can branch conversations, undo responses, resume sessions after a restart, and whether your data ever leaves your infrastructure. The Agent Framework team published a deep dive on this and it’s worth understanding the full landscape.

Two fundamental patterns

Service-managed: the AI service stores the conversation state. Your app holds a reference (a thread ID, a response ID) and the service automatically includes relevant history on each request. Simpler to set up. Less control.

Client-managed: your app maintains the full history and sends relevant messages with every request. The service is stateless. You control everything — what gets sent, how it’s compressed, where it lives.

Neither is universally better. The right choice depends on what you’re building.

Service-managed: linear vs forking

Not all service-managed storage is the same. There are two distinct models:

Linear (single-threaded): messages form an ordered sequence. You can append, but you can’t branch. This is the traditional chat model — used by Foundry Prompt Agents and the now-deprecated OpenAI Assistants API. Great for chatbots and support agents. Terrible if you want “try again” or parallel exploration.

Forking-capable: each response has a unique ID, and new requests can reference any previous response as the continuation point. This is what the Responses API (Microsoft Foundry, Azure OpenAI, OpenAI) supports. Users can branch conversations, build “undo” flows, explore multiple answer paths.

If you’re building any kind of agentic workflow where multiple paths might be explored, forking is a capability you want.

Client-managed: you own the complexity

When the service doesn’t store history, your app does everything:

Context window management — you can’t send unlimited history. You need truncation, sliding windows, summarization, or tool-call collapse strategies.
Persistence — in-memory works for demos. Production needs a database, Redis, or blob storage.
Privacy — conversation data never leaves your infrastructure unless you explicitly send it.

The upside on privacy is real. For sensitive applications where you can’t have conversation history sitting on a third-party server, client-managed is the only option.

Agent Framework ships built-in compaction strategies for all the common patterns, so you don’t have to build them from scratch. But you do need to choose and configure the right one.

How Agent Framework abstracts this

The beauty of the framework is that your agent invocation code stays the same regardless of which storage model you’re using. The AgentSession handles the underlying differences.

In C#:

// Works with Chat Completions (client-managed)
// AND with Responses API (service-managed)
// The session handles the details.
AgentSession session = await agent.CreateSessionAsync();
var first = await agent.RunAsync("My name is Alice.", session);
var second = await agent.RunAsync("What is my name?", session);

In Python:

session = agent.create_session()
first = await agent.run("My name is Alice.", session=session)
second = await agent.run("What is my name?", session=session)

When you switch from OpenAI Chat Completions to the Responses API, you change the client configuration — not the agent invocation code.

The Responses API is uniquely flexible

Most providers have a fixed storage model. The Responses API is the exception — it’s configurable via the store parameter:

store=true (default): service stores each response, supports forking via response IDs. Service handles compaction.
store=false: service is stateless, Agent Framework manages history client-side. You control compaction.
Conversations API: linear thread model on top of Responses. Pass a conversation ID instead of a response ID.

Here’s the client-managed mode in practice (C#):

AIAgent agent = new OpenAIClient("<your_api_key>")
 .GetResponseClient("gpt-5.4-mini")
 .AsIChatClientWithStoredOutputDisabled()
 .AsAIAgent(new ChatClientAgentOptions
 {
 ChatOptions = new() { Instructions = "You are a helpful assistant." },
 ChatHistoryProvider = new InMemoryChatHistoryProvider()
 });

And in Python:

agent = Agent(
 client=OpenAIChatClient(),
 name="StatelessAgent",
 instructions="You are a helpful assistant.",
 default_options={"store": False},
 context_providers=[InMemoryHistoryProvider("memory", load_messages=True)],
)

Swap InMemoryHistoryProvider for your DatabaseHistoryProvider when you’re ready for production persistence.

Provider quick reference

Provider	Storage	Model	Compaction
OpenAI / Azure OpenAI Chat Completions	Client	N/A	You
Foundry Agent Service	Service	Linear	Service
Responses API (default)	Service	Forking	Service
Responses API (`store=false`)	Client	N/A	You
Anthropic Claude, Ollama	Client	N/A	You

How to choose

Start with these questions:

Do you need conversation branching or “undo”? → Forking service-managed (Responses API)
Do you need full data sovereignty? → Client-managed, with a database-backed provider
Is this a simple chatbot or support flow? → Service-managed linear is fine
Do you need to migrate between providers later? → Client-managed gives you portability

The most important thing: don’t default to whatever is easiest to start with and forget to revisit it. Changing storage patterns after launch is painful.

Wrapping up

Chat history storage shapes what your agents can actually do — not just in demos but in production, under real user behavior. Agent Framework’s abstractions let you evolve your choice without rewriting your application logic, which is genuinely useful when you’re still figuring out the right model.

Read the full post for the complete decision tree, the Conversations API walkthrough, and the compaction strategy details.

C# 15 Gets Union Types — and They're Exactly What We've Been Asking For

Emiliano Montesdeoca — Sun, 05 Apr 2026 00:00:00 +0000

This is the one I’ve been waiting for. C# 15 introduces the union keyword — proper discriminated unions with compiler-enforced exhaustive pattern matching. If you’ve ever envied F#’s discriminated unions or Rust’s enums, you know exactly why this matters.

Bill Wagner published the deep dive on the .NET blog, and honestly? The design is clean, practical, and very C#. Let me walk you through what’s actually here and why it’s a bigger deal than it might seem at first glance.

The problem unions solve

Before C# 15, returning “one of several possible types” from a method was always a compromise:

object — no constraints, no compiler help, defensive casting everywhere
Marker interfaces — better, but anyone can implement them. The compiler can never consider the set complete
Abstract base classes — same issue, plus the types need a common ancestor

None of these give you what you actually want: a closed set of types where the compiler guarantees you’ve handled every case. That’s what union types do.

The syntax is beautifully simple

public record class Cat(string Name);
public record class Dog(string Name);
public record class Bird(string Name);

public union Pet(Cat, Dog, Bird);

One line. Pet can hold a Cat, a Dog, or a Bird. Implicit conversions are generated automatically:

Pet pet = new Dog("Rex");
Console.WriteLine(pet.Value); // Dog { Name = Rex }

And here’s the magic — the compiler enforces exhaustive matching:

string name = pet switch
{
 Dog d => d.Name,
 Cat c => c.Name,
 Bird b => b.Name,
};

No discard _ needed. The compiler knows this switch covers every possible case. If you later add a fourth type to the union, every switch expression that doesn’t handle it produces a warning. Missing cases caught at build time, not at runtime.

Where this gets practical

The Pet example is cute, but here’s where unions actually shine in real code.

API responses that return different shapes

public union ApiResult<T>(T, ApiError, ValidationFailure);

Now every consumer is forced to handle success, error, and validation failure. No more “I forgot to check the error case” bugs.

Single value or collection

The OneOrMore<T> pattern shows how unions can have a body with helper methods:

public union OneOrMore<T>(T, IEnumerable<T>)
{
 public IEnumerable<T> AsEnumerable() => Value switch
 {
 T single => [single],
 IEnumerable<T> multiple => multiple,
 null => []
 };
}

Callers pass whichever form is convenient:

OneOrMore<string> tags = "dotnet";
OneOrMore<string> moreTags = new[] { "csharp", "unions", "preview" };

foreach (var tag in tags.AsEnumerable())
 Console.Write($"[{tag}] ");
// [dotnet]

Composing unrelated types

This is the killer feature over traditional hierarchies. You can union types that have nothing in common — string and Exception, int and IEnumerable<T>. No common ancestor needed.

Custom unions for existing libraries

Here’s a smart design choice: any class or struct with a [Union] attribute is recognized as a union type, as long as it follows the basic pattern (public constructors for case types and a Value property). Libraries like OneOf that already provide union-like types can opt into compiler support without rewriting their internals.

For performance-sensitive scenarios with value types, libraries can implement a non-boxing access pattern with HasValue and TryGetValue methods.

The bigger picture

Union types are part of a broader exhaustiveness story coming to C#:

Union types — exhaustive matching over a closed set of types (available now in preview)
Closed hierarchies — closed modifier prevents derived classes outside the defining assembly (proposed)
Closed enums — prevents creation of values other than declared members (proposed)

Together, these three features will give C# one of the most comprehensive type-safe pattern matching systems in any mainstream language.

Try it today

Union types are available in .NET 11 Preview 2:

Install the .NET 11 Preview SDK
Target net11.0 in your project
Set <LangVersion>preview</LangVersion>

One caveat: in Preview 2, you’ll need to declare UnionAttribute and IUnion in your project since they’re not in the runtime yet. Grab RuntimePolyfill.cs from the docs repo, or add this:

namespace System.Runtime.CompilerServices
{
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct,
 AllowMultiple = false)]
 public sealed class UnionAttribute : Attribute;

 public interface IUnion
 {
 object? Value { get; }
 }
}

Wrapping up

Union types are one of those features that make you wonder how we got by without them. Compiler-enforced exhaustive matching, clean syntax, generic support, and integration with existing pattern matching — it’s everything we’ve been asking for, done the C# way.

Try them in .NET 11 Preview 2, break things, and share your feedback on GitHub. This is preview, and the C# team is actively listening. Your edge cases and design feedback will shape the final release.

For the full language reference, check out the union types docs and the feature specification.