Semantic Kernel - Maximem Synap

Add persistent, per-user memory to a Semantic Kernel application as a single plugin. Both kernel functions (search_memory and store_memory) are auto-invokable, so the kernel can decide when to query or persist memories on its own.

Requires Python 3.11+.

Overview

This guide shows how to add Synap to a Semantic Kernel application to build kernels that:

Recall user-specific facts, preferences, and past conversations
Persist new information surfaced during a conversation
Auto-invoke memory functions when the model decides they are relevant

The Synap Semantic Kernel integration ships a single plugin class with two kernel functions.

Export	SK interface	Purpose
`SynapPlugin`	Kernel plugin	Provides `search_memory` and `store_memory` kernel functions

Setup

Install the package alongside Semantic Kernel:

pip install maximem-synap-semantic-kernel semantic-kernel

uv add maximem-synap-semantic-kernel semantic-kernel
# pip-compatible (existing venv): uv pip install maximem-synap-semantic-kernel semantic-kernel

The pip package is maximem-synap-semantic-kernel, but the import drops the maximem- prefix and uses underscores: from synap_semantic_kernel import ....

Configure your API key. Generate one from the Synap Dashboard.

.env

SYNAP_API_KEY=synap_your_key_here
OPENAI_API_KEY=your-openai-api-key

Initialize the SDK once at application startup:

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK()
await sdk.initialize()

See SDK Initialization for the full lifecycle and configuration options.

Basic integration

The smallest useful integration adds SynapPlugin to a kernel and invokes a prompt that references the plugin’s functions:

# pip install maximem-synap-semantic-kernel semantic-kernel
from maximem_synap import MaximemSynapSDK
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from synap_semantic_kernel import SynapPlugin

sdk = MaximemSynapSDK()
await sdk.initialize()

kernel = Kernel()
kernel.add_service(OpenAIChatCompletion(service_id="default"))

kernel.add_plugin(
    SynapPlugin(sdk=sdk, user_id="alice", customer_id="acme"),
    plugin_name="synap",
)

result = await kernel.invoke_prompt(
    "{{synap.search_memory query='project priorities'}} What are my top priorities?"
)

The scoping triple (user_id, optional customer_id) is bound when you construct the plugin. The kernel functions only ever see query, content, and other model-supplied parameters. This prevents prompts (or prompt injections) from spoofing scope. For automatic invocation (the kernel chooses when to call memory functions), enable auto function calling. See “Auto function calling” below.

Core concepts

SynapPlugin

SynapPlugin is a regular Semantic Kernel plugin class with @kernel_function annotated methods. Adding it to the kernel registers both functions under the plugin name you choose:

from synap_semantic_kernel import SynapPlugin

plugin = SynapPlugin(
    sdk=sdk,
    user_id="alice",
    customer_id="acme",   # optional, required for B2B instances
)

kernel.add_plugin(plugin, plugin_name="synap")

After registration, the kernel can invoke synap.search_memory and synap.store_memory either through prompt templating, manual invocation, or auto function calling.

search_memory

Function signature exposed to the kernel:

search_memory(query: str, max_results: int = 5) -> str

Returns a formatted string of results, suitable for direct interpolation into prompt templates. Search failures degrade gracefully: the function returns an empty result string and logs an error so the prompt template renders without breaking.

store_memory

Function signature exposed to the kernel:

store_memory(content: str, memory_type: str = "fact") -> str

Returns "Memory stored successfully." on success. Store failures surface explicitly: the function raises SynapIntegrationError so the kernel (and caller) know if persistence failed.

Complete example: chat function with auto-invoked memory

The following kernel auto-invokes synap.search_memory and synap.store_memory whenever the model decides they are relevant. The application just adds messages to a ChatHistory and the kernel handles the rest:

from semantic_kernel import Kernel
from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.contents import ChatHistory
from synap_semantic_kernel import SynapPlugin


def build_kernel(sdk, user_id: str, customer_id: str | None = None) -> Kernel:
    kernel = Kernel()
    kernel.add_service(OpenAIChatCompletion(service_id="default"))
    kernel.add_plugin(
        SynapPlugin(sdk=sdk, user_id=user_id, customer_id=customer_id),
        plugin_name="synap",
    )
    return kernel


async def chat(kernel: Kernel, history: ChatHistory, message: str) -> str:
    settings = kernel.get_prompt_execution_settings_from_service_id("default")
    settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

    history.add_user_message(message)

    chat_service = kernel.get_service("default")
    response = await chat_service.get_chat_message_content(
        chat_history=history,
        settings=settings,
        kernel=kernel,
    )
    history.add_message(response)
    return str(response)


# Usage
kernel = build_kernel(sdk, user_id="alice", customer_id="acme")
history = ChatHistory(system_message=(
    "You are a personal assistant. Call synap.search_memory before answering "
    "questions about the user. Call synap.store_memory when they share a new fact."
))

await chat(kernel, history, "I just upgraded to the Pro plan.")
reply = await chat(kernel, history, "What plan am I on?")
# → "You're on the Pro plan."

Three things to notice in this pattern:

FunctionChoiceBehavior.Auto() lets the model drive memory. No prompt-template plumbing; the model calls the right function when it’s the right time.
Scope is per-kernel. build_kernel(...) constructs a fresh kernel per user so concurrent requests cannot bleed scope.
The system message is the policy. Tell the model when to search and when to store; the plugin just enforces it.

Advanced patterns

Multi-tenant scoping

SynapPlugin accepts the standard scoping triple: user_id (required), optional customer_id, optional conversation_id. customer_id is required on B2B Synap instances and ignored on single-tenant ones. See Memory Scopes.

# User-scoped only
plugin = SynapPlugin(sdk=sdk, user_id="alice")

# Organization-scoped (user sees org-shared memories too)
plugin = SynapPlugin(sdk=sdk, user_id="alice", customer_id="acme-corp")

For multi-tenant services, build the plugin (and kernel) per request rather than sharing one across users.

Prompt-template invocation

Outside of auto function calling, you can interpolate plugin calls directly in prompt templates:

result = await kernel.invoke_prompt(
    "Context: {{synap.search_memory query='dietary preferences'}}\n"
    "Question: What should I order for dinner?"
)

This pattern is useful when you want deterministic recall (the function always runs) rather than letting the model decide.

Failure semantics

The integration follows the Synap-wide contract:

search_memory degrades gracefully: returns an empty result string and logs an error if Synap is unreachable.
store_memory surfaces failures: raises SynapIntegrationError so the kernel and caller know persistence failed.

This is by design: read failures shouldn’t break a user-facing answer, but silent write failures would let the memory drift away from reality.

Going further

Patterns overview: reusable memory patterns across frameworks.
Cookbook overview: end-to-end worked examples.

Next steps

Microsoft Agent Framework

Context and history providers for MAF agents.

OpenAI Agents

Function tools for the OpenAI Agents SDK.

Context Fetch

The retrieval API behind search_memory: modes, scopes, and response shapes.

Memory Scopes

How user_id and customer_id interact across reads and writes.

​Overview

​Setup

​Basic integration

​Core concepts

​SynapPlugin

​search_memory

​store_memory

​Complete example: chat function with auto-invoked memory

​Advanced patterns

​Multi-tenant scoping

​Prompt-template invocation

​Failure semantics

​Going further

​Next steps

Microsoft Agent Framework

OpenAI Agents

Context Fetch

Memory Scopes

Overview

Setup

Basic integration

Core concepts

SynapPlugin

search_memory

store_memory

Complete example: chat function with auto-invoked memory

Advanced patterns

Multi-tenant scoping

Prompt-template invocation

Failure semantics

Going further

Next steps