Facts

Facts are extracted from the Chat History as a conversation unfolds.

What are Facts?

Facts are observations about a user and their interaction with your Assistant. They are derived from user interactions, such as chat history, and business data added to Zep.

Zep autonomously builds a knowledge graph from user interaction and business data while handling changing relationships and maintaining historical context. Zep generates facts from relationships identified in the graph. As Zep incorporates new information, outdated facts are marked as invalid. Retaining a history of facts enables agents to reason with changing user state.

Zep supports two APIs for adding data:

How Fact Retrieval Works

Relevant Facts can be retrieved via a Memory call, the Search API, or the Graph Search API.

When using the Memory API to retrieve relevant Facts, the most recent messages in the Chat History are used to retrieve relevant facts. These facts are then reranked by graph distance from the user and returned.

The other two APIs will return graph edges, which contain an edge.fact field as the relevant fact.

Rating Facts for Relevancy

Available to Subscription customers only.

All accounts created after October 18th, 2024 should use client.user.add() instead of client.session.add() to add fact rating instructions. See the Add User API.

Not all Facts are relevant to your application and users. For example, a realtionship 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.

Adding spurious Facts to your prompt may result in the LLM hallucinating or exhibiting other undesired behavior.

Fact Ratings are a way to help Zep understand the relevance of a Fact to your particular use case. After implementing Fact Ratings, you can specify a minimum rating when retrieving Facts from Zep, ensuring that prompt only contains high-signal context.

Implementing Fact Ratings

A Fact Rating framework consist of an Instruction and three example Facts, one for each of a “High”, “Medium”, and “Low” rating. This is passed into a Session on creation.

1fact_rating_instruction = """Rate the facts by poignancy. Highly poignant 
2facts have a significant emotional impact or relevance to the user. 
3Low poignant facts are minimally relevant or of little emotional 
4significance."""
5fact_rating_examples = FactRatingExamples(
6    high="The user received news of a family member's serious illness.",
7    medium="The user completed a challenging marathon.",
8    low="The user bought a new brand of toothpaste.",
9)
10await zep.memory.add_session(
11    user_id=user_id,
12    session_id=session_id,
13    fact_rating_instruction=FactRatingInstruction(
14        instruction=fact_rating_instruction,
15        examples=fact_rating_examples,
16    ),
17)

Facts are rated on a scale between 0 and 1. You can review ratings for a Session by visiting the web app or retrieving all Facts for a Session.

Fact Ratings
Fact Ratings in the Zep Web App

Limiting Memory Recall to High-Rating Facts

Zep automatically returns relevant Facts when retrieving Memory. You can limit the returned Facts by Rating when setting the min_rating parameter in the get method.

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

It’s also possible to filter search results by Fact Rating by setting the min_fact_rating parameter when searching Sessions.

Adding additional data to the graph

You can add additional data to the graph using the Add Data API. This can be used to add additional relevant business data that may not be present in the Chat History.

Unlike RAG, where documents in a vector index are static, facts extracted from data you add to a Session will be curated as the conversation with the user progresses. They may be updated, merged into new Facts, or invalidated as new information is learned from the user.

Creating Facts

Creating facts is deprecated and will not work with graph-based facts. Please use the Add Data API to add data to the graph instead.

You may have information about your user that would be helpful context when prompting an LLM. You can generate textual facts from this data and persist these to a Session. The data will be returned if relevant to the current conversation, alongside other facts gleaned from the Chat History.

Unlike RAG, where documents in a vector index are static, Facts you add to a Session will be curated as the conversation with the user progresses. They may be updated, merged into new Facts, or deleted as new information is learned from the user.

1from zep_cloud.types import AddedFact
2client.memory.add_session_facts(
3    session_id="sessionId",
4    facts=[
5        AddedFact(fact="The user is a software engineer"),
6        AddedFact(fact="The user studied at MIT"),
7        AddedFact(fact="The user lives in San Francisco"),
8    ]
9)

Deleting Facts

You or your users may want to remove a fact from Zep’s memory. You can do this by deleting a fact by Fact UUID.

Retrieving Facts

Facts are added to Memory responses when you retrieve a Session’s Memory. They’re also accessible the Search API and lower-level Session API and Graph Search API.