CAMEL-AI - Maximem Synap

Give a CAMEL-AI ChatAgent persistent memory through Synap. CAMEL exposes a first-class pluggable memory interface (ChatAgent(memory=...) accepts any AgentMemory), and SynapAgentMemory plugs Synap in there, plus @tool functions and a short-term context helper.

Requires Python 3.11+ and camel-ai>=0.2.90.

Overview

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

Surface	CAMEL extension point	Purpose
`SynapAgentMemory`	`AgentMemory` → `ChatAgent(memory=...)`	Long-term recall + persistence, layered over CAMEL’s conversation history
`create_synap_tools`	`FunctionTool`	Explicit `search_memory` / `store_memory` the model can call
`synap_st_system_message`	`ChatAgent(system_message=...)`	Fold Synap short-term context into the system prompt

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

Setup

pip install maximem-synap-camel-ai camel-ai

uv add maximem-synap-camel-ai camel-ai

Basic integration

from camel.agents import ChatAgent
from camel.models import ModelFactory
from maximem_synap import MaximemSynapSDK
from synap_camel_ai import SynapAgentMemory

sdk = MaximemSynapSDK(api_key="sk-...")
memory = SynapAgentMemory(sdk, user_id="alice", customer_id="acme")

agent = ChatAgent(
    system_message="You are a helpful assistant.",
    model=ModelFactory.create(model_platform="openai", model_type="gpt-4o"),
    memory=memory,            # constructor only — not agent.memory = ...
)
print(agent.step("What did we decide about the rollout?").msgs[0].content)

Core concepts

SynapAgentMemory

Unlike a bolt-on store, CAMEL’s AgentMemory.get_context() is the sole source of the model’s input: it returns whatever the memory’s retrieve() yields. So Synap augments CAMEL’s history rather than replacing it: SynapAgentMemory subclasses ChatHistoryMemory (which keeps the live conversation) and adds two things.

Recall. retrieve() returns the real conversation (system + user + assistant) with Synap’s long-term memories prepended as a system context block, fetched via sdk.fetch using the latest user turn as the query. A Synap blip degrades to the plain local history; recall never crashes the turn.
Persistence. When a turn completes, the accumulated transcript is ingested via sdk.memories.create (server-side extraction) under a stable document_id, so future sessions remember it.

Attach the memory through the constructor (ChatAgent(memory=...)). Do not assign agent.memory = ... afterward; that path re-runs retrieve/clear/write and would amplify the injected context.

create_synap_tools

For agents that want model-driven memory instead of, or alongside, SynapAgentMemory. Returns search_memory and store_memory as CAMEL FunctionTool objects.

from synap_camel_ai import create_synap_tools

agent = ChatAgent(
    system_message="You are a helpful assistant.",
    model=ModelFactory.create(model_platform="openai", model_type="gpt-4o"),
    tools=create_synap_tools(sdk, user_id="alice", customer_id="acme"),
)

synap_st_system_message

CAMEL’s system_message is a static string, so short-term context is folded into it once at construction.

from synap_camel_ai import SynapAgentMemory, synap_st_system_message

agent = ChatAgent(
    system_message=synap_st_system_message(
        sdk, conversation_id="conv_abc",
        system_message="You are a support agent.",
    ),
    memory=SynapAgentMemory(sdk, user_id="alice"),
)

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: multi-user support agent

from camel.agents import ChatAgent
from camel.models import ModelFactory
from maximem_synap import MaximemSynapSDK
from synap_camel_ai import SynapAgentMemory, synap_st_system_message

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

def build_agent(user_id: str, conversation_id: str) -> ChatAgent:
    return ChatAgent(
        system_message=synap_st_system_message(
            sdk, conversation_id=conversation_id,
            system_message="You are a concise, friendly support agent.",
        ),
        model=ModelFactory.create(model_platform="openai", model_type="gpt-4o"),
        memory=SynapAgentMemory(sdk, user_id=user_id, customer_id="acme"),
    )

agent = build_agent("alice", "conv_alice_001")
print(agent.step("Remind me what plan I'm on and my open ticket.").msgs[0].content)
# → recalls prior context from Synap, answers, and persists the turn for extraction.

Advanced patterns

Sync interface, async SDK

CAMEL’s AgentMemory methods are synchronous, so SynapAgentMemory bridges to the async Synap SDK internally (via the shared run_async helper). This works whether you drive the agent with agent.step(...) (sync) or agent.astep(...) (async), but construct the SDK, the memory, and run the agent on one asyncio event loop.

Error policy

Reads (recall, search_memory) degrade: a Synap failure returns no recall and the turn continues.
The persistence write runs inside the agent loop, so it is best-effort by default (on_error="fallback"): a transient outage never discards the model’s just-produced response. Set SynapAgentMemory(..., on_error="raise") for strict environments.
The explicit store_memory tool raises SynapIntegrationError on failure.

Not a vector store

SynapAgentMemory deliberately does not reduce Synap to a VectorDBBlock behind CAMEL’s storage. It owns both the recall shape (Synap’s formatted context) and the write pipeline (server-side extraction), which a dumb vector backend would throw away.

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

​SynapAgentMemory

​create_synap_tools

​synap_st_system_message

​Complete example: multi-user support agent

​Advanced patterns

​Sync interface, async SDK

​Error policy

​Not a vector store

​Going further

​Next steps

SDK: Ingestion

Integrations overview

Overview

Setup

Basic integration

Core concepts

SynapAgentMemory

create_synap_tools

synap_st_system_message

Complete example: multi-user support agent

Advanced patterns

Sync interface, async SDK

Error policy

Not a vector store

Going further

Next steps