MemorySync
Integrations

AutoGen Memory

Give Microsoft AutoGen agents long-term memory in three lines. The adapter implements AutoGen’s own Memory protocol: recalled context is injected before every model call under a hard latency budget, and one extra call sends the user’s side of each exchange for fact extraction — outage-proof and safe to retry.

AutoGen calls update_context before the model, while add_turn_pair sends the user text for fact extraction after the exchange.

How it works

  1. Install autogen-memorysync from PyPI.
  2. Create a MemorySyncMemory with your API key and the end user’s id.
  3. Pass it to any AssistantAgent via memory=[memory] — recall now happens automatically before every model call.
  4. After each exchange, call add_turn_pair once: the user’s text is sent for fact extraction and the reply is not stored. That’s the whole loop.

Before you start

  1. A MemorySync API key. Create one in the dashboard under Settings → API Keys, inside a project.
  2. Python 3.10+ with autogen-agentchat / autogen-core 0.4 or newer.

Install

One package, zero framework lock-in:

Terminal
pip install autogen-memorysync

Quickstart

Step 1 — create the memory

The memory object is where you say whose memories these are. user_id is required — it keeps every customer’s memories isolated. session_id separates conversations (support ticket vs onboarding chat): every distilled fact is tagged with it, and clear() is bounded by it.

memory.py
from autogen_memorysync import MemorySyncMemory


memory = MemorySyncMemory(
    api_key="ms_...",        # or set MEMORYSYNC_API_KEY in the environment
    user_id="customer-42",   # required — the end user these memories belong to
    session_id="support",    # optional — tags this conversation's facts; bounds clear()
)

Step 2 — attach it to your agent

Hand the memory to the agent. From now on, AutoGen calls the adapter before every model call: relevant memories are recalled, injected as a SystemMessage, and announced as a MemoryQueryEvent — the framework’s own eventing, nothing custom.

agent.py
from autogen_agentchat.agents import AssistantAgent


agent = AssistantAgent("assistant", model_client=..., memory=[memory])


result = await agent.run(task="Which seat should I book for Alex?")

Step 3 — capture the exchange

By AutoGen’s own design, nothing is captured automatically — that is the application’s job. This one call sends the user’s text to fact extraction: the server stores only the durable facts in it (filler such as “ok” yields none), and the assistant’s reply is not stored. It is safe to retry: a replay is recognised server-side and not extracted twice.

agent.py
await memory.add_turn_pair(user_text, result.messages[-1].content)

Optional: memory as agent tools

For tool-equipped agents, two ready-made FunctionTools let the model search and save memory on its own. search_memory performs the server’s semantic query; save_memory goes through server-side extraction, so the server — not the model — decides whether the text is durable enough to keep.

tools.py
from autogen_memorysync import create_memory_tools


tools = create_memory_tools(memory)   # search_memory + save_memory
agent = AssistantAgent("assistant", model_client=...,
                       memory=[memory], tools=tools)

Built-in safety guarantees

GuaranteeHow
A reply is never lateRecall waits at most recall_timeout (default 1.2s); on a miss the agent answers without memories
An outage never breaks the agentupdate_context catches everything, logs a warning, injects nothing
A retry is not extracted twiceSeeds derived from role + session + content hash, recognised server-side
Only the user’s words are sentadd() sends user (and role-less) content as plain text with role: "user"; content whose metadata["role"] is assistant, system or tool is not sent, and add_turn_pair sends only the user text
Your metadata dict is safeCopied before reading — never mutated
clear() cannot nuke a customerSession-scoped deletion by default; clear_scope="user" is an explicit, documented opt-in

Configuration

ParameterDefaultMeaning
user_id— (required)End user the memories belong to — never auto-generated (a random namespace strands data)
session_iddefaultSession scope autogen::<session> — tags this conversation’s facts; bounds clear()
top_k5Memories considered per turn
recall_timeout1.2Hard recall budget in seconds
min_prompt_chars8Skip recall for trivial prompts
context_templatebuilt-in{context} placeholder; brace-safe .replace rendering
clear_scopesessionclear() blast radius; "user" opt-in wipes everything

Choosing a user_id

The user_id is a stable string you pick to identify whose memories these are: your app’s internal user ID, an email address, or a UUID. Use the same value when storing and recalling, or recall returns nothing. It also powers per-user isolation — one customer’s memories can never reach another’s agent.

Quotas and plan limits

Hitting a monthly plan limit never breaks the agent. On free and paid plans, over-limit writes are accepted without storing and reads return empty — the conversation continues. Evaluation keys instead surface a truthful 429, so you find out during testing, not in production.

Troubleshooting

  • `pip install` can’t find the package — upgrade pip (python -m pip install -U pip); the package requires Python 3.10+.
  • `ModuleNotFoundError: autogen_agentchat` — the framework itself isn’t installed: pip install autogen-agentchat.
  • Recall returns nothing right after storing — extraction is asynchronous; give it a moment. Also confirm store and recall use the same user_id.
  • The agent answered without memories once — that’s the latency budget working: a slow lookup is skipped rather than delaying the reply. The next turn recalls normally.
  • `clear()` deleted less than expected — by design it clears only the current session. Pass clear_scope="user" explicitly to wipe a user.

Supported versions

SurfaceRequiresVerified on
autogen-memorysync 1.1.0autogen-agentchat / autogen-core 0.4+ (Python 3.10+)43 CI checks against the latest autogen-agentchat: a REAL AssistantAgent driven via the official ReplayChatCompletionClient (SystemMessage injection in the true turn order, MemoryQueryEvent emission), the role-aware retrieval regression, user-turn-only capture (assistant, system and tool content never sent), the 1.2s budget vs a slow backend, session-scoped clear, seed idempotency, metadata non-mutation, and both monthly-quota server modes

How it compares

Mem0 (`autogen-ext[mem0]`)Zep (`zep-autogen`)SupermemoryMemorySync
Async correctness✗ sync client inside async methods — blocks the event loop✓— no adapter at all✓ async httpx throughout
Recall latency budget✗ none✗ none—✓ hard 1.2s default, tested against a slow backend
Retrieval query✗ messages[-1] — assistant text after a tool resultlast context message—✓ last user message, role-aware
Explicit query() on failure✗ silently returns empty — outage looks like amnesialogged—✓ raises; only the hot path fails open
clear() blast radius✗ the entire user✗ the entire user—✓ session-scoped by default; whole-user wipe is an explicit opt-in
Retry safety✗✗—✓ deterministic idempotency seeds
Docs for the current API△ docs page shows the old 0.2 recipe✗ integration pages 404—✓ this page

Where to go next

AG2

The classic ConversableAgent fork — an automatic hook loop.

Agent Framework

The Microsoft Agent Framework successor adapter.

Memory Tools

Every operation, argument by argument.

Was this page helpful?
← Previous
Pydantic AI
Next →
AG2