Smolagents - Maximem Synap

Give a Smolagents CodeAgent or ToolCallingAgent persistent memory through Synap. Smolagents keeps its own fixed step log with no pluggable memory backend, so Synap plugs into the extension points it does expose: @tool functions, a step_callbacks recorder, and static instructions.

Requires Python 3.11+ and smolagents>=1.26.

Overview

Three surfaces, mapped onto Smolagents’ own extension points. Adopt only the ones you need.

Surface	Smolagents extension point	Purpose
`create_synap_tools`	`@tool`	Explicit `search_memory` / `store_memory` the model can call
`create_synap_recorder`	`step_callbacks={ActionStep: ...}`	Record each completed action into Synap for future recall
`synap_st_instructions`	`CodeAgent(instructions=...)`	Fold Synap short-term context into the agent’s instructions

All three take an already-constructed MaximemSynapSDK — your app owns the SDK and its credentials.

Setup

pip install maximem-synap-smolagents smolagents

uv add maximem-synap-smolagents smolagents

Basic integration

Give the agent memory tools it can call. Because CodeAgent writes its actions as Python, search_memory / store_memory compose naturally into the code it generates.

from smolagents import CodeAgent, InferenceClientModel
from maximem_synap import MaximemSynapSDK
from synap_smolagents import create_synap_tools

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

agent = CodeAgent(
    model=InferenceClientModel(),
    tools=create_synap_tools(sdk, user_id="alice", customer_id="acme"),
)
agent.run("What did we decide about the rollout?")

Core concepts

create_synap_tools

Returns search_memory and store_memory as Smolagents @tool functions. search_memory reads Synap’s long-term layer and returns formatted context; store_memory ingests a fact for future recall. Reads degrade to a not-found message; the write raises SynapIntegrationError so a failed store is observable.

create_synap_recorder

Records each completed step into Synap. Register it per step type on the agent:

from smolagents import CodeAgent, InferenceClientModel
from smolagents.memory import ActionStep
from synap_smolagents import create_synap_recorder

agent = CodeAgent(
    model=InferenceClientModel(),
    tools=[],
    step_callbacks={
        ActionStep: create_synap_recorder(
            sdk, user_id="alice", conversation_id="conv_abc"
        )
    },
)

Each ActionStep is written to its own Synap document, so a multi-step run is captured in full. Failed or empty steps are skipped.

synap_st_instructions

Smolagents’ instructions is a static string, so short-term context is folded into it once at construction.

from synap_smolagents import synap_st_instructions

agent = CodeAgent(
    model=InferenceClientModel(),
    tools=[],
    instructions=synap_st_instructions(
        sdk, conversation_id="conv_abc",
        instructions="You are a concise, friendly assistant.",
    ),
)

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

Complete example: memory-augmented CodeAgent

from smolagents import CodeAgent, InferenceClientModel
from smolagents.memory import ActionStep
from maximem_synap import MaximemSynapSDK
from synap_smolagents import create_synap_tools, create_synap_recorder, synap_st_instructions

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

agent = CodeAgent(
    model=InferenceClientModel(),
    tools=create_synap_tools(sdk, user_id="alice", customer_id="acme"),
    instructions=synap_st_instructions(
        sdk, conversation_id="conv_abc",
        instructions="You are a concise, friendly assistant.",
    ),
    step_callbacks={
        ActionStep: create_synap_recorder(
            sdk, user_id="alice", conversation_id="conv_abc", customer_id="acme"
        )
    },
)
agent.run("Remind me what plan I'm on and my open ticket.")

Advanced patterns

Synchronous framework, async SDK

Smolagents runs synchronously and its tools do not support async, so every surface bridges to the async Synap SDK internally (via the shared run_async helper). If your application is otherwise async, follow Hugging Face’s guidance and run the agent on its own thread (e.g. await anyio.to_thread.run_sync(agent.run, task)).

Error policy

The search_memory tool degrades — a Synap blip returns a not-found message.
The store_memory tool raises SynapIntegrationError on failure (model-driven, user-initiated).
The recorder logs and never raises. It runs inside the agent loop, in a finally with no surrounding try/except, so a raising callback would abort the whole run — a failed ingest is logged and swallowed.

Going further

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 differs from conversation recording.

Integrations overview

Every framework Synap plugs into.

​Overview

​Setup

​Basic integration

​Core concepts

​create_synap_tools

​create_synap_recorder

​synap_st_instructions

​Complete example: memory-augmented CodeAgent

​Advanced patterns

​Synchronous framework, async SDK

​Error policy

​Going further

​Next steps

SDK: Ingestion

Integrations overview

Overview

Setup

Basic integration

Core concepts

create_synap_tools

create_synap_recorder

synap_st_instructions

Complete example: memory-augmented CodeAgent

Advanced patterns

Synchronous framework, async SDK

Error policy

Going further

Next steps