Episodic Memory

Event-based memories that capture what happened, when it happened, where, and who was involved. The foundation of an agent's autobiographical history.

What Is Episodic Memory?

Episodic memory stores discrete events and experiences as they occur. Each memory captures the full context of an interaction: the content of what happened, the emotional valence, who participated, where it took place, and how important it was.

These memories are automatically embedded into vector space using Qdrant, enabling semantic search across your agent's entire history. Over time, episodic memories are consolidated into long-term knowledge, and less-accessed memories naturally decay.

When to Use

•Recording conversation history and significant interactions
•Capturing meeting summaries and key decisions
•Storing code review findings and debugging sessions
•Remembering user-provided personal information ("my name is...")
•Building a searchable timeline of agent interactions

Quick Example

Create an episodic memory

import Rekall from '@rekall/sdk';

const rekall = new Rekall({ apiKey: 'rk_your_api_key' });

const memory = await rekall.episodic.create({
  content: 'User told me their name is Sarah and they prefer Python over TypeScript.',
  emotion: 'positive',
  importance: 0.8,
  participants: ['user:sarah', 'agent:assistant'],
  location: 'slack:general',
  metadata: {
    channel: 'general',
    topic: 'introduction',
  },
});

console.log(memory.id); // "mem_abc123"

Fields Reference

Field	Type	Required	Description
content	string	Yes	The event description. Automatically embedded for semantic search.
emotion	string	No	Emotional valence: positive, negative, neutral, mixed.
importance	number	No	Importance score from 0.0 to 1.0. Affects decay rate and consolidation priority.
participants	string[]	No	List of participant identifiers (e.g., "user:sarah", "agent:assistant").
location	string	No	Where the event occurred (e.g., "slack:general", "github:pr-42").
timestamp	ISO 8601	No	When the event occurred. Defaults to now if omitted.
metadata	object	No	Arbitrary key-value pairs for custom data.

Advanced Usage

Semantic Search

Episodic memories are automatically embedded, allowing you to search by meaning rather than exact keywords. The search returns memories ranked by semantic similarity.

Search episodic memories

const results = await rekall.episodic.search({
  query: 'What programming languages does the user prefer?',
  limit: 5,
  minImportance: 0.5,
});

for (const memory of results) {
  console.log(memory.content, memory.similarity);
}

Filtering & Metadata

Combine semantic search with metadata filters to narrow results. You can filter by participants, location, time range, emotion, and custom metadata fields.

Filtered search

const results = await rekall.episodic.search({
  query: 'deployment issues',
  filters: {
    participants: ['user:sarah'],
    location: 'slack:engineering',
    emotion: 'negative',
    after: '2025-01-01T00:00:00Z',
    metadata: { topic: 'deployment' },
  },
  limit: 10,
});

Use Cases

Conversation History

Store each significant interaction as an episodic memory. Later, search for "what did the user say about X?" to recall relevant context from past conversations.

Meeting Summaries

After a meeting, create an episodic memory with participants, decisions made, and action items. Tag with high importance so it persists longer.

Code Review Findings

Record code review feedback, bugs found, and patterns noticed. Search later to check if a similar issue was flagged before.

Personal Details

When a user shares personal information ("my name is Sarah", "I work at Acme Corp"), store it as a high-importance episodic memory. These are prime candidates for consolidation into long-term memory.

Best Practices

Writing good episodic memories

Write content as complete, self-contained descriptions. Instead of "said they like Python", write "User Sarah mentioned they prefer Python over TypeScript for backend services due to its data science ecosystem." More context means better semantic search results.

1.Be descriptive. Include who, what, when, and why. Richer content produces better embeddings.
2.Set importance thoughtfully. Reserve 0.9-1.0 for critical decisions or user-provided personal info. Use 0.3-0.5 for routine interactions.
3.Use participants consistently. Adopt a convention like "user:name" or "agent:role" so you can filter reliably.
4.Tag locations. Use structured location strings (e.g., "slack:channel", "github:repo/pr-42") for cross-platform filtering.
5.Let consolidation work. Do not try to manually maintain long-term knowledge. Let the consolidation process extract patterns from your episodic memories.

Episodic memories are automatically considered for consolidation into long-term memory. They can also reference entities in semantic memory.