AG2 Memory

How it works

1. Install ag2-memorysync from PyPI.
2. Create a MemorySyncCapability with your API key and the end user’s id.
3. Attach it to any ConversableAgent with one call: memory.add_to_agent(assistant).
4. Done — from now on the durable facts in every user message are remembered and relevant context is recalled before each answer. The agent’s own replies are not stored. No per-turn code.

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 the classic ConversableAgent framework (pip install autogen). The rewritten pip install ag2 v1 has no hook system yet — a future adapter target.

Install

One package, zero framework dependencies:

pip install ag2-memorysync

Quickstart

Step 1 — create the capability

The capability is where you say whose memories these are. user_id is required; session_id separates conversations — every distilled fact is tagged with it.

from ag2_memorysync import MemorySyncCapability

memory = MemorySyncCapability(
    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
)

Step 2 — attach it to your agent

One call wires the whole loop. AG2-classic has no memory protocol — register_hook is its only per-turn seam — so the capability registers two hooks for you and everything else is automatic.

from autogen import ConversableAgent

assistant = ConversableAgent("assistant", llm_config=...)
memory.add_to_agent(assistant)   # done

The automatic loop, precisely

Tool and function messages are never sent. Each user turn goes to MemorySync as plain text with role: "user" under the ag2::<session> session scope, with deterministic idempotency seeds; the server extracts the durable facts it contains and stores only those — the same shared user memories as every other MemorySync surface. Filler such as “ok” yields none, and the turn text itself is not stored.

The deadlock-free bridge

All async work rides one persistent background event loop per process. Hooks submit coroutines with run_coroutine_threadsafe and block — bounded by the recall budget — on a plain future. The caller’s thread and event loop are never touched, so a chat driven from inside asyncio.run(...) completes (a test proves it). Persistence is fire-and-forget off the hot path; memory.flush() waits for in-flight writes at shutdown, and memory.close() flushes and releases the HTTP client.

Optional: memory as agent tools

If you want the model itself to search or save memory, register the two ready-made tools. Both are synchronous — they ride the same bridge, so they work in plain initiate_chat without event-loop concerns. The caller agent needs an llm_config, as usual for AG2 tool registration.

from ag2_memorysync import register_memory_tools

# caller decides to use tools; executor runs them (AG2's standard split)
register_memory_tools(memory, caller=assistant, executor=user_proxy)

Configuration

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 across sessions 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 a conversation. On free and paid plans, over-limit writes are accepted without storing and reads return empty — the chat continues. Evaluation keys instead surface a truthful 429, so you find out during testing, not in production.

Troubleshooting

• `ModuleNotFoundError: autogen` — install the classic framework: pip install autogen. The rewritten pip install ag2 v1 has no hooks yet and is not supported.
• Two agents in one chat, each user message sent once — that’s correct: the dedup registry prevents the double-store bug zep-ag2 documents.
• Nothing is stored for the assistant’s replies — by design: assistant replies are not stored as memories. Only the durable facts in what the person says are kept.
• A chat inside `asyncio.run(...)` hangs with other adapters — not this one: the bridge never touches your event loop. If you see a hang, it isn’t the memory layer.
• Recall seems empty right after a message — extraction is asynchronous, and trivial messages (under min_prompt_chars) skip recall by design. Same user_id across turns is required.
• Writes seem missing after a short script exits — sending is fire-and-forget; call memory.flush() before exiting so in-flight sends land.

Supported versions

How it compares

Where to go next