zep-crewai 0.1.0__tar.gz

zep_crewai-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_crewai-0.1.0/Makefile

@@ -0,0 +1,72 @@
+# Makefile for zep-crewai 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_crewai --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_crewai-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: zep-crewai
+Version: 0.1.0
+Summary: CrewAI integration for Zep
+Project-URL: Homepage, https://github.com/getzep/zep
+Project-URL: Documentation, https://help.getzep.com
+Project-URL: Repository, https://github.com/getzep/zep
+Project-URL: Bug Tracker, https://github.com/getzep/zep/issues
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: crewai>=0.80.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 CrewAI Integration Tutorial
+
+Learn how to add persistent memory to your CrewAI agents using Zep's powerful memory platform.
+
+## Installation
+
+Install the Zep CrewAI integration package:
+
+```bash
+pip install zep-crewai
+```
+
+## Setup
+
+### 1. Get Your API Key
+
+Sign up at [Zep Cloud](https://app.getzep.com) and get your API key.
+
+### 2. Set Environment Variable
+
+```bash
+export ZEP_API_KEY="your-zep-api-key"
+```
+
+## Basic Usage
+
+### 1. Initialize Zep Client
+
+```python
+import os
+from zep_cloud.client import Zep
+
+# Initialize Zep client
+zep_client = Zep(api_key=os.getenv("ZEP_API_KEY"))
+```
+
+### 2. Create User and Thread
+
+**Important**: You must create a user and thread in Zep before using ZepStorage.
+
+```python
+# Create a user 
+user_id = "john_doe_123"
+zep_client.user.add(
+    user_id=user_id,
+    first_name="John",
+    last_name="Doe",
+    email="john.doe@example.com"
+)
+
+# Create a thread 
+thread_id = "project_alpha_456"
+zep_client.thread.create(
+    user_id=user_id,
+    thread_id=thread_id
+)
+```
+
+### 3. Initialize ZepStorage
+
+```python
+from zep_crewai import ZepStorage
+from crewai.memory.external.external_memory import ExternalMemory
+
+# Create storage for your project
+zep_storage = ZepStorage(
+    client=zep_client,
+    user_id=user_id,   
+    thread_id=thread_id
+)
+
+# Wrap in CrewAI's external memory
+external_memory = ExternalMemory(storage=zep_storage)
+```
+
+### 4. Create Crew with Persistent Memory
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Create your agents
+research_agent = Agent(
+    role='Research Analyst',
+    goal='Analyze market trends and provide insights',
+    backstory='You are an expert at finding and analyzing market data...',
+)
+
+# Create crew with Zep memory
+crew = Crew(
+    agents=[research_agent],
+    tasks=[...],
+    external_memory=external_memory,  # This enables the crew to search Zep
+    process=Process.sequential,
+)
+
+# Run your crew - memories will be automatically saved and retrieved
+result = crew.kickoff()
+```
+
+## How Memory Works
+
+Zep stores different types of content using metadata-based routing.
+
+### Messages (Conversation Context)
+Stored in Zep threads for conversation history:
+
+```python
+external_memory.save(
+    "I need help planning a business trip to New York",
+    metadata={"type": "message", "role": "user", "name": "John Doe"}
+)
+
+external_memory.save(
+    "I'd be happy to help you plan your trip!",
+    metadata={"type": "message", "role": "assistant", "name": "Travel Agent"}
+)
+```
+
+### Structured Data
+Added as episodes to the user knowledge graph in Zep:
+
+```python
+# JSON data
+external_memory.save(
+    '{"destination": "New York", "duration": "3 days", "budget": 2000}',
+    metadata={"type": "json"}
+)
+
+# Text facts and insights
+external_memory.save(
+    "User prefers mid-range hotels with business amenities",
+    metadata={"type": "text"}
+)
+```
+
+### Automatic Memory Retrieval
+
+CrewAI automatically searches your memories when agents need context:
+
+```python
+# When agents run, they automatically get relevant context from Zep
+results = crew.kickoff()
+
+# You can also search manually
+memory_results = zep_storage.search("hotel preferences", limit=5)
+for result in memory_results:
+    print(result['memory'])
+```
+
+## Complete Example
+
+For a full working example, check out [`examples/simple_example.py`](examples/simple_example.py) in this repository. This example demonstrates:
+
+- Setting up Zep user and thread
+- Saving different types of memory (messages, JSON data, text)
+- Creating CrewAI agents with access to Zep memory
+- Automatic context retrieval during agent execution
+
+## Requirements
+
+- Python 3.10+
+- `zep-cloud>=3.0.0rc1`
+- `crewai>=0.80.0`

zep_crewai-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Zep CrewAI Integration Tutorial
+
+Learn how to add persistent memory to your CrewAI agents using Zep's powerful memory platform.
+
+## Installation
+
+Install the Zep CrewAI integration package:
+
+```bash
+pip install zep-crewai
+```
+
+## Setup
+
+### 1. Get Your API Key
+
+Sign up at [Zep Cloud](https://app.getzep.com) and get your API key.
+
+### 2. Set Environment Variable
+
+```bash
+export ZEP_API_KEY="your-zep-api-key"
+```
+
+## Basic Usage
+
+### 1. Initialize Zep Client
+
+```python
+import os
+from zep_cloud.client import Zep
+
+# Initialize Zep client
+zep_client = Zep(api_key=os.getenv("ZEP_API_KEY"))
+```
+
+### 2. Create User and Thread
+
+**Important**: You must create a user and thread in Zep before using ZepStorage.
+
+```python
+# Create a user 
+user_id = "john_doe_123"
+zep_client.user.add(
+    user_id=user_id,
+    first_name="John",
+    last_name="Doe",
+    email="john.doe@example.com"
+)
+
+# Create a thread 
+thread_id = "project_alpha_456"
+zep_client.thread.create(
+    user_id=user_id,
+    thread_id=thread_id
+)
+```
+
+### 3. Initialize ZepStorage
+
+```python
+from zep_crewai import ZepStorage
+from crewai.memory.external.external_memory import ExternalMemory
+
+# Create storage for your project
+zep_storage = ZepStorage(
+    client=zep_client,
+    user_id=user_id,   
+    thread_id=thread_id
+)
+
+# Wrap in CrewAI's external memory
+external_memory = ExternalMemory(storage=zep_storage)
+```
+
+### 4. Create Crew with Persistent Memory
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Create your agents
+research_agent = Agent(
+    role='Research Analyst',
+    goal='Analyze market trends and provide insights',
+    backstory='You are an expert at finding and analyzing market data...',
+)
+
+# Create crew with Zep memory
+crew = Crew(
+    agents=[research_agent],
+    tasks=[...],
+    external_memory=external_memory,  # This enables the crew to search Zep
+    process=Process.sequential,
+)
+
+# Run your crew - memories will be automatically saved and retrieved
+result = crew.kickoff()
+```
+
+## How Memory Works
+
+Zep stores different types of content using metadata-based routing.
+
+### Messages (Conversation Context)
+Stored in Zep threads for conversation history:
+
+```python
+external_memory.save(
+    "I need help planning a business trip to New York",
+    metadata={"type": "message", "role": "user", "name": "John Doe"}
+)
+
+external_memory.save(
+    "I'd be happy to help you plan your trip!",
+    metadata={"type": "message", "role": "assistant", "name": "Travel Agent"}
+)
+```
+
+### Structured Data
+Added as episodes to the user knowledge graph in Zep:
+
+```python
+# JSON data
+external_memory.save(
+    '{"destination": "New York", "duration": "3 days", "budget": 2000}',
+    metadata={"type": "json"}
+)
+
+# Text facts and insights
+external_memory.save(
+    "User prefers mid-range hotels with business amenities",
+    metadata={"type": "text"}
+)
+```
+
+### Automatic Memory Retrieval
+
+CrewAI automatically searches your memories when agents need context:
+
+```python
+# When agents run, they automatically get relevant context from Zep
+results = crew.kickoff()
+
+# You can also search manually
+memory_results = zep_storage.search("hotel preferences", limit=5)
+for result in memory_results:
+    print(result['memory'])
+```
+
+## Complete Example
+
+For a full working example, check out [`examples/simple_example.py`](examples/simple_example.py) in this repository. This example demonstrates:
+
+- Setting up Zep user and thread
+- Saving different types of memory (messages, JSON data, text)
+- Creating CrewAI agents with access to Zep memory
+- Automatic context retrieval during agent execution
+
+## Requirements
+
+- Python 3.10+
+- `zep-cloud>=3.0.0rc1`
+- `crewai>=0.80.0`

zep_crewai-0.1.0/examples/simple_example.py

@@ -0,0 +1,168 @@
+"""
+Simple CrewAI + Zep integration example.
+
+This example demonstrates the basic usage of ZepStorage with CrewAI's external memory system.
+It shows how to manually save important information and let CrewAI automatically retrieve it
+during agent execution.
+"""
+
+import os
+import sys
+import time
+import uuid
+
+from crewai import Agent, Crew, Process, Task
+from crewai.memory.external.external_memory import ExternalMemory
+from zep_cloud.client import Zep
+
+from zep_crewai import ZepStorage
+
+
+def main():
+    # Check for API key
+    api_key = os.environ.get("ZEP_API_KEY")
+    if not api_key:
+        print("❌ Error: Please set your ZEP_API_KEY environment variable")
+        print("   Get your API key from: https://app.getzep.com")
+        sys.exit(1)
+
+    # Initialize Zep client
+    zep_client = Zep(api_key=api_key)
+
+    print("\n🤖 CrewAI + Zep Memory Integration Example")
+    print("=" * 50)
+
+    # Set up user and thread
+    user_id = "demo_user_" + str(uuid.uuid4())
+    thread_id = "demo_thread_" + str(uuid.uuid4())
+
+    print(f"👤 User ID: {user_id}")
+    print(f"🧵 Thread ID: {thread_id}")
+
+    # Create user in Zep
+    try:
+        zep_client.user.add(
+            user_id=user_id, first_name="John", last_name="Doe", email="john.doe@example.com"
+        )
+        print("✅ User created successfully")
+    except Exception as e:
+        if "already exists" in str(e).lower():
+            print("✅ User already exists")
+        else:
+            print(f"⚠️  User creation issue: {e}")
+
+    # Create thread
+    try:
+        zep_client.thread.create(user_id=user_id, thread_id=thread_id)
+        print("✅ Thread created successfully")
+    except Exception as e:
+        print(f"⚠️  Thread creation issue: {e}")
+
+    # Initialize Zep storage and external memory
+    zep_storage = ZepStorage(client=zep_client, user_id=user_id, thread_id=thread_id)
+    external_memory = ExternalMemory(storage=zep_storage)
+
+    # Save conversation context and data (demonstrates metadata-based routing)
+    print("\n💾 Saving conversation and business context to Zep...")
+
+    # Save structured business trip data (goes to graph via json type)
+    external_memory.save(
+        '{"trip_type": "business", "destination": "New York", "duration": "3 days", "budget": 2000, "accommodation_preference": "mid-range hotels", "dietary_preference": "local cuisine"}',
+        metadata={"type": "json"},
+    )
+
+    # Save user messages (go to thread via message type)
+    external_memory.save(
+        "Hi, I need help planning a business trip to New York. I'll be there for 3 days and prefer mid-range hotels.",
+        metadata={"type": "message", "role": "user", "name": "John Doe"},
+    )
+
+    external_memory.save(
+        "I'd be happy to help you plan your New York business trip! Let me find some great mid-range hotel options for you.",
+        metadata={"type": "message", "role": "assistant", "name": "Travel Planning Assistant"},
+    )
+
+    # Save user preferences as text data (goes to graph via text type)
+    external_memory.save(
+        "John Doe prefers mid-range hotels with business amenities, enjoys trying local cuisine, and values convenient locations near business districts",
+        metadata={"type": "text"},
+    )
+
+    external_memory.save(
+        "Could you also recommend some good restaurants nearby? I love trying authentic local food when I travel for business.",
+        metadata={"type": "message", "role": "user", "name": "John Doe"},
+    )
+
+    # Save budget constraint as text data (goes to graph)
+    external_memory.save(
+        "John Doe's budget constraint: Total budget is around $2000 for the entire trip including flights and accommodation. Looking for good value rather than luxury.",
+        metadata={"type": "text"},
+    )
+
+    print("✅ Context saved to Zep memory")
+    print("   • Messages → Thread API (conversation context)")
+    print("   • JSON data → Graph API (structured trip info)")
+    print("   • Text data → Graph API (preferences & constraints)")
+    print(
+        "   (Waiting 20 seconds until data is processed in zep)"
+    )  # Give time for Zep to index the data
+    time.sleep(20)
+
+    # Create a simple agent
+    travel_agent = Agent(
+        role="Travel Planning Assistant",
+        goal="Help plan business trips efficiently and within budget",
+        backstory="""You are an experienced travel planner who specializes in business trips.
+        You always consider the user's preferences, budget constraints, and trip context
+        to provide practical recommendations.""",
+        verbose=True,
+        llm="gpt-4.1-mini",
+    )
+
+    # Create a simple task
+    planning_task = Task(
+        description="""Based on the user's saved preferences and context, provide 3 specific
+        hotel recommendations in New York that would be good for a business traveler.
+
+        Include:
+        - Hotel names and locations
+        - Price range per night
+        - Why each hotel fits the user's preferences
+        - Any special business amenities""",
+        expected_output="A list of 3 hotel recommendations with detailed explanations",
+        agent=travel_agent,
+    )
+
+    # Create crew with Zep memory
+    crew = Crew(
+        agents=[travel_agent],
+        tasks=[planning_task],
+        process=Process.sequential,
+        external_memory=external_memory,  # This enables automatic memory retrieval during execution
+        verbose=True,
+    )
+
+    print("\n🚀 Starting CrewAI execution...")
+    print("   (The agent will automatically retrieve context from Zep memory)")
+
+    # Execute the crew - CrewAI will automatically call zep_storage.search() to get context
+    try:
+        result = crew.kickoff()
+
+        print("\n" + "=" * 60)
+        print("RESULT:")
+        print("=" * 60)
+        print(result)
+        print("=" * 60)
+
+        # Optionally save the result back to memory for future use
+        external_memory.save(str(result), metadata={"type": "message", "role": "assistant"})
+        print("\n💾 Agent result saved to memory for future reference")
+
+    except Exception as e:
+        print(f"\n❌ Execution failed: {e}")
+        return
+
+
+if __name__ == "__main__":
+    main()

zep_crewai-0.1.0/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name = "zep-crewai"
+version = "0.1.0"
+description = "CrewAI integration for Zep"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "crewai>=0.80.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://help.getzep.com"
+Repository = "https://github.com/getzep/zep"
+"Bug Tracker" = "https://github.com/getzep/zep/issues"
+
+[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_crewai"]
+
+[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_crewai"]
+
+[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 = [
+    "crewai.*",
+    "zep_cloud.*",
+]
+ignore_missing_imports = true

zep_crewai-0.1.0/src/zep_crewai/__init__.py

@@ -0,0 +1,45 @@
+"""
+Zep CrewAI Integration.
+
+This package provides memory integration between Zep and CrewAI agents,
+enabling persistent conversation memory and context retrieval.
+
+Installation:
+    pip install zep-crewai
+
+Usage:
+    from zep_crewai import ZepStorage
+    from zep_cloud.client import AsyncZep
+    from crewai.memory.external.external_memory import ExternalMemory
+    from crewai import Crew
+
+    # Initialize Zep client and storage
+    zep_client = AsyncZep(api_key="your-api-key")
+    zep_storage = ZepStorage(client=zep_client, user_id="user123", thread_id="thread123")
+    external_memory = ExternalMemory(storage=zep_storage)
+
+    # Create crew with Zep memory
+    crew = Crew(
+        agents=[...],
+        tasks=[...],
+        external_memory=external_memory
+    )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Zep AI"
+__description__ = "Zep integration for CrewAI"
+
+from .exceptions import ZepDependencyError
+
+try:
+    # Check for required CrewAI dependencies - just test import
+    import crewai.memory.storage.interface  # noqa: F401
+
+    # Import our integration
+    from .memory import ZepStorage
+
+    __all__ = ["ZepStorage", "ZepDependencyError"]
+
+except ImportError as e:
+    raise ZepDependencyError(framework="CrewAI", install_command="pip install zep-crewai") from e

zep_crewai-0.1.0/src/zep_crewai/exceptions.py

@@ -0,0 +1,12 @@
+"""
+Exception classes for CrewAI integration.
+"""
+
+
+class ZepDependencyError(ImportError):
+    """Raised when required CrewAI 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_crewai-0.1.0/src/zep_crewai/memory.py

@@ -0,0 +1,177 @@
+"""
+Zep Memory integration for CrewAI.
+
+This module provides memory storage that integrates Zep with CrewAI's memory system.
+"""
+
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+from crewai.memory.storage.interface import Storage
+from zep_cloud.client import Zep
+from zep_cloud.types import GraphSearchResults, Message
+
+
+class ZepStorage(Storage):
+    """
+    A storage implementation that integrates with Zep for persistent storage
+    and retrieval of CrewAI agent memories.
+    """
+
+    def __init__(self, client: Zep, user_id: str, thread_id: str, **kwargs: Any) -> None:
+        """
+        Initialize ZepStorage with a Zep client instance.
+
+        Args:
+            client: An initialized Zep instance (sync client)
+            user_id: User ID identifying a created Zep user (required)
+            thread_id: Thread ID identifying current conversation thread (required)
+            **kwargs: Additional configuration options
+        """
+        if not isinstance(client, Zep):
+            raise TypeError("client must be an instance of Zep")
+
+        if not user_id:
+            raise ValueError("user_id is required")
+
+        if not thread_id:
+            raise ValueError("thread_id is required")
+
+        self._client = client
+        self._user_id = user_id
+        self._thread_id = thread_id
+        self._config = kwargs
+
+        self._logger = logging.getLogger(__name__)
+
+    def save(self, value: Any, metadata: dict[str, Any] | None = None) -> None:
+        """
+        Save a memory entry to Zep using metadata-based routing.
+
+        Routes storage based on metadata.type:
+        - "message": Store as thread message with role from metadata
+        - "json" or "text": Store as graph data
+
+        Args:
+            value: The memory content to store
+            metadata: Metadata including type, role, name, etc.
+        """
+        metadata = metadata or {}
+
+        content_str = str(value)
+        content_type = metadata.get("type", "text")
+        if content_type not in ["message", "json", "text"]:
+            content_type = "text"
+
+        try:
+            if content_type == "message":
+                message_metadata = metadata.copy()
+                role = message_metadata.get("role", "norole")
+                name = message_metadata.get("name")
+
+                message = Message(
+                    role=role,
+                    name=name,
+                    content=content_str,
+                )
+
+                self._client.thread.add_messages(thread_id=self._thread_id, messages=[message])
+
+                self._logger.debug(
+                    f"Saved message from {metadata.get('name', 'unknown')}: {content_str[:100]}..."
+                )
+
+            else:
+                self._client.graph.add(
+                    user_id=self._user_id,
+                    data=content_str,
+                    type=content_type,
+                )
+
+                self._logger.debug(f"Saved {content_type} data: {content_str[:100]}...")
+
+        except Exception as e:
+            self._logger.error(f"Error saving to Zep: {e}")
+            raise
+
+    def search(
+        self, query: str, limit: int = 5, score_threshold: float = 0.5
+    ) -> dict[str, Any] | list[Any]:
+        """
+        Search Zep user graph.
+
+        This always retrieves thread-specific context and performs targeted graph search on the user graph
+        using the provided query, combining both sources.
+
+        Args:
+            query: Search query string (truncated to 400 chars max for graph search)
+            limit: Maximum number of results to return from graph search
+
+        Returns:
+            List of matching memory entries from both thread context and graph search
+        """
+        results: list[dict[str, Any]] = []
+
+        # Truncate query to max 400 characters to avoid API errors
+        truncated_query = query[:400] if len(query) > 400 else query
+
+        # Define search functions for concurrent execution
+        def get_thread_context() -> Any:
+            try:
+                return self._client.thread.get_user_context(thread_id=self._thread_id)
+            except Exception as e:
+                self._logger.debug(f"Thread context not available: {e}")
+                return None
+
+        def search_graph_edges() -> list[str]:
+            try:
+                if not query:
+                    return []
+                results: GraphSearchResults = self._client.graph.search(
+                    user_id=self._user_id, query=truncated_query, limit=limit, scope="edges"
+                )
+                edges: list[str] = []
+                if results.edges:
+                    for edge in results.edges:
+                        edge_str = f"{edge.fact} (valid_at: {edge.valid_at}, invalid_at: {edge.invalid_at or 'current'})"
+                        edges.append(edge_str)
+                return edges
+            except Exception as e:
+                self._logger.debug(f"Graph search not available: {e}")
+                return []
+
+        thread_context = None
+        edges_search_results: list[str] = []
+
+        try:
+            with ThreadPoolExecutor(max_workers=2) as executor:
+                future_thread = executor.submit(get_thread_context)
+                future_edges = executor.submit(search_graph_edges)
+
+                thread_context = future_thread.result()
+                edges_search_results = future_edges.result() or []
+
+        except Exception as e:
+            self._logger.debug(f"Failed to search user memories: {e}")
+
+        if thread_context and hasattr(thread_context, "context") and thread_context.context:
+            results.append({"memory": thread_context.context})
+
+        for result in edges_search_results:
+            results.append({"memory": result})
+
+        return results
+
+    def reset(self) -> None:
+        pass
+
+    @property
+    def user_id(self) -> str:
+        """Get the user ID."""
+        return self._user_id
+
+    @property
+    def thread_id(self) -> str:
+        """Get the thread ID."""
+        return self._thread_id

zep_crewai-0.1.0/tests/test_basic.py

@@ -0,0 +1,210 @@
+"""
+Basic tests for the zep-crewai package.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from zep_crewai import ZepStorage
+
+
+def test_package_import():
+    """Test that the package can be imported successfully."""
+    import zep_crewai
+
+    assert zep_crewai is not None
+
+
+def test_zep_storage_import():
+    """Test that ZepStorage can be imported successfully."""
+    assert ZepStorage is not None
+
+
+class TestBasicFunctionality:
+    """Basic functionality tests for the zep-crewai package."""
+
+    def test_package_structure(self):
+        """Test that the package has the expected structure."""
+        import zep_crewai
+
+        assert hasattr(zep_crewai, "__version__")
+        assert hasattr(zep_crewai, "__author__")
+        assert hasattr(zep_crewai, "__description__")
+
+
+class TestZepStorageMock:
+    """Test ZepStorage with mock clients."""
+
+    def test_zep_storage_initialization_with_mock(self):
+        """Test that ZepStorage can be initialized with a mock client."""
+        try:
+            from zep_cloud.client import Zep
+
+            # Create a mock Zep client
+            mock_client = MagicMock(spec=Zep)
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+            assert storage is not None
+            assert storage._client is mock_client
+            assert storage._user_id == "test-user"
+            assert storage._thread_id == "test-thread"
+
+        except ImportError:
+            # If zep_cloud is not available, test with a generic mock
+            class MockZep:
+                pass
+
+            mock_client = MockZep()
+            with pytest.raises(TypeError, match="client must be an instance of Zep"):
+                ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+    def test_zep_storage_requires_user_id_and_thread_id(self):
+        """Test that ZepStorage requires both user_id and thread_id."""
+        try:
+            from zep_cloud.client import Zep
+
+            mock_client = MagicMock(spec=Zep)
+
+            with pytest.raises(ValueError, match="user_id is required"):
+                ZepStorage(client=mock_client, user_id="", thread_id="test-thread")
+
+            with pytest.raises(ValueError, match="thread_id is required"):
+                ZepStorage(client=mock_client, user_id="test-user", thread_id="")
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_storage_requires_zep_client(self):
+        """Test that ZepStorage raises TypeError when client is not Zep."""
+        with pytest.raises(TypeError, match="client must be an instance of Zep"):
+            ZepStorage(client="not_a_client", user_id="test-user", thread_id="test-thread")
+
+    def test_zep_storage_save_message_sync(self):
+        """Test saving memory as thread message using sync interface."""
+        try:
+            from zep_cloud.client import Zep
+
+            mock_client = MagicMock(spec=Zep)
+            mock_client.thread = MagicMock()
+            mock_client.thread.add_messages = MagicMock()
+
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+            # Test saving message content to thread
+            storage.save(
+                "Test message content",
+                metadata={"type": "message", "role": "user", "name": "John Doe"},
+            )
+
+            # Verify the thread add_messages was called
+            mock_client.thread.add_messages.assert_called_once()
+
+            # Check the call arguments
+            call_args = mock_client.thread.add_messages.call_args
+            assert call_args[1]["thread_id"] == "test-thread"
+            assert len(call_args[1]["messages"]) == 1
+
+            message = call_args[1]["messages"][0]
+            assert message.content == "Test message content"
+            assert message.role == "user"
+            assert message.name == "John Doe"
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_storage_save_graph_sync(self):
+        """Test saving memory as graph data using sync interface."""
+        try:
+            from zep_cloud.client import Zep
+
+            mock_client = MagicMock(spec=Zep)
+            mock_client.graph = MagicMock()
+            mock_client.graph.add = MagicMock()
+
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+            # Test saving text content to graph
+            storage.save("Test text content", metadata={"type": "text", "category": "facts"})
+
+            # Verify the graph add was called
+            mock_client.graph.add.assert_called_once()
+
+            # Check the call arguments
+            call_args = mock_client.graph.add.call_args
+            assert call_args[1]["user_id"] == "test-user"
+            assert call_args[1]["data"] == "Test text content"
+            assert call_args[1]["type"] == "text"
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_storage_search_sync(self):
+        """Test searching memory using sync interface."""
+        try:
+            from zep_cloud.client import Zep
+            from zep_cloud.types import EntityEdge, GraphSearchResults
+
+            mock_client = MagicMock(spec=Zep)
+            mock_client.thread = MagicMock()
+            mock_client.thread.get_user_context = MagicMock()
+            mock_client.graph = MagicMock()
+            mock_client.graph.search = MagicMock()
+
+            # Mock thread context response
+            mock_thread_context = MagicMock()
+            mock_thread_context.context = "Mock thread context summary"
+            mock_client.thread.get_user_context.return_value = mock_thread_context
+
+            # Mock graph search response
+            mock_edge = MagicMock(spec=EntityEdge)
+            mock_edge.fact = "Mock fact from graph"
+            mock_edge.valid_at = "2023-01-01"
+            mock_edge.invalid_at = None
+
+            mock_graph_results = MagicMock(spec=GraphSearchResults)
+            mock_graph_results.edges = [mock_edge]
+            mock_client.graph.search.return_value = mock_graph_results
+
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+            results = storage.search("test query", limit=5)
+
+            # Should return a list of results
+            assert isinstance(results, list)
+            assert len(results) >= 1  # At least thread context
+
+            # Verify both thread context and graph search were called
+            mock_client.thread.get_user_context.assert_called_once_with(thread_id="test-thread")
+            mock_client.graph.search.assert_called_once()
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_storage_reset_sync(self):
+        """Test resetting memory using sync interface."""
+        try:
+            from zep_cloud.client import Zep
+
+            mock_client = MagicMock(spec=Zep)
+
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+            # Should not raise an exception (currently just logs a warning)
+            storage.reset()
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")
+
+    def test_zep_storage_properties(self):
+        """Test ZepStorage properties."""
+        try:
+            from zep_cloud.client import Zep
+
+            mock_client = MagicMock(spec=Zep)
+            storage = ZepStorage(client=mock_client, user_id="test-user", thread_id="test-thread")
+
+            assert storage.user_id == "test-user"
+            assert storage.thread_id == "test-thread"
+
+        except ImportError:
+            pytest.skip("zep_cloud not available")