Microsoft Agent Framework Memory with Supermemory

Microsoft Agent Framework can use a Supermemory context provider to retrieve background before an agent runs. Session state and persistent user context remain separate design choices. The provider should receive a stable authorized user scope, while the conversation identity identifies one interaction thread.

This guide covers the documented Python integration. It does not imply that an identical package or API exists for .NET. Check the framework and integration versions together before copying an example into a service.

Start with a scoped connection

The integration documentation describes a shared AgentSupermemory connection used by context providers, tools, and middleware. Install supermemory-agent-framework in an isolated environment, following its prerelease dependency instructions when required.

from supermemory_agent_framework import (
    AgentSupermemory,
    SupermemoryContextProvider,
)

def make_provider(scope, conversation_id):
    if not scope or not conversation_id:
        raise ValueError("Authorized scope and conversation ID are required")
    connection = AgentSupermemory(
        container_tag=scope,
        conversation_id=conversation_id,
    )
    return SupermemoryContextProvider(
        connection,
        mode="full",
        store_conversations=False,
    )

Credentials belong in the server environment. Construct scope from authenticated application identity; do not accept an arbitrary tenant or user scope from a prompt. The documented default scope is convenient for a demo but is not an identity policy for a multi-user product.

Attach one retrieval path first

Pass the provider in the agent's context_providers configuration. The documented integration retrieves context before the run; conversation storage is a separate option. Begin with saving disabled and inspect what is added to the agent input.

The package also offers tools and middleware. Enabling every mechanism at once can cause repeated retrieval or confusing write behavior. Choose the provider when context should be available before each run, tools when the agent should request memory explicitly, or middleware when that layer is the appropriate application boundary.

Understand the save switch

The documented context-provider default for store_conversations is false. Creating a provider therefore does not establish that the conversation was written for later sessions. If saving is enabled, inspect which messages are included, what ID groups them, and how retries update the same conversation.

Set a retention policy before turning the option on. A support assistant may need confirmed customer preferences but should not automatically treat its own suggested resolution as a completed action. Store operational outcomes through the application that owns them.

Define failure behavior

A retrieval timeout should have a deliberate outcome. For a low-risk personalization request, the agent may continue without historical context and say when a needed detail is unavailable. If a task depends on an account-specific fact, pause that action or retrieve it from the authoritative system.

Do not equate “no memories found” with a failed request. Record empty results, authentication errors, processing lag, and timeouts separately. A fallback that silently drops memory on every error can make an apparently healthy integration ineffective.

Test sessions and user isolation

Create two sessions for one fictional user with the same authorized scope and separate conversation IDs. Save one permitted preference, check processing readiness, and verify the second session can retrieve it. Then repeat under another scope and confirm the preference is absent.

Correct the original preference and check which version reaches the provider. Finally, delete the source and test every other path that could still supply it, including session history and caches. See the lifecycle guide for those boundaries.

The constructor and options are checked against the integration package. That check does not execute a live Azure/OpenAI model, cloud memory write, or deployed two-session workflow. Record those results with the exact dependency versions before describing the integration as production-tested.

Local constructor check: Python 3.12, supermemory-agent-framework 1.0.2, agent-framework-core 1.18.0, and supermemory 3.62.0. No provider request was made.

To move from constructor checks to a working integration, get your Supermemory API key and connect the context provider to a test agent. Run the two-session sequence with fictional data and choose explicitly whether conversations should be saved.