{"id":9419,"library":"zep-python","title":"Zep Python Client","description":"Zep is an open-source platform for long-term memory for AI agents, providing capabilities for summarization, embedding, and document management. The `zep-python` library offers an asynchronous client to interact with the Zep API, facilitating the management of user sessions, messages, and document collections. It is currently at version 2.0.2 and maintains an active release cadence with frequent updates and patches.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/getzep/zep-python","tags":["AI","LLM","memory","async","langchain","agents"],"install":[{"cmd":"pip install zep-python","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Asynchronous HTTP client for API communication.","package":"httpx","optional":false},{"reason":"Data validation and settings management for models.","package":"pydantic","optional":false}],"imports":[{"note":"The top-level package for the client is `zep_python`, not `zep`.","wrong":"from zep import ZepClient","symbol":"ZepClient","correct":"from zep_python import ZepClient"},{"note":"Data models like `Message` are now found under the `zep_python.models` module in v2.","wrong":"from zep_python.message import Message","symbol":"Message","correct":"from zep_python.models import Message"},{"symbol":"Memory","correct":"from zep_python.models import Memory"},{"symbol":"Document","correct":"from zep_python.models import Document"}],"quickstart":{"code":"import asyncio\nimport os\nfrom zep_python import ZepClient\nfrom zep_python.models import Message, Memory\n\nasync def main():\n    # Ensure ZEP_API_URL is set in your environment or provide a default\n    api_url = os.environ.get(\"ZEP_API_URL\", \"http://localhost:8000\")\n    api_key = os.environ.get(\"ZEP_API_KEY\", \"\") # Zep API key if authentication is enabled\n\n    client = ZepClient(api_url=api_url, api_key=api_key)\n\n    session_id = \"my-test-session-123\"\n    user_id = \"test_user\" # Optional\n\n    try:\n        # Sessions must be explicitly created before adding messages (Zep v2+)\n        await client.add_session(session_id=session_id, user_id=user_id, metadata={\"project\": \"chatbot\"})\n        print(f\"Session '{session_id}' created.\")\n    except Exception as e:\n        # Session might already exist, or another error occurred\n        if \"already exists\" in str(e):\n            print(f\"Session '{session_id}' already exists.\")\n        else:\n            print(f\"Error creating session '{session_id}': {e}\")\n\n    # Add messages to the session\n    messages_to_add = [\n        Message(role=\"user\", content=\"Hello, my name is Alice.\"),\n        Message(role=\"assistant\", content=\"Hi Alice, how can I help you today?\")\n    ]\n    await client.add_transcript(session_id=session_id, messages=messages_to_add)\n    print(f\"Added {len(messages_to_add)} messages to session '{session_id}'.\")\n\n    # Retrieve memory for the session\n    memory: Memory = await client.get_memory(session_id=session_id)\n    if memory and memory.messages:\n        print(f\"\\nRetrieved memory for session '{session_id}':\")\n        for msg in memory.messages:\n            print(f\"  {msg.role}: {msg.content}\")\n    else:\n        print(f\"\\nNo memory found or memory is empty for session '{session_id}'.\")\n\n    # Clean up: delete the session (uncomment to enable)\n    # await client.delete_session(session_id=session_id)\n    # print(f\"Session '{session_id}' deleted.\")\n\n    # Close the client session\n    await client.close()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates initializing the ZepClient, creating a new session (or handling an existing one), adding messages to that session, and then retrieving the session's memory. All client operations are asynchronous and require `await`."},"warnings":[{"fix":"Migrate your code to use the new async API. All client methods are now `await`able. Refer to the official Zep v2 migration guide.","message":"Zep Python Client v2.x is a complete rewrite and is **not backward compatible** with v1.x. It is an asynchronous-only client, uses `httpx` internally, and has significant API changes.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update method calls to their new v2 equivalents. Always `await` client method calls as they are now asynchronous.","message":"The `ZepClient` constructor and many core methods have changed names and signatures in v2. For example, `add_message` is now `add_transcript`, and `get_session_memory` is `get_memory`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure you call `await client.add_session(session_id=...)` first, wrapping it in a `try-except` block to handle cases where the session might already exist.","message":"In Zep v2+, you must explicitly create a session using `client.add_session()` before you can add messages or interact with its memory. Attempting to add messages to a non-existent session will result in a `NotFoundError`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always prepend `await` to any Zep client method call. Ensure your application's entry point uses `asyncio.run()`.","message":"The `zep-python` client is fully asynchronous. Forgetting `await` before client method calls (`client.add_session()`, `client.get_memory()`, etc.) will lead to runtime errors or unexpected behavior.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are awaiting specific methods of the client, e.g., `await client.add_session(...)`. If you see `TypeError: object NoneType can't be used in 'await' expression`, it likely means an awaited method returned `None` when you expected an object, often due to an underlying error.","cause":"You are trying to `await` the `ZepClient` object itself, or calling an `async` method without `await`.","error":"TypeError: object ZepClient can't be used in 'await' expression"},{"fix":"Before interacting with a session, ensure it is created using `await client.add_session(session_id=..., ...)`. You can wrap this call in a `try-except` block to handle cases where the session might already exist.","cause":"You are attempting to interact with a session (e.g., add messages or get memory) that has not yet been created or does not exist on the Zep server.","error":"zep_python.exceptions.NotFoundError: Session with session_id '...' not found."},{"fix":"Update your import statements to `from zep_python import ZepClient` and ensure all sub-module imports follow the `zep_python.<module>` convention.","cause":"Incorrect import path. The package name changed from `zep` to `zep_python` (or you are trying to use an old v1 import pattern).","error":"ImportError: cannot import name 'ZepClient' from 'zep'"}]}