📢 Announcing our research paper: Zentry achieves 26% higher accuracy than OpenAI Memory, 91% lower latency, and 90% token savings! Read the paper to learn how we're revolutionizing AI agent memory.
Zentry’s Criteria Retrieval feature allows you to retrieve memories based on specific criteria. This is useful when you need to find memories that match certain conditions or criteria, such as emotional content, sentiment, or other custom attributes.
You can define custom criteria at the project level, assigning weights to each criterion. These weights will be normalized during memory retrieval.
Copy
from Zentry import MemoryClientclient = MemoryClient( api_key="Zentry_api_key", org_id="Zentry_organization_id", project_id="Zentry_project_id")# Define custom criteria with weightsretrieval_criteria = [ { "name": "joy", "description": "Measure the intensity of positive emotions such as happiness, excitement, or amusement expressed in the sentence. A higher score reflects greater joy.", "weight": 3 }, { "name": "curiosity", "description": "Assess the extent to which the sentence reflects inquisitiveness, interest in exploring new information, or asking questions. A higher score reflects stronger curiosity.", "weight": 2 }, { "name": "emotion", "description": "Evaluate the presence and depth of sadness or negative emotional tone, including expressions of disappointment, frustration, or sorrow. A higher score reflects greater sadness.", "weight": 1 }]# Update project with custom criteriaclient.update_project( retrieval_criteria=retrieval_criteria)
After setting up your criteria, you can use them to filter and retrieve memories. Here’s an example:
Copy
# Add some example memoriesmessages = [ {"role": "user", "content": "What a beautiful sunny day! I feel so refreshed and ready to take on anything!"}, {"role": "user", "content": "I've always wondered how storms form—what triggers them in the atmosphere?"}, {"role": "user", "content": "It's been raining for days, and it just makes everything feel heavier."}, {"role": "user", "content": "Finally I get time to draw something today, after a long time!! I am super happy today."}]client.add(messages, user_id="alice")# Search with criteria-based filteringfilters = { "AND": [ {"user_id": "alice"} ]}results_with_criteria = client.search( query="Why I am feeling happy today?", filters=filters, version="v2")# Standard search without criteria filteringresults_without_criteria = client.search( query="Why I am feeling happy today?", user_id="alice")
[ { "memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.666, ... }, { "memory": "User finally has time to draw something after a long time", "score": 0.616, ... }, { "memory": "User is happy today", "score": 0.500, ... }, { "memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.400, ... }, { "memory": "It has been raining for days, making everything feel heavier.", "score": 0.116, ... }]
[ { "memory": "User is happy today", "score": 0.607, ... }, { "memory": "User feels refreshed and ready to take on anything on a beautiful sunny day", "score": 0.512, ... }, { "memory": "It has been raining for days, making everything feel heavier.", "score": 0.4617, ... }, { "memory": "User is curious about how storms form and what triggers them in the atmosphere.", "score": 0.340, ... }, { "memory": "User finally has time to draw something after a long time", "score": 0.336, ... }]
Looking at the example results above, we can see how criteria-based filtering affects the output:
Memory Ordering: With criteria, memories with high joy scores (like feeling refreshed and drawing) are ranked higher, while without criteria, the most relevant memory (“User is happy today”) comes first.
Score Distribution: With criteria, scores are more spread out (0.116 to 0.666) and reflect the criteria weights, while without criteria, scores are more clustered (0.336 to 0.607) and based purely on relevance.
Negative Content: With criteria, the negative memory about rain has a much lower score (0.116) due to the emotion criteria, while without criteria it maintains a relatively high score (0.4617) due to its relevance.
Curiosity Content: The storm-related memory gets a moderate score (0.400) with criteria due to the curiosity weighting, while without criteria it’s ranked lower (0.340) as it’s less relevant to the happiness query.
Scoring: With criteria, normalized scores (0-1) are used based on custom criteria weights, while without criteria, standard relevance scoring is used
Ordering: With criteria, memories are first retrieved by relevance, then criteria-based filtering and prioritization is applied, while without criteria, ordering is solely by relevance
Filtering: With criteria, post-retrieval filtering based on custom criteria (joy, curiosity, etc.) is available, which isn’t available without criteria
When no custom criteria are specified, the search will default to standard relevance-based retrieval. In this case, results are returned based solely on their relevance to the query, without any additional filtering or prioritization that would normally be applied through criteria.