Tuning Zep ingestion for a dataset
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.
If the building-with-zep skill is not available, read the Zep
documentation through the zep-docs MCP server, or at
https://help.getzep.com/<slug>.md.
This skill is a procedure. A page name in this skill, such as debug-mode,
is the help.getzep.com slug of the page.
API surface
The procedure uses these operations. Some method names are
different in each SDK major version. Get the method names from the documentation of the SDK
version that you install, and record the SDK version in the manifest.
| Operation |
Used in |
Notes |
| Create a graph, set the ontology, set the custom instructions |
Step 4 |
|
| Enable debug mode |
Step 4 |
The current SDK has a call for this. The call returns the window duration and a flag that states whether Ingestion Traces are on. Record both in the manifest. |
| Add nodes |
Step 4 |
Returns the node UUIDs. Keep them in the state file. |
| Add edges between two nodes |
Step 4 |
Refer to each endpoint by node UUID, not by name. The documentation of the SDK version tells whether a name makes a new node or matches an existing node by name. A match by name can select the wrong node when two imported nodes have the same name. |
| Create a batch, add items, process the batch, poll the batch and its items |
Step 4 |
|
| List the nodes, the edges, and the episodes of a graph, with paging |
Step 5 |
Each node and edge carries the UUIDs of the episodes that produced it. |
| Get the debug logs and list the Ingestion Traces of one episode |
Step 6 |
|
| Search the graph |
Step 5 |
For the needle check. |
Terms
| Term |
Meaning in this skill |
| Record |
One unit of the source data: one database row, one email, one chat message, one document, one event. |
| Structured field |
A field of a record with a fixed meaning and a short value: an ID, a name, a category, a status, a date, a reference to another record. |
| Prose field |
A field of a record with free text: a message body, a document body, a transcript, a ticket description. |
| Deterministic import |
Nodes and edges that you write into the graph from the structured data of the source, through one field mapping for each structured schema (Step 1), with the node and edge import calls of the SDK (see "API surface"). No LLM is involved. |
| Narrative episode |
Text that you send to Zep for LLM extraction, through graph.episode.add or the Batch API. |
| Lead sentence |
The first sentence of a narrative episode. It names the record kind, the subject with its identifier, the author, the time, and the source. It uses the same name and identifier for the subject that the deterministic import used. It does not list the identifiers of related records. |
| Configuration version |
An integer that you increase each time you change the ontology, the instructions, or the episode preparation. One graph holds one configuration version. |
| Manifest |
A file that records, for one run, the configuration version, a hash of the configuration, a hash of the prepared data, the graph ID, the debug-mode result, the start time, and the end time. Write each hash at run time and do not compute it again later. Freeze the prepared data file of each version. |
| Field repeat |
An extracted edge or attribute that restates a structured field that the deterministic import already wrote. Measure three kinds: (a) the same source node and edge name as an imported edge, with a different target; (b) an extracted edge on a node pair that an imported edge already connects; (c) an extracted fact or attribute value that restates an imported attribute value. |
| Needle check |
For one gold item, a check that the episodes that hold the evidence exist in the graph, were processed, and produced a fact or a node that a search for the gold item returns. When the gold item is a decision or a task output and not a fact string, the check is a search hit on the gold entity in the top results. |
Principles
- Import what the data already states. Extract only what the prose adds.
Structured data (database rows, JSON records, spreadsheet rows, email
headers, event log rows) goes into the deterministic import: map its fields
to entities and edges, and write them into the graph before the first
episode. Unstructured data (message bodies, document bodies, transcripts,
ticket descriptions) becomes narrative episodes. Do not use an LLM, or your
own reading of the text, to make structured records from unstructured data
for the import. A production pipeline must run the same import on each new
record, with no agent in the loop. When the LLM also sees the structured fields, it
extracts them again. The edge deduplication merges exact repeats, and it
keeps a near repeat (a different edge name, or a fact that restates an
attribute value) as a new edge.
- Each episode must stand alone. The extractor sees one episode. It also sees
the earlier episodes that have the same
document_id (documents), so give
the parts of one source the same document_id. Without a document_id, Zep
extracts the episode alone. Put the identity of the subject, the author, the
time, and the source into the lead sentence of each episode. Episode
metadata is for search filters. The extractor does not read it.
- Identity is a data decision. Decide the canonical name and the identifier of
each entity type before the ingestion. When you have an authoritative alias
map, rewrite the aliases in the data. Declare
identity_properties for the
types that carry an ID, and give each imported node the name that the prose
uses for the entity. In measured runs, an extracted node merged into the
imported node with the same identity value only when the imported node was
in the candidate list of the resolution step, and the candidates came from
a name search. An imported node named "<account> deal <id>" did not
receive the merges of extracted nodes named "<id>". An instruction about
identity helps only when the data is already unambiguous.
- The model reads a type description as a list of answers. When a type
description lists the permitted values (the issue categories, the status
codes), the model emits those values also when the episode text does not
contain them. Keep a closed vocabulary in the deterministic import. Do not
list the values in the type description.
- An instruction cannot stop a repeat. A rule such as "these facts already
exist, do not repeat them" has no measured effect. The extractor cannot see
the graph, so the rule has no reference. Remove the fact from the text and
from the type descriptions (principle 4), or accept the repeat.
- Change one variable per run. Each run has a configuration version, a new
graph, and a manifest. Zep itself changes between runs. When you compare two
runs, state every difference, including the dates of the runs.
- Measure the graph shape before you measure the answers. The counts of nodes
and edges by type, the untyped nodes, the edge names outside the ontology,
the identity correctness against the source records, and the field repeats
are deterministic, and they explain most answer failures.
- Treat each LLM explanation as a claim. The Ingestion Traces show the stage
inputs and outputs. Count what the stages did. Do not report the generated
explanation text as the cause.
- Separate the evidence types in each report: direct measurement, behavior
that the documentation confirms, interpretation, and open hypothesis. The
reader will act on the report. A hypothesis must not look like a fact.
Procedure
Intake. Ask about the use case and the test data
Do this step before Step 0. Ask the user only the questions that the
conversation and the data do not answer. Put all the questions in one message.
Do not start Step 1 until the user answers, or until the user tells you to
continue without the answers.
Ask these questions:
- How will the graph be used? Ask what the customer tries to do with the
graph: the agent or the application that reads the graph, and the task of
that agent.
- Which questions must the graph answer? Ask for 5 to 20 real questions that
the users of the agent ask.
- Does the customer have evaluation question-and-answer pairs? When pairs
exist, ask the user to upload them. When no pairs exist, tell the user that
you will write draft pairs from the data (Step 5), and ask the user to
correct them.
- Can the user upload a sample of the data? Ask for a sample of each record
kind. Ask that the sample include the records that the questions refer to.
Example message to the user:
Before I design the ontology, I need some information about the use case.
- How will the graph be used? For example: "A support agent reads the
graph to answer questions about the orders and the returns of a
customer."
- Which questions must the graph answer? Give 5 to 20 real examples.
- Do you have evaluation question-and-answer pairs? If yes, upload them as
a CSV or a JSON file. The format is below.
- Upload a sample of the data that you want to ingest. Include the records
that the questions refer to.
If you do not have question-and-answer pairs, I will write draft pairs from
the data. You can then correct them.
Example question-and-answer file. The evidence column is optional. It holds
the IDs of the source records that contain the answer.
question,answer,evidence
"Which plan does Acme Corp use?","Enterprise, since 2026-03-01","account-1042; email-88213"
"Who is the main contact for the Acme renewal?","Jane Doe, VP Operations","contact-551"
"Why did Acme open a support ticket in May?","The SSO login failed after a certificate change","ticket-7730"
Record the answers in the project notes. Use the use case and the questions
in Step 0 (question kinds), Step 2 (the types that the questions need), and
Step 5 (the needle check).
Step 0. Learn the data
Read a sample of each record kind. For each kind, fill one row of this table
and keep the table in the project notes:
| Kind |
Structured fields |
Prose fields |
Natural identifier |
Event time field |
Related record kinds |
Also record:
- The number of records per kind.
- The size distribution of the prose fields. The documentation gives the
episode size limit. Zep rejects an episode above the limit and does not
truncate it.
- The alias patterns: short names, logins, email addresses, IDs with prefixes.
- Whether a gold question set exists (see "Intake"). When one exists, read
each question kind and note which structured fields and which prose each
kind needs.
Then read these documentation pages: prepare-data-for-ingestion,
adding-fact-triplets, customizing-graph-structure, custom-instructions,
documents, adding-batch-data, and debug-mode. Read them on each project,
because the limits and the method names change.
Step 1. Split the dataset
The rule for the split: structured data goes into the deterministic import,
and unstructured data becomes narrative episodes (principle 1). A record often
has both kinds, for example an email with headers and a body, or a ticket with
a status and a description. Split each record by field.
For each structured schema in the data (each table, each JSON record type, each
file layout), write a field mapping before you write code. The mapping states
the result of each field in the graph: an entity, an attribute of an entity, an
edge between two entities, or nothing. Map only to the kinds of entities,
relationships, and attributes in the first column of the table below, and use
the same type names in the ontology (Step 2). The import code applies the
mappings and nothing else, so that it can run again on each new record.
Write the split as a table before you write code:
| Deterministic import (structured data) |
Narrative episodes (unstructured data) |
Dropped |
| Entities with a natural ID: people, accounts, cases, products, tickets, documents, channels, meetings |
The prose fields, each with a lead sentence |
Records with no prose and no relationship, for example a code table |
| Relationships that the records state: reports-to, works-on, authored, attends, filed-against, has-status |
Facts that only the prose states: what happened, who said what, decisions, amounts, reasons |
Header lines, MIME lines, signatures, redaction markers |
| Attributes with a closed vocabulary: categories, statuses, regions |
|
|
Rules for the deterministic import:
- Create one node per entity. Give the node the name that the prose uses for
the entity (principle 3). Store the natural ID in a node attribute, so that
you can join the graph to the source.
- Create one edge per stated relationship. Write a
fact sentence that names
both endpoints in full, with the date when the record has one. Example:
"Ana Ruiz attends the meeting 'Q3 plan review' on 2026-03-04." The sentence
"The employee attends the meeting." is not searchable.
- Refer to the endpoints of each edge by the node UUIDs that the node import
returned.
- Set
valid_at from the record time.
- Make the import resumable. Write a state file with the keys of the nodes and
edges that are already created. Zep does not deduplicate nodes by name, so a
retry without the state file creates each node twice.
- Validate the import before you send it: each node key is unique, and each
edge endpoint refers to a known node key. Stop the run on an unknown key.
Rules for the narrative episodes:
- Start each episode with a lead sentence. Example:
"Email from Ana Ruiz <ana.ruiz@example.com> to Ben Ott <ben.ott@example.com>, 2026-03-04, subject 'Q3 plan review'."
- Keep the name and the identifier of the subject of the episode in the lead
sentence. Remove the identifiers of the related records that the
deterministic import already linked to the subject. When the lead sentence
lists a related identifier, the extractor makes a new node with that
identifier as the name. When the lead sentence has no subject identifier,
the extractor writes another value (often the name) into the identity
attribute of the subject, and nodes with the same name merge.
- Put the prose after the lead sentence. Remove the structural noise (header
lines, signatures, redaction markers).
- Set the episode time to the event time of the record. Do not use the
ingestion time.
- When a prose field is longer than the episode limit, split it at a sentence
or paragraph end. Repeat the lead sentence in each part, add
(part i of n),
and give the parts of one source the same document_id. Do not give
unrelated records the same document_id.
- For an event log with many similar rows (one row per process step), write
one sentence per row that names the case, the activity, the actor, and the
time. State in the instructions which activity gives the current state and
which activities are final.
Step 2. Design the ontology
- An entity type is a noun with a natural identity. An edge type is a verb
between two named types. Start with the types that the questions or the use
case need. The documentation gives the maximum number of types.
- Give each type a short description that defines membership. Add one or two
positive examples and one negative example: a similar item that does not
belong, with the type that it belongs to instead. The examples show the
boundary of the type. Do not list all values in the description (principle 4).
- Make the types mutually exclusive, so that each entity or fact has one
correct type. When two types must overlap, state in the descriptions which
type takes priority.
- Declare
identity_properties for each type that has an ID in the lead
sentence.
- Declare the
source_targets of each edge type. With strict_ontology set
to false, Zep stores an extracted edge whose endpoints do not match a
declared pair under the generic edge name RELATES_TO. Count these edges in
Step 5. With true, Zep drops these edges.
- Keep a type that exists only for the import in the ontology, because a search
filter needs the label. Tell the extractor in the instructions that these
nodes exist, and that the prose adds facts to them. Expect partial compliance
and measure it.
- Decide
strict_ontology per run, from a measurement. With false, the graph
has more recall and a tail of edge names and untyped entities outside the
ontology. With true, Zep drops the tail and some true facts with it. When
the tail is large, measure both settings.
Step 3. Write the custom instructions
Use at most five short named blocks:
| Block |
Content |
corpus |
What the data is, what one episode is, what the lead sentence contains, how reliable the text is |
identity |
Which field identifies each type, which short names map to which canonical names, which values must never merge |
temporality |
Which field is the event time, the date format, when a fact starts to hold |
record |
Which record states the current or final state, which state supersedes which |
narrative |
What the prose adds: the event edges to extract and their names, which statements are facts on an existing node, which redacted values must not become entities |
Write what the extractor must do. A rule about what the extractor must not do
works only when the prompt does not offer the forbidden value in another place
(principle 5).
Step 4. Run a versioned ingestion
- Create a new graph. Put the dataset name, the configuration version, and the
first eight characters of the data hash in the graph ID.
- Set the ontology and the instructions. Record their hashes in the manifest.
The ontology and the instructions apply only to episodes that Zep processes
after you set them.
- Enable debug mode on the project through the SDK call. Record the returned
window duration and the trace flag in the manifest. When the trace flag is
off, your plan does not include Ingestion Traces; the
debug-mode page
gives the plan requirements and the retention. Confirm that the API key and
the dashboard account open the same project before you use the dashboard.
When the window is shorter than the run, enable debug mode again during the
run, or make the slice smaller. After the first batch item completes, get
its debug logs through the API; use the API result, not a documentation
statement, to decide whether batch items have per-episode debug logs.
- Run the deterministic import. Wait for its tasks. Count the created nodes and
edges and compare the counts with the plan from Step 1.
- Submit all narrative episodes through the Batch API in event-time order, in
batches of the documented maximum size, without a wait between the batches.
- Record the start time in the manifest. Measure the time of the first
processing window (the first group of items that complete together) and
estimate the run time of the full batch from it before you plan the next
version.
- Poll until each batch and each item is terminal. Record each failed item by
key. Record the end time.
- Keep the graph until the comparison report is written.
Zep dispatches the items of one graph in the order of submission, and it
processes a window of items at the same time. An episode does not see the nodes
that the other episodes of the same window create. Do not depend on one
episode seeing the result of a near episode. Import the shared entities
deterministically before the batch. Run one graph per dataset at a time.
Step 5. Measure the graph shape
Export each node, edge, and episode of the graph with the list calls of the
SDK, with paging. Write one script that produces this table, and keep the script in the project,
because you will run it on each configuration version:
| Check |
Method |
Meaning of a bad value |
| Nodes by type, and untyped nodes |
Count the labels. A node with only the generic label is untyped. |
Many untyped nodes: the ontology lacks a type that the prose needs, or a type description is unclear. |
| Edges by name, inside and outside the ontology |
Compare each edge name with the declared set. |
A long tail (many names with one to five edges each): the prose has event facts with no declared edge type. Declare a closed event set, or accept the tail and rank. |
| Generic edges |
Count the edges named RELATES_TO. |
The endpoints did not match a declared pair, or no type matched. With strict_ontology set to true, Zep drops these edges, so a low count does not show that the endpoints matched. |
| Identity correctness |
For each imported node, compare the identity property values, the name, and the labels in the graph with the import plan. Report the changed nodes by type. |
A wrong ID: a later extraction changed an imported attribute, or two records merged. Only this comparison finds the change. |
| Identity collisions |
Nodes of one type with the same name or the same ID. Edges between two nodes of a type that must not be related, for example case to case. |
Context leaked across records, or aliases merged. |
| Field repeats |
The three kinds in the Terms table, each as a share of the extracted edges. |
The extractor emitted a structured field again (principle 4). |
| Node coverage |
The share of extracted node names that occur in the episode text. |
A low share for one type: the model takes the values from the type description. |
| Episode coverage |
Each prepared episode key is present and processed. Failed items by key. |
Missing episodes: items that failed, were skipped, or were canceled, items that are still processing, or a batch that is invalid. |
| Import integrity |
The imported node and edge counts equal the plan. |
A retry doubled the import, or a chunk failed. |
| Timing |
Items per minute, per batch. |
A slow run. Do not infer the cause from one run. |
When a reference graph exists, add the entity recall and precision by type
against the reference. When the gold set is a question set or a task output
(a decision, a changed field, a cited source record) and not a graph, measure
the presence and the coverage of the gold entities, and define the needle check
as a search hit on the gold entity in the top results. Precision has no
reference in that case; do not report it.
When no gold set exists, build a small one from the data. For each record
kind, write 10 to 25 questions of the kinds that the use case needs (point in
time, current state, count, sequence, who did what). Give each question the
episode keys that hold the evidence and a short gold answer. Write the
questions from the records, not from memory. The identity checks and the field
repeat check need no gold set, and they are the first checks to make pass.
Step 6. Read the debug logs and the Ingestion Traces
Select the episodes that produced a bad value in Step 5, and a random sample of
20 episodes. Each node and edge carries the UUIDs of the episodes that produced
it; use them to find the episodes behind a bad value. For each selected
episode, get the debug logs and the Ingestion Traces through the API. Record:
| Trace content |
Question that it answers |
| Extraction input: episode content, previous episodes, entity types, edge types, instructions |
What did the model see? Did the previous-episode list hold anything? Were the instructions present? |
| Extraction output: nodes with labels, edges with names |
What did the model emit before deduplication? Which names are not in the text? |
| Node resolution: extracted node, resolved node, candidates |
Which nodes merged, into what, and with which candidates? A merge onto a different record is an identity failure. |
| Edge resolution: new edges, merged edges, invalidations |
How many exact repeats merged? How many near repeats survived? |
| Attempt count, validation status, error details |
Did a stage retry or fail? A failed trace does not change the graph. |
| Trace creation times |
In what order did the steps run? The gaps between them give only an approximate time for each step. |
Aggregate the stage outputs over all episodes with a script. Compare the
number of new nodes in the node-resolution traces with the number of extracted
nodes in the graph, and the number of new edges in the edge-resolution traces
with the number of extracted edges in the graph. Also count the episodes with
no record for a stage. A difference is a finding: record it in the report, and
do not change the configuration because of it. Use the explanation text as a
pointer to where to look.
Step 7. Decide the next change
Use this table. Make one change, increase the configuration version, run
again, and compare the two Step 5 tables.
| Symptom (Step 5 or 6) |
Probable cause |
Change |
| Extracted values of one type are not in the text |
The type description lists a vocabulary |
Move the type to the deterministic import. Remove the vocabulary from the description. |
| Field repeats |
The extractor saw the structured field |
Remove the field from the episode text and from the type description. Keep the identifier of the subject of the episode (Step 1). |
| A wrong ID on an imported node |
A later extraction changed the attribute (confirm in the trace), often because the lead sentence lost the subject identifier |
Put the subject identifier back in the lead sentence. Otherwise remove the attribute from the extractor's view, or write the imported attributes again after the narrative batch. |
| Extracted nodes with an ID as the name, next to imported nodes with the same ID |
The imported node name is not the name that the prose uses, so the name search did not return it as a candidate |
Give the imported node the name that the prose uses. Remove the related identifiers from the lead sentence. |
| Edges between two records that must not be related |
Context leaked between episodes |
Check the document_id grouping and the lead sentence. Make each part self-identifying. |
| Many untyped nodes |
A missing type |
Add the noun type that the prose needs, with a membership definition. |
| A long tail of edge names |
Free event extraction |
Declare a closed event edge set with endpoints, or set strict_ontology and measure the recall cost. |
| Many generic edges |
Endpoint pairs not declared |
Add the source_targets that the prose uses. |
| The second part of a document loses its subject |
The parts do not have the same document_id |
Give all the parts of the document the same document_id. Repeat the identity in each part. |
| Missing episodes |
Batch items that failed, were skipped, or were canceled, or a batch that is still processing or is invalid |
Read the batch status, and the status and the error of each item. Repair the preparation, and send only the missing items again. |
Stop the iteration when the identity checks pass for each imported record,
the field repeats and the untyped share are at the level that the use case
accepts, and the gold or derived questions show that the needed facts exist in
the graph. Retrieval tuning is a separate loop. Start it after that point.
Report format
Write one report per configuration version, and one comparison table across
versions. Use the Step 5 table as the comparison. Then write four sections in
this order:
- Direct measurements.
- Behavior that the documentation confirms.
- Interpretations.
- Open hypotheses.
State each difference between the compared runs, including the dates. Give n
for each rate.
Do not put episode text, personal data, or payload samples in a report. Use
aggregate counts and sanitized identifiers.
Anti-patterns
- Using an LLM or an agent to make structured records from prose for the
deterministic import. That step does not run again by itself on new
production data, and it replaces the Zep extraction.
- Sending the full record as JSON and expecting the model to produce the entity
graph. The model produces a near copy of the record, with the IDs as entity
names and a generic relation for each field.
- Listing the taxonomy in the type descriptions.
- Repairing a repeat with an instruction instead of a change to the data.
- Comparing two runs that differ in the data, the configuration, and the date
at the same time.
- Running the deterministic import again without the state file.
- Deleting the graph before the comparison is written.
- Reading one trace, finding a plausible explanation, and reporting it as the
cause.
1---2name: tuning-zep-ingestion3description: >-4 Procedure for an agent that must turn a dataset (database records, documents,5 email, chat messages, meeting transcripts, event logs, or a mix) into a6 domain-specific Zep Context Graph, with or without a gold question set. The7 procedure splits the data into a deterministic import and narrative episodes,8 shapes each episode, designs the ontology and the custom instructions, runs a9 versioned ingestion on a new graph, measures the graph shape, reads the debug10 logs and the Ingestion Traces, and changes one variable per run. Use when a11 user asks to "ingest my data into Zep", "improve extraction quality", "why12 does my graph have duplicate or untyped entities", "tune the ontology or the13 instructions", or "evaluate Zep on my dataset". Use together with the14 building-with-zep skill from the same plugin. Activate that skill first if15 it is not active yet.16metadata:17 source: https://skillmd.com/skills/getzep/tuning-zep-ingestion18---1920# Tuning Zep ingestion for a dataset2122**Required: use this skill together with the building-with-zep skill from23the same plugin.** If that skill is not active, activate it now, before you24continue. If your runtime cannot activate skills, read25[`../building-with-zep/SKILL.md`](../building-with-zep/SKILL.md). Use the26Documentation index and the source rules of the building-with-zep skill.27If the building-with-zep skill is not available, read the Zep28documentation through the `zep-docs` MCP server, or at29`https://help.getzep.com/<slug>.md`.3031This skill is a procedure. A page name in this skill, such as `debug-mode`,32is the `help.getzep.com` slug of the page.3334## API surface3536The procedure uses these operations. Some method names are37different in each SDK major version. Get the method names from the documentation of the SDK38version that you install, and record the SDK version in the manifest.3940| Operation | Used in | Notes |41|---|---|---|42| Create a graph, set the ontology, set the custom instructions | Step 4 | |43| Enable debug mode | Step 4 | The current SDK has a call for this. The call returns the window duration and a flag that states whether Ingestion Traces are on. Record both in the manifest. |44| Add nodes | Step 4 | Returns the node UUIDs. Keep them in the state file. |45| Add edges between two nodes | Step 4 | Refer to each endpoint by node UUID, not by name. The documentation of the SDK version tells whether a name makes a new node or matches an existing node by name. A match by name can select the wrong node when two imported nodes have the same name. |46| Create a batch, add items, process the batch, poll the batch and its items | Step 4 | |47| List the nodes, the edges, and the episodes of a graph, with paging | Step 5 | Each node and edge carries the UUIDs of the episodes that produced it. |48| Get the debug logs and list the Ingestion Traces of one episode | Step 6 | |49| Search the graph | Step 5 | For the needle check. |5051## Terms5253| Term | Meaning in this skill |54|---|---|55| Record | One unit of the source data: one database row, one email, one chat message, one document, one event. |56| Structured field | A field of a record with a fixed meaning and a short value: an ID, a name, a category, a status, a date, a reference to another record. |57| Prose field | A field of a record with free text: a message body, a document body, a transcript, a ticket description. |58| Deterministic import | Nodes and edges that you write into the graph from the structured data of the source, through one field mapping for each structured schema (Step 1), with the node and edge import calls of the SDK (see "API surface"). No LLM is involved. |59| Narrative episode | Text that you send to Zep for LLM extraction, through `graph.episode.add` or the Batch API. |60| Lead sentence | The first sentence of a narrative episode. It names the record kind, the subject with its identifier, the author, the time, and the source. It uses the same name and identifier for the subject that the deterministic import used. It does not list the identifiers of related records. |61| Configuration version | An integer that you increase each time you change the ontology, the instructions, or the episode preparation. One graph holds one configuration version. |62| Manifest | A file that records, for one run, the configuration version, a hash of the configuration, a hash of the prepared data, the graph ID, the debug-mode result, the start time, and the end time. Write each hash at run time and do not compute it again later. Freeze the prepared data file of each version. |63| Field repeat | An extracted edge or attribute that restates a structured field that the deterministic import already wrote. Measure three kinds: (a) the same source node and edge name as an imported edge, with a different target; (b) an extracted edge on a node pair that an imported edge already connects; (c) an extracted fact or attribute value that restates an imported attribute value. |64| Needle check | For one gold item, a check that the episodes that hold the evidence exist in the graph, were processed, and produced a fact or a node that a search for the gold item returns. When the gold item is a decision or a task output and not a fact string, the check is a search hit on the gold entity in the top results. |6566## Principles67681. Import what the data already states. Extract only what the prose adds.69 Structured data (database rows, JSON records, spreadsheet rows, email70 headers, event log rows) goes into the deterministic import: map its fields71 to entities and edges, and write them into the graph before the first72 episode. Unstructured data (message bodies, document bodies, transcripts,73 ticket descriptions) becomes narrative episodes. Do not use an LLM, or your74 own reading of the text, to make structured records from unstructured data75 for the import. A production pipeline must run the same import on each new76 record, with no agent in the loop. When the LLM also sees the structured fields, it77 extracts them again. The edge deduplication merges exact repeats, and it78 keeps a near repeat (a different edge name, or a fact that restates an79 attribute value) as a new edge.802. Each episode must stand alone. The extractor sees one episode. It also sees81 the earlier episodes that have the same `document_id` (`documents`), so give82 the parts of one source the same `document_id`. Without a `document_id`, Zep83 extracts the episode alone. Put the identity of the subject, the author, the84 time, and the source into the lead sentence of each episode. Episode85 metadata is for search filters. The extractor does not read it.863. Identity is a data decision. Decide the canonical name and the identifier of87 each entity type before the ingestion. When you have an authoritative alias88 map, rewrite the aliases in the data. Declare `identity_properties` for the89 types that carry an ID, and give each imported node the name that the prose90 uses for the entity. In measured runs, an extracted node merged into the91 imported node with the same identity value only when the imported node was92 in the candidate list of the resolution step, and the candidates came from93 a name search. An imported node named `"<account> deal <id>"` did not94 receive the merges of extracted nodes named `"<id>"`. An instruction about95 identity helps only when the data is already unambiguous.964. The model reads a type description as a list of answers. When a type97 description lists the permitted values (the issue categories, the status98 codes), the model emits those values also when the episode text does not99 contain them. Keep a closed vocabulary in the deterministic import. Do not100 list the values in the type description.1015. An instruction cannot stop a repeat. A rule such as "these facts already102 exist, do not repeat them" has no measured effect. The extractor cannot see103 the graph, so the rule has no reference. Remove the fact from the text and104 from the type descriptions (principle 4), or accept the repeat.1056. Change one variable per run. Each run has a configuration version, a new106 graph, and a manifest. Zep itself changes between runs. When you compare two107 runs, state every difference, including the dates of the runs.1087. Measure the graph shape before you measure the answers. The counts of nodes109 and edges by type, the untyped nodes, the edge names outside the ontology,110 the identity correctness against the source records, and the field repeats111 are deterministic, and they explain most answer failures.1128. Treat each LLM explanation as a claim. The Ingestion Traces show the stage113 inputs and outputs. Count what the stages did. Do not report the generated114 explanation text as the cause.1159. Separate the evidence types in each report: direct measurement, behavior116 that the documentation confirms, interpretation, and open hypothesis. The117 reader will act on the report. A hypothesis must not look like a fact.118119## Procedure120121### Intake. Ask about the use case and the test data122123Do this step before Step 0. Ask the user only the questions that the124conversation and the data do not answer. Put all the questions in one message.125Do not start Step 1 until the user answers, or until the user tells you to126continue without the answers.127128Ask these questions:1291301. How will the graph be used? Ask what the customer tries to do with the131 graph: the agent or the application that reads the graph, and the task of132 that agent.1332. Which questions must the graph answer? Ask for 5 to 20 real questions that134 the users of the agent ask.1353. Does the customer have evaluation question-and-answer pairs? When pairs136 exist, ask the user to upload them. When no pairs exist, tell the user that137 you will write draft pairs from the data (Step 5), and ask the user to138 correct them.1394. Can the user upload a sample of the data? Ask for a sample of each record140 kind. Ask that the sample include the records that the questions refer to.141142Example message to the user:143144> Before I design the ontology, I need some information about the use case.145>146> 1. How will the graph be used? For example: "A support agent reads the147> graph to answer questions about the orders and the returns of a148> customer."149> 2. Which questions must the graph answer? Give 5 to 20 real examples.150> 3. Do you have evaluation question-and-answer pairs? If yes, upload them as151> a CSV or a JSON file. The format is below.152> 4. Upload a sample of the data that you want to ingest. Include the records153> that the questions refer to.154>155> If you do not have question-and-answer pairs, I will write draft pairs from156> the data. You can then correct them.157158Example question-and-answer file. The `evidence` column is optional. It holds159the IDs of the source records that contain the answer.160161```csv162question,answer,evidence163"Which plan does Acme Corp use?","Enterprise, since 2026-03-01","account-1042; email-88213"164"Who is the main contact for the Acme renewal?","Jane Doe, VP Operations","contact-551"165"Why did Acme open a support ticket in May?","The SSO login failed after a certificate change","ticket-7730"166```167168Record the answers in the project notes. Use the use case and the questions169in Step 0 (question kinds), Step 2 (the types that the questions need), and170Step 5 (the needle check).171172### Step 0. Learn the data173174Read a sample of each record kind. For each kind, fill one row of this table175and keep the table in the project notes:176177| Kind | Structured fields | Prose fields | Natural identifier | Event time field | Related record kinds |178|---|---|---|---|---|---|179180Also record:181182- The number of records per kind.183- The size distribution of the prose fields. The documentation gives the184 episode size limit. Zep rejects an episode above the limit and does not185 truncate it.186- The alias patterns: short names, logins, email addresses, IDs with prefixes.187- Whether a gold question set exists (see "Intake"). When one exists, read188 each question kind and note which structured fields and which prose each189 kind needs.190191Then read these documentation pages: `prepare-data-for-ingestion`,192`adding-fact-triplets`, `customizing-graph-structure`, `custom-instructions`,193`documents`, `adding-batch-data`, and `debug-mode`. Read them on each project,194because the limits and the method names change.195196### Step 1. Split the dataset197198The rule for the split: structured data goes into the deterministic import,199and unstructured data becomes narrative episodes (principle 1). A record often200has both kinds, for example an email with headers and a body, or a ticket with201a status and a description. Split each record by field.202203For each structured schema in the data (each table, each JSON record type, each204file layout), write a field mapping before you write code. The mapping states205the result of each field in the graph: an entity, an attribute of an entity, an206edge between two entities, or nothing. Map only to the kinds of entities,207relationships, and attributes in the first column of the table below, and use208the same type names in the ontology (Step 2). The import code applies the209mappings and nothing else, so that it can run again on each new record.210211Write the split as a table before you write code:212213| Deterministic import (structured data) | Narrative episodes (unstructured data) | Dropped |214|---|---|---|215| Entities with a natural ID: people, accounts, cases, products, tickets, documents, channels, meetings | The prose fields, each with a lead sentence | Records with no prose and no relationship, for example a code table |216| Relationships that the records state: reports-to, works-on, authored, attends, filed-against, has-status | Facts that only the prose states: what happened, who said what, decisions, amounts, reasons | Header lines, MIME lines, signatures, redaction markers |217| Attributes with a closed vocabulary: categories, statuses, regions | | |218219Rules for the deterministic import:220221- Create one node per entity. Give the node the name that the prose uses for222 the entity (principle 3). Store the natural ID in a node attribute, so that223 you can join the graph to the source.224- Create one edge per stated relationship. Write a `fact` sentence that names225 both endpoints in full, with the date when the record has one. Example:226 `"Ana Ruiz attends the meeting 'Q3 plan review' on 2026-03-04."` The sentence227 `"The employee attends the meeting."` is not searchable.228- Refer to the endpoints of each edge by the node UUIDs that the node import229 returned.230- Set `valid_at` from the record time.231- Make the import resumable. Write a state file with the keys of the nodes and232 edges that are already created. Zep does not deduplicate nodes by name, so a233 retry without the state file creates each node twice.234- Validate the import before you send it: each node key is unique, and each235 edge endpoint refers to a known node key. Stop the run on an unknown key.236237Rules for the narrative episodes:238239- Start each episode with a lead sentence. Example:240 `"Email from Ana Ruiz <ana.ruiz@example.com> to Ben Ott <ben.ott@example.com>, 2026-03-04, subject 'Q3 plan review'."`241- Keep the name and the identifier of the subject of the episode in the lead242 sentence. Remove the identifiers of the related records that the243 deterministic import already linked to the subject. When the lead sentence244 lists a related identifier, the extractor makes a new node with that245 identifier as the name. When the lead sentence has no subject identifier,246 the extractor writes another value (often the name) into the identity247 attribute of the subject, and nodes with the same name merge.248- Put the prose after the lead sentence. Remove the structural noise (header249 lines, signatures, redaction markers).250- Set the episode time to the event time of the record. Do not use the251 ingestion time.252- When a prose field is longer than the episode limit, split it at a sentence253 or paragraph end. Repeat the lead sentence in each part, add `(part i of n)`,254 and give the parts of one source the same `document_id`. Do not give255 unrelated records the same `document_id`.256- For an event log with many similar rows (one row per process step), write257 one sentence per row that names the case, the activity, the actor, and the258 time. State in the instructions which activity gives the current state and259 which activities are final.260261### Step 2. Design the ontology262263- An entity type is a noun with a natural identity. An edge type is a verb264 between two named types. Start with the types that the questions or the use265 case need. The documentation gives the maximum number of types.266- Give each type a short description that defines membership. Add one or two267 positive examples and one negative example: a similar item that does not268 belong, with the type that it belongs to instead. The examples show the269 boundary of the type. Do not list all values in the description (principle 4).270- Make the types mutually exclusive, so that each entity or fact has one271 correct type. When two types must overlap, state in the descriptions which272 type takes priority.273- Declare `identity_properties` for each type that has an ID in the lead274 sentence.275- Declare the `source_targets` of each edge type. With `strict_ontology` set276 to `false`, Zep stores an extracted edge whose endpoints do not match a277 declared pair under the generic edge name `RELATES_TO`. Count these edges in278 Step 5. With `true`, Zep drops these edges.279- Keep a type that exists only for the import in the ontology, because a search280 filter needs the label. Tell the extractor in the instructions that these281 nodes exist, and that the prose adds facts to them. Expect partial compliance282 and measure it.283- Decide `strict_ontology` per run, from a measurement. With `false`, the graph284 has more recall and a tail of edge names and untyped entities outside the285 ontology. With `true`, Zep drops the tail and some true facts with it. When286 the tail is large, measure both settings.287288### Step 3. Write the custom instructions289290Use at most five short named blocks:291292| Block | Content |293|---|---|294| `corpus` | What the data is, what one episode is, what the lead sentence contains, how reliable the text is |295| `identity` | Which field identifies each type, which short names map to which canonical names, which values must never merge |296| `temporality` | Which field is the event time, the date format, when a fact starts to hold |297| `record` | Which record states the current or final state, which state supersedes which |298| `narrative` | What the prose adds: the event edges to extract and their names, which statements are facts on an existing node, which redacted values must not become entities |299300Write what the extractor must do. A rule about what the extractor must not do301works only when the prompt does not offer the forbidden value in another place302(principle 5).303304### Step 4. Run a versioned ingestion3053061. Create a new graph. Put the dataset name, the configuration version, and the307 first eight characters of the data hash in the graph ID.3082. Set the ontology and the instructions. Record their hashes in the manifest.309 The ontology and the instructions apply only to episodes that Zep processes310 after you set them.3113. Enable debug mode on the project through the SDK call. Record the returned312 window duration and the trace flag in the manifest. When the trace flag is313 off, your plan does not include Ingestion Traces; the `debug-mode` page314 gives the plan requirements and the retention. Confirm that the API key and315 the dashboard account open the same project before you use the dashboard.316 When the window is shorter than the run, enable debug mode again during the317 run, or make the slice smaller. After the first batch item completes, get318 its debug logs through the API; use the API result, not a documentation319 statement, to decide whether batch items have per-episode debug logs.3204. Run the deterministic import. Wait for its tasks. Count the created nodes and321 edges and compare the counts with the plan from Step 1.3225. Submit all narrative episodes through the Batch API in event-time order, in323 batches of the documented maximum size, without a wait between the batches.3246. Record the start time in the manifest. Measure the time of the first325 processing window (the first group of items that complete together) and326 estimate the run time of the full batch from it before you plan the next327 version.3287. Poll until each batch and each item is terminal. Record each failed item by329 key. Record the end time.3308. Keep the graph until the comparison report is written.331332Zep dispatches the items of one graph in the order of submission, and it333processes a window of items at the same time. An episode does not see the nodes334that the other episodes of the same window create. Do not depend on one335episode seeing the result of a near episode. Import the shared entities336deterministically before the batch. Run one graph per dataset at a time.337338### Step 5. Measure the graph shape339340Export each node, edge, and episode of the graph with the list calls of the341SDK, with paging. Write one script that produces this table, and keep the script in the project,342because you will run it on each configuration version:343344| Check | Method | Meaning of a bad value |345|---|---|---|346| Nodes by type, and untyped nodes | Count the labels. A node with only the generic label is untyped. | Many untyped nodes: the ontology lacks a type that the prose needs, or a type description is unclear. |347| Edges by name, inside and outside the ontology | Compare each edge name with the declared set. | A long tail (many names with one to five edges each): the prose has event facts with no declared edge type. Declare a closed event set, or accept the tail and rank. |348| Generic edges | Count the edges named `RELATES_TO`. | The endpoints did not match a declared pair, or no type matched. With `strict_ontology` set to `true`, Zep drops these edges, so a low count does not show that the endpoints matched. |349| Identity correctness | For each imported node, compare the identity property values, the name, and the labels in the graph with the import plan. Report the changed nodes by type. | A wrong ID: a later extraction changed an imported attribute, or two records merged. Only this comparison finds the change. |350| Identity collisions | Nodes of one type with the same name or the same ID. Edges between two nodes of a type that must not be related, for example case to case. | Context leaked across records, or aliases merged. |351| Field repeats | The three kinds in the Terms table, each as a share of the extracted edges. | The extractor emitted a structured field again (principle 4). |352| Node coverage | The share of extracted node names that occur in the episode text. | A low share for one type: the model takes the values from the type description. |353| Episode coverage | Each prepared episode key is present and processed. Failed items by key. | Missing episodes: items that failed, were skipped, or were canceled, items that are still processing, or a batch that is invalid. |354| Import integrity | The imported node and edge counts equal the plan. | A retry doubled the import, or a chunk failed. |355| Timing | Items per minute, per batch. | A slow run. Do not infer the cause from one run. |356357When a reference graph exists, add the entity recall and precision by type358against the reference. When the gold set is a question set or a task output359(a decision, a changed field, a cited source record) and not a graph, measure360the presence and the coverage of the gold entities, and define the needle check361as a search hit on the gold entity in the top results. Precision has no362reference in that case; do not report it.363364When no gold set exists, build a small one from the data. For each record365kind, write 10 to 25 questions of the kinds that the use case needs (point in366time, current state, count, sequence, who did what). Give each question the367episode keys that hold the evidence and a short gold answer. Write the368questions from the records, not from memory. The identity checks and the field369repeat check need no gold set, and they are the first checks to make pass.370371### Step 6. Read the debug logs and the Ingestion Traces372373Select the episodes that produced a bad value in Step 5, and a random sample of37420 episodes. Each node and edge carries the UUIDs of the episodes that produced375it; use them to find the episodes behind a bad value. For each selected376episode, get the debug logs and the Ingestion Traces through the API. Record:377378| Trace content | Question that it answers |379|---|---|380| Extraction input: episode content, previous episodes, entity types, edge types, instructions | What did the model see? Did the previous-episode list hold anything? Were the instructions present? |381| Extraction output: nodes with labels, edges with names | What did the model emit before deduplication? Which names are not in the text? |382| Node resolution: extracted node, resolved node, candidates | Which nodes merged, into what, and with which candidates? A merge onto a different record is an identity failure. |383| Edge resolution: new edges, merged edges, invalidations | How many exact repeats merged? How many near repeats survived? |384| Attempt count, validation status, error details | Did a stage retry or fail? A failed trace does not change the graph. |385| Trace creation times | In what order did the steps run? The gaps between them give only an approximate time for each step. |386387Aggregate the stage outputs over all episodes with a script. Compare the388number of new nodes in the node-resolution traces with the number of extracted389nodes in the graph, and the number of new edges in the edge-resolution traces390with the number of extracted edges in the graph. Also count the episodes with391no record for a stage. A difference is a finding: record it in the report, and392do not change the configuration because of it. Use the explanation text as a393pointer to where to look.394395### Step 7. Decide the next change396397Use this table. Make one change, increase the configuration version, run398again, and compare the two Step 5 tables.399400| Symptom (Step 5 or 6) | Probable cause | Change |401|---|---|---|402| Extracted values of one type are not in the text | The type description lists a vocabulary | Move the type to the deterministic import. Remove the vocabulary from the description. |403| Field repeats | The extractor saw the structured field | Remove the field from the episode text and from the type description. Keep the identifier of the subject of the episode (Step 1). |404| A wrong ID on an imported node | A later extraction changed the attribute (confirm in the trace), often because the lead sentence lost the subject identifier | Put the subject identifier back in the lead sentence. Otherwise remove the attribute from the extractor's view, or write the imported attributes again after the narrative batch. |405| Extracted nodes with an ID as the name, next to imported nodes with the same ID | The imported node name is not the name that the prose uses, so the name search did not return it as a candidate | Give the imported node the name that the prose uses. Remove the related identifiers from the lead sentence. |406| Edges between two records that must not be related | Context leaked between episodes | Check the `document_id` grouping and the lead sentence. Make each part self-identifying. |407| Many untyped nodes | A missing type | Add the noun type that the prose needs, with a membership definition. |408| A long tail of edge names | Free event extraction | Declare a closed event edge set with endpoints, or set `strict_ontology` and measure the recall cost. |409| Many generic edges | Endpoint pairs not declared | Add the `source_targets` that the prose uses. |410| The second part of a document loses its subject | The parts do not have the same `document_id` | Give all the parts of the document the same `document_id`. Repeat the identity in each part. |411| Missing episodes | Batch items that failed, were skipped, or were canceled, or a batch that is still processing or is invalid | Read the batch status, and the status and the error of each item. Repair the preparation, and send only the missing items again. |412413Stop the iteration when the identity checks pass for each imported record,414the field repeats and the untyped share are at the level that the use case415accepts, and the gold or derived questions show that the needed facts exist in416the graph. Retrieval tuning is a separate loop. Start it after that point.417418## Report format419420Write one report per configuration version, and one comparison table across421versions. Use the Step 5 table as the comparison. Then write four sections in422this order:4234241. Direct measurements.4252. Behavior that the documentation confirms.4263. Interpretations.4274. Open hypotheses.428429State each difference between the compared runs, including the dates. Give `n`430for each rate.431432Do not put episode text, personal data, or payload samples in a report. Use433aggregate counts and sanitized identifiers.434435## Anti-patterns436437- Using an LLM or an agent to make structured records from prose for the438 deterministic import. That step does not run again by itself on new439 production data, and it replaces the Zep extraction.440- Sending the full record as JSON and expecting the model to produce the entity441 graph. The model produces a near copy of the record, with the IDs as entity442 names and a generic relation for each field.443- Listing the taxonomy in the type descriptions.444- Repairing a repeat with an instruction instead of a change to the data.445- Comparing two runs that differ in the data, the configuration, and the date446 at the same time.447- Running the deterministic import again without the state file.448- Deleting the graph before the comparison is written.449- Reading one trace, finding a plausible explanation, and reporting it as the450 cause.