Skip to main content

Data Models

All TypeScript interfaces used across the Estuary SDK.

Session​

SessionInfo​

Returned by connect() and emitted with the connected event.

interface SessionInfo {
  sessionId: string;        // Unique session identifier
  conversationId: string;   // Persistent conversation ID for this player-character pair
  characterId: string;      // The character (agent) ID
  playerId: string;         // The player identifier
}

Responses​

BotResponse​

Emitted by the botResponse event. Represents a streaming text response from the character.

interface BotResponse {
  text: string;             // Accumulated response text so far
  isFinal: boolean;         // true when the response is complete
  partial: string;          // Text content of just this chunk
  messageId: string;        // Unique message identifier
  chunkIndex: number;       // Sequential chunk index (starts at 0)
  isInterjection: boolean;  // true if proactive (not a reply to user input)
}

BotVoice​

Emitted by the botVoice event. Contains a chunk of voice audio (WebSocket transport) or playback metadata (LiveKit transport).

interface BotVoice {
  audio?: string;           // Base64-encoded PCM audio data. Omitted for LiveKit metadata events.
  messageId: string;        // Message this audio belongs to
  chunkIndex: number;       // Sequential audio chunk index
  isFinal?: boolean;        // true if this is the last audio chunk
  isLivekit?: boolean;      // true when this is a LiveKit metadata event (audio is omitted; the
                            // bytes flow over the WebRTC track instead)
}
info

For the LiveKit transport, bot_voice events arrive as metadata-only (no audio field). The actual audio bytes are streamed as a WebRTC media track and played by the browser directly. Always guard against voice.audio being undefined if you handle this event yourself.

SttResponse​

Emitted by the sttResponse event. Contains speech-to-text transcription.

interface SttResponse {
  text: string;             // Transcribed text
  isFinal: boolean;         // true if this is the final transcription
}

Events​

InterruptData​

Emitted by the interrupt event when a response is interrupted.

interface InterruptData {
  messageId?: string;       // ID of the interrupted message
  reason?: string;          // Reason for interruption
  interruptedAt?: string;   // ISO timestamp of the interruption
}

QuotaExceededData​

Emitted by the quotaExceeded event.

interface QuotaExceededData {
  message: string;          // Human-readable quota message
  current: number;          // Current usage count
  limit: number;            // Usage limit
  remaining: number;        // Remaining quota
  tier: string;             // Account tier
}

CameraCaptureRequest​

Emitted by the cameraCaptureRequest event when the server requests a camera image.

interface CameraCaptureRequest {
  requestId: string;        // ID to include when responding with sendCameraImage()
  text?: string;            // Optional prompt text from the server
}

CharacterAction​

Emitted by the characterAction event. Represents a parsed action tag from a bot response.

interface CharacterAction {
  name: string;                    // Action name (e.g., "navigate", "emote")
  params: Record<string, string>; // All other tag attributes as key-value pairs
  messageId: string;              // Message ID of the bot response that contained this action
}

MemoryUpdatedEvent​

Emitted by the memoryUpdated event when the server extracts memories from a conversation turn. Requires realtimeMemory: true in config.

interface MemoryUpdatedEvent {
  agentId: string;                // Character (agent) ID
  playerId: string;               // Player ID
  memoriesExtracted: number;      // Number of memories extracted this turn
  factsExtracted: number;         // Number of core facts extracted this turn
  conversationId: string;         // Conversation ID
  newMemories: MemoryData[];      // Array of newly extracted memory objects
  timestamp: string;              // ISO timestamp
}

MemoryData​

Individual memory object returned by the memory API and in MemoryUpdatedEvent.newMemories.

interface MemoryData {
  id: string;                     // Unique memory ID
  userId: string;                 // Owning user ID
  agentId: string;                // Character (agent) ID
  playerId: string;               // Player ID
  content: string;                // Memory content text
  memoryType: string;             // Type of memory (e.g., "episodic", "semantic")
  confidence: number;             // Confidence score (0-1)
  status: string;                 // Memory status (e.g., "active")
  sourceConversationId: string;   // Conversation that produced this memory
  sourceQuote?: string;           // Original quote from conversation
  source?: string;                // Origin tag (e.g., extraction source)
  topic?: string;                 // Primary memory topic
  secondaryTopics?: string[];     // Additional topics
  lastAccessedAt?: string | null; // ISO timestamp of last access
  accessCount?: number;           // Number of times this memory was retrieved
  extractedAt?: string | null;    // ISO timestamp of extraction
  createdAt?: string | null;      // ISO timestamp of creation
  updatedAt?: string | null;      // ISO timestamp of last update
}

LiveKitTokenResponse​

Token data used internally by the LiveKit voice manager.

interface LiveKitTokenResponse {
  token: string;            // LiveKit access token
  url: string;              // LiveKit server URL
  room: string;             // Room name
}

Character​

CharacterInfo​

Returned by client.getCharacter().

interface CharacterInfo {
  id: string;
  name: string;
  tagline: string | null;
  avatar: string | null;            // Avatar image URL
  modelUrl: string | null;          // 3D model (e.g., GLB) URL
  modelPreviewUrl: string | null;   // Preview render of the 3D model
  modelStatus: string | null;       // Generation/processing status
  sourceImageUrl: string | null;    // Source image used for generation
}

Sharing​

ShareOpenResponse​

Returned by EstuaryClient.openShare(). Contains everything needed to construct a session-token-authenticated client.

