Microsoft Agent Framework Memory
A ContextProvider for the Microsoft Agent Framework: budgeted recall into the instructions layer before every run, per-run identity, and automatic once-per-turn capture that can never crash the agent. Install agent-framework-memorysync from PyPI.
What installs
pip install agent-framework-memorysync
The framework calls before_run before every model invocation — relevant memories are recalled under the budget and injected into the instructions layer — and after_run after the run completes, where both sides of the exchange persist automatically.
| Mem0 (`agent-framework-mem0`) | Zep (`zep-ms-agent-framework`) | Supermemory | MemorySync | |
|---|---|---|---|---|
| Injection layer | ✗ fabricates a role="user" message the model believes the user wrote | ✓ instructions | — no adapter at all | ✓ instructions |
| Recall latency budget | ✗ none | ✗ none | — | ✓ hard 1.2s default |
| Capture failure | ✗ after_run errors crash the agent after a successful run | swallowed | — | ✓ entirely fail-open, logged |
| Scope model | ✗ storage ≠ retrieval scopes; forget search_user_id and the agent is silently memoryless | single | — | ✓ one user_id drives both |
| Per-run identity | ✗ construction-only | ✗ construction-only (documented) | — | ✓ run options → resolver → constructor |
| Write dedup | ✗ re-adds every turn | ✗ | — | ✓ deterministic idempotency seeds |
| Release status | △ beta | 0.2.1 | — | ✓ stable 1.0.0 |
| Python floor | 3.10 | ✗ 3.11 only | — | ✓ 3.10 (matches the framework) |
Per-run identity — the documented gap, solved
Both competitor adapters bind identity at construction and document it as a framework limitation: multi-tenant servers must build one provider per user. This provider adds a three-rung ladder, resolved fresh on every run and pinned in the provider’s session-state slice so recall and capture can never diverge within a run:
| Rung | Mechanism | Use case |
|---|---|---|
| 1 | await agent.run(..., options={"memorysync_user_id": user}) | Multi-tenant servers: one agent, per-request identity |
| 2 | user_id_resolver=lambda session: ... | Identity derived from your session store |
| 3 | Constructor user_id | Single-user agents and simple deployments |
The capture loop
| Guarantee | How |
|---|---|
| A run is never stalled | Recall waits at most recall_timeout (default 1.2s); on a miss the agent runs without memories |
| A memory outage never crashes the agent | after_run catches everything and logs — the run’s success is never converted into a failure (the Mem0 provider does exactly that) |
| Tool loops capture once | after_run_once_per_turn = True — one persistence per user turn, not per model round-trip |
| Retries never duplicate | Deterministic seeds from role + session + content hash |
| Sessions stay serializable | The provider writes only JSON-native values to its state slice — AgentSession.to_dict() keeps working |
curl --request POST https://api.memorysync.io/v1/memory/add_turn \--header "X-API-Key: $MEMORYSYNC_API_KEY" \--header "Content-Type: application/json" \--data '{"tenant_id":"acme","user_id":"customer-42","source":"agent-framework","text":"human: which seat should I book?","speaker":"human@agent-framework::support#h<content-hash>","metadata":{"session_id":"agent-framework::support"}}'
Configuration
| Parameter | Default | Meaning |
|---|---|---|
user_id | — (required) | End user the memories belong to |
session_id | default | Transcript scope: agent-framework::<session> |
top_k | 5 | Memories considered per run |
recall_timeout | 1.2 | Hard recall budget in seconds |
min_prompt_chars | 8 | Skip recall for trivial prompts |
context_template | built-in | {context} placeholder; brace-safe .replace rendering |
capture | True | Persist the exchange after each run |
expose_search_tool | False | Register search_memory + save_memory tools each run |
user_id_resolver | None | Callable for dynamic identity |
Supported versions
| Surface | Requires | Verified on |
|---|---|---|
agent-framework-memorysync 1.0.0 | agent-framework-core 1.8+ (Python 3.10+) | 21 CI checks against the latest agent-framework-core: real SessionContext/AgentSession objects and a REAL Agent run via a stub chat client — instructions-layer injection, the 1.2s budget vs a slow backend, the per-run identity ladder, fail-open once-per-turn capture (the Mem0 crash regression), seed idempotency, JSON-safe session state, and both monthly-quota server modes |