feat: Enhance CrewAI integration with broader Zep functionality

[paul-paliychuk]

Summary

• Enhanced the CrewAI integration to match the functionality and patterns of the existing Autogen integration
• Added support for broader Zep functionality including user graphs, knowledge graphs, search filters, and tools
• Implemented distinct storage classes for graph and user data with CrewAI-native tools

Changes

New Storage Classes

• ZepGraphStorage: Storage implementation for Zep's generic knowledge graphs

  • Performs parallel searches across edges, nodes, and episodes
  • Uses compose_context_string() for context formatting
  • Supports search filters for refined queries

• ZepUserStorage: Storage implementation for user-specific graphs and threads

  • Required thread_id parameter for thread context
  • Supports mode parameter for context retrieval ("summary" or "raw_messages")
  • Performs multi-dimensional graph searches on user data

New Tools

• ZepSearchTool: CrewAI-native tool for searching Zep graphs
• ZepAddDataTool: CrewAI-native tool for adding data to Zep graphs
• Both tools use private attributes pattern for Pydantic compatibility

Shared Utilities

• search_graph_and_compose_context(): Extracted common logic for parallel graph searches
• Reduces code duplication between storage classes
• Handles concurrent searches efficiently using ThreadPoolExecutor

Tests and Examples

• Comprehensive test coverage for all new components
• Real-world examples demonstrating usage patterns
• Mock-based example showing context data flow
• All examples use environment variables for API keys (no hardcoded secrets)

Key Design Decisions

1. No backwards compatibility: Fresh implementation as requested
2. Thread ID required: Made thread_id a required parameter in ZepUserStorage
3. Direct context retrieval: ZepUserStorage uses thread.get_user_context() directly, not compose_context_string()
4. Parallel searches: All graph searches run concurrently for performance
5. Unified search method: Both storage classes implement search with multi-dimensional graph queries

Testing

• Unit tests for storage classes and tools
• Integration examples with mock data
• Verified CrewAI memory retrieval patterns (no automatic saves)

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

---

Important

Enhances CrewAI integration with Zep by adding new storage classes, tools, utilities, examples, and tests for handling user and graph data.

• Behavior:
  • Adds ZepGraphStorage for generic knowledge graphs with parallel searches and context composition.
  • Adds ZepUserStorage for user-specific graphs and threads with context retrieval modes.
  • Introduces ZepSearchTool and ZepAddDataTool for searching and adding data to Zep storage.
• Utilities:
  • Implements search_graph_and_compose_context() for parallel graph searches and context composition.
• Examples:
  • Adds examples for using ZepGraphStorage, ZepUserStorage, and tools in examples/.
• Tests:
  • Comprehensive tests for ZepGraphStorage, ZepUserStorage, and tools in tests/.
• Misc:
  • Updates README.md with installation, usage, and configuration details.

