Azure Foundry Memory — Memory Store APIs
You have access to persistent long-term memory via Azure AI Foundry Memory Store. Memory survives pod restarts, upgrades, and session boundaries. The system uses embedding models for semantic search and chat models to extract/consolidate memories automatically.
Memory Persistence — How It Works
Memories are stored server-side in Foundry's managed Memory Store (not in the pod). They persist across pod restarts, upgrades, and session boundaries.
Scope is the key to persistence. Always use $SANDBOX_NAME (environment variable) as the scope. This is the agent's stable identity — the CRD name (e.g., my-agent) — and never changes even when pods restart.
# Read the stable scope from environment
SCOPE=$(printenv SANDBOX_NAME)
# Use it in all memory operations
For per-user memory within an agent, use a composite scope like ${SANDBOX_NAME}-${user_id}.
Why use this instead of local files
Local files in /sandbox/ are ephemeral. Foundry Memory Store is managed, uses vector search (text-embedding-3-small), and supports:
- User profile memory: preferences, name, restrictions
- Chat summary memory: distilled summaries of past conversations
Endpoint
All requests: http://localhost:8443 with ?api-version=2025-11-15-preview. Auth is automatic.
Operations
Create a memory store
curl -s -X POST 'http://localhost:8443/memory_stores?api-version=2025-11-15-preview' \
-H 'Content-Type: application/json' \
-d '{"name":"agent-memory","description":"Agent persistent memory","definition":{"kind":"default","chat_model":"gpt-4.1","embedding_model":"text-embedding-3-small","options":{"user_profile_enabled":true,"chat_summary_enabled":true}}}'
Store memories from conversation
curl -s -X POST 'http://localhost:8443/memory_stores/agent-memory:update_memories?api-version=2025-11-15-preview' \
-H 'Content-Type: application/json' \
-d '{"items":[{"role":"user","content":"I prefer dark roast coffee and code in Rust","type":"message"},{"role":"assistant","content":"Noted!","type":"message"}],"scope":"$SANDBOX_NAME","update_delay":0}'
Returns {"update_id": "...", "status": "queued"}. The system asynchronously extracts memories using the chat model.
Search memories (with semantic embedding)
curl -s -X POST 'http://localhost:8443/memory_stores/agent-memory:search_memories?api-version=2025-11-15-preview' \
-H 'Content-Type: application/json' \
-d '{"scope":"$SANDBOX_NAME","items":[{"role":"user","content":"What coffee does the user like?","type":"message"}],"options":{"max_memories":10}}'
Returns memories[] array with content, kind (user_profile/chat_summary), and usage (embedding_tokens).
List all memories for scope (no embedding)
curl -s -X POST 'http://localhost:8443/memory_stores/agent-memory:search_memories?api-version=2025-11-15-preview' \
-H 'Content-Type: application/json' \
-d '{"scope":"$SANDBOX_NAME","options":{"max_memories":50}}'
Delete memories for a scope
curl -s -X POST 'http://localhost:8443/memory_stores/agent-memory:delete_scope?api-version=2025-11-15-preview' \
-H 'Content-Type: application/json' \
-d '{"scope":"$SANDBOX_NAME"}'
When to use
- User says "remember this", "save this for later"
- Start of session: search memories for the user to personalize
- After meaningful conversation: store key facts via update_memories
- User asks "what do you know about me"
When NOT to use
- For searching documents (use foundry-knowledge skill)
- For temporary scratch data (use local files)
- For real-time web info (use foundry-web-search skill)