{"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":"python","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":[{"wrong":"from zep_python import ZepClient","symbol":"Memory","correct":"from zep_python import Memory"},{"symbol":"Message","correct":"from zep_python import Message"},{"symbol":"Session","correct":"from zep_python import Session"}],"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,"search_vec":"'2.0.2':57 'activ':61 'agent':18,74 'ai':17,69 'api':41 'async':72 'asynchron':34 'cadenc':63 'capabl':20 'client':3,35 'collect':51 'current':54 'document':25,50 'embed':23 'facilit':42 'frequent':65 'interact':37 'langchain':73 'librari':31 'llm':70 'long':13 'long-term':12 'maintain':59 'manag':26,44 'memori':15,71 'messag':48 'offer':32 'open':8 'open-sourc':7 'patch':68 'platform':10 'provid':19 'python':2,30 'releas':62 'session':47 'sourc':9 'summar':22 'term':14 'updat':66 'user':46 'version':56 'zep':1,4,29,40 'zep-python':28","created_at":"2026-04-16T18:50:07.001406+00:00","updated_at":"2026-04-16T18:50:07.001406+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.zep.com","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/zep-python/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml","vector-search","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}