maximem-synap-smolagents

Synap memory integration for Smolagents — give a CodeAgent / ToolCallingAgent persistent memory through Synap.

pip install maximem-synap-smolagents smolagents

Surfaces

Smolagents keeps its own fixed step log (no pluggable memory backend), so Synap plugs into the two extension points it does expose, plus static instructions:

Example

from smolagents import CodeAgent, InferenceClientModel
from maximem_synap import MaximemSynapSDK
from synap_smolagents import create_synap_tools, synap_step_callbacks, 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=synap_step_callbacks(
        sdk, user_id="alice", conversation_id="conv_abc", customer_id="acme"
    ),
)
agent.run("Remind me what plan I'm on and my open ticket.")

Because CodeAgent calls tools as plain Python, search_memory / store_memory compose naturally into agent-written code.

Notes

• Synchronous framework. Smolagents runs synchronously and its tools do not support async, so every surface bridges to the async Synap SDK internally. Run the agent on its own thread if your app is otherwise async.
• Error policy. The search_memory tool degrades (returns a not-found message); store_memory raises SynapIntegrationError; the recorder logs and never raises — it runs inside the agent loop, where a raising callback would abort the run.
• Turns are conversation messages. The user's task and the assistant's final answer are written to the conversation conversation_id names: on the stream when sdk.instance.listen() is running, otherwise with sdk.conversation.record_message, never both. The server compacts that conversation and promotes it to long-term memory, and the SDK's local history search can find old turns after compaction. Reuse one conversation_id across agent.run() calls that belong together.
• No per-step documents by default. Earlier versions ingested every step's model output with memories.create, which left no conversation on the server. That is now off (ingest_steps=True turns it back on): with the turns recorded, it would extract the final answer twice.
• Live stream. With sdk.instance.listen() running, the recorder also reports every tool call and its result, and the model's plan and step output as reasoning. Without a stream those are no-ops.
• Register against MemoryStep. synap_step_callbacks does this for you. Registering the recorder against ActionStep alone (what earlier versions of this README showed) never delivers the final answer, and the assistant turn is the one event anticipation acts on.
• Two gaps, on purpose. Smolagents never passes its TaskStep to a callback, so the user turn is read from agent.task and written at the end of the first step rather than before it (report_user_task=False turns it off). And a step with several parallel tool calls merges their outputs into one observations string, so that result is reported with no tool_call_id rather than being attributed to a guessed call.

Requires Python 3.11+ and smolagents>=1.26.