Skip to content

Conversations

The conversation module provides multi-turn chat history persistence for agents. It maintains runtime state (the sequence of user and assistant messages) that is distinct from the tracing module's observability data. The ConversationStore interface supports pluggable backends with in-memory and Firestore implementations.

Import

import {
  // Store interface
  ConversationStore,
  ConversationFilter,
  MessageQueryOptions,

  // Data types
  Conversation,
  ConversationMessage,
  ConversationRole,

  // Implementations
  InMemoryConversationStore,
  FirestoreConversationStore,
} from "@modernpath/agent-framework";

Architecture

graph LR
    UI["Chat UI"] -->|sends message| H[Conversation Handler]
    H -->|loads history| CS{ConversationStore}
    H -->|executes| Agent[BaseAgent]
    H -->|saves messages| CS
    CS -->|dev| IM[InMemoryConversationStore]
    CS -->|prod| FS[FirestoreConversationStore]
    Agent -->|returns result| H

Components

ConversationStore Interface

The abstract interface for persisting conversations and messages. Defines write operations (createConversation, addMessage, updateConversation), read operations (getConversation, getMessages, listConversations), and lifecycle management (deleteConversation).

InMemoryConversationStore

Map-based implementation for tests and local development. Zero external dependencies, with test helper methods.

FirestoreConversationStore

Production-grade Firestore implementation with collection prefixing, automatic Date/Timestamp conversion, and atomic message writes.

Data Model

Type Description Storage
Conversation A chat session with metadata (agent name, title, user) conversations/{conversationId}
ConversationMessage One turn in a conversation (user, assistant, or system) conversations/{conversationId}/messages/{messageId}

When a TraceStore is also used, Conversation.conversationId equals Trace.sessionId, linking chat history to observability data.

Quick Start

import {
  InMemoryConversationStore,
  ConversationMessage,
} from "@modernpath/agent-framework";

const store = new InMemoryConversationStore();

// Create a conversation
await store.createConversation({
  schemaVersion: 1,
  conversationId: "conv-001",
  userId: 1,
  auditingId: 100,
  agentName: "QAChatAgent",
  createdAt: new Date(),
  updatedAt: new Date(),
});

// Add a user message
await store.addMessage("conv-001", {
  schemaVersion: 1,
  messageId: "msg-001",
  conversationId: "conv-001",
  role: "user",
  content: "What is the building temperature?",
  timestamp: new Date(),
});

// Load messages for agent context
const history = await store.getMessages("conv-001", { limit: 50 });