feat(agent-framework): Hindsight memory for Microsoft Agent Framework (no MCP) (#1989)

* feat(agent-framework): add Hindsight memory integration via context provider

Persistent memory for Microsoft Agent Framework (the successor to Semantic
Kernel) without MCP. HindsightProvider is a ContextProvider whose before_run
recalls relevant memories and injects them into the agent's instructions, and
whose after_run retains the conversation. Reuses the LlamaIndex integration's
client/config pattern and the hindsight-client Python SDK.

Targets the agent-framework-core 1.x before_run/after_run + SessionContext
contract (verified against the installed package since the API has churned).
15 unit tests subclass the real ContextProvider so drift fails loudly, plus a
gated e2e. Includes CI job, release + changelog + docs wiring, and an icon.

* chore(agent-framework): refresh lock to agent-framework-core 1.8.1 (verified no API drift)

* fix(agent-framework): drop unused per-op timeout constants

TIMEOUT_RETAIN/TIMEOUT_RECALL/TIMEOUT_BANK were defined but never used: the
hindsight-client SDK sets one timeout on the constructor and has no per-call
timeout argument, so per-op values can't be wired in. Keep the single
constructor-level TIMEOUT_DEFAULT and document why. Addresses review feedback.

Author: benfrank241

.github/workflows/test.yml

@@ -32,6 +32,7 @@ jobs:
       integration-tests: ${{ steps.filter.outputs.integration-tests }}
       integrations-openclaw: ${{ steps.filter.outputs.integrations-openclaw }}
       integrations-ai-sdk: ${{ steps.filter.outputs.integrations-ai-sdk }}
+      integrations-agent-framework: ${{ steps.filter.outputs.integrations-agent-framework }}
       integrations-chat: ${{ steps.filter.outputs.integrations-chat }}
       integrations-claude-code: ${{ steps.filter.outputs.integrations-claude-code }}
       integrations-cline: ${{ steps.filter.outputs.integrations-cline }}
@@ -124,6 +125,8 @@ jobs:
             - 'hindsight-integrations/openclaw/**'
           integrations-ai-sdk:
             - 'hindsight-integrations/ai-sdk/**'
+          integrations-agent-framework:
+            - 'hindsight-integrations/agent-framework/**'
           integrations-chat:
             - 'hindsight-integrations/chat/**'
           integrations-claude-code:
@@ -3155,6 +3158,49 @@ jobs:
       working-directory: ./hindsight-integrations/obsidian
       run: npm test
 
+  test-agent-framework-integration:
+    needs: [detect-changes]
+    if: >-
+      (github.event_name == 'workflow_dispatch' ||
+      needs.detect-changes.outputs.integrations-agent-framework == 'true' ||
+      needs.detect-changes.outputs.ci == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.event.pull_request.head.sha || '' }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        prune-cache: false
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version-file: ".python-version"
+
+    - name: Build agent-framework integration
+      working-directory: ./hindsight-integrations/agent-framework
+      run: uv build
+
+    - name: Install dependencies
+      working-directory: ./hindsight-integrations/agent-framework
+      run: uv sync --frozen
+
+    - name: Lint
+      working-directory: ./hindsight-integrations/agent-framework
+      run: uv run ruff check .
+
+    - name: Run tests
+      working-directory: ./hindsight-integrations/agent-framework
+      # PR CI runs only the deterministic bucket; the real-LLM E2E bucket
+      # (requires_real_llm) needs a live Hindsight server and runs separately.
+      run: uv run pytest tests -v -m "not requires_real_llm"
+
   test-crewai-integration:
     needs: [detect-changes]
     if: >-
@@ -4486,6 +4532,7 @@ jobs:
       - test-dify-integration
       - test-flowise-integration
       - test-obsidian-integration
+      - test-agent-framework-integration
       - test-crewai-integration
       - test-langgraph-integration
       - test-superagent-integration

hindsight-dev/hindsight_dev/generate_changelog.py

@@ -41,6 +41,7 @@ class IntegrationMeta:
     "litellm": IntegrationMeta("hindsight-litellm", "LiteLLM"),
     "pydantic-ai": IntegrationMeta("hindsight-pydantic-ai", "Pydantic AI"),
     "crewai": IntegrationMeta("hindsight-crewai", "CrewAI"),
+    "agent-framework": IntegrationMeta("hindsight-agent-framework", "Microsoft Agent Framework"),
     "ag2": IntegrationMeta("hindsight-ag2"),
     "ai-sdk": IntegrationMeta("@vectorize-io/hindsight-ai-sdk", "AI SDK"),
     "chat": IntegrationMeta("@vectorize-io/hindsight-chat", "Chat SDK"),

hindsight-docs/docs-integrations/agent-framework.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 8
+title: "Microsoft Agent Framework Persistent Memory with Hindsight | Integration Guide"
+description: "Add persistent memory to Microsoft Agent Framework agents with Hindsight via a context provider. Recalls relevant context before each run and retains the conversation after — no MCP, no tools to call."
+---
+
+# Microsoft Agent Framework
+
+[View Changelog →](/changelog/integrations/agent-framework)
+
+Persistent memory for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) — the successor to Semantic Kernel — using [Hindsight](https://vectorize.io/hindsight). The integration plugs in as a **context provider**, so every agent run automatically recalls relevant memories into the agent's context and retains the conversation afterward. No MCP, and no tools the model has to remember to call.
+
+## Quick Start
+
+:::tip Recommended: Hindsight Cloud
+[Sign up free](https://ui.hindsight.vectorize.io/signup) for a Hindsight Cloud API key — no self-hosting required.
+:::
+
+```bash
+pip install hindsight-agent-framework
+export HINDSIGHT_API_KEY=your-hindsight-key
+```
+
+```python
+from agent_framework.openai import OpenAIChatClient
+from hindsight_agent_framework import HindsightProvider
+
+agent = OpenAIChatClient().as_agent(
+    name="assistant",
+    instructions="You are a helpful assistant.",
+    context_providers=[HindsightProvider(bank_id="user-123")],
+)
+
+session = agent.create_session()
+await agent.run("Remember that I prefer vegetarian food.", session=session)
+await agent.run("Suggest a recipe.", session=session)  # recalls the preference
+```
+
+## How It Works
+
+| Hook | Behavior |
+| --- | --- |
+| `before_run` | Recall memories relevant to the user's message and inject them as a `## Memories` block in the agent's instructions. |
+| `after_run` | Retain the user input + agent response so future runs build on them. |
+
+Memories live in a Hindsight **bank** — one per user, agent, or session (you choose via `bank_id`). Recall and retain are best-effort: a memory hiccup never blocks the agent.
+
+## Configuration
+
+`HindsightProvider(bank_id, ...)` accepts `hindsight_api_url`, `api_key`, `budget` (low/mid/high), `max_tokens`, `tags`, `recall_tags`, `mission`, `auto_recall`, `auto_retain`, and more. Process-wide defaults can be set with `configure(...)`.
+
+## Self-Hosting
+
+```bash
+pip install hindsight-all
+export HINDSIGHT_API_LLM_API_KEY=your-openai-key
+hindsight-api  # http://localhost:8888
+```
+
+```python
+HindsightProvider(bank_id="user-123", hindsight_api_url="http://localhost:8888")
+```
+
+See the [integration source](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/agent-framework) for full details.

hindsight-docs/src/data/integrations.json

@@ -10,6 +10,16 @@
       "link": "/sdks/integrations/litellm",
       "icon": "/img/icons/litellm.png"
     },
+    {
+      "id": "agent-framework",
+      "name": "Microsoft Agent Framework",
+      "description": "Persistent memory for Microsoft Agent Framework (the successor to Semantic Kernel) via a context provider that auto-recalls and auto-retains each turn.",
+      "type": "official",
+      "by": "hindsight",
+      "category": "framework",
+      "link": "/sdks/integrations/agent-framework",
+      "icon": "/img/icons/agent-framework.svg"
+    },
     {
       "id": "crewai",
       "name": "CrewAI",

hindsight-docs/src/pages/changelog/integrations/agent-framework.md

@@ -0,0 +1,9 @@
+---
+hide_table_of_contents: true
+---
+
+import PageHero from '@site/src/components/PageHero';
+
+<PageHero title="Microsoft Agent Framework Changelog" subtitle="Hindsight memory integration for Microsoft Agent Framework." />
+
+[← Microsoft Agent Framework integration](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/agent-framework)

hindsight-docs/static/img/icons/agent-framework.svg

@@ -0,0 +1,65 @@
+# hindsight-agent-framework
+
+Persistent long-term memory for [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) via [Hindsight](https://github.com/vectorize-io/hindsight).
+
+Microsoft Agent Framework is the successor to Semantic Kernel. This integration plugs Hindsight in as a **context provider**, so every agent run automatically **recalls** relevant memories into the agent's context and **retains** the conversation afterward — no MCP, and no tools the model has to remember to call.
+
+## Installation
+
+```bash
+pip install hindsight-agent-framework
+```
+
+> ✨ **Recommended:** [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup) — sign up free, get an API key, and skip self-hosting.
+
+## Usage
+
+```python
+from agent_framework.openai import OpenAIChatClient
+from hindsight_agent_framework import HindsightProvider
+
+agent = OpenAIChatClient().as_agent(
+    name="assistant",
+    instructions="You are a helpful assistant.",
+    context_providers=[HindsightProvider(bank_id="user-123")],
+)
+
+session = agent.create_session()
+await agent.run("Remember that I prefer vegetarian food.", session=session)
+# ...later, even in a new process:
+await agent.run("Suggest a recipe.", session=session)  # recalls the preference
+```
+
+Set your API key once via the `HINDSIGHT_API_KEY` environment variable, or pass `api_key=`/`hindsight_api_url=` to `HindsightProvider`. For self-hosting:
+
+```bash
+pip install hindsight-all
+export HINDSIGHT_API_LLM_API_KEY=your-openai-key
+hindsight-api  # http://localhost:8888
+```
+
+```python
+HindsightProvider(bank_id="user-123", hindsight_api_url="http://localhost:8888")
+```
+
+## How It Works
+
+| Hook | Behavior |
+| --- | --- |
+| `before_run` | Recall memories relevant to the user's message and inject them as a `## Memories` block in the agent's instructions. |
+| `after_run` | Retain the user input + agent response so future runs build on them. |
+
+Memories live in a Hindsight **bank** (one per user/agent/session — you choose). Recall and retain are best-effort: a memory hiccup never blocks the agent.
+
+## Configuration
+
+`HindsightProvider(bank_id, ...)` accepts: `client`, `hindsight_api_url`, `api_key`, `budget` (low/mid/high), `max_tokens`, `context`, `tags`, `recall_tags`, `recall_tags_match`, `mission` (creates the bank with a fact-extraction persona), `auto_recall`, `auto_retain`, `source_id`. You can also set process-wide defaults via `configure(...)`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run pytest tests -v          # unit tests
+uv run pytest tests -v -m requires_real_llm   # e2e (needs a live Hindsight server)
+```

hindsight-integrations/agent-framework/README.md

@@ -0,0 +1,37 @@
+"""Hindsight memory integration for Microsoft Agent Framework.
+
+Provides ``HindsightProvider``, an Agent Framework ``ContextProvider`` that
+automatically recalls relevant memories into an agent's context before each run
+and retains the conversation afterward — persistent long-term memory with no MCP
+and no tools the model must remember to call.
+
+Usage::
+
+    from agent_framework.openai import OpenAIChatClient
+    from hindsight_agent_framework import HindsightProvider
+
+    agent = OpenAIChatClient().as_agent(
+        name="assistant",
+        context_providers=[HindsightProvider(bank_id="user-123")],
+    )
+"""
+
+from .config import (
+    HindsightAgentFrameworkConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+from .errors import HindsightError
+from .provider import HindsightProvider
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "configure",
+    "get_config",
+    "reset_config",
+    "HindsightAgentFrameworkConfig",
+    "HindsightError",
+    "HindsightProvider",
+]

hindsight-integrations/agent-framework/hindsight_agent_framework/__init__.py

@@ -0,0 +1,49 @@
+"""Shared Hindsight client resolution logic."""
+
+import os
+from importlib import metadata
+from typing import Any, Optional
+
+from hindsight_client import Hindsight
+
+from .config import DEFAULT_HINDSIGHT_API_URL, HINDSIGHT_API_KEY_ENV, get_config
+
+try:
+    _VERSION = metadata.version("hindsight-agent-framework")
+except metadata.PackageNotFoundError:
+    _VERSION = "0.0.0"
+_USER_AGENT = f"hindsight-agent-framework/{_VERSION}"
+
+# Request timeout (seconds). The hindsight-client SDK takes a single timeout at
+# construction and exposes no per-call timeout, so this one bound applies to
+# every recall/retain/bank operation. The provider guards all calls and degrades
+# gracefully, so this is a backstop, not a tight per-op budget.
+TIMEOUT_DEFAULT = 30.0
+
+
+def resolve_client(
+    client: Optional[Hindsight],
+    hindsight_api_url: Optional[str],
+    api_key: Optional[str],
+) -> Hindsight:
+    """Resolve a Hindsight client from explicit args or global config.
+
+    Falls back to the default API URL and the ``HINDSIGHT_API_KEY`` env var
+    when neither an explicit argument nor a prior ``configure()`` call supplied
+    them, so the provider works with nothing but the env var set. Self-hosted
+    users override the URL. The API key is optional at construction time — a
+    missing key only fails when a call is actually made.
+    """
+    if client is not None:
+        return client
+
+    config = get_config()
+    url = hindsight_api_url or (config.hindsight_api_url if config else DEFAULT_HINDSIGHT_API_URL)
+    # Read HINDSIGHT_API_KEY directly so the no-configure() path still honours
+    # the env var — the base Hindsight client doesn't fall back to it on its own.
+    key = api_key or (config.api_key if config else None) or os.environ.get(HINDSIGHT_API_KEY_ENV)
+
+    kwargs: dict[str, Any] = {"base_url": url, "timeout": TIMEOUT_DEFAULT, "user_agent": _USER_AGENT}
+    if key:
+        kwargs["api_key"] = key
+    return Hindsight(**kwargs)