Zep Python Client

2.0.2 · active · verified Thu Apr 16

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.

Common errors

```
TypeError: object ZepClient can't be used in 'await' expression
```
cause You are trying to `await` the `ZepClient` object itself, or calling an `async` method without `await`.

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.
```
zep_python.exceptions.NotFoundError: Session with session_id '...' not found.
```
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.

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.
```
ImportError: cannot import name 'ZepClient' from 'zep'
```
cause Incorrect import path. The package name changed from `zep` to `zep_python` (or you are trying to use an old v1 import pattern).

fix Update your import statements to `from zep_python import ZepClient` and ensure all sub-module imports follow the `zep_python.<module>` convention.

Warnings

breaking 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.
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.
breaking 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`.
Fix: Update method calls to their new v2 equivalents. Always `await` client method calls as they are now asynchronous.
gotcha 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`.
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.
gotcha 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.
Fix: Always prepend `await` to any Zep client method call. Ensure your application's entry point uses `asyncio.run()`.

Install

pip install zep-python Install latest version

Imports

ZepClient
wrong:
```
from zep import ZepClient
```
correct:
```
from zep_python import ZepClient
```
The top-level package for the client is `zep_python`, not `zep`.
Message
wrong:
```
from zep_python.message import Message
```
correct:
```
from zep_python.models import Message
```
Data models like `Message` are now found under the `zep_python.models` module in v2.
Memory
```
from zep_python.models import Memory
```
Document
```
from zep_python.models import Document
```

Quickstart

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`.

import asyncio
import os
from zep_python import ZepClient
from zep_python.models import Message, Memory

async def main():
    # Ensure ZEP_API_URL is set in your environment or provide a default
    api_url = os.environ.get("ZEP_API_URL", "http://localhost:8000")
    api_key = os.environ.get("ZEP_API_KEY", "") # Zep API key if authentication is enabled

    client = ZepClient(api_url=api_url, api_key=api_key)

    session_id = "my-test-session-123"
    user_id = "test_user" # Optional

    try:
        # Sessions must be explicitly created before adding messages (Zep v2+)
        await client.add_session(session_id=session_id, user_id=user_id, metadata={"project": "chatbot"})
        print(f"Session '{session_id}' created.")
    except Exception as e:
        # Session might already exist, or another error occurred
        if "already exists" in str(e):
            print(f"Session '{session_id}' already exists.")
        else:
            print(f"Error creating session '{session_id}': {e}")

    # Add messages to the session
    messages_to_add = [
        Message(role="user", content="Hello, my name is Alice."),
        Message(role="assistant", content="Hi Alice, how can I help you today?")
    ]
    await client.add_transcript(session_id=session_id, messages=messages_to_add)
    print(f"Added {len(messages_to_add)} messages to session '{session_id}'.")

    # Retrieve memory for the session
    memory: Memory = await client.get_memory(session_id=session_id)
    if memory and memory.messages:
        print(f"\nRetrieved memory for session '{session_id}':")
        for msg in memory.messages:
            print(f"  {msg.role}: {msg.content}")
    else:
        print(f"\nNo memory found or memory is empty for session '{session_id}'.")

    # Clean up: delete the session (uncomment to enable)
    # await client.delete_session(session_id=session_id)
    # print(f"Session '{session_id}' deleted.")

    # Close the client session
    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →