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 { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';
import type { CodeContent, ConversationAnalytics, ConversationContext, ConversationMessage, ConversationSession, ConversationSummary, FileContent, FunctionCall, ImageContent, MessageContent, MessageContentType, MessagePruningEvent, MessageRole, TextContent, TokenBudgetConfig, TokenBudgetStrategy, TokenUsageStats, ToolCall } from '@objectstack/spec/ai';

// Validate data
const result = CodeContent.parse(data);

CodeContent

Properties

Property	Type	Required	Description
type	`string`	✅
text	`string`	✅	Code snippet
language	`string`	✅
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`	✅
summarizationEvents	`integer`	✅
tokensSavedByPruning	`integer`	✅
tokensSavedBySummarization	`integer`	✅
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	`Object \| Object \| Object \| Object[]`	✅	Message content (multimodal array)
functionCall	`Object`	optional	Legacy function call
toolCalls	`Object[]`	optional	Tool calls
toolCallId	`string`	optional	Tool call ID this message responds to
name	`string`	optional	Name of the function/user
tokens	`Object`	optional	Token usage for this message
cost	`number`	optional	Cost for this message in USD
pinned	`boolean`	✅	Prevent removal during pruning
importance	`number`	optional	Importance score for pruning
embedding	`number[]`	optional	Vector embedding for semantic search
metadata	`Record<string, any>`	optional

ConversationSession

Properties

Property	Type	Required	Description
id	`string`	✅	Unique session ID
name	`string`	optional	Session name/title
context	`Object`	✅
modelId	`string`	optional	AI model ID
tokenBudget	`Object`	✅
messages	`Object[]`	✅
tokens	`Object`	optional
totalTokens	`Object`	optional	Total tokens across all messages
totalCost	`number`	optional	Total cost for this session in USD
status	`Enum<'active' \| 'paused' \| 'completed' \| 'archived'>`	✅
createdAt	`string`	✅	ISO 8601 timestamp
updatedAt	`string`	✅	ISO 8601 timestamp
expiresAt	`string`	optional	ISO 8601 timestamp
metadata	`Record<string, any>`	optional

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	`Object`	✅	Range of messages summarized
generatedAt	`string`	✅	ISO 8601 timestamp
modelId	`string`	optional	Model used for summarization

FileContent

Properties

Property	Type	Required	Description
type	`string`	✅
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	`string`	✅
imageUrl	`string`	✅	Image URL
detail	`Enum<'low' \| 'high' \| '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	`string`	✅
text	`string`	✅	Text content
metadata	`Record<string, any>`	optional

Option 2

Type: image

Properties

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

Option 3

Type: file

Properties

Property	Type	Required	Description
type	`string`	✅
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	`string`	✅
text	`string`	✅	Code snippet
language	`string`	✅
metadata	`Record<string, any>`	optional

MessageContentType

Allowed Values

text
image
file
code
structured

MessagePruningEvent

Properties

Property	Type	Required	Description
timestamp	`string`	✅	Event timestamp
prunedMessages	`Object[]`	✅
tokensFreed	`integer`	✅
messagesRemoved	`integer`	✅
remainingTokens	`integer`	✅
remainingMessages	`integer`	✅

MessageRole

Allowed Values

system
user
assistant
function
tool

TextContent

Properties

Property	Type	Required	Description
type	`string`	✅
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`	✅	Reserve tokens for system messages
bufferPercentage	`number`	✅	Buffer percentage (0.1 = 10%)
strategy	`Enum<'fifo' \| 'importance' \| 'semantic' \| 'sliding_window' \| 'summary'>`	✅
slidingWindowSize	`integer`	optional	Number of recent messages to keep
minImportanceScore	`number`	optional	Minimum importance to keep
semanticThreshold	`number`	optional	Semantic similarity threshold
enableSummarization	`boolean`	✅	Enable context summarization
summarizationThreshold	`integer`	optional	Trigger summarization at N tokens
summaryModel	`string`	optional	Model ID for summarization
warnThreshold	`number`	✅	Warn at % of budget (0.8 = 80%)

TokenBudgetStrategy

Allowed Values

fifo
importance
semantic
sliding_window
summary

TokenUsageStats

Properties

Property	Type	Required	Description
promptTokens	`integer`	✅
completionTokens	`integer`	✅
totalTokens	`integer`	✅
budgetLimit	`integer`	✅
budgetUsed	`integer`	✅
budgetRemaining	`integer`	✅
budgetPercentage	`number`	✅	Usage as percentage of budget
messageCount	`integer`	✅
prunedMessageCount	`integer`	✅
summarizedMessageCount	`integer`	✅

ToolCall

Properties

Property	Type	Required	Description
id	`string`	✅	Tool call ID
type	`Enum<'function'>`	✅
function	`Object`	✅

On this page