Custom instructions
Available to Enterprise Plan customers only.
Why use custom instructions
Zep’s graph extraction uses general-purpose logic by default. Custom instructions let you describe the domain your application operates in, including specialized terminology and concepts that Zep might not otherwise understand. This domain context helps Zep interpret data more accurately during extraction.
Custom instructions describe your domain — the terminology, concepts, and context Zep needs to understand your data. If you need to define specific entity types or relationship types for your graph, use custom ontology instead.
How custom instructions work
Custom instructions are applied automatically in the background whenever data is added to a graph. There is no parameter on thread.add_messages, graph.add, or any other ingestion method to select which instructions to use — Zep fetches and applies the relevant instructions based on the target graph.
Resolution order
When data is ingested into a graph, Zep determines which instructions to use in the following order:
- Graph-specific instructions — If the target graph has instructions set via
user_idsorgraph_ids, those are used. - Project-wide defaults — If no graph-specific instructions exist, Zep falls back to project-wide default instructions.
- Built-in extraction logic — If no custom instructions are defined at all, Zep uses its general-purpose extraction logic.
This means you can set broad project-wide instructions as a baseline and override them for specific users or graphs when needed.
Defining custom instructions
Project-wide instructions
When you omit user_ids and graph_ids, instructions are added as project-wide defaults. These apply to all graphs that don’t have their own graph-specific instructions.
When you add data to any graph, Zep automatically applies these project-wide instructions. No extra parameters are needed:
Graph-specific instructions
To add instructions for specific users or graphs, provide user_ids or graph_ids. These override any project-wide defaults for the specified graphs.
When you add messages to a thread belonging to one of these users, Zep automatically applies the healthcare_domain instructions. No extra parameters are needed:
Important behaviors
Upsert behavior
Adding an instruction with an existing name updates the instruction text rather than creating a duplicate. This allows you to refine instructions over time without manually deleting the old version first.