CAMEL-AI Role-Playing Agents: How Multi-Agent Memory Works
CAMEL-AI is an open-source Python framework for building teams of LLM agents. It started with one idea: let two chat agents play assigned roles and solve a task together with little human help. That idea came from a 2023 NeurIPS paper. The framework has since grown a task engine called Workforce and a memory module with several storage backends. By the end you will know how a role-playing loop runs and which memory class to start with. You will also know why that memory is gone when the process exits.
What is CAMEL-AI role-playing, in one sentence?
CAMEL role-playing is a turn-based loop in which an AI user agent gives instructions and an AI assistant agent carries them out, each held to its role by its prompt.
The method comes from the paper CAMEL: Communicative Agents for "Mind" Exploration of Large Language Model Society by Guohao Li and co-authors. It was first submitted on March 31, 2023 and accepted at NeurIPS 2023. The paper calls its prompting technique inception prompting: the task and both roles are written into each agent's system prompt at the start. The code is in the CAMEL repository under Apache-2.0. The latest stable release on PyPI is 0.2.90 from March 22, 2026, with alpha builds after it.
How does CAMEL role-playing differ from a single agent with tools?
A single agent plans and acts alone, while role-playing splits the work between two agents that talk to each other. Workforce, the newer engine, puts a coordinator above many workers.
| Single ChatAgent | RolePlaying | Workforce | |
|---|---|---|---|
| Agents per task | 1 | 2, plus an optional critic | A coordinator and a planner over many workers |
| Who decides the next step | The agent | The AI user agent | The coordinator assigns subtasks |
| How it ends | The agent stops | Turn limit, a terminated flag or the CAMEL_TASK_DONE token | All subtasks finish or recovery gives up |
| Failure handling | Yours to write | Yours to write | Retry, replan or decompose again |
| Memory by default | In-process chat history | Each agent keeps its own history | Workers can share memory if you ask |
Sources: CAMEL's societies docs, Workforce docs and memory docs.
How does a role-playing session run?
You create a RolePlaying object with a role name for the assistant and one for the user, plus a task prompt. Two optional helpers sit around the pair. A task specifier rewrites a vague prompt into a concrete one before the chat starts. A critic reviews the assistant's answers against criteria you set.
The societies docs describe the loop as "turn-based, prompt-engineered, zero-role-flip agent collaboration." Each turn, the AI user sends one instruction and the assistant replies with a solution or a step. The docs' example stops in one of three ways:
- the loop reaches its turn limit, 50 by default
- either agent's response comes back flagged as terminated
- the user agent writes
CAMEL_TASK_DONE
The docs also warn about infinite loops. In practice two agents can agree politely for many turns. Set a turn limit and a critic.
What is CAMEL Workforce?
Workforce is the engine for tasks too large for one pair. A task agent splits the main task into self-contained subtasks, and a coordinator hands each one to the best-suited worker. Most workers are a SingleAgentWorker, which wraps one agent with its own tools and system prompt. A RolePlayingWorker runs a full role-playing session as one worker, which the Workforce docs suggest for brainstorming or debate.
When a subtask fails, Workforce analyzes why. Its recovery options are to retry, replan or decompose the subtask again.
How does CAMEL agent memory work?
The memory docs build memory from two kinds of block. A ChatHistoryBlock returns recent messages by recency. A VectorDBBlock stores records as embeddings (Qdrant and OpenAI by default) and returns them by similarity. Three memory classes wrap these blocks:
- ChatHistoryMemory keeps a sequential window of the conversation.
- VectorDBMemory retrieves by meaning, three records at a time by default.
- LongtermAgentMemory combines both, and the docs recommend it as the starting point.
A context creator decides what fits in the model's window. The docs' example uses ScoreBasedContextCreator with a 1,024-token limit. You attach the memory to a ChatAgent by setting its memory attribute.
Where does CAMEL memory live after the run ends?
By default, chat history sits in in-memory key-value storage. The docs' own advice is to "use persistent storage (not just in-memory)" in production. You can swap in a custom key-value or vector backend. The docs also list a Mem0 storage option for keeping chat history in the cloud.
Memory is also scoped to agents. Each agent in a RolePlaying session keeps its own history. In Workforce, the share_memory flag lets SingleAgentWorker instances share memory. The docs do not say what exactly is shared, so test it before you rely on it.
A team that reruns a role-playing setup every day starts each run from the same prompts unless it wires up a persistent store.
The bottom line
Start with RolePlaying when one agent should question another. Set a turn limit and a critic on day one. Switch to Workforce for more than two agents or real failure recovery, and pick a persistent backend before you expect memory to carry over.
How do you keep what several agents learn after the session ends?
Each CAMEL agent holds its own history, and that history ends with the process unless you persist it. Coding agents have the same gap at a larger scale. Claude Code and Codex each keep their own context, and a new session starts without what the last one figured out.
memU handles that gap for coding agent hosts. It does not plug into CAMEL. A scheduled background task slices new session logs into jobs. The host agent distills each job into memory and skill Markdown, which memU commits to one backend that every host reads from. memU's core makes no LLM calls. It indexes the Markdown the agent wrote and returns matches on request.
A standing instruction in CLAUDE.md or AGENTS.md handles the read side: it tells each agent to retrieve before answering. A fix that Codex worked out on Tuesday can then show up in Claude Code on Wednesday.
To try it with a key from memu.so, send your agent one message:
Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU
The memU GitHub repository has the self-hosted install and the list of supported hosts. For the design reasoning, see why memU gives memory back to the agent.
FAQ
What is CAMEL-AI used for?
CAMEL-AI is used to build multi-agent systems in Python. The original paper used role-playing pairs to generate conversation data for studying agent behavior. Workforce extends that to pipelines that split large tasks across many workers.
What is inception prompting in CAMEL?
Inception prompting writes the task and both roles into each agent's system prompt before the conversation starts. The prompts keep the AI user giving instructions and the AI assistant solving them, so the two do not swap roles.
Does CAMEL have long-term memory?
CAMEL has a LongtermAgentMemory class that combines recent chat history with vector search. Chat history is stored in memory by default, so it lasts beyond a run only if you configure a persistent backend.
Can CAMEL agents share memory?
In Workforce, setting share_memory to true lets SingleAgentWorker instances share memory. In a RolePlaying session each agent keeps its own history.
How do I install CAMEL-AI?
Run pip install camel-ai on Python 3.10 or later. The README also shows an extra for web search tools.