Context templates

Context templates allow you to customize how context is formatted and returned when calling thread.get_user_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.

Why use context templates

Context templates let you define a custom context format once and reuse it across all threads and users in your project. They provide a balance between simplicity and control:

• More control than: Default Context Block (customize format/structure)
• Less control than: Advanced construction with graph search (cannot customize search query)
• Best for: When you need consistent custom formatting but want 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:

• %{edges} - Graph edges (facts/relationships)
• %{entities} - Graph entities (nodes)
• %{episodes} - Episode data
• %{user_summary} - User summary information

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

Example template definition:

# CUSTOMER PROFILE
%{user_summary}
# RECENT INTERACTIONS
%{edges limit=10}
# KEY ENTITIES
%{entities limit=5 types=[person,organization]}

Create a template

Create a new template with a unique template ID and template content. Templates are validated when created—Zep checks for valid variable names, proper bracket balancing, valid parameter syntax, and limit values within range.

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
client.context.create_context_template(
6
    template_id="customer-support",
7
    template="""# CUSTOMER PROFILE
8
%{user_summary}
9
10
# RECENT INTERACTIONS
11
%{edges limit=10}
12
13
# KEY ENTITIES
14
%{entities limit=5}"""
15
)

Use a template

Pass the template_id parameter when retrieving context:

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
memory = client.thread.get_user_context(
6
    thread_id="thread_id",
7
    template_id="customer-support"
8
)
9
context_block = memory.context

Resulting context block

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

# CUSTOMER PROFILE
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.
# RECENT INTERACTIONS
- (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
- { 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:

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
client.context.update_context_template(
6
    template_id="customer-support",
7
    template="""# CUSTOMER PROFILE
8
%{user_summary}
9
10
# RECENT INTERACTIONS
11
%{edges limit=20}
12
13
# ACCOUNT DETAILS
14
%{entities types=[subscription,payment_method]}
15
16
# TEAM MEMBERS
17
%{entities limit=10 types=[person]}"""
18
)

Read a template

Retrieve a specific template by its ID or list all templates:

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
# Get a specific template
6
template = client.context.get_context_template(template_id="customer-support")
7
8
# List all templates
9
templates = client.context.list_context_templates()

Delete a template

Delete a template when it’s no longer needed:

1
from zep_cloud import Zep
2
3
client = Zep(api_key="YOUR_API_KEY")
4
5
client.context.delete_context_template(template_id="customer-support")