Migrating from v3

Most v3 methods have a direct v4 replacement. This page maps all of them for Python, TypeScript, and Go, then covers the changes that need more than a rename.

The tables match zep-cloud / @getzep/zep-cloud / zep-go v3.28.0 and the v4 alpha packages 4.0.0a5 / 4.0.0-alpha.5 / v4.0.0-alpha.5.

UUID addressing, pagination, and asynchronous deletes account for most of the work in a port. Read Identifiers, Pagination, and Deletes first.

Identifiers need to be adapted

Your existing user_id, thread_id, and graph_id values do not work the way they did in v3. You cannot pass them to get, update, delete, add_messages, or any other method that used to accept them. Those methods now take a UUID. If you pass the old identifier, the call fails.

Zep generates the UUID of every user, thread, and graph. The client addresses each resource by that UUID. A v4 create call does not accept an identifier from the client:

• user.create does not accept a user_id.
• thread.create does not accept a thread_id.
• graph.create does not accept a graph_id.
• graph.clone does not accept a target_graph_id.

A create request that contains one of these fields with a value fails with HTTP 400 and the error code invalid_request.

A resource that v4 creates has no legacy name. The v4 response for that resource contains no user_id, thread_id, or graph_id. A resource that v3 created keeps the identifier that your application gave it in v3. In v4, that identifier is a legacy name: a read-only field that you cannot change. A legacy name is not an address. Only the transitional lookup operations accept a legacy name as input.

Two reasons drive the design. Every identifier is an opaque UUID that holds no tenant, no resource type, no order, and no customer data. A customer-supplied value can hold personal data, and a value in a URL path or a query string goes into access logs, proxy logs, referrer headers, and error reports. For the same reason, each lookup operation is a POST with the identifier in the request body.

Store the UUID in your own database

Every v4 application uses the same pattern:

1. Call user.create, thread.create, or graph.create with no identifier.
2. Read the uuid from the response. The user.create response also contains the graph_uuid of the user graph.
3. Write the UUID into your own table. For example, use zep_user_uuid and zep_graph_uuid columns on your users table, and a zep_thread_uuid column on the table that holds conversations.
4. Pass the stored UUID on every later call.

Your own identifiers stay in your database, in the same row as the Zep UUID. Zep does not store them, and no Zep operation accepts them. To find the Zep resource for one of your records, read the UUID from that record.

If you need a label on a Zep user, put the label in the user metadata. A thread has no metadata field. A graph has a name and a description. The graph name is descriptive text. It is not an identifier, and no operation addresses a graph by its name.

Migrate a production application shows this pattern with code, including safe retries.

Resolve legacy names with lookup

The lookup operations resolve a legacy name to a UUID:

• user.lookup resolves one user_id.
• thread.lookup resolves one thread_id.
• graph.lookup resolves one graph_id.
• lookup.batch resolves up to 1000 identifiers of users, threads, and graphs in one request.

Use lookup only to migrate identifiers that your application stored in v3. A resource that v4 creates has no legacy name, so lookup never finds it.

The example below resolves many identifiers in one request. The response has one item for each identifier in the request. An identifier that does not resolve returns found: false with no UUID.

lookup = client.lookup.batch(
    users=["user_1234", "user_5678"],
    threads=["thread_1234"],
    graphs=["support-emea"],
)
uuids = {
    (item.resource_type, item.legacy_id): item.uuid_
    for item in lookup.items or []
    if item.found
}

The map key contains the resource type, because a user and a thread can have the same legacy name.

Migrate one call

The example below resolves one thread and then adds messages to it. The lookup is a one-time migration step. In production code, read the UUID from your own database, as the production procedure shows.

from zep_cloud.types import Message
client.thread.add_messages(
    thread_id="thread_1234",
    messages=[
        Message(role="user", name="Ada", content="I prefer window seats."),
    ],
)

from zep_cloud import AddMessage
thread = client.thread.lookup(thread_id="thread_1234")
client.thread.add_messages(
    thread.uuid_,
    messages=[
        AddMessage(role="user", name="Ada", content="I prefer window seats."),
    ],
)

Migrate a production application

