Facts

Zep uses low-latency agents to continuously update a Fact Table as the conversation progresses. Facts are deconflicted and deduplicated, and the relationship between conflicting information is preserved.

A stylized example below:

How Fact Retrieval Works

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

When using the Memory API to retrieve relevant Facts, low-latency agents use a combination of semantic search and LLM tools to review the most recent messages in the Chat History. Facts are ranked by the current state of the conversation and returned.

Rating Facts for Relevancy

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.

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.

1
fact_rating_instruction = """Rate the facts by poignancy. Highly poignant 
2
facts have a significant emotional impact or relevance to the user. 
3
Low poignant facts are minimally relevant or of little emotional 
4
significance."""
5
fact_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
)
10
await 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.

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.

1
result = 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.

Creating Facts

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.

1
from zep_cloud.types import AddedFact
2
client.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.

Customizing Fact Generation

You can customize the contents and format of facts by providing Custom Instructions when persisting a Memory to a Session.

1
custom_instructions = """
2
Focus on the user's family and friend relationships. 
3
Identify life goals and interests. 
4
Note any standout characteristics or traits about the user.
5
"""
6
7
result = await client.memory.add(
8
    session_id,
9
    messages=messages,
10
    fact_instruction=custom_instructions
11
)

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.