interface ShareOpenResponse {
  sessionToken: string;       // Pass to EstuaryConfig.sessionToken (starts with "sst_")
  characterId: string;        // Pass to EstuaryConfig.characterId
  playerId: string;           // Pass to EstuaryConfig.playerId
  serverUrl: string;          // Pass to EstuaryConfig.serverUrl
  character: CharacterInfo & { personality?: string | null };  // Character details for UI
}

Memory Types​

MemoryListOptions​

Options for client.memory.getMemories().

interface MemoryListOptions {
  memoryType?: string;                                        // Filter by memory type
  status?: string;                                            // Filter by status (e.g., 'active')
  limit?: number;                                             // Max results to return
  offset?: number;                                            // Pagination offset

  /** @deprecated Still accepted, but ignored and no longer sent. */
  sortBy?: 'created_at' | 'confidence' | 'last_accessed_at';
  /** @deprecated Still accepted, but ignored and no longer sent. */
  sortOrder?: 'asc' | 'desc';
}

:::warning sortBy and sortOrder are deprecated Both options are still part of the type, so existing code keeps compiling, but they have no effect: the SDK no longer puts them on the wire, and no memories route ever honored them. Memories come back in the server's default order. Sort client side if you need a specific order. :::

MemoryListResponse​

Response from client.memory.getMemories().

interface MemoryListResponse {
  memories: MemoryData[];               // Array of memory objects
  total: number;                        // Total matching memories
  limit: number;                        // Limit applied
  offset: number;                       // Offset applied
}

MemoryTimelineOptions​

Options for client.memory.getTimeline().

interface MemoryTimelineOptions {
  startDate?: string;               // ISO date string for range start
  endDate?: string;                 // ISO date string for range end
  groupBy?: 'day' | 'week' | 'month'; // Grouping period
}

MemoryTimelineResponse​

Response from client.memory.getTimeline().

interface MemoryTimelineResponse {
  timeline: {
    date: string;
    memories: MemoryData[];
  }[];
  totalMemories: number;            // Total memories across all groups
  groupBy: string;                  // Grouping used
}

MemoryGraphOptions​

Options for client.memory.getGraph().

interface MemoryGraphOptions {
  includeEntities?: boolean;           // Include entity nodes
  includeCharacterMemories?: boolean;  // Include character's own memories
}

MemoryGraphNode​

interface MemoryGraphNode {
  id: string;
  type: 'user' | 'cluster' | 'memory' | 'entity';
  label?: string;

  // Cluster fields
  level?: number;
  memoryCount?: number;
  typeDistribution?: Record<string, number>;
  expanded?: boolean;
  parentClusterId?: string | null;
  childClusterIds?: string[];
  labelPending?: boolean;

  // Memory fields
  memoryType?: string;
  content?: string;
  confidence?: number;
  clusterId?: string;
  sourceQuote?: string | null;
  sourceConversationId?: string | null;
  createdAt?: string | null;
  accessCount?: number;

  // Entity fields
  entityType?: string | null;
  name?: string;
  mentionCount?: number;
  extraData?: Record<string, string>;
}

MemoryGraphEdge​

interface MemoryGraphEdge {
  source: string;                       // Source node id
  target: string;                       // Target node id
  type: 'has_cluster' | 'contains' | 'mentions' | 'relationship';
  relationshipType?: string;
  label?: string | null;
  confidence?: number;
}

MemoryGraphResponse​

Response from client.memory.getGraph().

interface MemoryGraphResponse {
  nodes: MemoryGraphNode[];
  edges: MemoryGraphEdge[];
  stats: {
    totalMemories: number;
    totalEntities: number;
    clusterCount: number;
    clusters: Record<string, number>;   // Memories per cluster id
  };
  stale?: boolean;                      // true if a fresh graph build is in progress
}

MemorySearchOptions​

Options for client.memory.search().

interface MemorySearchOptions {
  query: string;                       // Natural language search query
  limit?: number;                      // Max results
}

MemorySearchResult​

A single hit returned by client.memory.search().

interface MemorySearchResult {
  memoryId: string;                    // ID of the matching memory
  similarity: number;                  // Similarity to the query (higher is closer)
  content: string;                     // The matching memory's content text
}

A hit carries the memory's id and content, not a full MemoryData object. If you need the remaining fields, match memoryId against the results of getMemories().

MemorySearchResponse​

Response from client.memory.search().

interface MemorySearchResponse {
  results: MemorySearchResult[];       // Matching memories, ranked by similarity
  query: string;                       // Original query
  total: number;                       // Total matches
}

:::warning Corrected shape Earlier revisions of this page described each hit as a nested memory object alongside score and similarityScore. The server never returned that shape, and search() could not return results at all before the current release, so no working code could have depended on it. The three fields above are what the API actually returns: see Search Memories in the REST reference. :::

CoreFact​

Individual core-fact object.

interface CoreFact {
  id: string;
  userId: string;
  agentId: string;
  playerId: string;
  factKey: string;                     // Stable key (e.g., "favorite_color")
  factValue: string;                   // Current value (e.g., "blue")
  sourceMemoryId?: string | null;      // Memory this fact was distilled from
  createdAt?: string | null;
  updatedAt?: string | null;
}

CoreFactsResponse​

Response from client.memory.getCoreFacts().

interface CoreFactsResponse {
  coreFacts: CoreFact[];
}

MemoryStatsResponse​

Response from client.memory.getStats().

interface MemoryStatsResponse {
  totalActive: number;                 // Active memories
  totalSuperseded: number;             // Memories replaced by newer info
  totalDecayed: number;                // Memories that have decayed out
  byType: Record<string, number>;      // Active count per memory type
  coreFacts: number;                   // Total core facts
}
Last updated