Skip to content

Commit 5ee1888

Browse files
westey-mwestey-m
authored
Merge pull request #596 from MicrosoftDocs/main
Merge main to live
2 parents 82432bd + fde574c commit 5ee1888

3 files changed

Lines changed: 407 additions & 0 deletions

File tree

‎semantic-kernel/Frameworks/agent/TOC.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@
1212
href: agent-templates.md
1313
- name: Streaming Agent Responses
1414
href: agent-streaming.md
15+
- name: Agent Memory
16+
href: agent-memory.md
17+
- name: Agent Text Search (RAG)
18+
href: agent-rag.md
1519
- name: Supported Agent Types
1620
href: agent-types/TOC.yml
1721
- name: Agent Orchestration

‎semantic-kernel/Frameworks/agent/agent-memory.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: Adding memory to Semantic Kernel Agents
3+
description: How to add memory to Semantic Kernel Agents
4+
zone_pivot_groups: programming-languages
5+
author: westey-m
6+
ms.topic: conceptual
7+
ms.author: westey
8+
ms.date: 05/21/2025
9+
ms.service: semantic-kernel
10+
---
11+
12+
# Using memory with Agents
13+
14+
::: zone pivot="programming-language-csharp"
15+
16+
> [!WARNING]
17+
> The Semantic Kernel Agent Memory functionality is experimental, is subject to change and will only be finalized based on feedback and evaluation.
18+
19+
It's often important for an agent to remember important information.
20+
This information may be retained for the duration of a conversation or longer term to span multiple conversations.
21+
The information may be learned from interacting with a user and may be specific to that user.
22+
23+
We call this information memories.
24+
25+
To capture and retain memories, we support components that can be used with an `AgentThread` to extract memories from any messages that are added to the thread, and provide those memories to the agent as needed.
26+
27+
## Using Mem0 for Agent memory
28+
29+
[Mem0](https://mem0.ai) is a self-improving memory layer for LLM applications, enabling personalized AI experiences.
30+
31+
The `Microsoft.SemanticKernel.Memory.Mem0Provider` integrates with the Mem0 service allowing agents to remember user preferences and context across multiple threads, enabling a seamless user experience.
32+
33+
Each message added to the thread is sent to the Mem0 service to extract memories.
34+
For each agent invocation, Mem0 is queried for memories matching the provided user request, and any memories are added to the agent context for that invocation.
35+
36+
The Mem0 memory provider can be configured with a user id to allow storing memories about the user, long term, across multiple threads.
37+
It can also be configured with a thread id or to use the thread id of the agent thread, to allow for short term memories that are only attached to a single thread.
38+
39+
Here is an example of how to use this component.
40+
41+
```csharp
42+
// Create an HttpClient for the Mem0 service.
43+
using var httpClient = new HttpClient()
44+
{
45+
BaseAddress = new Uri("https://api.mem0.ai")
46+
};
47+
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", "<Your_Mem0_API_Key>");
48+
49+
// Create a Mem0 provider for the current user.
50+
var mem0Provider = new Mem0Provider(httpClient, options: new()
51+
{
52+
UserId = "U1"
53+
});
54+
55+
// Clear any previous memories (optional).
56+
await mem0Provider.ClearStoredMemoriesAsync();
57+
58+
// Add the mem0 provider to the agent thread.
59+
ChatHistoryAgentThread agentThread = new();
60+
agentThread.AIContextProviders.Add(mem0Provider);
61+
62+
// Use the agent with mem0 memory.
63+
ChatMessageContent response = await agent.InvokeAsync("Please retrieve my company report", agentThread).FirstAsync();
64+
Console.WriteLine(response.Content);
65+
```
66+
67+
### Mem0Provider options
68+
69+
The `Mem0Provider` can be configured with various options to customize its behavior.
70+
Options are provided using the `Mem0ProviderOptions` class to the `Mem0Provider` constructor.
71+
72+
#### Scoping Options
73+
74+
Mem0 provides the ability to scope memories by Application, Agent, Thread and User.
75+
76+
Options are available to provide ids for these scopes, so that the memories can be stored in mem0 under these ids.
77+
See the `ApplicationId`, `AgentId`, `ThreadId` and `UserId` properties on `Mem0ProviderOptions`.
78+
79+
In some cases you may want to use the thread id of the server side agent thread, when using a service based agent.
80+
The thread may however not have been created yet when the `Mem0Provider` object is being constructed.
81+
In this case, you can set the `ScopeToPerOperationThreadId` option to `true`, and the `Mem0Provider` will
82+
use the id of the `AgentThread` when it is available.
83+
84+
#### Context Prompt
85+
86+
The `ContextPrompt` option allows you to override the default prompt that is prefixed to memories.
87+
The prompt is used to contextualize the memories provided to the AI model, so that the AI model knows what they are and how to use them.
88+
89+
## Using Whiteboard Memory for Short-Term Context
90+
91+
The whiteboard memory feature allows agents to capture and retain the most relevant information from a conversation, even when the chat history is truncated.
92+
93+
Each message added to the conversation is processed by the `Microsoft.SemanticKernel.Memory.WhiteboardProvider` to extract requirements, proposals, decisions, actions.
94+
These are stored on a whiteboard and provided to the agent as additional context on each invocation.
95+
96+
Here is an example of how to set up Whiteboard Memory:
97+
98+
```csharp
99+
// Create a whiteboard provider.
100+
var whiteboardProvider = new WhiteboardProvider(chatClient);
101+
102+
// Add the whiteboard provider to the agent thread.
103+
ChatHistoryAgentThread agentThread = new();
104+
agentThread.AIContextProviders.Add(whiteboardProvider);
105+
106+
// Simulate a conversation with the agent.
107+
await agent.InvokeAsync("I would like to book a trip to Paris.", agentThread);
108+
109+
// Whiteboard should now contain a requirement that the user wants to book a trip to Paris.
110+
```
111+
112+
Benefits of Whiteboard Memory
113+
114+
- Short-Term Context: Retains key information about the goals of ongoing conversations.
115+
- Allows Chat History Truncation: Supports maintaining critical context if the chat history is truncated.
116+
117+
### WhiteboardProvider options
118+
119+
The `WhiteboardProvider` can be configured with various options to customize its behavior.
120+
Options are provided using the `WhiteboardProviderOptions` class to the `WhiteboardProvider` constructor.
121+
122+
#### MaxWhiteboardMessages
123+
124+
Specifies a maximum number of messages to retain on the whiteboard.
125+
When the maximum is reached, less valuable messages will be removed.
126+
127+
#### ContextPrompt
128+
129+
When providing the whiteboard contents to the AI model it's important to describe what the messages are for.
130+
This setting allows overriding the default messaging that is built into the `WhiteboardProvider`.
131+
132+
#### WhiteboardEmptyPrompt
133+
134+
When the whiteboard is empty, the `WhiteboardProvider` outputs a message saying that it is empty.
135+
This setting allows overriding the default messaging that is built into the `WhiteboardProvider`.
136+
137+
#### MaintenancePromptTemplate
138+
139+
The `WhiteboardProvider` uses an AI model to add/update/remove messages on the whiteboard.
140+
It has a built in prompt for making these updates.
141+
This setting allows overriding this built-in prompt.
142+
143+
The following parameters can be used in the template:
144+
145+
- `{{$maxWhiteboardMessages}}`: The maximum number of messages allowed on the whiteboard.
146+
- `{{$inputMessages}}`: The input messages to be added to the whiteboard.
147+
- `{{$currentWhiteboard}}`: The current state of the whiteboard.
148+
149+
## Combining Mem0 and Whiteboard Memory
150+
151+
You can use both Mem0 and whiteboard memory in the same agent to achieve a balance between long-term and short-term memory capabilities.
152+
153+
```csharp
154+
// Add both Mem0 and whiteboard providers to the agent thread.
155+
agentThread.AIContextProviders.Add(mem0Provider);
156+
agentThread.AIContextProviders.Add(whiteboardProvider);
157+
158+
// Use the agent with combined memory capabilities.
159+
ChatMessageContent response = await agent.InvokeAsync("Please retrieve my company report", agentThread).FirstAsync();
160+
Console.WriteLine(response.Content);
161+
```
162+
163+
By combining these memory features, agents can provide a more personalized and context-aware experience for users.
164+
165+
## Next steps
166+
167+
> [!div class="nextstepaction"]
168+
> [Explore the Agent with Mem0 sample](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Agents/ChatCompletion_Mem0.cs)
169+
> [Explore the Agent with Whiteboard sample](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Agents/ChatCompletion_Whiteboard.cs)
170+
171+
::: zone-end
172+
173+
::: zone pivot="programming-language-python"
174+
175+
## Coming Soon
176+
177+
More information coming soon.
178+
179+
::: zone-end
180+
181+
::: zone pivot="programming-language-java"
182+
183+
## Coming Soon
184+
185+
More information coming soon.
186+
187+
::: zone-end

0 commit comments

Comments
 (0)