Match memory persistence to its purpose

Learning objective

Select working, episodic, semantic, and shared-memory persistence strategies

Core idea

Select persistence from the question the agent must answer later. Working memory supports the task in progress. Episodic memory recalls what happened in a particular interaction. Semantic memory retains reusable facts or preferences. Shared memory coordinates knowledge used by several agents. These are architectural categories, not four interchangeable database products.

For a senior engineer, the decisive properties are lifetime, fidelity, retrieval pattern, and write ownership. A transcript can preserve an episode without extracting a reusable fact. A consolidated preference can improve personalization without preserving the episode that established it. A shared scope can expose the same memories to several participants without making their updates transactional.

Foundry Agent Service memory is a managed long-term memory feature in public preview. Its documented types are user profile, chat summary, and procedural memory. Map the architectural categories to those actual mechanisms; do not rename the service’s options to match a conceptual taxonomy.

How it works

Keep working memory close to execution

Working memory includes recent messages, tool observations, temporary hypotheses, and the state needed to complete the active request. Agent Framework supports local conversation history in AgentSession.state, for example through Python’s InMemoryHistoryProvider, and service-managed state referenced by AgentSession.service_session_id.

Choose local history when the application needs to control the messages sent on each run. Choose a service-managed conversation when durable server-side items fit the interaction. In either case, bound model-visible context and preserve authoritative task state separately. See 2.2.1 for continuation and 2.2.4 for reduction.

Persist the complete session, not only its messages; see 2.2.1 for the serialization mechanisms. Durable storage for restart recovery remains an application responsibility.

Avoid promoting every temporary thought into long-term memory. An unconfirmed customer claim or a speculative repair explanation can help the current interaction while remaining unsuitable as durable knowledge. Promotion requires a decision about confidence, provenance, purpose, and retention.

Preserve episodes at the required fidelity

An episode records a particular event: which case was discussed, what evidence appeared, what action completed, and what remained unresolved. A Foundry conversation persists items such as messages, tool calls, and tool outputs. That makes it useful when later investigation needs the interaction record rather than a distilled preference.

Foundry memory’s chat_summary_enabled option instead enables distilled summaries of prior conversation topics and threads. The documented retrieval guidance is to retrieve chat summaries per turn using the recent conversation to surface relevant continuity. This can answer “what were we discussing?” without loading an entire past conversation.

Choose a conversation or an application event record when exact evidence matters. Choose chat summary memory when thematic continuity is enough. A generated summary should not be described as an immutable event log: extraction and consolidation can change the representation of the remembered information.

Consolidate reusable knowledge selectively

Semantic memory, in the architectural sense, captures knowledge that remains useful outside one episode. Foundry’s user profile memory is a concrete match for durable personal preferences and context. The user_profile_enabled option controls this type, and user_profile_details guides which details the memory system extracts or excludes.

Retrieve profile context near the beginning of a conversation. The usage page documents search_memories with scope and without items or previous_search_id for static profile retrieval. Supplying recent messages as items instead supports contextual retrieval. This is more precise than assuming every preference must be semantically similar to the user’s next question.

Procedural memory captures reusable operating patterns inferred from previous interactions. The procedural_memory_enabled option enables it. A learned routine is distinct from a personal preference and from a curated organization policy. Select it for recurring workflows, then validate that its remembered steps remain appropriate before execution.

Microsoft recommends memory for learned user or agent context, a Foundry IQ knowledge base for curated organizational content, and file search for user-provided documents during an interaction. This distinction prevents a recollected conversation from replacing the source of truth for a contractual rule. See 2.2.3 for the context-selection budget.

Share deliberately rather than globally

Foundry memory stores partition items with scope. Low-level APIs can use a scope representing an end user, a team, or another stable identifier. Several agents can coordinate access to an intentionally shared collection through application-selected stores and scopes, but sharing must have a defined purpose and designated update ownership.

Apply the store ownership and personal-data sharing controls in 1.1.10; choose shared persistence here only when several agents need the same reusable knowledge and a designated publisher governs updates.

The memory lifecycle is extraction, consolidation, and retrieval. Python’s begin_update_memories() adds conversation content through a long-running operation; search_memories() retrieves relevant memories. Consolidation can merge overlapping information and resolve conflicts, and the conceptual page warns that behavior varies by memory type during preview. Shared memory therefore needs explicit rules for which agent can write and how conflicting observations are handled.

Key distinctions and trade-offs

The persistence choices serve different future questions:

Longer retention improves continuity but increases the consequences of stale or excessive data. Retrieval reduces prompt size but makes recall depend on query relevance. Consolidation reduces duplication but can obscure which original observation produced a fact unless the application retains provenance separately.

Capacity can also change the design. The memory overview lists 100 scopes per memory store and 10,000 memories per scope. A design for thousands of users cannot assume one store with one scope per user fits that quota. Validate the store layout and region availability before making memory a required production component.

Architecture / decision scenario

A maintenance assistant serves technicians across several customer organizations. During a repair, the active machine ID and pending inspection belong to working state. The complete incident record must preserve measurements and actions, so it remains in the case record and persisted conversation. Chat summary memory supplies continuity when the technician returns.

The technician’s language preference belongs in user profile memory. A reusable inspection routine can use procedural memory, but the authorized maintenance policy stays in a curated knowledge source. A team scope may hold nonpersonal troubleshooting lessons; it must not become a repository for every technician’s personal history.

Assign a designated publisher for team lessons and keep exact source records for each promoted lesson. Partition the store layout with the 100-scope quota in mind. On restart, restore full working session state; on another case, retrieve only the profile and relevant summaries. These choices preserve both continuity and the distinction between a remembered experience and an authoritative rule.

Common exam traps

• Treating conceptual memory categories as service option names.
• Assuming in-memory session history survives process restart.
• Using a consolidated summary as an exact event ledger.
• Promoting unverified temporary context into reusable knowledge.
• Treating a shared scope as safe global memory for all users.
• Ignoring store quotas when choosing per-user partitioning.

What to remember

Choose persistence by lifetime and required fidelity. Keep working state resumable, distinguish episode records from summaries, and separate learned knowledge from curated policy. Shared memory needs deliberate scope and update ownership; managed consolidation does not settle those architectural decisions.

Knowledge check

References

• Microsoft, Memory in Foundry Agent Service
• Microsoft, Create and use memory in Foundry Agent Service
• Microsoft, Storage
• Microsoft, Build with runtime components in Foundry Agent Service