Build Better Context Graphs: Custom Instructions, Search Filters, and Webhooks

We've shipped a lot over the past few months. This week: everything new in how you build and query context graphs.

Custom Extraction Instructions

Every domain has terminology that general-purpose NLP gets wrong. In legal contexts, "party" means a person or organization in an agreement — not a social event. In healthcare, "contraindication" has a precise clinical meaning. In financial services, "consideration" is a contractual concept, not an act of thinking.

Without domain guidance, Zep's extraction logic may misclassify entities or miss domain-specific relationships. Custom extraction instructions fix this.

Describe your domain — its terminology, acronyms, conventions — and Zep adapts its extraction logic to interpret your data correctly. Instructions are applied automatically in the background whenever data is ingested. No changes needed at ingestion or retrieval time.

from zep_cloud.client import Zep
from zep_cloud import CustomInstruction

client = Zep(api_key=API_KEY)

client.graph.add_custom_instructions(
    instructions=[
        CustomInstruction(
            name="legal_domain",
            text=(
                "This application operates in the legal domain. "
                "A 'party' refers to a person or organization in a legal agreement. "
                "'Consideration' refers to something of value exchanged "
                "between parties in a contract. "
                "'Force majeure' refers to unforeseeable circumstances "
                "preventing contract fulfillment."
            )
        )
    ]
)

Instructions can be scoped project-wide or to specific users and graphs. Adding an instruction with an existing name updates it (upsert behavior). Graph-specific instructions take precedence over project-wide defaults.

This is distinct from custom ontology, which defines the types of entities and relationships in your graph (e.g., a Restaurant entity with a cuisine_type attribute). Custom instructions describe the domain itself so Zep interprets data correctly during extraction. Use both together for the most precise context graphs.

Custom extraction instructions are available on Enterprise and Flex+ plans. Read the docs →

Graph Search Upgrades

Two new filters for more precise retrieval from your context graphs.

Property Filters

Filter search results by custom attribute values on nodes and edges. If you've defined custom entity types with attributes — say, a department on a Person entity or a priority on a task — you can now filter search results by those values directly.

Supported operators: =, <>, >, <, >=, <=, IS NULL, IS NOT NULL.

from zep_cloud.client import Zep
from zep_cloud.types import SearchFilters, PropertyFilter

client = Zep(api_key=API_KEY)

results = client.graph.search(
    user_id=user_id,
    query="team members",
    scope="edges",
    search_filters=SearchFilters(
        property_filters=[
            PropertyFilter(
                comparison_operator="=",
                property_name="department",
                property_value="Engineering"
            ),
            PropertyFilter(
                comparison_operator=">",
                property_name="level",
                property_value=3
            )
        ]
    )
)

Exclusion Filters

New exclude_node_labels and exclude_edge_types parameters let you remove specific entity or relationship types from search results. Useful when you know certain types add noise to a particular query. Combine with inclusion filters for precise control over what comes back.

results = client.graph.search(
    user_id=user_id,
    query="project information",
    scope="nodes",
    search_filters={
        "node_labels": ["Person", "Organization"],
        "exclude_edge_types": ["LOCATED_AT", "OCCURRED_AT"]
    }
)

Full search documentation →

Webhooks

Polling for completion status doesn't scale when you're wiring Zep into a data pipeline. Webhooks notify you when processing finishes so you can trigger downstream work automatically.

Supported events:

• episode.processed — fires when an episode finishes processing and enters the context graph
• ingest.batch.completed — fires when a batch ingestion job completes, with episode UUIDs
• byom.rate_limited / byom.request_failed — fires when your custom LLM credentials hit rate limits or errors

Configure webhooks through the Zep dashboard: specify your HTTPS endpoint, select the events you want, and Zep sends signed HTTP POST requests you can verify with the included Svix integration. BYOM events are aggregated over 60-second windows to prevent webhook spam during error bursts.

Available on Enterprise and Flex+ plans. Read the docs →

Other Updates

Flex+ Plan — A new tier between Flex and Enterprise. Flex+ includes webhooks, custom extraction instructions, and custom entity types — without requiring an enterprise contract. If you need these capabilities but aren't ready for an enterprise commitment, Flex+ is designed for you. See pricing →

• Fact Triple Enhancements — Specify triple types when adding facts programmatically, with increased character limits for fact text
• Task Management API — Track long-running async operations (graph clone, fact triple ingestion) with status polling
• Chunking Cookbook — A new guide for ingesting business data into context graphs (read the guide)

Get started with Zep →  |  Documentation →