Migrating from Zep V3 to V4
Required: use this skill together with the building-with-zep skill from
the same plugin. If that skill is not active, activate it now, before you
continue. If your runtime cannot activate skills, read
../building-with-zep/SKILL.md. Use the
Documentation index and the source rules of the building-with-zep skill.
Source of truth
The migration guide is the source of truth for every method name, field,
and behavior change. This skill tells you how to apply the guide. It does not
repeat the guide.
- Read the guide through the
zep-docs MCP server. Search for "Migrating
from v3", or read the resource zep-docs://migrating-from-v3.
- If the MCP server is not available, read
Migrating from v3 at
https://help.getzep.com/migrating-from-v3.md.
- Read the whole guide before you change code. Read these sections first:
"Migration steps", "Pagination", and "Deletes". These changes cause most of
the work.
If the guide and this skill do not agree, obey the guide.
Procedure
Step 1. Make an inventory of the V3 usage
- Find each Zep SDK import and each Zep SDK call in the codebase, in each
language. Include tests, scripts, background jobs, and infrastructure code.
- Record the SDK version that each service uses now. The method map of the
guide matches one V3 SDK version. If the application uses an older V3 SDK,
tell the user before you continue.
- For each call, record the method, the file, and the identifier that the
call uses (
user_id, thread_id, graph_id, or a UUID).
- Find each place where the application stores or makes a Zep identifier.
Step 2. Classify each call
Use the "Method map" of the guide for each call. Put each call in one of these
groups:
- A rename: the V4 method has the same behavior.
- A change that needs more than a rename: the call is in a section of
"Changes that need more than a rename", for example pagination, deletes,
instruction updates, list filters, or errors.
- No V4 equivalent: the call is in "What has no v4 equivalent". Tell the user
about each of these calls before you change code. Do not make a replacement
that the guide does not give.
Show the classified inventory to the user before you start Step 3.
Step 3. Plan the identifier migration
V4 addresses each user, thread, and graph by a UUID that Zep generates. This
is the largest part of the migration. Follow the five steps in "Migration
steps" of the guide, in their order. Do not combine or skip a step.
- The UUID columns are a change to the database of the user. Show the schema
change to the user, and get approval before you write the database
migration.
- Use
lookup only in the one backfill job of the guide. The application
code must never call lookup, also not as a fallback, because lookup
will become deprecated.
- Move resource creation to V4 only after no V3 read or write remains. The V3
API cannot address a resource that V4 created.
- The application uses both SDKs during the migration. Read the note in
"Migration steps" for each language before you change the dependencies.
Some languages cannot load both SDKs in one process.
Step 4. Change the code
- Make one migration step of the guide per change, so that the user can
deploy and verify each step. Open one PR for each step. Start the next step
only after the user has merged and deployed the PR before it.
- Get each V4 method name and argument from the method map and the V4 SDK
reference of the installed SDK version. Do not guess a name from the V3
name.
- Use the SDKs. Do not call the Zep API over raw HTTP.
- Read each "Changes that need more than a rename" section that applies to a
call before you change that call. A change that compiles can still have
different behavior. For example, the type checker does not find a loop that
reads only the first page of a list, or code that expects a delete to be
complete when the call returns.
Step 5. Verify
- Run the type checker, the linter, and the tests after each step.
- Search the codebase again for V3 imports and for
lookup calls. After the
last step, no V3 import remains, and only the backfill job calls lookup.
- Test each changed path against a Zep project that is not production. Use the
test project that the user gives you.
- Tell the user which calls you could not test.
Report
When you finish each step, tell the user:
- The calls that you changed, by group (Step 2).
- The calls that have no V4 equivalent, and what the user must decide for each.
- The database changes and the backfill status.
- The checks that passed, and the paths that you did not test.
1---2name: migrating-zep-v3-to-v43description: >-4 Procedure for a coding agent that migrates an application from the Zep V35 API and SDKs to V4. The procedure reads the V4 migration guide, finds each6 V3 call in the codebase, maps it to its V4 replacement, moves the7 application to Zep-generated UUIDs in the documented order, and verifies8 each step. Use when a user asks to "migrate to Zep v4", "upgrade zep-cloud9 to v4", "port my Zep code from v3", or "what breaks when I move to Zep v4".10 Use together with the building-with-zep skill from the same plugin.11 Activate that skill first if it is not active yet.12metadata:13 source: https://skillmd.com/skills/getzep/migrating-zep-v3-to-v414---1516# Migrating from Zep V3 to V41718**Required: use this skill together with the building-with-zep skill from19the same plugin.** If that skill is not active, activate it now, before you20continue. If your runtime cannot activate skills, read21[`../building-with-zep/SKILL.md`](../building-with-zep/SKILL.md). Use the22Documentation index and the source rules of the building-with-zep skill.2324## Source of truth2526The migration guide is the source of truth for every method name, field,27and behavior change. This skill tells you how to apply the guide. It does not28repeat the guide.29301. Read the guide through the `zep-docs` MCP server. Search for "Migrating31 from v3", or read the resource `zep-docs://migrating-from-v3`.322. If the MCP server is not available, read33 [Migrating from v3](https://help.getzep.com/migrating-from-v3) at34 `https://help.getzep.com/migrating-from-v3.md`.353. Read the whole guide before you change code. Read these sections first:36 "Migration steps", "Pagination", and "Deletes". These changes cause most of37 the work.3839If the guide and this skill do not agree, obey the guide.4041## Procedure4243### Step 1. Make an inventory of the V3 usage4445- Find each Zep SDK import and each Zep SDK call in the codebase, in each46 language. Include tests, scripts, background jobs, and infrastructure code.47- Record the SDK version that each service uses now. The method map of the48 guide matches one V3 SDK version. If the application uses an older V3 SDK,49 tell the user before you continue.50- For each call, record the method, the file, and the identifier that the51 call uses (`user_id`, `thread_id`, `graph_id`, or a UUID).52- Find each place where the application stores or makes a Zep identifier.5354### Step 2. Classify each call5556Use the "Method map" of the guide for each call. Put each call in one of these57groups:5859- A rename: the V4 method has the same behavior.60- A change that needs more than a rename: the call is in a section of61 "Changes that need more than a rename", for example pagination, deletes,62 instruction updates, list filters, or errors.63- No V4 equivalent: the call is in "What has no v4 equivalent". Tell the user64 about each of these calls before you change code. Do not make a replacement65 that the guide does not give.6667Show the classified inventory to the user before you start Step 3.6869### Step 3. Plan the identifier migration7071V4 addresses each user, thread, and graph by a UUID that Zep generates. This72is the largest part of the migration. Follow the five steps in "Migration73steps" of the guide, in their order. Do not combine or skip a step.7475- The UUID columns are a change to the database of the user. Show the schema76 change to the user, and get approval before you write the database77 migration.78- Use `lookup` only in the one backfill job of the guide. The application79 code must never call `lookup`, also not as a fallback, because `lookup`80 will become deprecated.81- Move resource creation to V4 only after no V3 read or write remains. The V382 API cannot address a resource that V4 created.83- The application uses both SDKs during the migration. Read the note in84 "Migration steps" for each language before you change the dependencies.85 Some languages cannot load both SDKs in one process.8687### Step 4. Change the code8889- Make one migration step of the guide per change, so that the user can90 deploy and verify each step. Open one PR for each step. Start the next step91 only after the user has merged and deployed the PR before it.92- Get each V4 method name and argument from the method map and the V4 SDK93 reference of the installed SDK version. Do not guess a name from the V394 name.95- Use the SDKs. Do not call the Zep API over raw HTTP.96- Read each "Changes that need more than a rename" section that applies to a97 call before you change that call. A change that compiles can still have98 different behavior. For example, the type checker does not find a loop that99 reads only the first page of a list, or code that expects a delete to be100 complete when the call returns.101102### Step 5. Verify103104- Run the type checker, the linter, and the tests after each step.105- Search the codebase again for V3 imports and for `lookup` calls. After the106 last step, no V3 import remains, and only the backfill job calls `lookup`.107- Test each changed path against a Zep project that is not production. Use the108 test project that the user gives you.109- Tell the user which calls you could not test.110111## Report112113When you finish each step, tell the user:114115- The calls that you changed, by group (Step 2).116- The calls that have no V4 equivalent, and what the user must decide for each.117- The database changes and the backfill status.118- The checks that passed, and the paths that you did not test.