Use this procedure when your application runs on v3 in production and must continue to create users, threads, and graphs during the migration. At the end, your application uses only v4, and it addresses every resource by a UUID that it keeps in its own database.

Two facts set the order of the steps:

• v3 and v4 serve the same project data at the same time. A resource that v3 creates is available through v4, and v4 addresses it by UUID.
• v3 cannot address a resource that v4 creates. v3 addresses users, threads, and graphs by the identifier that your application gave them. A resource that v4 creates has no such identifier.

For these reasons, your application moves its reads and writes to v4 first. It moves resource creation to v4 only after no v3 read or write remains.

from zep_cloud.client import Zep  # zep-cloud 3.30.0 or later (v3)
zep_v3 = Zep(api_key=ZEP_API_KEY)
def create_user(db, user_id: str, email: str) -> None:
    user = zep_v3.user.add(user_id=user_id, email=email)
    db.execute(
        "UPDATE users SET zep_user_uuid = %s, zep_graph_uuid = %s WHERE id = %s",
        (user.uuid_, user.graph_uuid, user_id),
    )
def create_conversation(db, conversation_id: str, user_id: str) -> None:
    thread = zep_v3.thread.create(thread_id=conversation_id, user_id=user_id)
    db.execute(
        "UPDATE conversations SET zep_thread_uuid = %s WHERE id = %s",
        (thread.uuid_, conversation_id),
    )
def create_team_graph(db, team_id: str) -> None:
    graph = zep_v3.graph.create(graph_id=team_id, name="Team knowledge")
    db.execute(
        "UPDATE teams SET zep_graph_uuid = %s WHERE id = %s",
        (graph.canonical_graph_uuid, team_id),
    )

import time
from zep_cloud.client import Zep  # v4
from zep_cloud.core.api_error import ApiError
zep = Zep(api_key=ZEP_API_KEY)
PAGE_SIZE = 1000
def backfill_users(db) -> None:
    last_id = ""
    while True:
        rows = db.fetch_all(
            "SELECT id FROM users"
            " WHERE zep_user_uuid IS NULL AND zep_lookup_status IS NULL AND id > %s"
            " ORDER BY id LIMIT %s",
            (last_id, PAGE_SIZE),
        )
        if not rows:
            return
        ids = [row.id for row in rows]
        result = lookup_with_retry(ids)
        for item in result.items or []:
            if item.found:
                db.execute(
                    "UPDATE users SET zep_user_uuid = %s"
                    " WHERE id = %s AND zep_user_uuid IS NULL",
                    (item.uuid_, item.legacy_id),
                )
            else:
                db.execute(
                    "UPDATE users SET zep_lookup_status = 'not_found' WHERE id = %s",
                    (item.legacy_id,),
                )
        last_id = ids[-1]
def lookup_with_retry(ids: list[str]):
    while True:
        try:
            return zep.lookup.batch(users=ids)
        except ApiError as err:
            if err.status_code != 429:
                raise  # 403 and 503 stop the job. No row is marked.
            time.sleep(int((err.headers or {}).get("retry-after", "1")))

from zep_cloud.client import Zep  # v4
zep = Zep(api_key=ZEP_API_KEY)
def create_user(db, user_id: str, email: str) -> None:
    db.execute(
        "INSERT INTO users (id, email) VALUES (%s, %s)",
        (user_id, email),
    )
    provision_zep_user(db, user_id)
def provision_zep_user(db, user_id: str) -> None:
    """Called at creation time, and again by the repair task."""
    row = db.fetch_one(
        "SELECT email FROM users WHERE id = %s", (user_id,)
    )
    user = zep.user.create(email=row.email)
    db.execute(
        "UPDATE users SET zep_user_uuid = %s, zep_graph_uuid = %s"
        " WHERE id = %s AND zep_user_uuid IS NULL",
        (user.uuid_, user.graph_uuid, user_id),
    )
def provision_zep_thread(db, conversation_id: str) -> None:
    row = db.fetch_one(
        "SELECT u.zep_user_uuid FROM conversations c"
        " JOIN users u ON u.id = c.user_id WHERE c.id = %s",
        (conversation_id,),
    )
    thread = zep.thread.create(user_uuid=row.zep_user_uuid)
    db.execute(
        "UPDATE conversations SET zep_thread_uuid = %s"
        " WHERE id = %s AND zep_thread_uuid IS NULL",
        (thread.uuid_, conversation_id),
    )

