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)