1# Agent Memory
2 
3Managed long-term memory for Foundry agents. Enables agent continuity across sessions, devices, and workflows. Agents retain user preferences, conversation history, and deliver personalized experiences. Memory is stored in your project's owned storage.
4 
5## Prerequisites
6 
7- A [Foundry project](https://learn.microsoft.com/azure/ai-foundry/how-to/create-projects) with authorization configured
8- A **chat model deployment** (e.g., `gpt-5.2`)
9- An **embedding model deployment** (e.g., `text-embedding-3-small`) — see [Check Embedding Model](#check-embedding-model) below
10- Python packages: `pip install azure-ai-projects azure-identity`
11 
12### Check Embedding Model
13 
14An embedding model is **required** before enabling memory. Check if one is already deployed:
15 
16Use `foundry_models_list` MCP tool to list all deployments and look for an embedding model (e.g., `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`).
17 
18| Result | Action |
19|--------|--------|
20| ✅ Embedding model found | Note the deployment name and proceed |
21| ❌ No embedding model | Deploy one before enabling memory — see below |
22 
23### Deploy Embedding Model
24 
25If no embedding model exists, use `foundry_models_deploy` MCP tool with:
26- `deploymentName`: `text-embedding-3-small` (or preferred name)
27- `modelName`: `text-embedding-3-small`
28- `modelFormat`: `OpenAI`
29 
30## Authorization and Permissions
31 
32| Role | Scope | Purpose |
33|------|-------|---------|
34| **Azure AI User** | AI Services resource | Assigned to project managed identity |
35| **System-assigned managed identity** | Project | Must be enabled on the project |
36 
37**Setup steps:**
381. In Azure portal → project → **Resource Management** → **Identity** → enable system-assigned managed identity
392. On the AI Services resource → **Access control (IAM)** → assign **Azure AI User** to the project managed identity
40 
41## Workflow
42 
43```
44User wants agent memory
45    │
46    ▼
47Step 1: Check for embedding model deployment
48    │  ├─ ✅ Found → Continue
49    │  └─ ❌ Not found → Deploy one (ask user)
50    │
51    ▼
52Step 2: Create memory store
53    │
54    ▼
55Step 3: Attach memory tool to agent
56    │
57    ▼
58Step 4: Test with conversation
59```
60 
61## Key Concepts
62 
63### Memory Store Options
64 
65| Option | Description |
66|--------|-------------|
67| `chat_summary_enabled` | Summarize conversations for memory |
68| `user_profile_enabled` | Build and maintain user profile |
69| `user_profile_details` | Control what data gets stored (e.g., `"Avoid sensitive data such as age, financials, location, credentials"`) |
70 
71> 💡 **Tip:** Use `user_profile_details` to control what the agent stores — e.g., `"flight carrier preference and dietary restrictions"` for a travel agent, or exclude sensitive data.
72 
73### Scope
74 
75The `scope` parameter partitions memory per user:
76 
77| Scope Value | Behavior |
78|-------------|----------|
79| `{{$userId}}` | Auto-extracts TID+OID from auth token (recommended) |
80| `"user_123"` | Static identifier — you manage user mapping |
81 
82### Memory Store Operations
83 
84| Operation | Description |
85|-----------|-------------|
86| Create | Initialize a memory store with chat/embedding models and options |
87| List | List all memory stores in the project |
88| Update | Update memory store description or configuration |
89| Delete scope | Delete memories for a specific user scope |
90| Delete store | Delete entire memory store (irreversible — all scopes lost) |
91 
92> ⚠️ **Warning:** Deleting a memory store removes all memories across all scopes. Agents with attached memory stores lose access to historical context.
93 
94## Troubleshooting
95 
96| Issue | Cause | Resolution |
97|-------|-------|------------|
98| Auth/authorization error | Identity or managed identity lacks required roles | Verify roles in Authorization section; refresh access token for REST |
99| Memories don't appear after conversation | Updates are debounced or still processing | Increase wait time or call update API with `update_delay=0` |
100| Memory search returns no results | Scope mismatch between update and search | Use same scope value for storing and retrieving memories |
101| Agent response ignores stored memory | Agent not configured with memory search tool | Confirm agent definition includes `MemorySearchTool` with correct store name |
102| No embedding model available | Embedding deployment missing | Deploy an embedding model — see Check Embedding Model section |
103 
104## References
105 
106- [Memory tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/memory-usage?view=foundry)
107- [Memory Concepts](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/what-is-memory)
108- [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry)
109- [Python Samples](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-projects/samples/memories)
110