Skip to content

feat(integrations): Add zep-ag2 — Zep memory integration for AG2#511

Merged
danielchalef merged 3 commits into
getzep:mainfrom
faridun-ag2:feat/zep-ag2-integration
Jun 18, 2026
Merged

feat(integrations): Add zep-ag2 — Zep memory integration for AG2#511
danielchalef merged 3 commits into
getzep:mainfrom
faridun-ag2:feat/zep-ag2-integration

Conversation

@faridun-ag2

Copy link
Copy Markdown
Contributor

Summary

  • Adds zep-ag2 package: Zep memory integration for AG2 (community AutoGen fork, 500K+ monthly PyPI downloads)
  • New package at integrations/python/zep_ag2/ following the established integration pattern
  • Provides sync tool factories for AG2's @register_for_llm/@register_for_execution pattern
  • Includes ZepMemoryManager for system message injection
  • Full test suite: 66 tests, 96% coverage

Why AG2?

AG2 is the most active community fork of AutoGen with 500K+ monthly downloads. It uses a different package (ag2 on PyPI) and API from the existing MS AutoGen integration. Existing zep-autogen targets MS AutoGen v4 (autogen-agentchat/autogen-core) — AG2 users need their own package.

Key Design Decisions

  • Sync tools: AG2 executes tool functions synchronously. Tools use a background event loop + run_coroutine_threadsafe to call the async Zep SDK
  • Per-call AsyncZep: Each tool coroutine creates its own AsyncZep instance inside the background loop to avoid event-loop binding issues
  • Composition over inheritance: AG2 has no formal Memory base class, so we use ZepMemoryManager for system message injection and tool factories for agent capabilities

Package Structure

integrations/python/zep_ag2/
├── src/zep_ag2/
│   ├── memory.py       — ZepMemoryManager (system message injection)
│   ├── tools.py        — 4 sync tool factories + register_all_tools()
│   ├── graph_memory.py — Knowledge graph integration
│   └── exceptions.py   — Package exceptions
├── tests/test_basic.py — 66 tests, 96% coverage
├── examples/           — 5 example scripts including manual integration test
├── pyproject.toml
├── README.md
└── Makefile

Test Plan

  • make format — clean
  • make lint — all checks passed
  • make type-check — no mypy issues
  • make test — 66 passed, 96% coverage
  • No MS AutoGen imports (autogen_agentchat/autogen_core/autogen_ext) in zep_ag2
  • Existing zep_autogen, zep_crewai, zep_livekit packages unmodified
  • Manual end-to-end test passes with real Zep + OpenAI APIs

@faridun-ag2

Copy link
Copy Markdown
Contributor Author

Hi @danielchalef!

We've put together a new zep-ag2 integration package for the AG2 framework.

It follows the same structure and patterns as the existing zep-autogen package, but adapted for AG2's API — sync tool factories with a background event loop for the async Zep SDK, composition-based memory management via ZepMemoryManager, and AG2's native @register_for_llm/@register_for_execution tool registration.

All quality gates pass (ruff, mypy, 66 tests at 96% coverage), and we've verified it end-to-end with real Zep and OpenAI APIs.

We'd love to get your feedback on this when you have a chance. Thank you!

Add zep-ag2 package providing Zep memory integration for AG2
(community AutoGen fork, 400K+ monthly PyPI downloads).

Key design: AG2 has no formal Memory base class like MS AutoGen v4,
so the integration uses composition — tool factories for
@register_for_llm/@register_for_execution and ZepMemoryManager
for system message injection.

Tools are synchronous (AG2 executes tools synchronously) with a
background event loop for async Zep SDK calls. Each tool coroutine
creates its own AsyncZep instance to avoid event-loop binding issues.

- ZepMemoryManager: system message injection + conversation memory
- ZepGraphMemoryManager: knowledge graph operations
- 4 tool factories: search_memory, add_memory, search_graph, add_graph_data
- register_all_tools() convenience function
- 66 tests, 96% coverage
- 4 examples + manual integration test
…ations/ag2/python

Relocates the AG2 integration to the platform-first path and applies
code-review fixes:

- Fix Python 3.13 sync-bridge crash: replace asyncio.get_event_loop() in the
  manager sync wrappers with a shared _run_sync() that submits coroutines to a
  single daemon background event loop via run_coroutine_threadsafe.
- Eliminate the per-call AsyncZep leak and private _client_wrapper.api_key
  access: tools now reuse the caller-supplied AsyncZep, driven on the shared
  background loop (verified httpx loop affinity allows this).
- Never log message content / raw exceptions: log type(e).__name__ only and
  return generic, non-leaking error strings; keep graceful degradation.
- Make the dependency guard truthful: verify `import autogen` (AG2) at import.
- Add message (4000) and graph-data (9900) size guards with truncate-and-warn
  (lengths only) across tools and ZepMemoryManager.add_messages.
- register_all_tools: register each uniquely-named tool once for LLM and once
  for execution (no duplicate-execution override warnings).
- Validate/normalize message roles to the Zep RoleType set (default assistant).
- Guard graph node summary None -> "No summary".
- Drop the redundant thread.get(lastn=10) read in get_memory_context.
- Align scope handling between create_search_memory_tool and
  create_search_graph_tool.
- Thread-safe lazy background-loop init with documentation and an optional
  shutdown_background_loop() helper.
- Docs/metadata: add SETUP.md; fix README (Python 3.11+, zep-cloud>=3.23.0,
  reworked background-loop copy); single coherent CHANGELOG 0.1.0 entry;
  pyproject classifiers, authors, keywords.
- Tests: exercise the real client-reuse path (no per-call construction, no
  _client_wrapper access), the 3.11-3.13 sync bridge, size truncation, role
  validation, and override-free registration.

Validation (Python 3.11/3.12/3.13): ruff check, ruff format --check, mypy
src/, and pytest tests/ (83 passed) all green; the 4 previously-failing
sync-wrapper tests now pass on 3.13.

Co-Authored-By: faridun-ag2 <faridun-ag2@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@danielchalef danielchalef force-pushed the feat/zep-ag2-integration branch from 513741f to d33a75e Compare June 18, 2026 14:30
@danielchalef

Copy link
Copy Markdown
Member

Thank you for the contribution!

@danielchalef danielchalef merged commit c0e1d13 into getzep:main Jun 18, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants