Utilizing Facts and Summaries — Zep Documentation

Understanding Facts and Summaries in Zep

Facts are Precise and Time-Stamped Information

A fact is stored on an edge and captures a detailed relationship about specific events. It includes valid_at and invalid_at timestamps, ensuring temporal accuracy and preserving a clear history of changes over time. This makes facts reliable sources of truth for critical information retrieval, providing the authoritative context needed for accurate decision-making and analysis by your agent.

Summaries are High-Level Overviews of Entities or Concepts

A summary resides on a node and provides a broad snapshot of an entity or concept and its relationships to other nodes. Summaries offer an aggregated and concise representation, making it easier to understand key information at a glance.

Choosing Between Facts and Summaries

Zep does not recommend relying solely on summaries for grounding LLM responses. While summaries provide a high-level overview, they lack the temporal accuracy necessary for precise reasoning. Instead, the memory context should be used since it includes relevant facts (each with valid and invalid timestamps). This ensures that conversations are based on up-to-date and contextually accurate information.

Context String

When calling Get Session Memory, Zep employs a sophisticated search strategy to surface the most pertinent information. The system first examines recent context by analyzing the last 4 messages (2 complete chat turns). It then utilizes multiple search techniques, with reranking steps to identify and prioritize the most contextually significant details for the current conversation.

The returned, context is structured as a string, optimized for language model prompts, making it easy to integrate into AI workflows. For more details, see Key Concepts. In addition to the context, the API response includes an array of the identified relevant_facts with their supporting details.

Rating Facts for Relevancy

Not all relevant_facts are equally important to your specific use-case. For example, a relationship coach app may need to recall important facts about a user’s family, but what the user ate for breakfast Friday last week is unimportant.

Fact ratings are a way to help Zep understand the importance of relevant_facts to your particular use case. After implementing fact ratings, you can specify a minRating when retrieving relevant_facts from Zep, ensuring that the memory context string contains customized content.

Implementing Fact Ratings

The fact_rating_instruction framework consists of an instruction and three example facts, one for each of a high, medium, and low rating. These are passed when Adding a User or Adding a Group and become a property of the User or Group.

Example: Fact Rating Implementation

1 fact_rating_instruction = """Evaluate the relevance of facts based on impact. 
2 Highly relevant facts directly affect the user's goals or emotions.
3 Low-relevance facts are incidental with minimal long-term significance.
4 """
5 
6 fact_rating_examples = FactRatingExamples(
7     high="The user received a job promotion.",
8     medium="The user finished a side project.",
9     low="The user changed their desktop wallpaper.",
10 )
11 
12 await client.user.add(
13     user_id=user_id,
14     fact_rating_instruction=FactRatingInstruction(
15         instruction=fact_rating_instruction,
16         examples=fact_rating_examples,
17     ),
18 )

All facts are rated on a scale between 0 and 1. You can access rating when retrieving relevant_facts from Get Session Memory.

Limiting Memory Recall to High-Rating Facts

You can filter relevant_facts by setting the minRating parameter in Get Session Memory.

1 result = await client.memory.get(session_id, min_rating=0.7)

Adding or Deleting Facts or Summaries

Facts and summaries are generated as part of the ingestion process. If you follow the directions for adding data to the graph, new facts and summaries will be created.

Deleting facts and summaries is handled by deleting data from the graph. Facts and summaries will be deleted when you delete the edge or node they exist on.

You can extract facts and summaries using the following methods:

Method	Description
Get Session Memory	Retrieves the `context` string and `relevant_facts`
Add User Update User Create Group Update Group	Allows specifying `fact_rating_instruction`
Get User Get Users Get Group Get All Groups	Retrieves `fact_rating_instruction` for each user or group
Search the Graph	Returns a list. Each item is an `edge` or `node` and has an associated `fact` or `summary`
Get User Edges Get Group Edges Get Edge	Retrieves `fact` on each `edge`
Get User Nodes Get Group Nodes Get Node	Retrieves `summary` on each `node`

1	fact_rating_instruction = """Evaluate the relevance of facts based on impact.
2	Highly relevant facts directly affect the user's goals or emotions.
3	Low-relevance facts are incidental with minimal long-term significance.
4	"""
5
6	fact_rating_examples = FactRatingExamples(
7	high="The user received a job promotion.",
8	medium="The user finished a side project.",
9	low="The user changed their desktop wallpaper.",
10	)
11
12	await client.user.add(
13	user_id=user_id,
14	fact_rating_instruction=FactRatingInstruction(
15	instruction=fact_rating_instruction,
16	examples=fact_rating_examples,
17	),
18	)