Conversation

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

TypeScript Usage

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);

CodeContent

Properties

Property	Type	Required	Description
type	`'code'`	✅
text	`string`	✅	Code snippet
language	`string`	optional (default: `"text"`)
metadata	`Record<string, any>`	optional

ConversationAnalytics

Properties

Property	Type	Required	Description
sessionId	`string`	✅
totalMessages	`integer`	✅
userMessages	`integer`	✅
assistantMessages	`integer`	✅
systemMessages	`integer`	✅
totalTokens	`integer`	✅
averageTokensPerMessage	`number`	✅
peakTokenUsage	`integer`	✅
pruningEvents	`integer`	optional (default: `0`)
summarizationEvents	`integer`	optional (default: `0`)
tokensSavedByPruning	`integer`	optional (default: `0`)
tokensSavedBySummarization	`integer`	optional (default: `0`)
duration	`number`	optional	Session duration in seconds
firstMessageAt	`string`	optional	ISO 8601 timestamp
lastMessageAt	`string`	optional	ISO 8601 timestamp

ConversationContext

Properties

Property	Type	Required	Description
sessionId	`string`	✅	Conversation session ID
userId	`string`	optional	User identifier
agentId	`string`	optional	AI agent identifier
object	`string`	optional	Related object (e.g., "case", "project")
recordId	`string`	optional	Related record ID
scope	`Record<string, any>`	optional	Additional context scope
systemMessage	`string`	optional	System prompt/instructions
metadata	`Record<string, any>`	optional

ConversationMessage

Properties

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	`string`	optional	Tool call ID this message responds to
name	`string`	optional	Name of the function/user
tokens	`{ promptTokens: integer; completionTokens: integer; totalTokens: integer }`	optional	Token usage for this message
cost	`number`	optional	Cost for this message in USD
pinned	`boolean`	optional (default: `false`)	Prevent removal during pruning
importance	`number`	optional	Importance score for pruning
embedding	`number[]`	optional	Vector embedding for semantic search
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationMessage.content[number][type='text']`

Property	Type	Required	Description
type	`'text'`	✅
text	`string`	✅	Text content
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationMessage.content[number][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

Nested Shape: `ConversationMessage.content[number][type='file']`

Property	Type	Required	Description
type	`'file'`	✅
fileUrl	`string`	✅	File attachment URL
mimeType	`string`	✅	MIME type
fileName	`string`	optional
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationMessage.content[number][type='code']`

Property	Type	Required	Description
type	`'code'`	✅
text	`string`	✅	Code snippet
language	`string`	optional (default: `"text"`)
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationMessage.functionCall`

Property	Type	Required	Description
name	`string`	✅	Function name
arguments	`string`	✅	JSON string of function arguments
result	`string`	optional	Function execution result

Nested Shape: `ConversationMessage.toolCalls[number]`

Property	Type	Required	Description
id	`string`	✅	Tool call ID
type	`Enum<'function'>`	optional (default: `"function"`)
function	`{ name: string; arguments: string; result?: string }`	✅

Nested Shape: `ConversationMessage.tokens`

Property	Type	Required	Description
promptTokens	`integer`	✅	Tokens consumed by the prompt
completionTokens	`integer`	✅	Tokens generated in the completion
totalTokens	`integer`	✅	Total tokens (prompt + completion)

ConversationSession

Properties

Property	Type	Required	Description
id	`string`	✅	Unique session ID
name	`string`	optional	Session name/title
context	`{ sessionId: string; userId?: string; agentId?: string; object?: string; … }`	✅
modelId	`string`	optional	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	`number`	optional	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	`string`	optional	ISO 8601 timestamp
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationSession.context`

