Friction Log: How I Tried and Failed to Follow the Zep Quickstart Guide :D

No time tonight to get a PR for these things going, but figured I would document my findings in case it is helpful to someone.

Profile: I'm someone with, shall we say, "fledgling" Python experience ;) but who is interested in taking Zep Community Edition for a spin. (Since this may not be your direct target audience, you may or may not want to do something about this report ;))

Machine: This was on a Mac M3 Pro running macOS Sequoia 15.0.1 (24A348), in case this is relevant.

Expectation: I could copy/pasta/modify the stuff in the quickstart guide and get Zep up and running in ~5 minutes.

Reality: Welllll... 😅

Here's the story of what actually happened. :)

Starting Zep

➡️ Starting point: https://github.com/getzep/zep README

➡️ This directs me to: https://help.getzep.com/ce/quickstart

✅ git clone https://github.com/getzep/zep.git

✅ set api_secret and organization_name in zep.yaml => Suggestion: Instead of pasting the whole file and having me play inspector gadget ;) call out only the lines you need me to edit.

❌ ./zep up Results in error:

WARN[0000] The "OPENAI_API_KEY" variable is not set. Defaulting to a blank string. 
env file /Users/webchick/TechAround/zep/.env not found: stat /Users/webchick/TechAround/zep/.env: no such file or directory

A few things:

There is a note about needing OPENAI_API_KEY but it comes after this command in the instructions. (Recommendation: Simply swap them.)
The instructions above this line make it sound like an .env file is an optional thing, and that I "could" use it, e.g. for a PostgreSQL password. This error, OTOH, is telling me it's actually required. This is a bit confusing.
(Nit) That blue box tells me to make sure to set the secret value but the value is actually called api_secret no? (unless there are two??)

If I follow the instructions in the blue box and create an .env fie with that line in it, then things seem to work. 👍

Starter code

➡️ Directed to https://help.getzep.com/ce/sdks

✅ pip install zep-python

⚠️ By default, Python will use pip3 and python3 here instead of pip/python, though most people can probably figure that out. :)

❌ Initialize client example

Ran into a few snags here, first is:

Missing requirement: packaging

Traceback (most recent call last):
  File "/Users/webchick/TechAround/zep/example.py", line 2, in <module>
    from zep_python.client import Zep
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/client.py", line 5, in <module>
    from .external_clients.memory import MemoryClient, AsyncMemoryClient
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/external_clients/memory.py", line 4, in <module>
    from packaging import version
ModuleNotFoundError: No module named 'packaging'

Turns out you need to pip install packaging if you just set your Python environment up for the first time earlier this evening. ;) 👍

The case of the missing .env variables

Then, I get:

Traceback (most recent call last):
  File "/Users/webchick/TechAround/zep/example.py", line 7, in <module>
    client = Zep(
        api_key=API_KEY,
        base_url=BASE_URL
    )
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/client.py", line 27, in __init__
    super().__init__(
    ~~~~~~~~~~~~~~~~^
        base_url=api_url,
        ^^^^^^^^^^^^^^^^^
    ...<3 lines>...
        httpx_client=httpx_client,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/base_client.py", line 64, in __init__
    raise ApiError(body="The client must be instantiated be either passing in api_key or setting ZEP_API_KEY")
zep_python.core.api_error.ApiError: status_code: None, body: The client must be instantiated be either passing in api_key or setting ZEP_API_KEY

==> Suggestion: In the Zep Cloud UI it calls this a "Project Key" — consider unifying the labels of these.

Back to that .env file again, which now looks like this:

export ZEP_BASE_URL=http://localhost:8000
export ZEP_API_KEY=XXX
export OPENAI_API_KEY=XXX

and run:

source .env

...to re-load it. This seems to get past the error. 👍

❌ Usage example

Aysnc code error

Error:

  File "/Users/webchick/TechAround/zep/example.py", line 11
    new_user = await client.user.add(
               ^^^^^^^^^^^^^^^^^^^^^^
SyntaxError: 'await' outside function

For this one, I'm not sure. I asked ChatGPT and got back that this should be wrapped in an asyncio call, but I assume this is probably PEBCAK where my Python knowledge hits a wall. ;) Still, since this is billed as "Quick Start" and since it is conceivable that someone might have an interest in tinkering with Zep without having a previous experience with async Python, it might not hurt to be a bit more explicit here about how to run the file.

Anyway, if you do that:

import uuid
+import asyncio
from zep_python.client import AsyncZep
from zep_python.types import Message

+async def main():
  # Indent everything from here to the end :P
...
...
...
  facts = [r.fact for r in search_response.results]

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

The case of the missing env variables (part II)

Then you get this:

Traceback (most recent call last):
  File "/Users/webchick/TechAround/zep/example.py", line 57, in <module>
    asyncio.run(main())
    ~~~~~~~~~~~^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 194, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/base_events.py", line 721, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/Users/webchick/TechAround/zep/example.py", line 9, in main
    api_key=API_KEY,
            ^^^^^^^
NameError: name 'API_KEY' is not defined

This is because the second code block is missing lines from the first code block:

import os
...
API_KEY = os.environ.get('ZEP_API_KEY')
BASE_URL = os.environ.get('ZEP_BASE_URL')

I add that stuff (above the async def main() line) we move past that error, onto NEW errors:

I dunno, but it sure is mad about something ;)

Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/user/client.py", line 438, in add
    _response_json = _response.json()
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/httpx/_models.py", line 766, in json
    return jsonlib.loads(self.content, **kwargs)
           ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 344, in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
               ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/decoder.py", line 362, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/webchick/TechAround/zep/example.py", line 61, in <module>
    asyncio.run(main())
    ~~~~~~~~~~~^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 194, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/base_events.py", line 721, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/Users/webchick/TechAround/zep/example.py", line 18, in main
    new_user = await client.user.add(
               ^^^^^^^^^^^^^^^^^^^^^^
    ...<5 lines>...
    )
    ^
  File "/Library/Frameworks/Python.framework/Versions/3.13/lib/python3.13/site-packages/zep_python/user/client.py", line 440, in add
    raise core_api_error_ApiError(status_code=_response.status_code, body=_response.text)
zep_python.core.api_error.ApiError: status_code: 401, body: unauthorized

And here is where I must sadly retire, and don't have time atm to investigate further. Hopefully it's a couple of easy fixes to the docs to get this working all spiffy for the next person, though! :) HTH.

getzep / docs.getzep.com