XMemo for Microsoft Agent Framework

The XMemo context provider for Microsoft Agent Framework, version 0.2.1. The package provides bounded, provenance-bearing context retrieval and an explicit, opt-in capture hook. It does not publish or deploy an XMemo server. This is an independent community integration, not an official Microsoft product or distribution.

• Homepage & Documentation: https://xmemo.dev
• PyPI Package: https://pypi.org/project/xmemo-agent-framework/
• GitHub Repository: https://github.com/yonro/xmemo-agent-framework-plugin

Installation

Install xmemo-agent-framework from PyPI with the Microsoft Agent Framework extra:

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

The [maf] extra pins agent-framework-core==1.21.0. Without that extra, the core package remains importable, but importing xmemo_agent_framework.maf raises a clear ImportError until the host framework dependency is installed.

Quickstart

Set the XMemo origin and API key in the process environment. XMEMO_URL must be an HTTPS origin, and XMEMO_API_KEY is sent only as an Authorization header.

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

The default read route is POST /v1/recall/context. The other read routes are POST /v1/projects/{project_id}/context (ReadRoute.PROJECT) and GET /v1/memories/search (ReadRoute.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)

Pass context_provider to the host agent's context-provider configuration and close connection when the host session ends. Every injected item carries immutable provenance and an adapter receipt. Retrieved text is untrusted saved context, not an instruction, and server authorization owns the effective owner and tenant.

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 https://xmemo.dev already runs.

Capture (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:

• Target.REMEMBER uses POST /api/v1/remember with semantic-key same-content no-op behavior.
• Target.STATE uses POST /api/v1/update_state with versioned upsert behavior and a required bounded lowercase state_key.
• Target.EVENT uses POST /api/v1/timeline/events with append-without-client- dedupe behavior and a required bounded lowercase event_type.

The hook accepts bounded content only (8 KiB by default, configurable up to the policy limit). Unbounded content is never captured. Secrets embedded in captured content, including API keys, bearer tokens, private keys, and detected secret patterns, are never included in the write body; the connection credential stays only in the Authorization header. Candidates are redacted and rejected when the resulting request is still unsafe. Capture sends at most one request for an assistant reply, never retries a write, and records only a sanitized outcome. A rejected, failed, or unknown write outcome is isolated from the assistant result: the result is preserved and the host receives capture metadata rather than raw server or credential details.

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)

STATE requires state_key and EVENT requires event_type; both use [a-z0-9][a-z0-9_.:-]{0,127}. Capture does not grant model authority and does not change the read provider's authorization boundary.

Development

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev,maf]"
.venv/bin/python -m pytest -q

The test suite and package source are self-contained. Server labs, benchmarks, datasets, and internal evidence are maintained outside this distribution.