> ## 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.

# Strands Agents

> Synap as a native MemoryStore, a hook that sends the model Synap's compacted history, tools, and a real-time turn and tool-call feed for Strands Agents.

Give a [Strands Agents](https://strandsagents.com/) agent persistent memory through Synap. Unlike bolt-on integrations, Synap plugs into Strands' own extension points: a native `MemoryStore` for long-term memory, hooks for compacted history and real-time reporting, and `@tool` functions for explicit control.

> [!NOTE]
>
> Requires Python 3.11+ and `strands-agents>=1.48`.

## Overview

Four surfaces, each mapped onto a native Strands extension point. Adopt only the ones you need.

| Surface | Strands extension point | Purpose |
| - | - | - |
| `SynapMemoryStore` | `MemoryStore` → `MemoryManager` | Long-term memory: recall, automatic prompt injection, server-side extraction |
| `SynapShortTermHook` | `HookProvider` (`BeforeInvocationEvent`) | Send the model Synap's compaction in place of the earlier turns |
| `create_synap_tools` | `@tool` | Explicit `search_memory` / `store_memory` for agents not using `MemoryManager` |
| `SynapStreamHook` | `HookProvider` (message and tool-call events) | Report turns, tool calls and tool results to Synap, on the real-time stream |

All four take an already-constructed `MaximemSynapSDK`. Your app owns the SDK and its credentials. The hook opens the real-time stream itself on the first turn.

## Setup

```bash pip theme={null}
pip install maximem-synap-strands-agents strands-agents
```

```bash uv theme={null}
uv add maximem-synap-strands-agents strands-agents
```

Installing the package also installs `maximem-synap` (0.5.3 or later) and `maximem-synap-integrations-common` (0.2.3 or later).

## Basic integration

Register Synap as a Strands `MemoryStore`; `MemoryManager` then handles recall, automatic prompt injection, and extraction.

```python theme={null}
import asyncio
from strands import Agent
from strands.memory import MemoryManager
from maximem_synap import MaximemSynapSDK
from synap_strands_agents import SynapMemoryStore

sdk = MaximemSynapSDK()  # reads SYNAP_API_KEY from the environment
asyncio.run(sdk.initialize())  # required: without it every Synap call fails
store = SynapMemoryStore(sdk, user_id="alice", customer_id="acme")

agent = Agent(memory_manager=MemoryManager(stores=[store]))
result = agent("What did we decide about the rollout?")
```

## Core concepts

### SynapMemoryStore

A structural implementation of Strands' `MemoryStore` protocol.

* **`search`** reads Synap's long-term layer via `sdk.fetch` and returns structured `MemoryEntry` objects (facts, preferences, episodes, emotions, temporal events). Reads degrade gracefully: a Synap blip returns `[]` rather than crashing recall.
* **`add_messages`** is the primary write sink. `MemoryManager` hands it conversation batches, and it records each user and assistant message as a conversation turn: on the real-time stream, opened on first use, or over REST when the stream cannot carry it, never both. Synap extracts long-term memory from the conversation it keeps. A turn that `SynapStreamHook` already wrote is skipped, so the store and the hook compose without extracting a turn twice. If a turn cannot be recorded, `add_messages` raises `SynapIntegrationError`, and `MemoryManager` retries the batch.
* **`add`** ingests a single fact via `sdk.memories.create`.

Pass `conversation_id` to the store so its turns land in the same conversation as the hook's. Left unset, the store records under a fresh id of its own.

### SynapShortTermHook

Strands keeps the conversation in `agent.messages` and sends all of it, so the hook replaces earlier turns instead of adding a second copy. On the first turn it installs model-call middleware on the agent. Once Synap has compacted the conversation, every call to the model is sent Synap's compaction block (in `<synap_conversation_history>` tags) and the turns after it, in place of every turn before the current one. The current turn, including a tool call and its result, is untouched. `agent.messages` is not rewritten, so Strands' own conversation manager keeps working on it and is what the model is sent whenever Synap has no compaction or cannot answer.

```python theme={null}
import uuid
from synap_strands_agents import SynapShortTermHook

conversation_id = str(uuid.uuid4())  # a UUID, reused for every turn

agent = Agent(
    system_prompt="You are a support agent.",
    hooks=[SynapShortTermHook(sdk, conversation_id=conversation_id)],
)
```

`SynapStreamHook` installs the same middleware on its first turn, so either hook gives you the replacement. `conversation_id` is required, explicit and must be a UUID. SDK failures are swallowed by default (`on_error="fallback"`), or set `on_error="raise"` for strict environments.

The hook has one more job. When an agent starts with an empty `agent.messages` (after a restart, say) and Synap has no compaction yet, it folds Synap's short-term context into the first user message, so the model still knows what came before. With a non-empty history, or once a compaction exists, nothing is folded.

> [!NOTE]
>
> The middleware needs a version of `strands-agents` with model-call middleware (`strands.middleware`, or `strands._middleware` on earlier versions). On one with neither, the hook logs a warning once and leaves the messages alone.

> [!NOTE]
>
> Strands exposes no ephemeral per-call injection hook to user code, so the context the hook folds into the first user message stays in the conversation the agent persists. The hook guards against folding it twice, and the stream hook does not record it as something the user said.

### create\_synap\_tools

For agents that want explicit control instead of `MemoryManager`. Returns `search_memory` and `store_memory` as Strands `@tool` functions.

```python theme={null}
from synap_strands_agents import create_synap_tools

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=create_synap_tools(sdk, user_id="alice", customer_id="acme"),
)
```

### SynapStreamHook

Reports the agent's turns, tool calls and tool results to Synap on the real-time stream, which it opens on the first turn. See [Advanced patterns](#advanced-patterns).

## Complete example: multi-user support agent

```python theme={null}
import asyncio
import uuid
from strands import Agent
from strands.memory import MemoryManager
from maximem_synap import MaximemSynapSDK
from synap_strands_agents import (
    SynapMemoryStore,
    SynapShortTermHook,
    SynapStreamHook,
)

sdk = MaximemSynapSDK()  # reads SYNAP_API_KEY from the environment
asyncio.run(sdk.initialize())  # required: without it every Synap call fails

def build_agent(user_id: str, conversation_id: str) -> Agent:
    store = SynapMemoryStore(sdk, user_id=user_id, customer_id="acme",
                             conversation_id=conversation_id)
    return Agent(
        system_prompt="You are a concise, friendly support agent.",
        memory_manager=MemoryManager(stores=[store]),
        hooks=[
            SynapShortTermHook(sdk, conversation_id=conversation_id),
            SynapStreamHook(sdk, conversation_id=conversation_id,
                            user_id=user_id, customer_id="acme"),
        ],
    )

agent = build_agent("alice", str(uuid.uuid4()))
print(agent("Remind me what plan I'm on and my open ticket."))
# → recalls prior context from Synap, answers, and records the turns for extraction.
```

## Advanced patterns

### Real-time reporting and anticipation

`SynapStreamHook` writes the agent's user and assistant turns, and reports each tool call and its result with the same call id, so Synap's anticipation agent can pre-fetch context before the agent asks. A tool that raised is reported too, as an error result. You do not call `listen()`: the first turn opens the stream. See [Real-time anticipation](https://docs.maximem.ai/concepts/real-time-anticipation.md) for the model, and [Real-time anticipation in a server](https://docs.maximem.ai/patterns/real-time-anticipation-server.md) for running it in a multi-tenant process.

```python theme={null}
import uuid
from strands import Agent
from synap_strands_agents import SynapShortTermHook, SynapStreamHook

conversation_id = str(uuid.uuid4())  # a UUID, reused for every turn

agent = Agent(hooks=[
    SynapStreamHook(sdk, conversation_id=conversation_id, user_id="alice"),
    SynapShortTermHook(sdk, conversation_id=conversation_id),
])

result = await agent.invoke_async("What did we decide about the rollout?")
```

* **Opening the stream.** The open gets up to ten seconds. After a failure the hook tries once more a few seconds later, then no more than once a minute, and in the meantime each turn is written over REST. It never raises into the agent.
* **If the stream cannot carry a turn,** the turn goes over REST, never both. Tool calls and results exist only on the stream, so they are dropped in that case, without an error.
* **Stay on REST.** Set `SYNAP_AUTO_LISTEN=false`, or call `set_auto_listen(sdk, False)` from `synap_integrations_common`, and the hook never opens a stream. A stream your own code opened with `await sdk.instance.listen()` is used as is.
* **Event loops.** The stream belongs to the event loop that opened it, and a write from another loop is not sent over it. Run the agent with `invoke_async` on one loop so the stream stays open between turns. If the loop closes, the next turn replaces the stream, and after a few of those the integration stays on REST.

> [!NOTE]
>
> Use a real UUID for `conversation_id`. The stream accepts any string, so a free-form id like `"conv_abc"` appears to work there, but every call that reads the conversation back (`fetch`, `record_message`, compaction) rejects it with `InvalidConversationIdError`, leaving you with a conversation you cannot read back or compact.

> [!WARNING]
>
> The turns the hook writes are persisted server-side and are promoted into long-term memory when the conversation compacts. `SynapMemoryStore.add_messages` skips the turns the hook already wrote, so pairing them does not extract a turn twice. See [What the stream does to memory](https://docs.maximem.ai/concepts/real-time-anticipation.md#what-the-stream-does-to-memory).

### Not `SessionManager`

This integration does not implement Strands' `SessionManager` / snapshot storage. That persists opaque conversation snapshots for replay, a different concern from Synap's semantic memory. Use `FileSessionManager` / `S3SessionManager` for durable sessions *and* a `SynapMemoryStore` for memory; they compose.

## Going further

* **Error policy.** `SynapMemoryStore.search` degrades and returns `[]`. The writes (`add`, `add_messages`) and both tools (`search_memory`, `store_memory`) raise `SynapIntegrationError`. The hooks log and never raise; with no compaction, or on an error, the model is sent Strands' own messages.
* **Scoping.** `user_id` and `customer_id` flow straight to Synap; per-user isolation and B2C/B2B scope are derived server-side from the ids you pass.

## Next steps

> [card] [SDK: Ingestion](https://docs.maximem.ai/sdk/ingestion.md)
>
> How `memories.create` extraction and conversation recording differ.

> [card] [Integrations overview](https://docs.maximem.ai/integrations/overview.md)
>
> Every framework Synap plugs into.


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