Episodic Replay

Category: Retrieval

Problem

Agents often need to replay past interactions in chronological order to understand how a conversation evolved. Standard semantic recall returns the most relevant memories by similarity, but loses the sequential narrative. Without ordered replay, agents cannot reconstruct the reasoning chain that led to a decision or track how user requirements changed over time.

Architecture

This pattern stores each interaction with a session ID and sequence number in metadata. When replay is needed, memories are recalled by session and sorted by their sequence index, reconstructing the original conversation flow. This preserves temporal causality that pure vector search destroys.

Flow

• Assign a session ID and auto-incrementing sequence number to each interaction
• Store memories with session and sequence metadata
• Recall all memories for a given session, sorted by sequence
• Replay the ordered list to reconstruct conversation context

Implementation

from dakera import Dakera
import time

client = Dakera(base_url="http://localhost:3300", api_key="dk-...")

# Store interactions with session and sequence metadata
def store_interaction(session_id: str, sequence: int, role: str, content: str):
    """Store a single interaction in episodic memory."""
    client.memory.store(
        content=f"[{role}] {content}",
        namespace="agent-episodes",
        metadata={
            "session_id": session_id,
            "sequence": sequence,
            "role": role,
            "timestamp": time.time(),
            "type": "episode"
        }
    )

# Record a full exchange
store_interaction("sess-2024-0531", 1, "user", "I need help migrating to PostgreSQL")
store_interaction("sess-2024-0531", 2, "agent", "Which database are you migrating from?")
store_interaction("sess-2024-0531", 3, "user", "MySQL 5.7, about 200 tables")
store_interaction("sess-2024-0531", 4, "agent", "I recommend pgloader for schema conversion")

# Replay a session in order
def replay_session(session_id: str) -> list:
    """Replay all interactions from a session in chronological order."""
    results = client.memory.recall(
        query=f"session {session_id}",
        namespace="agent-episodes",
        top_k=100,
        metadata_filter={"session_id": session_id}
    )
    episodes = results["results"]
    episodes.sort(key=lambda x: x["metadata"]["sequence"])
    return [ep["content"] for ep in episodes]

# Reconstruct the conversation
history = replay_session("sess-2024-0531")
# Returns ordered: ["[user] I need help...", "[agent] Which database...", ...]

When to Use This Pattern

• Debugging agent behavior by replaying decision sequences
• Resuming multi-step workflows where order matters
• Audit trails that require chronological reconstruction
• Training data extraction from past successful interactions

Key Considerations

• Use integer sequence numbers rather than timestamps alone to avoid ordering ambiguity
• Set a reasonable top_k limit based on your maximum expected session length
• Consider compressing old episodes into summaries to save storage (see Summarization and Decay)
• Combine with namespace isolation to keep sessions from different users separate