> ## 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.
# CAMEL-AI
> Synap as a native AgentMemory for CAMEL-AI — long-term recall and persistence layered over the agent's own conversation history.
Give a [CAMEL-AI](https://github.com/camel-ai/camel) `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
```bash pip theme={null}
pip install maximem-synap-camel-ai camel-ai
```
```bash uv theme={null}
uv add maximem-synap-camel-ai camel-ai
```
## Basic integration
Register Synap as the agent's `AgentMemory`; CAMEL then calls it for context on every turn.
```python theme={null}
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.
```python theme={null}
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.
```python theme={null}
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
```python theme={null}
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
How `memories.create` extraction differs from conversation recording.
Every framework Synap plugs into.