zep-autogen 0.1.0__tar.gz

zep_autogen-0.1.0/.gitignore

@@ -0,0 +1,88 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+out/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Secrets
+.env
+.env.local
+
+# Test data
+test_data
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+.idea
+.vscode
+
+# VSCode local history
+.history
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# PyCharm
+.idea/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pytest
+.pytest_cache/
+.coverage
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# UV (Python package manager)
+uv.lock
+.uv_cache/
+__pypackages__/

zep_autogen-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to the zep-autogen package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+- Initial release of zep-autogen integration package
+- `ZepMemory` class implementing AutoGen's Memory interface
+- Support for persistent conversation memory with Zep Cloud
+- Async/await support for modern Python applications
+- Comprehensive type hints and documentation
+- Basic example demonstrating usage with AutoGen agents
+- Error handling for missing dependencies
+
+### Features
+- Seamless integration with AutoGen agents
+- Intelligent context retrieval from Zep memory
+- Support for user-specific and thread-specific memory contexts
+- Configurable memory retrieval limits
+- Compatible with AutoGen 0.6.1+
+
+[Unreleased]: https://github.com/getzep/zep/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/getzep/zep/releases/tag/v0.1.0

zep_autogen-0.1.0/Makefile

@@ -0,0 +1,72 @@
+# Makefile for zep-autogen development
+
+.PHONY: help install format lint type-check test test-cov clean build all
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  install     - Install package and dependencies in development mode"
+	@echo "  format      - Format code with ruff"
+	@echo "  lint        - Run linting checks"
+	@echo "  type-check  - Run type checking with mypy"
+	@echo "  test        - Run tests"
+	@echo "  test-cov    - Run tests with coverage report"
+	@echo "  all         - Run format, lint, type-check, and test"
+	@echo "  build       - Build the package"
+	@echo "  clean       - Clean build artifacts"
+
+# Install package in development mode
+install:
+	uv sync --extra dev
+
+# Format code
+format:
+	uv run ruff format .
+
+# Run linting checks
+lint:
+	uv run ruff check .
+
+# Fix linting issues automatically
+lint-fix:
+	uv run ruff check --fix .
+
+# Run type checking
+type-check:
+	uv run mypy src/
+
+# Run tests
+test:
+	uv run pytest tests/ -v
+
+# Run tests with coverage
+test-cov:
+	uv run pytest tests/ -v --cov=zep_autogen --cov-report=term-missing --cov-report=xml
+
+# Run all checks (the order matters: format first, then lint, then type-check, then test)
+all: format lint type-check test
+
+# Build the package
+build:
+	uv build
+
+# Clean build artifacts
+clean:
+	rm -rf dist/
+	rm -rf build/
+	rm -rf *.egg-info/
+	rm -rf .pytest_cache/
+	rm -rf .mypy_cache/
+	rm -rf .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -f coverage.xml
+	rm -f .coverage
+
+# Development workflow - run this before committing
+pre-commit: lint-fix format lint type-check test
+	@echo "✅ All checks passed! Ready to commit."
+
+# CI workflow - strict checks without auto-fixing
+ci: lint type-check test
+	@echo "✅ CI checks passed!"

