AutoGen integration — CLS++ as a native Memory provider

clsplusplus.integrations.autogen.CLSMemory is a native implementation of Microsoft AutoGen's autogen_core.memory.Memory protocol — the memory object you pass to AssistantAgent(memory=[...]). It routes every memory operation through the CLS++ brain, so your agent's memory is persistent, shared across processes/machines, and reusable across AI vendors that point at the same CLS++ namespace.

This targets the new AutoGen (autogen-core / autogen-agentchat, 0.4+ — the autogen_core.memory.Memory line, not the legacy pyautogen). CLSMemory implements the full protocol: add, query, update_context, clear, and close, mirroring how AutoGen's built-in ListMemory works.

Install

pip install clsplusplus[autogen]

autogen-core / autogen-agentchat are an optional extra. The base package imports fine without them; only this integration requires AutoGen installed.

Environment

Get an API key from https://www.clsplusplus.com/profile#api-keys, then:

export CLS_API_KEY="cls_live_..."
# optional — defaults to https://www.clsplusplus.com
export CLS_BASE_URL="https://www.clsplusplus.com"

CLSMemory(user=..., api_key=..., url=...) also accepts these directly; unset values fall back to the env vars above.

Usage

Pass one (or more) CLSMemory instances to AssistantAgent(memory=[...]). AutoGen calls update_context before each model turn (recalling relevant memories and injecting them as a system message) and add when the agent records a new memory.

import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_core.memory import MemoryContent, MemoryMimeType
from autogen_ext.models.openai import OpenAIChatCompletionClient
from clsplusplus.integrations.autogen import CLSMemory


async def main():
    # One CLS++ "brain" namespace for this agent/tenant.
    memory = CLSMemory(user="my-agent")

    # Seed a memory (also happens automatically as the agent runs).
    await memory.add(
        MemoryContent(content="The user prefers Python.", mime_type=MemoryMimeType.TEXT)
    )

    agent = AssistantAgent(
        name="assistant",
        model_client=OpenAIChatCompletionClient(model="gpt-4o"),
        memory=[memory],  # CLS++ now backs the agent's memory
    )

    result = await agent.run(task="What language should I use for my next project?")
    print(result.messages[-1].content)

    await memory.close()


asyncio.run(main())

You can also query the memory directly:

hits = await memory.query("user coding preferences")
for item in hits.results:
    print(item.content)

Operation mapping & limitations

CLS++ is a semantic memory (vector recall). Intentional, documented limitations:

• update_context seeds recall from the last message. It derives the recall query from the most recent message already in the model context (falling back to a broad recall when there is no prior message), then injects the recalled memories as a single numbered SystemMessage — the same shape ListMemory uses, so prompt behavior is consistent.
• clear() is a no-op. CLS++ is a durable, shared memory service; wiping a namespace from a framework adapter would be destructive and hard to undo, so the SDK does not expose it here. Manage retention/forgetting via the CLS++ API or Brain.forget directly, or subclass CLSMemory to override clear.
• MemoryContent payloads are stored as text. str is stored as-is, bytes is UTF-8 decoded, and other payloads (dict/Image) are str()-coerced so a write never hard-fails. metadata is forwarded under autogen_metadata.
• The CLS++ SDK is synchronous. All blocking calls run in a worker thread (asyncio.to_thread) so they never block the AutoGen event loop.

The same adapter pattern extends to the broader Microsoft Agent Framework and other frameworks that accept a pluggable memory backend.

See also

• Integrations index
• CrewAI · LangGraph · LlamaIndex
• Architecture overview · API reference