Facts

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:

• The Memory API which supports adding structured chat messages.
• The Graph Add Data API which supports adding messages, text, or JSON 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

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.

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.

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 and Graph Search API.