Custom instructions

Describe your domain so Zep can better understand your data

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:

  1. Graph-specific instructions — If the target graph has instructions set via user_ids or graph_ids, those are used.
  2. Project-wide defaults — If no graph-specific instructions exist, Zep falls back to project-wide default instructions.
  3. 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.

1from zep_cloud import Zep, CustomInstruction
2
3client = Zep(api_key="YOUR_API_KEY")
4
5# Add project-wide custom instructions
6client.graph.add_custom_instructions(
7 instructions=[
8 CustomInstruction(
9 name="legal_domain",
10 text=(
11 "This application operates in the legal domain. "
12 "Common legal terminology includes: consideration, "
13 "estoppel, tort, indemnification, force majeure, "
14 "severability, arbitration clause, non-compete, "
15 "and confidentiality. A 'party' refers to a person "
16 "or organization involved in a legal agreement. "
17 "'Clauses' are specific provisions within a contract."
18 )
19 )
20 ]
21)

When you add data to any graph, Zep automatically applies these project-wide instructions. No extra parameters are needed:

1# Add data to a graph — the legal_domain instructions apply automatically
2client.graph.add(
3 graph_id="contract_reviews",
4 type="text",
5 data=(
6 "The licensing agreement between Acme Corp and GlobalTech Inc "
7 "includes a non-compete clause effective for 24 months and an "
8 "arbitration clause requiring disputes be resolved in New York."
9 )
10)

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.

1from zep_cloud import Zep, CustomInstruction
2
3client = Zep(api_key="YOUR_API_KEY")
4
5# Add instructions for specific users
6client.graph.add_custom_instructions(
7 user_ids=["user_123", "user_456"],
8 instructions=[
9 CustomInstruction(
10 name="healthcare_domain",
11 text=(
12 "This application operates in the healthcare domain. "
13 "Common medical terminology includes: prognosis (expected "
14 "outcome), etiology (cause of a condition), contraindication "
15 "(reason to avoid a treatment), comorbidity (co-occurring "
16 "conditions), and differential diagnosis (distinguishing "
17 "between conditions with similar symptoms). A 'prescription' "
18 "refers to a specific medication, dosage, and schedule."
19 )
20 )
21 ]
22)

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:

1from zep_cloud.types import Message
2
3# Add messages — the healthcare_domain instructions apply automatically
4response = client.thread.add_messages(
5 thread_id,
6 messages=[
7 Message(
8 name="Dr. Patel",
9 role="user",
10 content="Patient shows signs of acute bronchitis with a secondary comorbidity of asthma. Prescribing azithromycin 500mg for 3 days.",
11 ),
12 Message(
13 name="Assistant",
14 role="assistant",
15 content="Noted. Should I flag any contraindications with the patient's existing medications?",
16 ),
17 Message(
18 name="Dr. Patel",
19 role="user",
20 content="Good point — check against the current prednisone prescription. The prognosis is good if we manage both conditions.",
21 ),
22 ]
23)

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.

Limits

LimitValue
Instructions per request5
Instruction name length100 characters
Instruction text length1-5,000 characters
User IDs per request50
Graph IDs per request50