> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Maximem Synap is a managed memory layer for AI agents: it ingests conversations and documents, extracts structured memory, and returns scoped context to the agent at retrieval time.
> The Python and JavaScript/TypeScript SDKs are the supported way to use Synap. Write integration code with SDK calls, not raw HTTP requests.
> Start with the Quickstart: https://docs.maximem.ai/getting-started/quickstart.md. Every SDK method is documented in the SDK reference: https://docs.maximem.ai/sdk-reference/overview.md.
> For requests about adding Vity memory to OpenClaw, Hermes, an MCP client, or a browser, start with the Vity Quickstart: https://docs.maximem.ai/vity/quickstart.md.

# AutoGen

> BaseTool memory search and storage for AutoGen agents, plus a model context that reports the run and uses Synap's compaction.

Expose Synap memory to an AutoGen agent as two `BaseTool` implementations. The agent decides when to call each, and both tools cooperate with AutoGen's `CancellationToken` so a long search can be aborted mid-flight. A model context reports the conversation to Synap and, once Synap has compacted it, gives the model Synap's compaction in place of AutoGen's earlier turns.

> [!NOTE]
>
> Requires Python 3.11+ and `maximem-synap` 0.5.18 or later. `autogen-core` pins `protobuf` 5.29, and earlier SDK versions need a newer `protobuf`, so their gRPC stream cannot open and every turn goes over REST. If you installed before, run `pip install -U maximem-synap`.

## Overview

This guide shows how to add Synap to an AutoGen application to build agents that:

* Recall user-specific facts, preferences, and past conversations
* Persist new information surfaced during a conversation
* Respect AutoGen's cooperative cancellation model so memory calls don't leak past a cancelled task
* Report each run to Synap and use Synap's compaction of the conversation

The Synap AutoGen integration ships two tool classes, both implementing AutoGen's `BaseTool` interface, and two model contexts.

| Class | AutoGen interface | Purpose |
| - | - | - |
| `SynapSearchTool` | `BaseTool` | Searches Synap memory by natural-language query |
| `SynapStoreTool` | `BaseTool` | Stores a new memory in Synap |
| `SynapStreamingChatContext` | `ChatCompletionContext` | Reports the turns, tool calls, tool results and thoughts, and swaps in Synap's compaction |
| `SynapShortTermChatContext` | `ChatCompletionContext` | Swaps in Synap's compaction without reporting |

## Setup

Install the package alongside AutoGen:

```bash pip theme={null}
pip install maximem-synap-autogen autogen-agentchat autogen-core
```

```bash uv theme={null}
uv add maximem-synap-autogen autogen-agentchat autogen-core
# pip-compatible (existing venv): uv pip install maximem-synap-autogen autogen-agentchat autogen-core
```

Installing the package also installs `maximem-synap`, `maximem-synap-integrations-common` and `autogen-core` (0.4 or later). Make sure `maximem-synap` resolves to 0.5.18 or later, as noted above.

> [!NOTE]
>
> The pip package is `maximem-synap-autogen`, but the import drops the `maximem-` prefix and uses underscores: `from synap_autogen import ...`.

