---
title: Conversation
description: Conversation protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

AI Conversation Memory Protocol

Multi-turn AI conversations with token budget management.

Enables context preservation, conversation history, and token optimization.

<Callout type="info">
**Source:** `packages/spec/src/ai/conversation.zod.ts`
</Callout>

## TypeScript Usage

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


---

