Episodic Memory

Purpose

The Episodic Memory module acts as the system's autobiographical memory. It preserves the timeline of user interactions, allowing the agent to recall past conversations ("What did we discuss yesterday?") and maintain continuity across sessions.

Key Features

• LLM Summarization: Compresses raw chat logs into semantic summaries (e.g., "User asked for Python debugging tips").
• Utility Scoring: Assigns a 0-1 score for importance/information density. Low-utility episodes are candidates for early pruning.
• Temporal Chaining: Episodes are linked in a chain (:Episode)-[:NEXT]->(:Episode) to preserve timeline continuity.

Functional Deep Dive

Summarization

Agents don't store raw chat logs directly in the graph as nodes. Instead, the LLMService processes the interaction to generate a concise semantic summary. This reduces noise and improves retrieval relevance.

Temporal Chaining

Episodes form a linked list in Neo4j using the [:NEXT] relationship. This structure enables the system to traverse history sequentially when reconstructing a conversation context.

Utility Scoring

Each episode is assigned a utility score (0-1).

• High Score: Important decisions, new facts, or user preferences.
• Low Score: Phatic communication (e.g., "Hello", "Thanks"), which can be pruned safely later.

Information Flow

The following diagram illustrates how an interaction becomes an episode:

Codebase Interaction

• Invocation: Called by MainOrchestrator.process_query → _post_response_hooks.
• Inputs: user_id, session_id, query, response.
• Outputs: episode_id, summary, utility_score.

API Reference

Episodic Memory provides RESTful endpoints for managing temporal interaction events.

SDK Reference

The Functor SDK provides a convenient Python interface for episodic memory operations.

Creating an Episode

from functor_sdk import FunctorClient

client = FunctorClient(api_key="your-api-key")

# Create an episode
episode = client.memory.episodic.create(
    session_id="session_123",
    event_type="query",
    event_data={
        "query": "What is machine learning?",
        "response": "Machine learning is..."
    },
    user_id="user_456",
    entities=["machine_learning", "ai"],
    kg_names=["tech_kg"],
    ttl_days=90
)

print(f"Created episode: {episode['id']}")

Searching Episodes

# Semantic search
results = client.memory.episodic.search(
    query="neural networks discussion",
    session_id="session_123",
    limit=10
)

for episode in results['episodes']:
    print(f"{episode['timestamp']}: {episode['summary']}")

Listing and Filtering

# List episodes with filters
episodes = client.memory.episodic.list(
    session_id="session_123",
    user_id="user_456",
    limit=50,
    offset=0
)

# Get episodes for a specific session
session_episodes = client.memory.episodic.get_by_session(
    session_id="session_123",
    limit=50
)

Updating and Deleting

# Update episode
updated = client.memory.episodic.update(
    episode_id="ep_123",
    event_data={"updated": "data"},
    metadata={"importance": "high"}
)

# Delete episode
client.memory.episodic.delete(episode_id="ep_123")