Episodic Memory

Episodic Memory groups individual memories into coherent sequences of events with temporal boundaries, participants, and narrative structure. This enables queries like "What happened during the Q3 planning meeting?" rather than searching for isolated facts.

What is an Episode?

An episode represents a bounded sequence of events or interactions:

• Conversations - Chat sessions, email threads
• Meetings - Scheduled discussions with participants
• Document Sessions - Collaborative editing sessions
• Interactions - Customer support tickets, sales calls
• Project Phases - Sprints, milestones, releases

Episode Structure

Each episode contains:

Field	Description
Title	Human-readable name (e.g., "Q3 Planning Meeting")
Type	Category (conversation, meeting, document, etc.)
Time Range	Start and optional end timestamps
Participants	People/entities involved
Summary	Auto-generated or manual summary
Memories	List of memories belonging to this episode
Importance	Score from 0.0 to 1.0

Using Episodes in the Visualizer

Viewing the Timeline

Navigate to Episodes in the sidebar to see a chronological timeline of all episodes. Episodes are grouped by date and displayed as cards showing:

• Episode title and type
• Time range
• Number of memories
• Participant count

Creating Episodes

Click New Episode to create a manual episode. You can:

1. Set a title and type
2. Define the time range
3. Add participants
4. Link existing memories

Episode Details

Click any episode card to open the detail panel showing:

• Full summary and narrative
• All linked memories
• Relationship to other episodes (parent, follows)

API Usage

List Episodes

GET /api/v1/episodes/?limit=20
Headers:
  x-tenant-id: your-tenant-id

Create Episode

POST /api/v1/episodes/
Headers:
  x-tenant-id: your-tenant-id
Content-Type: application/json

{
  "tenant_id": "your-tenant-id",
  "type": "meeting",
  "title": "Weekly Sync",
  "description": "Team standup meeting"
}

Add Memory to Episode

POST /api/v1/episodes/{episode_id}/memories/{memory_id}
Headers:
  x-tenant-id: your-tenant-id

Best Practices

1. Group by Context - Create episodes for coherent interaction sessions
2. Use Meaningful Titles - Make episodes searchable with descriptive names
3. Set Importance - Higher importance episodes surface first in retrieval
4. Link Memories - Connect individual memories to their episode for context