Method map

Use the language tab that matches your SDK. Each row is one v3 method.

TypeScript POST list and search methods take pagination on the request object and the JSON body under body. The SDK throws JsonError: Expected object when body is missing. Use { limit: 1, body: {} } for an unfiltered list and { limit: 1, body: { query: "..." } } for search. Filter keys in that body stay snake_case (connected_node_uuids), because filters is an untyped object.

Go search methods put the query on Body, for example GraphSearchEdgesRequest{Body: &SearchRequest{Query: "..."}}. Artifact list Filters is map[string]any. Use the snake_case keys connected_node_uuids, mentioned_node_uuids, and episode_uuids.

Users

Threads

Graphs and ingestion

Search and context

Graph artifacts

Configuration

Batches, tasks, and user groups

New in v4

These methods have no v3 counterpart.

Changes that need more than a rename

Pagination

Loops written against page_number or lastn, or against the Zep-Next-Cursor header, do not port. Replace them with the SDK pager. The pager walks an opaque cursor. Do not increment a page number.

page_number = 1
while True:
    page = client.user.list_ordered(page_number=page_number, page_size=50)
    users = page.users or []
    if not users:
        break
    for user in users:
        print(user.user_id)
    page_number += 1

for user in client.user.list(limit=50):
    print(user.user_id)

Deletes

A delete returns a task rather than a success envelope. The resource is not gone when the call returns. Poll the returned task until it reaches succeeded, partial, or failed. Bound the wait. Treat a missing status as not finished.

client.user.delete("user_1234")

import time
TERMINAL = {"succeeded", "partial", "failed"}
deadline = time.monotonic() + 600
result = client.user.delete(user.uuid_)
task = client.task.get(result.task.uuid_)
while task.status not in TERMINAL:
    if time.monotonic() > deadline:
        raise TimeoutError(f"task {result.task.uuid_} is still {task.status}")
    time.sleep(1)
    task = client.task.get(result.task.uuid_)

Instruction updates

v3 added and deleted individual instructions by name. v4 reads and writes the whole set. An update is a read, a change, and a write. A write that omits an existing name removes that instruction.

from zep_cloud import CustomInstruction
client.graph.add_custom_instructions(
    instructions=[
        CustomInstruction(name="tone", text="Prefer concise facts."),
    ]
)
client.graph.delete_custom_instructions(instruction_names=["tone"])

from zep_cloud import CustomInstruction
current = client.project.get_instructions()
updated = [i for i in (current.instructions or []) if i.name != "tone"]
updated.append(CustomInstruction(name="tone", text="Prefer concise facts."))
client.project.set_instructions(instructions=updated)

Declaring entity and edge types in code

v3 took your model classes or structs and derived the payload inside the SDK call. v4 separates the two steps. You declare the types with the SDK ontology helpers, you build the payload, and you pass the payload to graph.set_ontology or project.set_ontology. The helper names changed with the step:

The v3 Python module zep_cloud.external_clients.ontology does not exist in v4. Import the models and build_ontology from zep_cloud.ontology. The builder returns the payload. It does not call the API. build_ontology returns the entity_types list and the edge_types list. buildOntology and zep.BuildOntology return one Ontology object.

A type name is now a key of the builder input, not a struct tag or a class name. A property that tells two nodes of the same type apart is marked as an identity property in the declaration.

from pydantic import Field
from zep_cloud.external_clients.ontology import EntityModel, EntityText
class Traveler(EntityModel):
    """Someone who takes trips."""
    home_city: EntityText = Field(description="The city they live in", default=None)
client.graph.set_ontology(entities={"Traveler": Traveler})

from pydantic import Field
from typing_extensions import Annotated
from zep_cloud.ontology import EntityModel, EntityText, Identity, build_ontology
class Traveler(EntityModel):
    """Someone who takes trips."""
    home_city: Annotated[EntityText, Identity] = Field(
        default=None, description="The city they live in"
    )
