Episodic Memory

When to Use

Use episodic memory when you need to store distinct interaction events or "episodes" that happen at a specific point in time. Perfect for:

• Chat logs and conversation history
• User actions (e.g., "User clicked buy", "User started workout")
• Events that need to be recalled by "when" they happened

Key Operations

Code Example

In this example, we store a conversation about Emma's job as an episode, then search for it later using a natural language query.

# 1. Store a conversation episode
response = client.memory.episodes.create(
    session_id="session_week1_day1",
    user_id="emma_2024",
    event_type="conversation",
    event_data={
        "summary": "Discussed new Product Manager role and anxiety about presentation",
        "messages": [...] 
    },
    metadata={"topic": "career"}
)
print(f"Created episode: {response.episode_id}")

# 2. Recall it later with semantic search
# Note: We ask "How did she feel", not matching keywords
results = client.memory.episodes.search(
    query="How did Emma feel about her new job initially?",
    user_id="emma_2024",
    limit=1
)

for ep in results:
    print(f"Recall: {ep.event_data['summary']} (Score: {ep.score})")

Key Takeaways

• Episodic memory is temporal - it preserves the timeline of events.
• It supports semantic search, allowing you to find events based on their meaning ("sad moments") rather than just keywords.
• Episodes are grouped by session_id, making it easy to reconstruct a full conversation thread.