Configure your API key. Generate one from the [Synap Dashboard](https://synap.maximem.ai).

```bash theme={null}
export SYNAP_API_KEY=synap_your_key_here
export OPENAI_API_KEY=your-openai-api-key
```

Initialize the SDK once at application startup:

```python theme={null}
from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK()
await sdk.initialize()
```

See [SDK Initialization](https://docs.maximem.ai/sdk/initialization.md) for the full lifecycle and configuration options.

## Basic integration

The smallest useful integration registers both tools on an `AssistantAgent` and runs a task. The agent reads tool descriptions and decides whether to search or store:

```python theme={null}
# pip install maximem-synap-autogen autogen-agentchat autogen-core
from maximem_synap import MaximemSynapSDK
from autogen_agentchat.agents import AssistantAgent
from synap_autogen import SynapSearchTool, SynapStoreTool

sdk = MaximemSynapSDK()
await sdk.initialize()

tools = [
    SynapSearchTool(sdk=sdk, user_id="alice", customer_id="acme"),
    SynapStoreTool(sdk=sdk, user_id="alice", customer_id="acme"),
]

agent = AssistantAgent(
    name="MemoryAgent",
    model_client=your_model_client,
    tools=tools,
    system_message=(
        "Use search_memory to recall user context. "
        "Use store_memory to remember new information."
    ),
)

await agent.run(task="What are my top priorities this week?")
```

The scoping triple (`user_id`, optional `customer_id`) is bound at construction. The model only ever sees `query` and `content`, never the user identity. This prevents prompt-injection attempts from spoofing scope.

***

## Core concepts

### Search tool

`SynapSearchTool` is the read side. The model supplies only the question and cannot reach outside the scope bound at construction.

```python theme={null}
from synap_autogen import SynapSearchTool

search = SynapSearchTool(
    sdk=sdk,
    user_id="alice",
    customer_id="acme",   # optional, required for B2B instances
    mode="accurate",      # optional: "accurate" (the default) or "fast"
)
```

Tool schema exposed to the model:

```json theme={null}
{
  "query": "string"
}
```

Returns a `SearchMemoryResult` with one `context` field: the formatted memory context as a string, or `"No relevant memories found."` when nothing matches.

The `mode` you pass at construction sets how the tool searches. The two retrieval modes trade latency against comprehensiveness:

| | `fast` | `accurate` |
| - | - | - |
| Search | Vector search (no graph traversal, no LLM subquery decomposition) | Vector search + graph traversal + LLM subquery decomposition + reranking |
| Best for | Real-time chat | Multi-entity queries |

`fast` is lower-latency and suited to the hot path; `accurate` adds LLM-driven query decomposition and reranking for relationship-aware queries at a higher latency cost.

**Search failures surface**: an SDK error is logged and raised as `SynapIntegrationError`, so a failed search is never mistaken for an empty memory.

### Store tool

`SynapStoreTool` is the write side. The model supplies the content; everything else is fixed at construction.

```python theme={null}
from synap_autogen import SynapStoreTool

store = SynapStoreTool(
    sdk=sdk,
    user_id="alice",
    customer_id="acme",
)
```

Tool schema exposed to the model:

```json theme={null}
{
  "content": "string"
}
```

Returns a `StoreMemoryResult` with `ingestion_id` and a confirmation `message` on success. **Store failures surface explicitly**: the tool raises `SynapIntegrationError` so the agent (and you) know if persistence failed.

### Cooperative cancellation

Both tools propagate AutoGen's `CancellationToken`. When the token is cancelled, the in-flight Synap call is aborted and the tool returns control to the agent rather than continuing to completion:

```python theme={null}
from autogen_core import CancellationToken

token = CancellationToken()
result = await search.run_json({"query": "project deadlines"}, token)

# From elsewhere in the same asyncio task group:
token.cancel()
```

This matters in long-running team conversations where one agent's tool call should be cancellable by an orchestrator.

### Report the run to Synap

The tools let the model search and store. They do not tell Synap what the conversation is. `SynapStreamingChatContext` does: it wraps the agent's `model_context`, which every message an `AssistantAgent` produces passes through, and reports each one.

```python theme={null}
import uuid
from autogen_agentchat.agents import AssistantAgent
from synap_autogen import SynapStreamingChatContext, SynapSearchTool, SynapStoreTool

model_context = SynapStreamingChatContext(
    sdk,
    conversation_id=str(uuid.uuid4()),  # one UUID per conversation
    user_id="alice",
    customer_id="acme",                 # B2B instances only
)

agent = AssistantAgent(
    name="support",
    model_client=your_model_client,
    model_context=model_context,
    tools=[
        SynapSearchTool(sdk=sdk, user_id="alice", customer_id="acme"),
        SynapStoreTool(sdk=sdk, user_id="alice", customer_id="acme"),
    ],
)

result = await agent.run(task="Where is my order?")
await model_context.report_reply(result)
```

| Message the context receives | What Synap receives |
| - | - |
| `UserMessage` | A user turn |
| `AssistantMessage` with text | An assistant turn |
| `AssistantMessage` with tool calls | A tool call for each, with AutoGen's call id |
| `AssistantMessage.thought` | A reasoning step |
| `FunctionExecutionResultMessage` | A tool result for each, under the same id as its call |

You do not call `listen()` yourself. The first message opens the gRPC stream, and everything above goes on it. The stream gets up to 10 seconds to open. If it cannot open, the user and assistant turns are written over REST instead, never both, and the stream is tried once more a few seconds later, then no more than once a minute. Tool calls, tool results and thoughts exist only on the stream, so they are dropped while it is down. The REST write and the compaction lookup both need `conversation_id` to be a UUID. A stream you opened yourself is used as is. To keep the context on REST, set `SYNAP_AUTO_LISTEN=false`. See [gRPC vs REST](https://docs.maximem.ai/concepts/grpc-vs-rest.md). The context never raises into the agent's loop.

Two options control what leaves your process:

* `report_tool_results=False` stops tool results from being reported. A tool result is usually your own customer's data. Synap uses it only as an anticipation hint and never stores it as a long-term memory, but it does leave your process.
* `report_thoughts=False` stops `AssistantMessage.thought` from being reported. Most providers return nothing there.

Pass `inner=` to wrap a context you already use, such as `BufferedChatCompletionContext`. It stays installed and is what the agent sees until Synap has compacted the conversation.

#### Call report\_reply after each run

By default (`reflect_on_tool_use` is `False` unless you set `output_content_type`), a turn that ends in a tool call is answered with a `ToolCallSummaryMessage`, and AutoGen never adds that message to the model context. The context cannot see the reply. It reports the turn the only way it can: it keeps the tool results and, when the next user message arrives, writes them as the assistant turn in AutoGen's default summary format. That is not the text your `tool_call_summary_format` produced. `report_reply(result)` sends the exact reply as soon as the run returns and cancels the stand-in. It does nothing when the reply was already reported, so calling it after every `run` is safe. It returns `True` when it wrote the reply.

#### Teams

In a team, every agent receives the task and every other agent's reply as a `UserMessage`. Contexts in one process that share a `conversation_id` write each of those once: an agent's own reply is written as an assistant turn by its context, and the others skip it. Contexts in different processes cannot see each other, so give the context to one agent only.

### Synap's compaction replaces AutoGen's earlier turns

An `AssistantAgent` builds every model call from `model_context.get_messages()`, so that is where Synap's compaction goes. Once Synap has compacted the conversation, `SynapStreamingChatContext.get_messages()` returns your system messages, one system message with Synap's compaction (in `<synap_conversation_history>` tags), the turns recorded after it, and the current turn. Earlier turns, and the tool calls and results that belonged to them, are not sent. The current turn, from the last user message on, is untouched.

When Synap has no compaction yet, or cannot answer, the wrapped context's messages are returned as they were. A `BufferedChatCompletionContext` you pass as `inner` stays in place as that fallback.

### SynapShortTermChatContext

`SynapShortTermChatContext` does the same replacement without reporting anything. Use it when your own code already records the conversation, or when you only want the compaction.

```python theme={null}
from synap_autogen import SynapShortTermChatContext

conversation_id = str(uuid.uuid4())  # the UUID your turns are recorded under

agent = AssistantAgent(
    name="support",
    model_client=your_model_client,
    model_context=SynapShortTermChatContext(sdk, conversation_id=conversation_id),
)
```

`conversation_id` is required. Pass `inner=` to wrap another context. With the default `on_error="fallback"`, a failed lookup returns the wrapped context's messages unchanged; `on_error="raise"` raises `SynapIntegrationError` instead. You can wrap a `SynapShortTermChatContext` as the `inner` of `SynapStreamingChatContext`; the compaction is applied once.

***

## Complete example: assistant team with shared memory

The following team has two agents sharing the same Synap-backed memory: a `Researcher` that searches and stores, and a `Planner` that searches but never stores. Both run inside an AutoGen `RoundRobinGroupChat`:

```python theme={null}
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from synap_autogen import SynapSearchTool, SynapStoreTool


def build_team(sdk, model_client, user_id: str, customer_id: str = ""):
    # Researcher gets both tools: it can recall and remember
    researcher = AssistantAgent(
        name="Researcher",
        model_client=model_client,
        tools=[
            SynapSearchTool(sdk=sdk, user_id=user_id, customer_id=customer_id),
            SynapStoreTool(sdk=sdk, user_id=user_id, customer_id=customer_id),
        ],
        system_message=(
            "You gather facts about the user. "
            "Always call search_memory first; if you learn something new, "
            "call store_memory before responding."
        ),
    )

    # Planner only reads: it shouldn't pollute memory with plans
    planner = AssistantAgent(
        name="Planner",
        model_client=model_client,
        tools=[SynapSearchTool(sdk=sdk, user_id=user_id, customer_id=customer_id)],
        system_message=(
            "You produce action plans based on what Researcher has found. "
            "Use search_memory to verify facts. End your turn with TERMINATE."
        ),
    )

    return RoundRobinGroupChat(
        [researcher, planner],
        termination_condition=TextMentionTermination("TERMINATE"),
    )


# Usage
team = build_team(sdk, model_client, user_id="alice", customer_id="acme")
await team.run(task="Plan my work for next week.")
```

Three things to notice in this pattern:

1. **Scope is per-tool, per-agent.** Both agents see the same user's memory, but only the `Researcher` can write. This is a common safety pattern: minimize the surface that can mutate memory.
2. **Memory is shared across agents.** Anything `Researcher` stores during this run is immediately available to `Planner` on the next turn.
3. **`CancellationToken` flows automatically** through AutoGen's task group, so cancelling the team also cancels any in-flight Synap calls.

***

## Advanced patterns

### Multi-tenant scoping

Both tools take `user_id` (required) and `customer_id` (B2B instances only). `SynapSearchTool` also takes an optional `conversation_id`. `customer_id` is required on B2B Synap instances and **not accepted** on B2C (single-tenant) ones, where a call carrying it is rejected with HTTP 400. See [Memory Scopes](https://docs.maximem.ai/concepts/memory-scopes.md).

```python theme={null}
# User-scoped only
search = SynapSearchTool(sdk=sdk, user_id="alice")

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

For multi-tenant services, construct tools per request rather than caching them globally; each task should have its scope baked in.

### Tuning retrieval mode

The model cannot choose the mode: you fix it when you construct the tool. Use `mode="fast"` for latency-sensitive chat, or leave the default `"accurate"` for multi-entity questions.

### Failure semantics

The integration follows the Synap-wide contract:

* **`SynapSearchTool` surfaces failures**: logs an error and raises `SynapIntegrationError`, so the agent never reads a failed search as "nothing remembered"
* **`SynapStoreTool` surfaces failures**: raises `SynapIntegrationError` so the agent and caller know persistence failed
* **Cancellation is honored**: both tools abort cleanly when `CancellationToken.cancel()` fires
* **The model contexts never break a run**: a failed report or history lookup is logged and dropped, and the agent carries on with AutoGen's own messages

This is by design: a failed memory call is visible, while reporting and history never get in the way of the agent's answer.

***

## Going further

* [Patterns overview](https://docs.maximem.ai/patterns/overview.md): reusable memory patterns across frameworks.
* [Cookbook overview](https://docs.maximem.ai/cookbook/overview.md): end-to-end worked examples.

***

## Next steps

> [card] [OpenAI Agents](https://docs.maximem.ai/integrations/openai-agents.md)
>
> Function tools for the OpenAI Agents SDK.

> [card] [CrewAI](https://docs.maximem.ai/integrations/crewai.md)
>
> Storage backend for CrewAI crews.

> [card] [Context Fetch](https://docs.maximem.ai/sdk/context-fetch.md)
>
> The retrieval API behind `SynapSearchTool`: modes, scopes, and response shapes.

> [card] [Memory Scopes](https://docs.maximem.ai/concepts/memory-scopes.md)
>
> How `user_id` and `customer_id` interact across reads and writes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.