entity_types, edge_types = build_ontology(entities={"Traveler": Traveler})
client.graph.set_ontology(
    graph_uuid,
    entity_types=entity_types,
    edge_types=edge_types,
)

An edge type is declared the same way. Use EdgeModel in Python, an edge declaration with sourceTargets in TypeScript, and zep.EdgeBase with zep.Edges in Go. Give each edge type the entity type pairs it connects.

Ontology across many graphs

v3 applied one ontology to many graphs in a single call. v4 has one ontology operation per scope. Set the project ontology once for a shared default, or loop over the graphs that need an override.

client.graph.set_ontology(
    user_ids=["user_1234", "user_5678"],
    graph_ids=["support-kb", "sales-kb"],
    entities=entities,
    edges=edges,
)

client.project.set_ontology(entity_types=entity_types, edge_types=edge_types)
for graph_uuid in graph_uuids:
    client.graph.set_ontology(
        graph_uuid,
        entity_types=entity_types,
        edge_types=edge_types,
    )

List filters

v3 had one artifact getter per scope, and a getter took no filter. v4 has one list per artifact type, and the list takes a filters object in the request body. The server applies the object, and combines each key with the scope of the list with a logical AND.

The SDK types filters as a free-form object in all three languages: Dict[str, Any] in Python, Record<string, unknown> in TypeScript, and map[string]any in Go. A key is therefore checked by the server, not by the compiler or the type checker. Three rules apply:

• A key that no filter defines gets HTTP 400 with the code unsupported_filter and the name of the key.
• A key that the result type cannot enforce gets the same error. graph.edge.list is the only list that takes connected_node_uuids, source_node_uuids, and target_node_uuids, because the other lists return no edges. graph.observation.list, graph.thread_summary.list, and graph.document_summary.list also reject episode_uuids, because an observation and a summary are never in the mention set of an episode.
• metadata_filters selects results whose associated episodes’ stored metadata matches the filter. The episode_metadata_filters name from earlier revisions is rejected: rename the key.

graph.node.list takes episode_uuids, which selects the nodes that the listed episodes mention. graph.episode.list takes mentioned_node_uuids and the metadata filter, and rejects every other key.

Searching for a name

The user, graph, and context template lists are POST .../list with the filter term in the body. A term you search by is customer data, and a query string is logged. Pass the term on the SDK list call. Do not put the term in a URL.

page = client.graph.list_all(search="EMEA support", page_number=1, page_size=20)

for graph in client.graph.list(search="EMEA support", limit=20):
    print(graph.uuid_, graph.name)

user.list and graph.list take the same search field. context.list_templates has no search field. It takes name, which selects the template with that exact name.

Recency bias

v3 accepted a recency_bias object on graph.search with scope auto. v4 takes a preset of off, mild, or strong on graph.get_context. There is no object with strength, half-lives, or per-scope bands.

result = client.graph.search(
    user_id="user_1234",
    query="recent account issues",
    scope="auto",
    recency_bias={"strength": 0.8},
)

result = client.graph.get_context(
    user.graph_uuid,
    query="recent account issues",
    recency_bias="strong",
)

Document identifiers

v4 rejects a document_id that contains /, ?, #, or an ASCII control character, and rejects a whitespace-only value. v3 accepted any string of 1 to 100 characters.

Repeated creates

In v3, a retried create with the same identifier failed because the identifier was already in use. v4 creates carry no identifier, so each create call makes a new resource. The SDK sends an idempotency key on its own retries, so a retried request does not make a second resource. You can also pass an Idempotency-Key on a create that your application can repeat. See Move resource creation to v4 for the pattern.

Defaults and caps

Search limit defaults to 50, where v3 defaulted to 10. The maximum is 50 in both. A graph artifact list defaults to 50 with a maximum of 100.

What has no v4 equivalent

• graph.detect_patterns / graph.detectPatterns / Graph.DetectPatterns. The experimental endpoint is removed.
• User-group policy sets (list_policy_sets, attach_policy_set, detach_policy_set and the TypeScript / Go equivalents). Manage policy sets from the Zep dashboard.