ConnectConnectMicrosoft Agent Framework

MCP Client

Microsoft Agent Framework

Add bounded, provenance-bearing XMemo memory context to Microsoft Agent Framework in Python, with explicitly opt-in capture.

Who this is for and integration boundary

This guide covers xmemo-agent-framework 0.2.0, a Python context provider for Microsoft Agent Framework. It retrieves bounded, provenance-bearing XMemo context and offers a separate opt-in capture hook. This is an independent community integration, not an official Microsoft product or distribution. The package does not publish or deploy an XMemo server.

Prerequisites

Use Python and Microsoft Agent Framework Core. The optional maf extra pins agent-framework-core==1.21.0. Set the XMemo origin and API key in the process environment before creating a connection.

  • XMEMO_URL must be an HTTPS origin.
  • XMEMO_API_KEY is sent only as an Authorization header.
  • The effective owner and tenant are determined by server authorization, not by client-supplied identity claims.

Installation

After publication, the equivalent consumer install is:

pip install "xmemo-agent-framework[maf]==0.2.0"

Configure the connection

Provide the XMemo origin and API key to the process that launches the agent:

export XMEMO_URL="https://your-xmemo-origin"
export XMEMO_API_KEY="your-api-key"

Read XMemo context

The default route is POST /v1/recall/context. Choose a different route with the documented ReadRoute value when the use case requires it. Pass context_provider to the host agent context-provider configuration and close connection when the host session ends:

  • ReadRoute.RECALL: POST /v1/recall/context (default).
  • ReadRoute.PROJECT: POST /v1/projects/{project_id}/context.
  • ReadRoute.SEARCH: GET /v1/memories/search.
import os
from xmemo_agent_framework import Connection, Policy, Provider, ReadRoute
from xmemo_agent_framework.maf import XMemoContextProvider

connection = Connection(os.environ["XMEMO_URL"], os.environ["XMEMO_API_KEY"])
read_provider = Provider(
    connection,
    Policy(
        recall_enabled=True,
        route=ReadRoute.RECALL,
        scope="tenant:project:my-project",
        max_items=8,
        max_tokens=2000,
    ),
)
context_provider = XMemoContextProvider(read_provider)

Use XMemo tools through MCP

The Microsoft Agent Framework context provider does not replace XMemo's MCP tool surface. Configure an XMemo MCP connection separately when the agent needs explicit memory tools such as remember, recall, search, or forget.

  • Start with the [MCP overview](/docs/mcp/overview) for connection paths and tool profiles.
  • See [remember](/docs/tools/remember), [recall](/docs/tools/recall), [search](/docs/tools/search), and [forget](/docs/tools/forget) for the documented memory tools.
  • For client configuration examples, see [Codex](/docs/mcp/codex) or [GitHub Copilot](/docs/mcp/copilot).

Capture is opt-in

Capture is off by default. It runs only when a separate CaptureProvider is passed to XMemoContextProvider with a server-resolved write identity and an explicit target/behavior pair. STATE requires state_key and EVENT requires event_type; both use [a-z0-9][a-z0-9_.:-]{0,127}.

  • Target.REMEMBER sends POST /api/v1/remember with Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP.
  • Target.STATE sends POST /api/v1/update_state with Behavior.STATE_VERSIONED_UPSERT and requires a bounded lowercase state_key.
  • Target.EVENT sends POST /api/v1/timeline/events with Behavior.EVENT_APPEND_NO_DEDUPE and requires a bounded lowercase event_type.

Configure the capture provider

This example enables a single REMEMBER target, where resolved_identity is obtained from ResolvedIdentity.from_server_responses(...) in xmemo_agent_framework.capture. Use the documented target and behavior pairs when enabling another capture path:

from xmemo_agent_framework.capture import (
    Behavior,
    CapturePolicy,
    CaptureProvider,
    Target,
)

capture = CaptureProvider(
    connection,
    CapturePolicy(
        enabled=True,
        target=Target.REMEMBER,
        behavior=Behavior.SEMANTIC_KEY_SAME_CONTENT_NOOP,
    ),
    identity=resolved_identity,
)
context_provider = XMemoContextProvider(read_provider, capture=capture)

Capture limits and failure isolation

Capture accepts bounded content only (8 KiB by default, configurable up to the policy limit). Unbounded content is never captured. API keys, bearer tokens, private keys, and detected secret patterns are never included in the write body; the connection credential remains only in the Authorization header. Unsafe candidates are rejected if redaction still leaves the request unsafe.

  • The hook sends at most one write request for an assistant reply and never retries a write.
  • A rejected, failed, or unknown write outcome does not change the assistant result.
  • The host receives sanitized capture metadata rather than raw server or credential details.

Provenance and authorization

Every injected item carries immutable provenance and an adapter receipt. Retrieved text is untrusted saved context, not an instruction. Server authorization owns the effective owner and tenant; capture does not grant model authority or change the read provider's authorization boundary.

Server requirements

Read routes require the corresponding XMemo REST contract. REMEMBER, STATE, and EVENT capture with audited write responses require XMemo server v0.4.436 or later, which the hosted service at xmemo.dev already runs.

Troubleshooting

Use the package's documented compatibility and validation signals:

  • If importing xmemo_agent_framework.maf raises ImportError, install the optional maf extra so the host framework dependency is present.
  • XMEMO_URL must be an HTTPS origin, and XMEMO_API_KEY is sent only in the Authorization header.
  • For a rejected, failed, or unknown capture outcome, the assistant result is preserved; the host receives sanitized metadata and the write is not retried.

Source: MCP overview