zep_autogen-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: zep-autogen
+Version: 0.1.0
+Summary: Autogen integration for Zep
+Project-URL: Homepage, https://github.com/getzep/zep
+Project-URL: Documentation, https://docs.getzep.com/integrations/autogen
+Project-URL: Repository, https://github.com/getzep/zep
+Project-URL: Bug Tracker, https://github.com/getzep/zep/issues
+Project-URL: Changelog, https://github.com/getzep/zep/blob/main/integrations/python/autogen/CHANGELOG.md
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: autogen-agentchat>=0.6.1
+Requires-Dist: autogen-ext[azure,openai]>=0.6.1
+Requires-Dist: azure-identity>=1.23.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-slugify>=8.0.4
+Requires-Dist: rich>=14.0.0
+Requires-Dist: zep-cloud>=3.0.0rc1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Zep AutoGen Integration
+
+A dedicated integration package that enables [Zep](https://getzep.com) to work seamlessly with [Microsoft AutoGen](https://github.com/microsoft/autogen) agents, providing persistent conversation memory and intelligent context retrieval.
+
+## Installation
+
+```bash
+pip install zep-autogen
+```
+
+## Quick Start
+
+```python
+import asyncio
+from zep_cloud.client import AsyncZep
+from zep_autogen import ZepMemory
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+async def main():
+    # Initialize Zep client
+    zep_client = AsyncZep(api_key="your-zep-api-key")
+    
+    # Create Zep memory for your agent
+    memory = ZepMemory(
+        client=zep_client,
+        user_id="user_123",
+        thread_id="conversation_456"
+    )
+    
+    # Create AutoGen agent with Zep memory
+    agent = AssistantAgent(
+        name="MemoryAwareAssistant",
+        model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
+        memory=[memory]  # Add Zep memory to the agent
+    )
+    
+    # Your agent now has persistent memory across conversations!
+    response = await agent.run(task="What's my name again?")
+    print(response.messages[-1].content)
+    
+asyncio.run(main())
+```
+
+## Features
+
+- **Persistent Memory**: Conversations persist across agent sessions
+- **Intelligent Retrieval**: Zep's memory automatically provides relevant context
+- **AutoGen Compatible**: Seamlessly integrates with AutoGen's memory interface
+- **Async Support**: Full async/await support for modern applications
+- **Type Safety**: Fully typed with comprehensive type hints
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required: Your Zep Cloud API key
+export ZEP_API_KEY="your-zep-api-key"
+```
+
+### ZepMemory Parameters
+
+- `client` (AsyncZep): Your Zep client instance
+- `user_id` (str): Unique identifier for the user
+- `thread_id` (str, optional): Thread/conversation identifier
+- `memory_type` (str, optional): Type of memory to use (default: "perpetual")
+- `max_tokens` (int, optional): Maximum tokens to retrieve (default: 4000)
+
+## Examples
+
+### Basic Usage
+
+See [examples/autogen_basic.py](examples/autogen_basic.py) for a complete working example.
+
+### Multi-Agent with Shared Memory
+
+```python
+# Multiple agents can share the same memory context
+shared_memory = ZepMemory(
+    client=zep_client,
+    user_id="team_project",
+    thread_id="brainstorm_session"
+)
+
+researcher = AssistantAgent(
+    name="Researcher",
+    model_client=model_client,
+    memory=[shared_memory]
+)
+
+writer = AssistantAgent(
+    name="Writer", 
+    model_client=model_client,
+    memory=[shared_memory]
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- `zep-cloud>=2.15.0`
+- `autogen-agentchat>=0.6.1`
+- `autogen-core>=0.6.1`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- [Zep Documentation](https://docs.getzep.com)
+- [AutoGen Documentation](https://microsoft.github.io/autogen/)
+- [GitHub Issues](https://github.com/getzep/zep/issues)
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details.

zep_autogen-0.1.0/README.md

@@ -0,0 +1,118 @@
+# Zep AutoGen Integration
+
+A dedicated integration package that enables [Zep](https://getzep.com) to work seamlessly with [Microsoft AutoGen](https://github.com/microsoft/autogen) agents, providing persistent conversation memory and intelligent context retrieval.
+
+## Installation
+
+```bash
+pip install zep-autogen
+```
+
+## Quick Start
+
+```python
+import asyncio
+from zep_cloud.client import AsyncZep
+from zep_autogen import ZepMemory
+from autogen_agentchat.agents import AssistantAgent
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+async def main():
+    # Initialize Zep client
+    zep_client = AsyncZep(api_key="your-zep-api-key")
+    
+    # Create Zep memory for your agent
+    memory = ZepMemory(
+        client=zep_client,
+        user_id="user_123",
+        thread_id="conversation_456"
+    )
+    
+    # Create AutoGen agent with Zep memory
+    agent = AssistantAgent(
+        name="MemoryAwareAssistant",
+        model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
+        memory=[memory]  # Add Zep memory to the agent
+    )
+    
+    # Your agent now has persistent memory across conversations!
+    response = await agent.run(task="What's my name again?")
+    print(response.messages[-1].content)
+    
+asyncio.run(main())
+```
+
+## Features
+
+- **Persistent Memory**: Conversations persist across agent sessions
+- **Intelligent Retrieval**: Zep's memory automatically provides relevant context
+- **AutoGen Compatible**: Seamlessly integrates with AutoGen's memory interface
+- **Async Support**: Full async/await support for modern applications
+- **Type Safety**: Fully typed with comprehensive type hints
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required: Your Zep Cloud API key
+export ZEP_API_KEY="your-zep-api-key"
+```
+
+### ZepMemory Parameters
+
+- `client` (AsyncZep): Your Zep client instance
+- `user_id` (str): Unique identifier for the user
+- `thread_id` (str, optional): Thread/conversation identifier
+- `memory_type` (str, optional): Type of memory to use (default: "perpetual")
+- `max_tokens` (int, optional): Maximum tokens to retrieve (default: 4000)
+
+## Examples
+
+### Basic Usage
+
+See [examples/autogen_basic.py](examples/autogen_basic.py) for a complete working example.
+
+### Multi-Agent with Shared Memory
+
+```python
+# Multiple agents can share the same memory context
+shared_memory = ZepMemory(
+    client=zep_client,
+    user_id="team_project",
+    thread_id="brainstorm_session"
+)
+
+researcher = AssistantAgent(
+    name="Researcher",
+    model_client=model_client,
+    memory=[shared_memory]
+)
+
+writer = AssistantAgent(
+    name="Writer", 
+    model_client=model_client,
+    memory=[shared_memory]
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- `zep-cloud>=2.15.0`
+- `autogen-agentchat>=0.6.1`
+- `autogen-core>=0.6.1`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Support
+
+- [Zep Documentation](https://docs.getzep.com)
+- [AutoGen Documentation](https://microsoft.github.io/autogen/)
+- [GitHub Issues](https://github.com/getzep/zep/issues)
+
+## Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](../../../CONTRIBUTING.md) for details.

zep_autogen-0.1.0/examples/autogen_basic.py

@@ -0,0 +1,98 @@
+import asyncio
+import os
+import uuid
+
+from autogen_agentchat.agents import AssistantAgent
+from autogen_core.memory import MemoryContent, MemoryMimeType
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from zep_cloud.client import AsyncZep
+
+from zep_autogen import ZepMemory
+
+
+async def main():
+    # Initialize AsyncZep client
+    zep_client = AsyncZep(api_key=os.environ.get("ZEP_API_KEY"))
+
+    user_id = f"user_{uuid.uuid4().hex[:16]}"
+    thread_id = f"thread_{uuid.uuid4().hex[:16]}"
+
+    try:
+        # Create user for the user (upfront initialization)
+        await zep_client.user.add(
+            user_id=user_id,
+            email="alice@agents.local",
+            first_name="Alice",
+        )
+        print(f"Created user: {user_id}")
+    except Exception as e:
+        print(f"User might already exist: {e}")
+
+    try:
+        # Create thread for this conversation
+        await zep_client.thread.create(thread_id=thread_id, user_id=user_id)
+        print(f"Created thread: {thread_id}")
+    except Exception as e:
+        print(f"Thread creation failed: {e}")
+
+    # Initialize Zep memory bound to the assistant
+    memory = ZepMemory(client=zep_client, thread_id=thread_id, user_id=user_id)
+
+    # Create assistant agent with Zep memory
+    agent = AssistantAgent(
+        name="MemoryAwareAssistant",
+        model_client=OpenAIChatCompletionClient(model="gpt-4.1-mini"),
+        memory=[memory],
+    )
+
+    print("Assistant ready with Zep memory!")
+
+    # Helper function to store individual messages in memory (AutoGen best practice)
+    async def add_message(message: str, role: str, name: str | None = None):
+        """Store a single message in memory following AutoGen standards"""
+        metadata = {"type": "message", "role": role, "name": name}
+
+        await memory.add(
+            MemoryContent(content=message, mime_type=MemoryMimeType.TEXT, metadata=metadata)
+        )
+
+    # Example conversation with proper memory management
+    try:
+        print("\n=== Starting conversation with memory persistence ===")
+
+        # First interaction
+        user_msg1 = "My name is Alice and I love hiking in the mountains."
+        print(f"User: {user_msg1}")
+        await add_message(user_msg1, "user")
+        response1 = await agent.run(task=user_msg1)
+        agent_msg1 = response1.messages[-1].content
+        print(f"Agent: {agent_msg1}")
+
+        await add_message(agent_msg1, "assistant")
+
+        # Second interaction - agent should remember Alice and her interests
+        user_msg2 = "What outdoor activities do you think I'd enjoy?"
+        print(f"\nUser: {user_msg2}")
+        response2 = await agent.run(task=user_msg2)
+        await add_message(user_msg2, "user")
+        agent_msg2 = response2.messages[-1].content
+        print(f"Agent: {agent_msg2}")
+        await add_message(agent_msg2, "assistant")
+
+        user_msg3 = "What's my name again?"
+        print(f"\nUser: {user_msg3}")
+        await add_message(user_msg3, "user")
+        response3 = await agent.run(task=user_msg3)
+        agent_msg3 = response3.messages[-1].content
+        print(f"Agent: {agent_msg3}")
+
+        await add_message(agent_msg3, "assistant")
+
+        print("\n=== Memory persistence test complete ===")
+
+    except Exception as e:
+        print(f"Error during conversation: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

zep_autogen-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "zep-autogen"
+version = "0.1.0"
+description = "Autogen integration for Zep"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "autogen-agentchat>=0.6.1",
+    "autogen-ext[azure,openai]>=0.6.1",
+    "azure-identity>=1.23.0",
+    "aiohttp>=3.8.0",
+    "python-dotenv>=1.0.0",
+    "python-slugify>=8.0.4",
+    "rich>=14.0.0",
+    "zep-cloud>=3.0.0rc1",
+]
+
+[project.urls]
+Homepage = "https://github.com/getzep/zep"
+Documentation = "https://docs.getzep.com/integrations/autogen"
+Repository = "https://github.com/getzep/zep"
+"Bug Tracker" = "https://github.com/getzep/zep/issues"
+Changelog = "https://github.com/getzep/zep/blob/main/integrations/python/autogen/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov",
+    "pytest-asyncio",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zep_autogen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "integration: marks tests as integration tests (deselect with '-m \"not integration\"')"
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501", # line too long, handled by formatter
+    "B008", # do not perform function calls in argument defaults
+    "C901", # too complex
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["zep_autogen"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "autogen_core.*",
+    "autogen_agentchat.*", 
+    "autogen_ext.*",
+    "zep_cloud.*",
+]
+ignore_missing_imports = true

zep_autogen-0.1.0/src/zep_autogen/__init__.py

@@ -0,0 +1,44 @@
+"""
+Zep AutoGen Integration.
+
+This package provides memory integration between Zep and Microsoft AutoGen agents,
+enabling persistent conversation memory and context retrieval.
+
+Installation:
+    pip install zep-autogen
+
+Usage:
+    from zep_autogen import ZepMemory
+    from zep_cloud.client import AsyncZep
+    from autogen_agentchat.agents import AssistantAgent
+
+    # Initialize Zep client and memory
+    zep_client = AsyncZep(api_key="your-api-key")
+    memory = ZepMemory(client=zep_client, user_id="user123")
+
+    # Create agent with Zep memory
+    agent = AssistantAgent(
+        name="assistant",
+        model_client=model_client,
+        memory=[memory]
+    )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Zep AI"
+__description__ = "Zep integration for Microsoft AutoGen"
+
+from .exceptions import ZepDependencyError
+
+try:
+    # Check for required AutoGen dependencies - just test import
+    import autogen_core.memory  # noqa: F401
+    import autogen_core.model_context  # noqa: F401
+
+    # Import our integration
+    from .memory import ZepMemory
+
+    __all__ = ["ZepMemory", "ZepDependencyError"]
+
+except ImportError as e:
+    raise ZepDependencyError(framework="AutoGen", install_command="pip install zep-autogen") from e

zep_autogen-0.1.0/src/zep_autogen/exceptions.py

@@ -0,0 +1,12 @@
+"""
+Exception classes for AutoGen integration.
+"""
+
+
+class ZepDependencyError(ImportError):
+    """Raised when required AutoGen dependencies are not installed."""
+
+    def __init__(self, framework: str, install_command: str):
+        self.framework = framework
+        self.install_command = install_command
+        super().__init__(f"{framework} dependencies not found. Install with: {install_command}")

zep_autogen-0.1.0/src/zep_autogen/memory.py

@@ -0,0 +1,304 @@
+"""
+Zep Memory integration for AutoGen.
+
+This module provides memory classes that integrate Zep with AutoGen's memory system.
+"""
+
+import logging
+import uuid
+from typing import Any
+
+from autogen_core import CancellationToken
+from autogen_core.memory import (
+    Memory,
+    MemoryContent,
+    MemoryMimeType,
+    MemoryQueryResult,
+    UpdateContextResult,
+)
+from autogen_core.model_context import ChatCompletionContext
+from autogen_core.models import SystemMessage
+from zep_cloud.client import AsyncZep
+from zep_cloud.types import Message
+
+
+class ZepMemory(Memory):
+    """
+    A memory implementation that integrates with Zep for persistent storage
+    and retrieval of conversation context and agent memories.
+
+    This class implements AutoGen's Memory interface and provides:
+    - Automatic context injection via update_context()
+    - Manual memory queries via query()
+    - Message storage in Zep threads
+    - Data storage in Zep user graphs
+    """
+
+    def __init__(
+        self, client: AsyncZep, user_id: str, thread_id: str | None = None, **kwargs: Any
+    ) -> None:
+        """
+        Initialize ZepMemory with an AsyncZep client instance.
+
+        Args:
+            client: An initialized AsyncZep instance
+            user_id: User ID for memory isolation (required)
+            thread_id: Optional thread ID. If not provided, will be created automatically
+            **kwargs: Additional configuration options
+        """
+        if not isinstance(client, AsyncZep):
+            raise TypeError("client must be an instance of AsyncZep")
+
+        if not user_id:
+            raise ValueError("user_id is required")
+
+        self._client = client
+        self._user_id = user_id
+        self._thread_id = thread_id
+        self._config = kwargs
+
+        # Set up module logger
+        self._logger = logging.getLogger(__name__)
+
+    async def add(
+        self, content: MemoryContent, cancellation_token: CancellationToken | None = None
+    ) -> None:
+        """
+        Add a memory entry to Zep storage.
+
+        Uses metadata.type to determine storage method:
+        - type="message": stores as message in thread using thread.add_messages
+        - type="data": stores as data in user's graph using graph.add (maps mime type to data type)
+
+        Args:
+            entry: The memory content to store
+
+        Raises:
+            ValueError: If the memory content mime type or metadata type is not supported
+        """
+        # Validate mime type - only support TEXT, MARKDOWN, and JSON
+        supported_mime_types = {MemoryMimeType.TEXT, MemoryMimeType.MARKDOWN, MemoryMimeType.JSON}
+
+        if content.mime_type not in supported_mime_types:
+            raise ValueError(
+                f"Unsupported mime type: {content.mime_type}. "
+                f"ZepMemory only supports: {', '.join(str(mt) for mt in supported_mime_types)}"
+            )
+
+        # Extract metadata
+        metadata_copy = content.metadata.copy() if content.metadata else {}
+        content_type = metadata_copy.get("type", "data")  # Default to "data" if no type specified
+
+        if content_type == "message":
+            if self._thread_id:
+                # Ensure thread exists
+                await self._client.thread.get(self._thread_id)
+
+            if not self._thread_id:
+                self._thread_id = f"thread_{uuid.uuid4().hex[:16]}"
+                await self._client.thread.create(thread_id=self._thread_id, user_id=self._user_id)
+            # Store as message in thread session
+            role = metadata_copy.get("role", "user")
+            name = metadata_copy.get("name")
+
+            message = Message(name=name, content=str(content.content), role=role)
+
+            # Add message to user's thread in Zep
+            await self._client.thread.add_messages(thread_id=self._thread_id, messages=[message])
+
+        elif content_type == "data":
+            # Store as data in the user's graph - map mime type to Zep data type
+            mime_to_data_type: dict[MemoryMimeType, str] = {
+                MemoryMimeType.TEXT: "text",
+                MemoryMimeType.MARKDOWN: "text",
+                MemoryMimeType.JSON: "json",
+            }
+
+            # Safely get the data type, handling both MemoryMimeType and string
+            if isinstance(content.mime_type, MemoryMimeType):
+                data_type = mime_to_data_type.get(content.mime_type, "text")
+            else:
+                data_type = "text"  # Default for string or unknown types
+
+            # Add data to user's graph
+            await self._client.graph.add(
+                user_id=self._user_id, type=data_type, data=str(content.content)
+            )
+
+        else:
+            raise ValueError(
+                f"Unsupported metadata type: {content_type}. Supported types: 'message', 'data'"
+            )
+
+    async def query(
+        self,
+        query: str | MemoryContent,
+        cancellation_token: CancellationToken | None = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        """
+        Query memories from Zep storage using graph.search.
+
+        Args:
+            query: Search query string or MemoryContent
+            cancellation_token: Optional cancellation token
+            **kwargs: Additional query parameters
+
+        Returns:
+            MemoryQueryResult containing matching memories
+        """
+        # Convert query to string if it's MemoryContent
+        if isinstance(query, MemoryContent):
+            query_str = str(query.content)
+        else:
+            query_str = query
+
+        # Extract limit from kwargs for backward compatibility
+        limit = kwargs.pop("limit", 5)
+
+        results = []
+
+        try:
+            # Search the user's graph
+            graph_results = await self._client.graph.search(
+                user_id=self._user_id, query=query_str, limit=limit, **kwargs
+            )
+
+            # Add graph search results
+            if graph_results.edges:
+                for edge in graph_results.edges:
+                    results.append(
+                        MemoryContent(
+                            content=edge.fact,
+                            mime_type=MemoryMimeType.TEXT,
+                            metadata={
+                                "source": "user_graph",
+                                "edge_name": edge.name,
+                                "edge_attributes": edge.attributes or {},
+                                "created_at": edge.created_at,
+                                "expired_at": edge.expired_at,
+                                "valid_at": edge.valid_at,
+                                "invalid_at": edge.invalid_at,
+                            },
+                        )
+                    )
+            if graph_results.nodes:
+                for node in graph_results.nodes:
+                    results.append(
+                        MemoryContent(
+                            content=f"{node.name}:\n {node.summary}",
+                            mime_type=MemoryMimeType.TEXT,
+                            metadata={
+                                "source": "user_graph",
+                                "node_name": node.name,
+                                "node_attributes": node.attributes or {},
+                                "created_at": node.created_at,
+                            },
+                        )
+                    )
+            if graph_results.episodes:
+                for episode in graph_results.episodes:
+                    results.append(
+                        MemoryContent(
+                            content=episode.content,
+                            mime_type=MemoryMimeType.TEXT,
+                            metadata={
+                                "source": "user_graph",
+                                "episode_type": episode.source,
+                                "episode_role": episode.role_type,
+                                "episode_name": episode.role,
+                                "created_at": episode.created_at,
+                            },
+                        )
+                    )
+        except Exception as e:
+            # Log error but don't fail completely
+            self._logger.error(f"Error querying Zep memory: {e}")
+
+        return MemoryQueryResult(results=results)
+
+    async def update_context(self, model_context: ChatCompletionContext) -> UpdateContextResult:
+        """
+        Update the agent's model context with retrieved memories.
+
+        Gets memory from Zep, and if memory exists, includes up to 10 last messages
+        from history and adds the memory context as a system message.
+
+        Args:
+            model_context: The model context to update
+
+        Returns:
+            UpdateContextResult with the memories that were retrieved
+        """
+        try:
+            # Get messages from current context
+            messages = await model_context.get_messages()
+            if not messages:
+                return UpdateContextResult(memories=MemoryQueryResult(results=[]))
+
+            # Get memory from Zep session
+            if not self._thread_id:
+                return UpdateContextResult(memories=MemoryQueryResult(results=[]))
+            memory_result = await self._client.thread.get_user_context(thread_id=self._thread_id)
+
+            memory_contents = []
+            memory_parts = []
+
+            # If we have memory context, include it
+            if memory_result.context:
+                memory_contents.append(
+                    MemoryContent(
+                        content=memory_result.context,
+                        mime_type=MemoryMimeType.TEXT,
+                        metadata={"source": "thread_context"},
+                    )
+                )
+                memory_parts.append(f"Memory context: {memory_result.context}")
+
+                # Only include recent messages if we have memory
+                if memory_result.messages:
+                    recent_messages = memory_result.messages[-10:]  # Get last 10 messages
+                    if recent_messages:
+                        message_history = []
+                        for msg in recent_messages:
+                            message_history.append(f"{msg.role}: {msg.content}")
+                        memory_parts.append("Recent conversation:\n" + "\n".join(message_history))
+
+            # If we have memory parts, add them to the context as a system message
+            if memory_parts:
+                memory_context = "\n\n".join(memory_parts)
+                await model_context.add_message(SystemMessage(content=memory_context))
+
+            return UpdateContextResult(memories=MemoryQueryResult(results=memory_contents))
+
+        except Exception as e:
+            # Log error but don't fail completely
+            self._logger.error(f"Error updating context with Zep memory: {e}")
+            return UpdateContextResult(memories=MemoryQueryResult(results=[]))
+
+    async def clear(self) -> None:
+        """
+        Clear all memories from Zep storage by deleting the session.
+
+        This will delete the entire session and all its messages.
+        Note: This operation cannot be undone.
+        """
+        try:
+            # Delete the session - this clears all messages and memory for this session
+            if self._thread_id:
+                await self._client.thread.delete(thread_id=self._thread_id)
+
+        except Exception as e:
+            self._logger.error(f"Error clearing Zep memory: {e}")
+            raise
+
+    async def close(self) -> None:
+        """
+        Clean up Zep client resources.
+
+        Note: This method does not close the AsyncZep instance since it was
+        provided externally. The caller is responsible for managing the client lifecycle.
+        """
+        # The client was provided externally, so we don't close it here
+        # The caller is responsible for closing the client when appropriate
+        pass

zep_autogen-0.1.0/tests/test_basic.py

@@ -0,0 +1,269 @@
+"""
+Basic tests for the zep-integrations package.
+"""
+
+import os
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from autogen_core.memory import MemoryContent, MemoryMimeType
+
+from zep_autogen import ZepMemory
+
+
+def test_package_import():
+    """Test that the package can be imported successfully."""
+    import zep_autogen
+
+    assert zep_autogen is not None
+
+
+def test_zep_memory_import():
+    """Test that ZepMemory can be imported successfully."""
+    assert ZepMemory is not None
+
+
+class TestBasicFunctionality:
+    """Basic functionality tests for the zep-autogen package."""
+
+    def test_package_structure(self):
+        """Test that the package has the expected structure."""
+        import zep_autogen
+
+        assert hasattr(zep_autogen, "__version__")
+        assert hasattr(zep_autogen, "__author__")
+        assert hasattr(zep_autogen, "__description__")
+
+
+class TestZepMemoryMock:
+    """Test ZepMemory with mock clients."""
+
+    def test_zep_memory_initialization_with_mock(self):
+        """Test that ZepMemory can be initialized with a mock client."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            # Create a mock AsyncZep client
+            mock_client = MagicMock(spec=AsyncZep)
+            memory = ZepMemory(client=mock_client, thread_id="test-session", user_id="test-user")
+            assert memory is not None
+            assert memory._client is mock_client
+            assert memory._thread_id == "test-session"
+            assert memory._user_id == "test-user"
+
+        except ImportError:
+            # If zep_cloud is not available, test with a generic mock
+            class MockAsyncZep:
+                pass
+
+            mock_client = MockAsyncZep()
+            with pytest.raises(TypeError, match="client must be an instance of AsyncZep"):
+                ZepMemory(client=mock_client, thread_id="test-session")
+
+    def test_zep_memory_requires_session_id(self):
+        """Test that ZepMemory requires a session_id."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+
+            with pytest.raises(ValueError, match="user_id is required"):
+                ZepMemory(client=mock_client, user_id="")
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_memory_requires_async_zep_client(self):
+        """Test that ZepMemory raises TypeError when client is not AsyncZep."""
+        with pytest.raises(TypeError, match="client must be an instance of AsyncZep"):
+            ZepMemory(client="not_a_client", user_id="test-user")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_add_message_with_mock(self):
+        """Test adding memory as message (with user_id) with a mock client."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+            mock_client.thread = MagicMock()
+            mock_client.thread.get = AsyncMock()
+            mock_client.thread.add_messages = AsyncMock()
+
+            memory = ZepMemory(client=mock_client, user_id="test-user", thread_id="test-session")
+
+            # Test adding memory content as message type
+            content = MemoryContent(
+                content="Test message",
+                mime_type=MemoryMimeType.TEXT,
+                metadata={"type": "message", "role": "user", "name": "user123"},
+            )
+
+            await memory.add(content)
+
+            # Verify the thread.add_messages mock was called
+            mock_client.thread.add_messages.assert_called_once()
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_add_graph_data_with_mock(self):
+        """Test adding memory as graph data (without user_id) with a mock client."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+            mock_client.graph = MagicMock()
+            mock_client.graph.add = AsyncMock()
+
+            memory = ZepMemory(
+                client=mock_client,
+                thread_id="test-session",
+                user_id="test-user",  # Required for graph data
+            )
+
+            # Test adding memory content without user_id (should store as graph data)
+            content = MemoryContent(
+                content="Test data for graph",
+                mime_type=MemoryMimeType.TEXT,
+                metadata={"category": "facts"},  # No user_id
+            )
+
+            await memory.add(content)
+
+            # Verify the graph.add mock was called
+            mock_client.graph.add.assert_called_once()
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_add_graph_data_requires_user_id(self):
+        """Test that adding graph data requires user_id."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+            mock_client.graph = MagicMock()
+            mock_client.graph.add = AsyncMock()
+
+            memory = ZepMemory(
+                client=mock_client,
+                user_id="test-user",  # user_id is now required
+                thread_id="test-session",
+            )
+
+            # Test adding memory content with unsupported type
+            content = MemoryContent(
+                content="Test data for graph",
+                mime_type=MemoryMimeType.TEXT,
+                metadata={"type": "unsupported", "category": "facts"},
+            )
+
+            with pytest.raises(ValueError, match="Unsupported metadata type"):
+                await memory.add(content)
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_query_with_mock(self):
+        """Test querying memory with a mock client."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+            mock_client.graph = MagicMock()
+            mock_client.graph.search = AsyncMock()
+
+            # Mock graph search response
+            mock_graph_response = MagicMock()
+            mock_graph_response.edges = []
+            mock_graph_response.nodes = []
+            mock_graph_response.episodes = []
+            mock_client.graph.search.return_value = mock_graph_response
+
+            memory = ZepMemory(client=mock_client, user_id="test-user", thread_id="test-session")
+
+            results = await memory.query("test query")
+
+            # Verify the mock was called and results returned
+            mock_client.graph.search.assert_called_once()
+            assert hasattr(results, "results")  # Should be a MemoryQueryResult
+            assert len(results.results) >= 0  # Should return some results
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_mime_type_validation(self):
+        """Test that ZepMemory validates mime types correctly."""
+        try:
+            from zep_cloud.client import AsyncZep
+
+            mock_client = MagicMock(spec=AsyncZep)
+            memory = ZepMemory(client=mock_client, user_id="test-user", thread_id="test-session")
+
+            # Test supported mime types - these should work (with user_id for message storage)
+            supported_types = [MemoryMimeType.TEXT, MemoryMimeType.MARKDOWN, MemoryMimeType.JSON]
+
+            mock_client.thread = MagicMock()
+            mock_client.thread.get = AsyncMock()
+            mock_client.thread.add_messages = AsyncMock()
+
+            for mime_type in supported_types:
+                content = MemoryContent(
+                    content="Test content",
+                    mime_type=mime_type,
+                    metadata={
+                        "type": "message",
+                        "role": "user",
+                        "name": "user123",
+                        "category": "test",
+                    },  # Add type for message storage
+                )
+                # Should not raise an exception
+                await memory.add(content)
+
+            # Test unsupported mime types - these should raise ValueError
+            unsupported_types = [MemoryMimeType.IMAGE, MemoryMimeType.BINARY]
+
+            for mime_type in unsupported_types:
+                unsupported_content = MemoryContent(
+                    content="Test content",
+                    mime_type=mime_type,
+                    metadata={"user_id": "user123", "category": "test"},  # Add user_id
+                )
+
+                with pytest.raises(ValueError, match="Unsupported mime type"):
+                    await memory.add(unsupported_content)
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+
+@pytest.mark.integration
+class TestZepMemoryReal:
+    """Integration tests with real Zep client (only run if ZEP_API_KEY is available)."""
+
+    @pytest.fixture
+    def zep_client(self):
+        """Create a real Zep client if API key is available."""
+        api_key = os.environ.get("ZEP_API_KEY")
+        if not api_key:
+            pytest.skip("ZEP_API_KEY not set - skipping integration tests")
+
+        try:
+            from zep_cloud.client import AsyncZep
+
+            return AsyncZep(api_key=api_key)
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    @pytest.mark.asyncio
+    async def test_zep_memory_real_client_initialization(self, zep_client):
+        """Test ZepMemory with a real Zep client."""
+        memory = ZepMemory(client=zep_client, thread_id="test-session-123", user_id="test-user-123")
+        assert memory is not None
+        assert memory._thread_id == "test-session-123"
+        assert memory._user_id == "test-user-123"