Conversation schema — AI Protocol reference Multi-turn AI conversations with token budget management. Enables context preservation, conversation history, and token optimization.
AI Conversation Memory Protocol
Multi-turn AI conversations with token budget management.
Enables context preservation, conversation history, and token optimization.
Source: packages/spec/src/ai/conversation.zod.ts
import { CodeContentSchema, ConversationAnalyticsSchema, ConversationContextSchema, ConversationMessageSchema, ConversationSessionSchema, ConversationSummarySchema, FileContentSchema, FunctionCallSchema, ImageContentSchema, MessageContentSchema, MessageContentTypeSchema, MessagePruningEventSchema, MessageRoleSchema, TextContentSchema, TokenBudgetConfigSchema, TokenBudgetStrategySchema, TokenUsageStatsSchema, ToolCallSchema } from '@objectstack/spec/ai' ; import type { ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai' ; // Validate data const result = CodeContentSchema. parse (data); Property Type Required Description type 'code'✅ text string✅ Code snippet language stringoptional (default: "text") metadata Record<string, any>optional
Property Type Required Description sessionId string✅ totalMessages integer✅ userMessages integer✅ assistantMessages integer✅ systemMessages integer✅ totalTokens integer✅ averageTokensPerMessage number✅ peakTokenUsage integer✅ pruningEvents integeroptional (default: 0) summarizationEvents integeroptional (default: 0) tokensSavedByPruning integeroptional (default: 0) tokensSavedBySummarization integeroptional (default: 0) durationSeconds numberoptional Session duration in seconds duration neveroptional [REMOVED] ConversationAnalytics.duration was renamed to durationSeconds in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to durationSeconds; the value (seconds) is unchanged. firstMessageAt stringoptional ISO 8601 timestamp lastMessageAt stringoptional ISO 8601 timestamp
Property Type Required Description sessionId string✅ Conversation session ID userId stringoptional User identifier agentId stringoptional AI agent identifier object stringoptional Related object (e.g., "case", "project") recordId stringoptional Related record ID scope Record<string, any>optional Additional context scope systemMessage stringoptional System prompt/instructions metadata Record<string, any>optional
Property Type Required Description id string✅ Unique message ID timestamp string✅ ISO 8601 timestamp role Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>✅ content ({ type: 'text'; text: string; metadata?: Record<string, any> } | { type: 'image'; imageUrl: string; detail?: Enum<'low' | 'high' | 'auto'>; metadata?: Record<string, any> } | { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } | { type: 'code'; text: string; language?: string; metadata?: Record<string, any> })[]✅ Message content (multimodal array) functionCall { name: string; arguments: string; result?: string }optional Legacy function call toolCalls { id: string; type?: Enum<'function'>; function: object }[]optional Tool calls toolCallId stringoptional Tool call ID this message responds to name stringoptional Name of the function/user tokens { promptTokens: integer; completionTokens: integer; totalTokens: integer }optional Token usage for this message cost numberoptional Cost for this message in USD pinned booleanoptional (default: false) Prevent removal during pruning importance numberoptional Importance score for pruning embedding number[]optional Vector embedding for semantic search metadata Record<string, any>optional
Property Type Required Description type 'text'✅ text string✅ Text content metadata Record<string, any>optional
Property Type Required Description type 'image'✅ imageUrl string✅ Image URL detail Enum<'low' | 'high' | 'auto'>optional (default: "auto") metadata Record<string, any>optional
Property Type Required Description type 'file'✅ fileUrl string✅ File attachment URL mimeType string✅ MIME type fileName stringoptional metadata Record<string, any>optional
Property Type Required Description type 'code'✅ text string✅ Code snippet language stringoptional (default: "text") metadata Record<string, any>optional
Property Type Required Description name string✅ Function name arguments string✅ JSON string of function arguments result stringoptional Function execution result
Property Type Required Description id string✅ Tool call ID type Enum<'function'>optional (default: "function") function { name: string; arguments: string; result?: string }✅
Property Type Required Description promptTokens integer✅ Tokens consumed by the prompt completionTokens integer✅ Tokens generated in the completion totalTokens integer✅ Total tokens (prompt + completion)
Property Type Required Description id string✅ Unique session ID name stringoptional Session name/title context { sessionId: string; userId?: string; agentId?: string; object?: string; … }✅ modelId stringoptional AI model ID tokenBudget { maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens?: integer; … }✅ messages { id: string; timestamp: string; role: Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>; content: (object | … +3 more)[]; … }[]optional (default: []) tokens { promptTokens?: integer; completionTokens?: integer; totalTokens?: integer; budgetLimit: integer; … }optional totalTokens { promptTokens: integer; completionTokens: integer; totalTokens: integer }optional Total tokens across all messages totalCost numberoptional Total cost for this session in USD status Enum<'active' | 'paused' | 'completed' | 'archived'>optional (default: "active") createdAt string✅ ISO 8601 timestamp updatedAt string✅ ISO 8601 timestamp expiresAt stringoptional ISO 8601 timestamp metadata Record<string, any>optional
Property Type Required Description sessionId string✅ Conversation session ID userId stringoptional User identifier agentId stringoptional AI agent identifier object stringoptional Related object (e.g., "case", "project") recordId stringoptional Related record ID scope Record<string, any>optional Additional context scope systemMessage stringoptional System prompt/instructions metadata Record<string, any>optional
Property Type Required Description maxTokens integer✅ Maximum total tokens maxPromptTokens integeroptional Max tokens for prompt maxCompletionTokens integeroptional Max tokens for completion reserveTokens integeroptional (default: 500) Reserve tokens for system messages bufferPercentage numberoptional (default: 0.1) Buffer percentage (0.1 = 10%) strategy Enum<'fifo' | 'importance' | 'semantic' | 'sliding_window' | 'summary'>optional (default: "sliding_window") slidingWindowSize integeroptional Number of recent messages to keep minImportanceScore numberoptional Minimum importance to keep semanticThreshold numberoptional Semantic similarity threshold enableSummarization booleanoptional (default: false) Enable context summarization summarizationThreshold integeroptional Trigger summarization at N tokens summaryModel stringoptional Model ID for summarization warnThreshold numberoptional (default: 0.8) Warn at % of budget (0.8 = 80%)
Property Type Required Description id string✅ Unique message ID timestamp string✅ ISO 8601 timestamp role Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>✅ content ({ type: 'text'; text: string; metadata?: Record<string, any> } | { type: 'image'; imageUrl: string; detail?: Enum<'low' | 'high' | 'auto'>; metadata?: Record<string, any> } | { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } | { type: 'code'; text: string; language?: string; metadata?: Record<string, any> })[]✅ Message content (multimodal array) functionCall { name: string; arguments: string; result?: string }optional Legacy function call toolCalls { id: string; type?: Enum<'function'>; function: object }[]optional Tool calls toolCallId stringoptional Tool call ID this message responds to name stringoptional Name of the function/user tokens { promptTokens: integer; completionTokens: integer; totalTokens: integer }optional Token usage for this message cost numberoptional Cost for this message in USD pinned booleanoptional (default: false) Prevent removal during pruning importance numberoptional Importance score for pruning embedding number[]optional Vector embedding for semantic search metadata Record<string, any>optional
Property Type Required Description promptTokens integeroptional (default: 0) completionTokens integeroptional (default: 0) totalTokens integeroptional (default: 0) budgetLimit integer✅ budgetUsed integeroptional (default: 0) budgetRemaining integer✅ budgetPercentage number✅ Usage as percentage of budget messageCount integeroptional (default: 0) prunedMessageCount integeroptional (default: 0) summarizedMessageCount integeroptional (default: 0)
Property Type Required Description promptTokens integer✅ Tokens consumed by the prompt completionTokens integer✅ Tokens generated in the completion totalTokens integer✅ Total tokens (prompt + completion)
Property Type Required Description summary string✅ Conversation summary keyPoints string[]optional Key discussion points originalTokens integer✅ Original token count summaryTokens integer✅ Summary token count tokensSaved integer✅ Tokens saved messageRange { startIndex: integer; endIndex: integer }✅ Range of messages summarized generatedAt string✅ ISO 8601 timestamp modelId stringoptional Model used for summarization
Property Type Required Description type 'file'✅ fileUrl string✅ File attachment URL mimeType string✅ MIME type fileName stringoptional metadata Record<string, any>optional
Property Type Required Description name string✅ Function name arguments string✅ JSON string of function arguments result stringoptional Function execution result
Property Type Required Description type 'image'✅ imageUrl string✅ Image URL detail Enum<'low' | 'high' | 'auto'>optional (default: "auto") metadata Record<string, any>optional
This schema accepts one of the following structures:
Type: text
Property Type Required Description type 'text'✅ text string✅ Text content metadata Record<string, any>optional
Type: image
Property Type Required Description type 'image'✅ imageUrl string✅ Image URL detail Enum<'low' | 'high' | 'auto'>optional (default: "auto") metadata Record<string, any>optional
Type: file
Property Type Required Description type 'file'✅ fileUrl string✅ File attachment URL mimeType string✅ MIME type fileName stringoptional metadata Record<string, any>optional
Type: code
Property Type Required Description type 'code'✅ text string✅ Code snippet language stringoptional (default: "text") metadata Record<string, any>optional
textimagefilecodestructured
Property Type Required Description timestamp string✅ Event timestamp prunedMessages { messageId: string; role: Enum<'system' | 'user' | 'assistant' | 'function' | 'tool'>; tokens: integer; importance?: number }[]✅ tokensFreed integer✅ messagesRemoved integer✅ remainingTokens integer✅ remainingMessages integer✅
systemuserassistantfunctiontool
Property Type Required Description type 'text'✅ text string✅ Text content metadata Record<string, any>optional
Property Type Required Description maxTokens integer✅ Maximum total tokens maxPromptTokens integeroptional Max tokens for prompt maxCompletionTokens integeroptional Max tokens for completion reserveTokens integeroptional (default: 500) Reserve tokens for system messages bufferPercentage numberoptional (default: 0.1) Buffer percentage (0.1 = 10%) strategy Enum<'fifo' | 'importance' | 'semantic' | 'sliding_window' | 'summary'>optional (default: "sliding_window") slidingWindowSize integeroptional Number of recent messages to keep minImportanceScore numberoptional Minimum importance to keep semanticThreshold numberoptional Semantic similarity threshold enableSummarization booleanoptional (default: false) Enable context summarization summarizationThreshold integeroptional Trigger summarization at N tokens summaryModel stringoptional Model ID for summarization warnThreshold numberoptional (default: 0.8) Warn at % of budget (0.8 = 80%)
fifoimportancesemanticsliding_windowsummary
Property Type Required Description promptTokens integeroptional (default: 0) completionTokens integeroptional (default: 0) totalTokens integeroptional (default: 0) budgetLimit integer✅ budgetUsed integeroptional (default: 0) budgetRemaining integer✅ budgetPercentage number✅ Usage as percentage of budget messageCount integeroptional (default: 0) prunedMessageCount integeroptional (default: 0) summarizedMessageCount integeroptional (default: 0)
Property Type Required Description id string✅ Tool call ID type Enum<'function'>optional (default: "function") function { name: string; arguments: string; result?: string }✅
Property Type Required Description name string✅ Function name arguments string✅ JSON string of function arguments result stringoptional Function execution result
ObjectStack