Strands Agents - Maximem Synap

Give a Strands Agents 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 short-term context and real-time anticipation, and @tool functions for explicit control.

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`)	Inject Synap’s working-memory summary before each turn
`create_synap_tools`	`@tool`	Explicit `search_memory` / `store_memory` for agents not using `MemoryManager`
`SynapStreamHook`	`HookProvider` (message + tool-call events)	Feed turns and tool intent onto Synap’s gRPC Listen / anticipation stream

All four take an already-constructed MaximemSynapSDK — your app owns the SDK, its credentials, and (for streaming) its connection lifecycle.

Setup

pip install maximem-synap-strands-agents strands-agents

uv add maximem-synap-strands-agents strands-agents

Basic integration

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

from strands import Agent
from strands.memory import MemoryManager
from maximem_synap import MaximemSynapSDK
from synap_strands_agents import SynapMemoryStore

sdk = MaximemSynapSDK(api_key="sk-...")
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; it ingests the assembled transcript via sdk.memories.create (server-side extraction, no extra model call) under a stable document_id, so repeated extraction submissions update one document instead of duplicating.
add ingests a single fact via sdk.memories.create.

Recorded conversation messages feed only Synap’s short-term compaction, not the long-term extraction layer search reads — which is why writes deliberately go through memories.create, not conversation recording.

SynapShortTermHook

Strands’ system_prompt is a static string, so short-term context is injected via a hook on BeforeInvocationEvent (the one before-event whose messages are writable). It folds Synap’s working-memory summary into the current turn’s first user message.

from synap_strands_agents import SynapShortTermHook

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

conversation_id is required and explicit. Empty context is a no-op; SDK failures are swallowed by default (on_error="fallback"), or set on_error="raise" for strict environments.

Strands exposes no ephemeral per-call injection hook to user code, so injected context becomes part of the conversation the agent persists. The hook folds one context block into each turn’s user message (with an idempotency guard) rather than adding throwaway turns.

create_synap_tools

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

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

Makes the agent a participant in Synap’s real-time anticipation pipeline by feeding its turns and tool-call intent onto the gRPC Listen stream. See Advanced patterns.

Complete example: multi-user support agent

from strands import Agent
from strands.memory import MemoryManager
from maximem_synap import MaximemSynapSDK
from synap_strands_agents import SynapMemoryStore, SynapShortTermHook

sdk = MaximemSynapSDK(api_key="sk-...")

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)],
    )

agent = build_agent("alice", "conv_alice_001")
print(agent("Remind me what plan I'm on and my open ticket."))
# → recalls prior context from Synap, answers, and extracts new memories.

Advanced patterns

Real-time anticipation with the Listen stream

SynapStreamHook feeds the agent’s turns and tool-call intent onto Synap’s gRPC Listen stream so the Anticipation Agent can pre-fetch context before the agent asks. Your app owns the stream lifecycle; the hook only feeds an already-open stream and no-ops when none is active.

from synap_strands_agents import SynapStreamHook, SynapShortTermHook

await sdk.instance.listen()                      # app opens the stream
hook = SynapStreamHook(sdk, conversation_id="conv_abc", user_id="alice")
agent = Agent(hooks=[hook, SynapShortTermHook(sdk, conversation_id="conv_abc")])
# ... run the agent ...
await sdk.instance.stop_listening()              # app closes it on shutdown

Run on one event loop. The stream’s background tasks bind to the loop listen() ran on — construct the SDK, call listen(), and run the agent on that same asyncio loop. The hook feeds real-time signal; it does not durably store memories (that’s SynapMemoryStore or the tools).

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. Reads (search, search_memory) degrade and return empty; writes (add, add_messages, store_memory) raise SynapIntegrationError; stream sends log and never raise.
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

SDK: Ingestion

How memories.create extraction and conversation recording differ.

Integrations overview

Every framework Synap plugs into.

​Overview

​Setup

​Basic integration

​Core concepts

​SynapMemoryStore

​SynapShortTermHook

​create_synap_tools

​SynapStreamHook

​Complete example: multi-user support agent

​Advanced patterns

​Real-time anticipation with the Listen stream

​Not SessionManager

​Going further

​Next steps

SDK: Ingestion

Integrations overview

Overview

Setup

Basic integration

Core concepts

SynapMemoryStore

SynapShortTermHook

create_synap_tools

SynapStreamHook

Complete example: multi-user support agent

Advanced patterns

Real-time anticipation with the Listen stream

Not `SessionManager`

Going further

Next steps