Overview

The Chat Database uses Qdrant, a vector database, to store chat history items with semantic search capabilities. This enables efficient retrieval of conversation history and supports AI agent orchestration by maintaining context across chat sessions.

Architecture

Vector Storage Implementation

The database is accessed through VectorChatMessageStore, which implements the ChatMessageStore interface from Microsoft.Agents.AI. This provides:

• Vector Collections: Chat messages are stored in vector collections using VectorStoreCollection<Guid, ChatHistoryItem>
• Thread-based Organization: Messages are grouped by ThreadId for conversation continuity
• User Isolation: Messages are filtered by UserId to ensure data privacy
• Temporal Ordering: Messages are stored with timestamps for chronological retrieval

Data Model

Messages are stored as ChatHistoryItem records with the following structure:

{
    Key: string,              // ThreadDbKey + MessageId (unique identifier)
    ThreadId: string,         // Conversation thread identifier (UUIDv7)
    Timestamp: DateTimeOffset, // Message creation time
    SerializedMessage: string, // Full ChatMessage JSON
    MessageText: string,      // Extracted message text for search
    UserId: string           // User who sent the message
}

Key Features

1. Thread Management

• Each conversation thread is identified by a UUIDv7-based ThreadDbKey
• Thread keys are generated on first message and maintained throughout the session
• Enables concurrent conversations without interference

2. Message Retrieval

• Retrieves up to MaxMessages per query (configurable via AppSettings)
• Messages are ordered by timestamp in descending order
• Results are reversed to maintain chronological order
• Filters by both thread ID and user ID for security

3. Message Persistence

• Uses upsert operations for idempotent writes
• Serializes full ChatMessage objects with JSON source generation
• Maintains metadata (timestamp, user ID) for filtering and analytics
• Extracts message text for semantic search capabilities

4. State Serialization

• Thread state can be serialized to JSON for session management
• Enables conversation resumption across sessions
• Supports state hydration from serialized JSON elements

Technical Details

Vector Store Configuration

• Collection Type: VectorStoreCollection<Guid, ChatHistoryItem>
• Key Type: Guid (for collection operations)
• Record Type: ChatHistoryItem with vector data attributes

Query Operations

// Retrieval query structure
x => x.ThreadId == ThreadDbKey && x.UserId == userId
// Ordering
OrderBy: x => x.Descending(y => y.Timestamp)
// Limit
MaxMessages (from AppSettings)

Serialization

• Uses JsonSerializerOptions with camelCase naming policy
• Source-generated serialization context for performance
• Property name case-insensitive deserialization

Security

• User Isolation: All queries filter by authenticated user ID from ClaimsPrincipal
• Thread Isolation: Messages are scoped to specific conversation threads
• Access Control: Read/write access controlled through authentication claims

Performance Considerations

• Batch Operations: Uses UpsertAsync for efficient bulk writes
• Query Limits: Configurable MaxMessages prevents over-fetching
• Async Operations: All database operations are asynchronous
• Collection Caching: Ensures collection exists before operations

Integration

The vector store integrates with:

• Microsoft.Agents.AI: Implements ChatMessageStore interface
• Microsoft.Extensions.VectorData: Uses vector data attributes and collections
• ASP.NET Core Authentication: Leverages ClaimsPrincipal for user context
• Qdrant: Underlying vector database engine