EverMemOS extracts four types of memories from conversations and provides four retrieval methods. This guide helps you understand when to use each.
Memory Types
EverMemOS automatically extracts different memory types from your conversations. Each serves a distinct purpose.
| Memory Type | Description | Example | Scene Support |
|---|
| Episode | Narrative summaries of conversations | ”Alice and Bob discussed the Q3 marketing strategy and decided to increase social media budget by 20%“ | All scenes |
| Profile | Persistent user attributes and preferences | ”Alice prefers morning meetings before 10am” | All scenes |
| Foresight | Time-valid prospective memories | ”Remind Alice about the dentist appointment on Friday at 3pm” | Assistant only |
| EventLog | Atomic factual records | ”Alice submitted the expense report on 2024-01-15” | Assistant only |
Episode Memory
Episodes capture the narrative flow of conversations. They’re automatically generated when EverMemOS detects a topic boundary (subject change, time gap, or explicit closure).
# Episode memories emerge from conversation context
messages = [
{"content": "Let's plan the product launch"},
{"content": "I think we should target Q2"},
{"content": "Good idea, I'll draft the timeline"},
{"content": "Perfect, let's discuss budget tomorrow"} # Topic closure
]
# Results in episode memory like:
# "The team discussed product launch planning, targeting Q2 release.
# They agreed to draft a timeline and discuss budget in a follow-up meeting."
Profile Memory
Profiles capture enduring user characteristics: preferences, habits, relationships, and biographical facts. They’re extracted when conversations reveal personal information.
# Profile memories capture user attributes
messages = [
{"content": "I always take my coffee black, no sugar"},
{"content": "I've been a vegetarian for 10 years"},
{"content": "My timezone is PST, so morning calls work best"}
]
# Results in profile memories like:
# - "User prefers black coffee without sugar"
# - "User is vegetarian (10+ years)"
# - "User is in PST timezone, prefers morning calls"
Foresight Memory
Foresight memories are prospective - they have a validity window defined by start_time and end_time. Use them for reminders, deadlines, and future context.
Foresight memories are only extracted in assistant scene mode. See the Foresight Memory guide for details. # Foresight memories have time validity
messages = [
{"content": "Remember to call John next Tuesday at 2pm"},
{"content": "The project deadline is March 15th"}
]
# Results in foresight memories with time windows:
# - "Call John" (start: next Tuesday 2pm, end: next Tuesday 3pm)
# - "Project deadline" (start: now, end: March 15th)
EventLog Memory
EventLog memories record atomic factual events - timestamped records of specific occurrences.
EventLog memories are only extracted in assistant scene mode.
# EventLog memories record specific events
messages = [
{"content": "I just submitted the quarterly report"},
{"content": "Completed the code review for PR #234"}
]
# Results in event log entries:
# - "User submitted quarterly report" (timestamp: now)
# - "User completed code review for PR #234" (timestamp: now)
Retrieval Methods
EverMemOS provides four retrieval methods, each with different latency and accuracy characteristics.
| Method | Latency | Best For | How It Works |
|---|
| keyword | <100ms | Exact term matching, known phrases | BM25 lexical search |
| vector | 200-500ms | Semantic similarity, paraphrased queries | Embedding-based search |
| hybrid / rrf | 200-600ms | General purpose (recommended default) | Reciprocal Rank Fusion of keyword + vector |
| agentic | 2-5s | Complex multi-part queries | LLM-guided query expansion |
Keyword (BM25)
Fast lexical search. Use when you know the exact terms.
search_params = {
"user_id": "user_alice",
"query": "quarterly report submission",
"retrieve_method": "keyword",
"top_k": 10
}
# Good for:
# - "Find messages mentioning 'Project Phoenix'"
# - "Search for 'budget approval'"
# - Known product names, IDs, or specific terms
Vector (Semantic)
Embedding-based semantic search. Finds conceptually similar content even with different wording.
search_params = {
"user_id": "user_alice",
"query": "what does alice like to do on weekends",
"retrieve_method": "vector",
"top_k": 10
}
# Good for:
# - "What are the user's hobbies?" (finds "I love hiking")
# - Conceptual queries with varied phrasing
# - When exact keywords are unknown
Hybrid / RRF (Recommended Default)
Combines keyword and vector search using Reciprocal Rank Fusion. Best balance of precision and recall.
search_params = {
"user_id": "user_alice",
"query": "alice's morning routine and work preferences",
"retrieve_method": "hybrid", # or "rrf" - they're equivalent
"top_k": 10
}
# Good for:
# - General-purpose queries
# - When you want both exact matches and semantic similarity
# - Default choice for most use cases
Agentic (LLM-Guided)
Uses an LLM to understand complex queries, expand them into sub-queries, and aggregate results. Higher latency but handles nuanced questions.
search_params = {
"user_id": "user_alice",
"query": "What context would help me prepare for my meeting with Alice about project priorities?",
"retrieve_method": "agentic",
"top_k": 10
}
# Good for:
# - Complex, multi-part questions
# - Queries requiring reasoning about what information is needed
# - High-stakes retrieval where accuracy matters more than speed
Choosing the Right Retrieval Method
Use this decision flowchart:
Is latency critical (<100ms required)?
├── Yes → Use "keyword"
└── No → Is the query complex or multi-part?
├── Yes → Use "agentic"
└── No → Use "hybrid" (default)
Quick Reference
| Scenario | Recommended Method |
|---|
| Real-time autocomplete | keyword |
| Chatbot memory retrieval | hybrid |
| Searching for specific terms/IDs | keyword |
| ”Tell me everything about X” | agentic |
| Semantic similarity search | vector |
| Default / unsure | hybrid |
Memory Type Filters
You can filter searches by memory type to get more relevant results:
# Search only profile memories
search_params = {
"user_id": "user_alice",
"query": "alice's preferences",
"retrieve_method": "hybrid",
"memory_types": ["profile"]
}
# Search profile and episodes
search_params = {
"user_id": "user_alice",
"query": "recent discussions and project updates",
"retrieve_method": "hybrid",
"memory_types": ["profile", "episodic_memory"]
}
Next Steps
