Skip to navigation
Build with ContextRetrieve

Context templates

Create reusable templates for Context Block contents and format

Context templates allow you to customize how context is formatted and returned when calling thread.get_context(). Templates are reusable configurations that you set once for your project and can use across all your threads. They let you specify what information goes into your context block and how much of it to include, while Zep handles the automatic relevance detection and retrieval.

Template control

Context templates let you reuse one format across threads and users in a project:

  • More control than the default Context Block: you set the contents and format.
  • Less control than Advanced Context Block construction: Zep still creates the query.
  • Use it when you need a consistent custom format and keep automatic relevance detection.

See Choosing a retrieval method for a comparison of all three methods.

Define a template

Templates use variables to specify what data to include. Available variables:

Variables (except user_summary) accept optional parameters:

  • limit=N - Limit number of results (max 1000)
  • types=[type1,type2] - Filter by entity or edge types
  • include_attributes=true/false - Include/exclude attributes

%{observations} and %{thread_summaries} only support limit.

%{observations} and %{thread_summaries} are each capped at 20 items per render. A template limit=N greater than 20 can only truncate further; it cannot raise the count above this ceiling.

Example template definition:

# CUSTOMER PROFILE
# A summary of who this user is and their background.
%{user_summary}
# FACTS
# Key facts and relationships extracted from conversations.
%{edges limit=10}
# KEY ENTITIES
# Important people, organizations, and concepts related to this user.
%{entities limit=5 types=[person,organization]}

Create a template

Create a new template with a name and template content. The name must be unique in the project and can contain at most 100 characters. Zep generates a UUID for each template and returns it in the uuid field. Store the UUID in your application configuration, because the other template operations and context retrieval use the UUID. Templates are validated when created—Zep checks for valid variable names, proper bracket balancing, valid parameter syntax, and limit values within range.

To make a create safe to retry, you can pass an idempotency key: idempotency_key in Python, requestOptions in TypeScript, or option.WithIdempotencyKey in Go.

from zep_cloud import Zep
client = Zep(api_key="YOUR_API_KEY")
template = client.context.create_template(
    name="customer-support",
    template="""# CUSTOMER PROFILE
# A summary of who this user is and their background.
%{user_summary}
# FACTS
# Key facts and relationships extracted from conversations.
%{edges limit=10}
# KEY ENTITIES
# Important people, organizations, and concepts related to this user.
%{entities limit=5}"""
)
# Store the template UUID in your application configuration
zep_template_uuid = template.uuid_

Use a template

Pass the template UUID as the template_uuid parameter when retrieving context:

thread_context = client.thread.get_context(
    zep_thread_uuid,
    template_uuid=zep_template_uuid,
)
context_block = thread_context.context

Resulting context block

When you use the template above, Zep returns a formatted context block like this:

# CUSTOMER PROFILE
# A summary of who this user is and their background.
Emily Johnson is a long-time enterprise customer who has been using the platform since March 2024. She is the technical lead for TechCorp Solutions' API integration team and prefers asynchronous communication methods. Emily has shown strong interest in advanced features like SSO integration and webhook capabilities.
# FACTS
# Key facts and relationships extracted from conversations.
- (2024-11-15 14:23:00 - present) [CONTACTED_SUPPORT_ABOUT] <Emily contacted support regarding API rate limit concerns for high-volume usage>
- (2024-11-10 09:15:00 - present) [UPGRADED_TO] <Emily upgraded her organization's subscription from Pro to Enterprise plan>
- (2024-11-08 16:45:00 - present) [REQUESTED_DOCUMENTATION_FOR] <Emily requested comprehensive documentation for webhook integration patterns>
- (2024-11-05 11:00:00 - present) [ATTENDED] <Emily attended the product webinar focused on advanced enterprise features>
- (2024-11-01 13:30:00 - present) [INQUIRED_ABOUT] <Emily inquired about SSO integration options and implementation timeline>
# KEY ENTITIES
# Important people, organizations, and concepts related to this user.
- { name: TechCorp Solutions, types: [organization,company], summary: Emily's company with 500+ employees, currently on Enterprise plan since November 2024 }
- { name: API Integration Team, types: [organization,team], summary: Emily's department responsible for integrating external APIs and managing technical implementations }
- { name: Enterprise Plan, types: [product,subscription], summary: Premium subscription tier with advanced features including SSO, webhooks, and priority support }
- { name: John Smith, types: [person,colleague], summary: Emily's technical team member who collaborates on API integration projects }
- { name: Sarah Chen, types: [person,account_manager], summary: Emily's dedicated account manager who handles enterprise support and feature requests }

Update a template

Update an existing template’s content. Pass the template UUID. The update request sends the complete template, so include each section that you want to keep:

client.context.update_template(
    zep_template_uuid,
    template="""# CUSTOMER PROFILE
# A summary of who this user is and their background.
%{user_summary}
# FACTS
# Key facts and relationships extracted from conversations.
%{edges limit=20}
# ACCOUNT DETAILS
# Subscription and payment information for this account.
%{entities types=[subscription,payment_method]}
# TEAM MEMBERS
# People associated with this user's organization.
%{entities limit=10 types=[person]}
# OBSERVATIONS
# Durable, evidence-backed patterns Zep has derived about this user.
%{observations limit=5}
# RECENT CONVERSATIONS
# Per-thread summaries of what was discussed and resolved.
%{thread_summaries limit=3}"""
)

Read a template

Retrieve a specific template by its UUID, or list the templates in the project. The list is paginated. To find a template by its name, pass the name filter, which selects the template with that exact name:

# Get a specific template
template = client.context.get_template(zep_template_uuid)
# List all templates. The pager fetches the next pages when you iterate.
for template in client.context.list_templates():
    print(template.uuid_, template.name)
# Find the template with an exact name
matches = client.context.list_templates(name="customer-support")

Delete a template

Delete a template when it’s no longer needed:

client.context.delete_template(zep_template_uuid)