^{This description was created by for 660bcf5. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Caution

Changes requested ❌

Reviewed everything up to e2e0f6b in 2 minutes and 13 seconds. Click for details.

• Reviewed 3624 lines of code in 13 files
• Skipped 0 files when reviewing.
• Skipped posting 1 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. integrations/python/zep_crewai/src/zep_crewai/user_storage.py:56

• Draft comment:
  The init method forces a thread_id (raising 'thread_id is required'), but the README and tests (e.g. test_initialization_without_thread) indicate that thread_id should be optional. Consider making thread_id optional (and then adjusting get_context behavior) to align with documentation and tests.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% While the comment references external documentation and tests, we can't verify those claims without seeing them. The code itself shows thread_id is used in critical functionality like save() for message types. Making it optional would require significant behavioral changes. Without seeing the conflicting documentation/tests, we can't be certain there's really an inconsistency. I may be too skeptical of the comment - if there are indeed tests and documentation showing thread_id should be optional, that's strong evidence of an inconsistency that should be addressed. However, without being able to verify the referenced documentation and tests, we can't be certain the comment is correct. The code's current design clearly depends on thread_id for core functionality. Given we can't verify the external documentation/tests the comment refers to, and following the principle of requiring strong evidence to keep comments, we should remove this comment.

Workflow ID: wflow_LXQNP73bdN9Vangg

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 451d9a7 in 2 minutes and 30 seconds. Click for details.

• Reviewed 351 lines of code in 2 files
• Skipped 0 files when reviewing.
• Skipped posting 3 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. integrations/python/zep_crewai/src/zep_crewai/user_storage.py:175

• Draft comment:
  Thread check in get_context() (line 175) may be redundant since thread_id is required in init. Consider removing it if no empty string is allowed.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% The comment points out a real redundancy since thread_id is validated in init. However, defensive programming with null checks is often good practice even when theoretically redundant. The check is simple and adds safety. The comment isn't pointing out a clear problem that needs fixing. The comment could be right that it's technically redundant, but removing safety checks can make code more brittle. What if the class is subclassed or modified later? While technically correct about the redundancy, the suggestion to remove a safety check isn't clearly beneficial and could make the code less robust. The comment should be removed as it's suggesting an optional change that isn't clearly beneficial and could potentially reduce code safety.

2. integrations/python/zep_crewai/tests/test_user_storage.py:405

• Draft comment:
  Using mock_client.assert_not_called() in test_reset_does_nothing may not catch calls on its sub-attributes. Consider asserting that mock_client.mock_calls is empty instead.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

3. integrations/python/zep_crewai/tests/test_user_storage.py:392

• Draft comment:
  Test for search filters relies on client.graph.search call arguments. Ensure that if the underlying implementation of search_graph_and_compose_context changes, this test still reliably verifies that search_filters are passed correctly.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_bni6LasQ1xHzCpc9

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 0ef6ccd in 1 minute and 29 seconds. Click for details.

• Reviewed 2660 lines of code in 12 files
• Skipped 0 files when reviewing.
• Skipped posting 2 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. integrations/python/zep_crewai/tests/test_user_storage.py:42

• Draft comment:
  In test_initialization_without_thread_raises_error, you expect a TypeError for a missing 'thread_id'. Consider having ZepUserStorage explicitly check for an empty or missing thread_id and raise a ValueError instead—this would allow for more controlled error handling.
• Reason this comment was not posted:
  Comment was on unchanged code.

2. integrations/python/zep_crewai/tests/test_user_storage.py:369

• Draft comment:
  The test_reset_does_nothing method uses mock_client.assert_not_called() to verify that reset() does nothing. This check might be too broad; consider asserting that specific client methods (like graph.add or thread.add_messages) are not called, to ensure that reset() truly has no side effects.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_Wyh0VjyX106CyPru

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 660bcf5 in 1 minute and 24 seconds. Click for details.

• Reviewed 357 lines of code in 2 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. integrations/python/zep_crewai/src/zep_crewai/tools.py:169

• Draft comment:
  Minor style change: switched from single to double quotes for string literals. This is acceptable but ensure consistent quoting throughout the codebase.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

2. integrations/python/zep_crewai/tests/test_graph_storage.py:103

• Draft comment:
  Refactored 'test_search_with_results' now patches 'search_graph_and_compose_context'. The test cleanly verifies that the composed context is returned with all expected keys.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

3. integrations/python/zep_crewai/tests/test_graph_storage.py:148

• Draft comment:
  The 'test_search_with_no_results' correctly handles a None return value from the search function and returns an empty list. This is clear and concise.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

4. integrations/python/zep_crewai/tests/test_graph_storage.py:168

• Draft comment:
  In 'test_search_with_custom_limits', custom limits (facts_limit, entity_limit, episodes_limit) are properly passed to the search function. This aligns well with the intended behavior.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

5. integrations/python/zep_crewai/tests/test_graph_storage.py:197

• Draft comment:
  The 'test_search_with_filters' properly verifies that the search filters are passed to the search function, ensuring that filter functionality is not lost.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

6. integrations/python/zep_crewai/tests/test_graph_storage.py:227

• Draft comment:
  In 'test_reset_does_nothing', using mock_client.assert_not_called() might not effectively check if methods on attributes were invoked. Consider verifying that 'mock_client.method_calls' is empty instead.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 50% None

Workflow ID: wflow_tJdvyiBCKUr7hO8P

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}