Property	Type	Required	Description
sessionId	`string`	✅	Conversation session ID
userId	`string`	optional	User identifier
agentId	`string`	optional	AI agent identifier
object	`string`	optional	Related object (e.g., "case", "project")
recordId	`string`	optional	Related record ID
scope	`Record<string, any>`	optional	Additional context scope
systemMessage	`string`	optional	System prompt/instructions
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationSession.tokenBudget`

Property	Type	Required	Description
maxTokens	`integer`	✅	Maximum total tokens
maxPromptTokens	`integer`	optional	Max tokens for prompt
maxCompletionTokens	`integer`	optional	Max tokens for completion
reserveTokens	`integer`	optional (default: `500`)	Reserve tokens for system messages
bufferPercentage	`number`	optional (default: `0.1`)	Buffer percentage (0.1 = 10%)
strategy	`Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>`	optional (default: `"sliding_window"`)
slidingWindowSize	`integer`	optional	Number of recent messages to keep
minImportanceScore	`number`	optional	Minimum importance to keep
semanticThreshold	`number`	optional	Semantic similarity threshold
enableSummarization	`boolean`	optional (default: `false`)	Enable context summarization
summarizationThreshold	`integer`	optional	Trigger summarization at N tokens
summaryModel	`string`	optional	Model ID for summarization
warnThreshold	`number`	optional (default: `0.8`)	Warn at % of budget (0.8 = 80%)

Nested Shape: `ConversationSession.messages[number]`

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	`string`	optional	Tool call ID this message responds to
name	`string`	optional	Name of the function/user
tokens	`{ promptTokens: integer; completionTokens: integer; totalTokens: integer }`	optional	Token usage for this message
cost	`number`	optional	Cost for this message in USD
pinned	`boolean`	optional (default: `false`)	Prevent removal during pruning
importance	`number`	optional	Importance score for pruning
embedding	`number[]`	optional	Vector embedding for semantic search
metadata	`Record<string, any>`	optional

Nested Shape: `ConversationSession.tokens`

Property	Type	Required	Description
promptTokens	`integer`	optional (default: `0`)
completionTokens	`integer`	optional (default: `0`)
totalTokens	`integer`	optional (default: `0`)
budgetLimit	`integer`	✅
budgetUsed	`integer`	optional (default: `0`)
budgetRemaining	`integer`	✅
budgetPercentage	`number`	✅	Usage as percentage of budget
messageCount	`integer`	optional (default: `0`)
prunedMessageCount	`integer`	optional (default: `0`)
summarizedMessageCount	`integer`	optional (default: `0`)

Nested Shape: `ConversationSession.totalTokens`

Property	Type	Required	Description
promptTokens	`integer`	✅	Tokens consumed by the prompt
completionTokens	`integer`	✅	Tokens generated in the completion
totalTokens	`integer`	✅	Total tokens (prompt + completion)

ConversationSummary

Properties

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	`string`	optional	Model used for summarization

FileContent

Properties

Property	Type	Required	Description
type	`'file'`	✅
fileUrl	`string`	✅	File attachment URL
mimeType	`string`	✅	MIME type
fileName	`string`	optional
metadata	`Record<string, any>`	optional

FunctionCall

Properties

Property	Type	Required	Description
name	`string`	✅	Function name
arguments	`string`	✅	JSON string of function arguments
result	`string`	optional	Function execution result

ImageContent

Properties

Property	Type	Required	Description
type	`'image'`	✅
imageUrl	`string`	✅	Image URL
detail	`Enum<'low' \| 'high' \| 'auto'>`	optional (default: `"auto"`)
metadata	`Record<string, any>`	optional

MessageContent

Union Options

This schema accepts one of the following structures:

Option 1

Type: text

Properties

Property	Type	Required	Description
type	`'text'`	✅
text	`string`	✅	Text content
metadata	`Record<string, any>`	optional

Option 2

Type: image

Properties

Property	Type	Required	Description
type	`'image'`	✅
imageUrl	`string`	✅	Image URL
detail	`Enum<'low' \| 'high' \| 'auto'>`	optional (default: `"auto"`)
metadata	`Record<string, any>`	optional

Option 3

Type: file

Properties

Property	Type	Required	Description
type	`'file'`	✅
fileUrl	`string`	✅	File attachment URL
mimeType	`string`	✅	MIME type
fileName	`string`	optional
metadata	`Record<string, any>`	optional

Option 4

Type: code

Properties

Property	Type	Required	Description
type	`'code'`	✅
text	`string`	✅	Code snippet
language	`string`	optional (default: `"text"`)
metadata	`Record<string, any>`	optional

MessageContentType

Allowed Values

text
image
file
code
structured

MessagePruningEvent

Properties

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`	✅

MessageRole

Allowed Values

system
user
assistant
function
tool

TextContent

Properties

Property	Type	Required	Description
type	`'text'`	✅
text	`string`	✅	Text content
metadata	`Record<string, any>`	optional

TokenBudgetConfig

Properties

Property	Type	Required	Description
maxTokens	`integer`	✅	Maximum total tokens
maxPromptTokens	`integer`	optional	Max tokens for prompt
maxCompletionTokens	`integer`	optional	Max tokens for completion
reserveTokens	`integer`	optional (default: `500`)	Reserve tokens for system messages
bufferPercentage	`number`	optional (default: `0.1`)	Buffer percentage (0.1 = 10%)
strategy	`Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>`	optional (default: `"sliding_window"`)
slidingWindowSize	`integer`	optional	Number of recent messages to keep
minImportanceScore	`number`	optional	Minimum importance to keep
semanticThreshold	`number`	optional	Semantic similarity threshold
enableSummarization	`boolean`	optional (default: `false`)	Enable context summarization
summarizationThreshold	`integer`	optional	Trigger summarization at N tokens
summaryModel	`string`	optional	Model ID for summarization
warnThreshold	`number`	optional (default: `0.8`)	Warn at % of budget (0.8 = 80%)

TokenBudgetStrategy

Allowed Values

fifo
importance
semantic
sliding_window
summary

TokenUsageStats

Properties

Property	Type	Required	Description
promptTokens	`integer`	optional (default: `0`)
completionTokens	`integer`	optional (default: `0`)
totalTokens	`integer`	optional (default: `0`)
budgetLimit	`integer`	✅
budgetUsed	`integer`	optional (default: `0`)
budgetRemaining	`integer`	✅
budgetPercentage	`number`	✅	Usage as percentage of budget
messageCount	`integer`	optional (default: `0`)
prunedMessageCount	`integer`	optional (default: `0`)
summarizedMessageCount	`integer`	optional (default: `0`)

ToolCall

Properties

Property	Type	Required	Description
id	`string`	✅	Tool call ID
type	`Enum<'function'>`	optional (default: `"function"`)
function	`{ name: string; arguments: string; result?: string }`	✅

Nested Shape: `ToolCall.function`

Property	Type	Required	Description
name	`string`	✅	Function name
arguments	`string`	✅	JSON string of function arguments
result	`string`	optional	Function execution result

Conversation

On this page