Customize Your Memory Context String

When using graph.search instead of memory.get, you need to use the search results to create a custom context string. In this recipe, we will demonstrate how to build a custom memory context string using the graph search API. We will also use the custom entity and edge types feature, though using this feature is optional.

Add data

First, we define our custom entity and edge types, create a user, and add some example data:

1import uuid
2from zep_cloud import Message
3from zep_cloud.external_clients.ontology import EntityModel, EntityText, EdgeModel, EntityBoolean
4from zep_cloud import EntityEdgeSourceTarget
5from pydantic import Field
6
7class Restaurant(EntityModel):
8 """
9 Represents a specific restaurant.
10 """
11 cuisine_type: EntityText = Field(description="The cuisine type of the restaurant, for example: American, Mexican, Indian, etc.", default=None)
12 dietary_accommodation: EntityText = Field(description="The dietary accommodation of the restaurant, if any, for example: vegetarian, vegan, etc.", default=None)
13
14class RestaurantVisit(EdgeModel):
15 """
16 Represents the fact that the user visited a restaurant.
17 """
18 restaurant_name: EntityText = Field(description="The name of the restaurant the user visited", default=None)
19
20class DietaryPreference(EdgeModel):
21 """
22 Represents the fact that the user has a dietary preference or dietary restriction.
23 """
24 preference_type: EntityText = Field(description="Preference type of the user: anything, vegetarian, vegan, peanut allergy, etc.", default=None)
25 allergy: EntityBoolean = Field(description="Whether this dietary preference represents a user allergy: True or false", default=None)
26
27client.graph.set_ontology(
28 entities={
29 "Restaurant": Restaurant,
30 },
31 edges={
32 "RESTAURANT_VISIT": (
33 RestaurantVisit,
34 [EntityEdgeSourceTarget(source="User", target="Restaurant")]
35 ),
36 "DIETARY_PREFERENCE": (
37 DietaryPreference,
38 [EntityEdgeSourceTarget(source="User")]
39 ),
40 }
41)
42
43messages_session1 = [
44 Message(content="Take me to a lunch place", role_type="user", role="John Doe"),
45 Message(content="How about Panera Bread, Chipotle, or Green Leaf Cafe, which are nearby?", role_type="assistant", role="Assistant"),
46 Message(content="Do any of those have vegetarian options? I’m vegetarian", role_type="user", role="John Doe"),
47 Message(content="Yes, Green Leaf Cafe has vegetarian options", role_type="assistant", role="Assistant"),
48 Message(content="Let’s go to Green Leaf Cafe", role_type="user", role="John Doe"),
49 Message(content="Navigating to Green Leaf Cafe", role_type="assistant", role="Assistant"),
50]
51
52messages_session2 = [
53 Message(content="Take me to dessert", role_type="user", role="John Doe"),
54 Message(content="How about getting some ice cream?", role_type="assistant", role="Assistant"),
55 Message(content="I can't have ice cream, I'm lactose intolerant, but I'm craving a chocolate chip cookie", role_type="user", role="John Doe"),
56 Message(content="Sure, there's Insomnia Cookies nearby.", role_type="assistant", role="Assistant"),
57 Message(content="Perfect, let's go to Insomnia Cookies", role_type="user", role="John Doe"),
58 Message(content="Navigating to Insomnia Cookies.", role_type="assistant", role="Assistant"),
59]
60
61user_id = f"user-{uuid.uuid4()}"
62client.user.add(user_id=user_id, first_name="John", last_name="Doe", email="[email protected]")
63
64session1_id = f"session-{uuid.uuid4()}"
65session2_id = f"session-{uuid.uuid4()}"
66client.memory.add_session(session_id=session1_id, user_id=user_id)
67client.memory.add_session(session_id=session2_id, user_id=user_id)
68
69client.memory.add(session_id=session1_id, messages=messages_session1, ignore_roles=["assistant"])
70client.memory.add(session_id=session2_id, messages=messages_session2, ignore_roles=["assistant"])

Example 1: Basic custom context string

For a basic custom context string, we search the graph for edges and nodes relevant to our custom query string, which typically represents a user message. Note that the default memory context string returned by memory.get uses the past few messages as the query instead.

Additionally, note that below we retrieve the past several episodes and use those episode IDs as the BFS node IDs. These are used to seed separate, shallow breadth first searches starting from those episodes, which helps make the search results more relevant to the user’s recent history. We can pass episode IDs instead of node IDs because episodes are represented as nodes under the hood. You can provide BFS nodes both when scope=nodes or scope=edges.

These searches can be performed in parallel to reduce latency, using our async Python client, TypeScript promises, or goroutines.

1query = "Find some food around here"
2
3episodes = client.graph.episode.get_by_user_id(
4 user_id=user_id,
5 lastn=10
6).episodes
7
8episode_uuids = [episode.uuid_ for episode in episodes if episode.role_type == 'user']
9
10search_results_nodes = client.graph.search(
11 query=query,
12 user_id=user_id,
13 scope='nodes',
14 reranker='cross_encoder',
15 limit=10,
16 bfs_origin_node_uuids=episode_uuids
17)
18search_results_edges = client.graph.search(
19 query=query,
20 user_id=user_id,
21 scope='edges',
22 reranker='cross_encoder',
23 limit=10,
24 bfs_origin_node_uuids=episode_uuids
25)

Build the context string

Using the search results and a few helper functions, we can build the context string. Note that for nodes, we typically want to unpack the node name and node summary, and for edges we typically want to unpack the fact and the temporal validity information:

1from zep_cloud import EntityEdge, EntityNode
2
3CONTEXT_STRING_TEMPLATE = """
4FACTS and ENTITIES represent relevant context to the current conversation.
5# These are the most relevant facts and their valid date ranges
6# format: FACT (Date range: from - to)
7<FACTS>
8{facts}
9</FACTS>
10
11# These are the most relevant entities
12# ENTITY_NAME: entity summary
13<ENTITIES>
14{entities}
15</ENTITIES>
16"""
17
18
19def format_fact(edge: EntityEdge) -> str:
20 valid_at = edge.valid_at if edge.valid_at is not None else "date unknown"
21 invalid_at = edge.invalid_at if edge.invalid_at is not None else "present"
22 formatted_fact = f" - {edge.fact} (Date range: {valid_at} - {invalid_at})"
23 return formatted_fact
24
25def format_entity(node: EntityNode) -> str:
26 formatted_entity = f" - {node.name}: {node.summary}"
27 return formatted_entity
28
29def compose_context_string(edges: list[EntityEdge], nodes: list[EntityNode]) -> str:
30 facts = [format_fact(edge) for edge in edges]
31 entities = [format_entity(node) for node in nodes]
32 return CONTEXT_STRING_TEMPLATE.format(facts='\n'.join(facts), entities='\n'.join(entities))
33
34edges = search_results_edges.edges
35nodes = search_results_nodes.nodes
36
37context_string = compose_context_string(edges, nodes)
38print(context_string)
FACTS and ENTITIES represent relevant context to the current conversation.
# These are the most relevant facts and their valid date ranges
# format: FACT (Date range: from - to)
<FACTS>
- User wants to go to dessert (Date range: 2025-06-16T02:17:25Z - present)
- John Doe wants to go to a lunch place (Date range: 2025-06-16T02:17:25Z - present)
- John Doe said 'Perfect, let's go to Insomnia Cookies' indicating he will visit Insomnia Cookies. (Date range: 2025-06-16T02:17:25Z - present)
- John Doe said 'Let’s go to Green Leaf Cafe' indicating intention to visit (Date range: 2025-06-16T02:17:25Z - present)
- John Doe is craving a chocolate chip cookie (Date range: 2025-06-16T02:17:25Z - present)
- John Doe states that he is vegetarian. (Date range: 2025-06-16T02:17:25Z - present)
- John Doe is lactose intolerant (Date range: 2025-06-16T02:17:25Z - present)
</FACTS>
# These are the most relevant entities
# ENTITY_NAME: entity summary
<ENTITIES>
- lunch place: The entity is a lunch place, but no specific details about its cuisine or dietary accommodations are provided.
- dessert: The entity 'dessert' refers to a preference related to sweet courses typically served at the end of a meal. The context indicates that the user has expressed an interest in going to a dessert place, but no specific dessert or place has been named. The entity is categorized as a Preference and Entity, but no additional attributes are provided or inferred from the messages.
- Green Leaf Cafe: Green Leaf Cafe is a restaurant that offers vegetarian options, making it suitable for vegetarian diners.
- user: The user is John Doe, with the email [email protected]. He has shown interest in visiting Green Leaf Cafe, which offers vegetarian options, and has also expressed a preference for lactose-free options, craving a chocolate chip cookie. The user has decided to go to Insomnia Cookies.
- vegetarian: The user is interested in lunch places such as Panera Bread, Chipotle, and Green Leaf Cafe. They are specifically looking for vegetarian options at these restaurants.
- chocolate chip cookie: The entity is a chocolate chip cookie, which the user desires as a snack. The user is lactose intolerant and cannot have ice cream, but is craving a chocolate chip cookie.
- Insomnia Cookies: Insomnia Cookies is a restaurant that offers cookies, including chocolate chip cookies. The user is interested in a dessert and has chosen to go to Insomnia Cookies. No specific cuisine type or dietary accommodations are mentioned in the messages.
- lactose intolerant: The entity is a preference indicating lactose intolerance, which is a dietary restriction that prevents the individual from consuming lactose, a sugar found in milk and dairy products. The person is specifically craving a chocolate chip cookie but cannot have ice cream due to lactose intolerance.
- John Doe: The user is John Doe, with user ID user-34c7a6c1-ded6-4797-9620-8b80a5e7820f, email [email protected], and role type user. He inquired about nearby lunch options and vegetarian choices, and expressed a preference for a chocolate chip cookie due to lactose intolerance.
</ENTITIES>

Example 2: Utilizing custom entity and edge types

Search

For a custom context string that uses custom entity and edge types, we perform multiple searches (with our custom query string) filtering to the custom entity or edge type we want to include in the context string:

As we do in Example 1, we pass episode IDs as BFS node IDs:

These searches can be performed in parallel to reduce latency, using our async Python client, TypeScript promises, or goroutines.

1query = "Find some food around here"
2
3episodes = client.graph.episode.get_by_user_id(
4 user_id=user_id,
5 lastn=10
6).episodes
7
8episode_uuids = [episode.uuid_ for episode in episodes if episode.role_type == 'user']
9
10search_results_restaurant_visits = client.graph.search(
11 query=query,
12 user_id=user_id,
13 scope='edges',
14 search_filters={
15 "edge_types": ["RESTAURANT_VISIT"]
16 },
17 reranker='cross_encoder',
18 limit=10,
19 bfs_origin_node_uuids=episode_uuids
20)
21search_results_dietary_preferences = client.graph.search(
22 query=query,
23 user_id=user_id,
24 scope='edges',
25 search_filters={
26 "edge_types": ["DIETARY_PREFERENCE"]
27 },
28 reranker='cross_encoder',
29 limit=10,
30 bfs_origin_node_uuids=episode_uuids
31)
32search_results_restaurants = client.graph.search(
33 query=query,
34 user_id=user_id,
35 scope='nodes',
36 search_filters={
37 "node_labels": ["Restaurant"]
38 },
39 reranker='cross_encoder',
40 limit=10,
41 bfs_origin_node_uuids=episode_uuids
42)

Build the context string

Using the search results and a few helper functions, we can compose the context string. Note that in this example, we focus on unpacking the custom attributes of the nodes and edges, but this is a design choice that you can experiment with for your use case.

Note also that we designed the context string template around the custom entity and edge types that we are unpacking into the context string:

1from zep_cloud import EntityEdge, EntityNode
2
3CONTEXT_STRING_TEMPLATE = """
4PREVIOUS_RESTAURANT_VISITS, DIETARY_PREFERENCES, and RESTAURANTS represent relevant context to the current conversation.
5# These are the most relevant restaurants the user has previously visited
6# format: restaurant_name: RESTAURANT_NAME
7<PREVIOUS_RESTAURANT_VISITS>
8{restaurant_visits}
9</PREVIOUS_RESTAURANT_VISITS>
10
11# These are the most relevant dietary preferences of the user, whether they represent an allergy, and their valid date ranges
12# format: allergy: True/False; preference_type: PREFERENCE_TYPE (Date range: from - to)
13<DIETARY_PREFERENCES>
14{dietary_preferences}
15</DIETARY_PREFERENCES>
16
17# These are the most relevant restaurants the user has discussed previously
18# format: name: RESTAURANT_NAME; cuisine_type: CUISINE_TYPE; dietary_accommodation: DIETARY_ACCOMMODATION
19<RESTAURANTS>
20{restaurants}
21</RESTAURANTS>
22"""
23
24def format_edge_with_attributes(edge: EntityEdge, include_timestamps: bool = True) -> str:
25 attrs_str = '; '.join(f"{k}: {v}" for k, v in sorted(edge.attributes.items()))
26 if include_timestamps:
27 valid_at = edge.valid_at if edge.valid_at is not None else "date unknown"
28 invalid_at = edge.invalid_at if edge.invalid_at is not None else "present"
29 return f" - {attrs_str} (Date range: {valid_at} - {invalid_at})"
30 return f" - {attrs_str}"
31
32def format_node_with_attributes(node: EntityNode) -> str:
33 attributes = {k: v for k, v in node.attributes.items() if k != "labels"}
34 attrs_str = '; '.join(f"{k}: {v}" for k, v in sorted(attributes.items()))
35 base = f" - name: {node.name}; {attrs_str}"
36 return base
37
38def compose_context_string(restaurant_visit_edges: list[EntityEdge], dietary_preference_edges: list[EntityEdge], restaurant_nodes: list[EntityNode]) -> str:
39 restaurant_visits = [format_edge_with_attributes(edge, include_timestamps=False) for edge in restaurant_visit_edges]
40 dietary_preferences = [format_edge_with_attributes(edge, include_timestamps=True) for edge in dietary_preference_edges]
41 restaurant_nodes = [format_node_with_attributes(node) for node in restaurant_nodes]
42 return CONTEXT_STRING_TEMPLATE.format(restaurant_visits='\n'.join(restaurant_visits), dietary_preferences='\n'.join(dietary_preferences), restaurants='\n'.join(restaurant_nodes))
43
44
45restaurant_visit_edges = search_results_restaurant_visits.edges
46dietary_preference_edges = search_results_dietary_preferences.edges
47restaurant_nodes = search_results_restaurants.nodes
48
49context_string = compose_context_string(restaurant_visit_edges, dietary_preference_edges, restaurant_nodes)
50print(context_string)
PREVIOUS_RESTAURANT_VISITS, DIETARY_PREFERENCES, and RESTAURANTS represent relevant context to the current conversation.
# These are the most relevant restaurants the user has previously visited
# format: restaurant_name: RESTAURANT_NAME
<PREVIOUS_RESTAURANT_VISITS>
- restaurant_name: Insomnia Cookies
- restaurant_name: Green Leaf Cafe
</PREVIOUS_RESTAURANT_VISITS>
# These are the most relevant dietary preferences of the user, whether they represent an allergy, and their valid date ranges
# format: allergy: True/False; preference_type: PREFERENCE_TYPE (Date range: from - to)
<DIETARY_PREFERENCES>
- allergy: False; preference_type: vegetarian (Date range: 2025-06-16T02:17:25Z - present)
- allergy: False; preference_type: lactose intolerance (Date range: 2025-06-16T02:17:25Z - present)
</DIETARY_PREFERENCES>
# These are the most relevant restaurants the user has discussed previously
# format: name: RESTAURANT_NAME; cuisine_type: CUISINE_TYPE; dietary_accommodation: DIETARY_ACCOMMODATION
<RESTAURANTS>
- name: Green Leaf Cafe; dietary_accommodation: vegetarian
- name: Insomnia Cookies;
</RESTAURANTS>