# $comment
Licensed under the Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0

# title
Portable AI Memory — Normalized Conversation Format

# description
Normalized conversation format for provider-agnostic storage. This is the target format for all provider importers. Raw provider exports (OpenAI, Anthropic, Google, Microsoft, xAI) are parsed and normalized into this format. Conversations stored in this format are referenced by conversations_index in the main memory-store. This format preserves the full message graph including branching (DAG) from providers like OpenAI.

# properties.schema_version.description
Schema version. MUST match the memory-store schema version.

# properties.id.description
Unique conversation identifier. SHOULD be UUID v4. This is the id referenced by conversations_index.

# properties.provider.description
Source provider information and original identifiers.

# properties.title.description
Human-readable conversation title. Extracted from provider export.

# properties.participants.description
Participants in the conversation. Typically user + assistant, but may include system, tool, etc.

# properties.messages.description
Array of normalized messages. For linear conversations, messages are in chronological order. For branching conversations (e.g., OpenAI), use parent_id and children_ids to reconstruct the DAG.

# properties.model.description
Primary model used in the conversation. May change per-message (see message.model).

# properties.system_instruction.description
System prompt or instruction active for this conversation. Extracted from provider when available.

# properties.is_archived.description
Whether this conversation was archived by the user in the source platform.

# properties.tags.description
Tags or topics associated with this conversation.

# properties.raw_metadata.description
Provider-specific conversation-level metadata preserved verbatim. Use for fields like starred, system_prompt_name, or other provider attributes that don't map to PAM fields. Not interpreted by PAM but available for provider-specific reconstruction.

# $defs.ProviderInfo.description
Source provider information. Preserves original identifiers for traceability.

# $defs.ProviderInfo.properties.name.description
Provider identifier. MUST use the same namespace as provenance.platform in the main memory-store schema (Section 11.4). Use product names (chatgpt, claude, gemini, copilot), not company names (openai, anthropic, google, microsoft).

# $defs.ProviderInfo.properties.conversation_id.description
Original conversation ID from the provider export.

# $defs.ProviderInfo.properties.account_id.description
User account ID on the provider platform.

# $defs.ProviderInfo.properties.export_format_version.description
Version or date identifier of the provider export format. Used to select the correct parser.

# $defs.Message.description
A single normalized message. Content may be text, multipart, or empty (for tool calls). For branching conversations, parent_id and children_ids reconstruct the full DAG.

# $defs.Message.properties.id.description
Unique message ID within this conversation. SHOULD be UUID v4.

# $defs.Message.properties.provider_message_id.description
Original message ID from the provider export.

# $defs.Message.properties.role.description
Normalized role. Provider-specific values mapped: human→user, Request→user, AI→assistant, ASSISTANT→assistant. See importer-mappings.md section 6 for full table.

# $defs.Message.properties.content.description
Message content. May be simple text or multipart.

# $defs.Message.properties.created_at.description
Message timestamp. Converted from provider format (Unix epoch for OpenAI, ISO for others).

# $defs.Message.properties.parent_id.description
ID of the parent message in the conversation graph. Enables DAG reconstruction for branching conversations (OpenAI). null for root messages.

# $defs.Message.properties.children_ids.description
IDs of child messages. Multiple children indicate conversation branching.

# $defs.Message.properties.model.description
Specific model that generated this message (for assistant messages).

# $defs.Message.properties.is_thought.description
Whether this is an internal thinking/reasoning step (Gemini isThought, Claude extended thinking). Not part of the visible conversation.

# $defs.Message.properties.token_count.description
Token count for this message if available from provider.

# $defs.Message.properties.attachments.description
Files, images, or other attachments on this message.

# $defs.Message.properties.citations.description
Citations or sources referenced by this message.

# $defs.Message.properties.tool_calls.description
Tool/function calls made by the assistant in this message.

# $defs.Message.properties.raw_metadata.description
Provider-specific metadata preserved verbatim. Not interpreted by PAM but available for provider-specific reconstruction.

# $defs.MessageContent.description
Normalized message content. Supports both simple text and multipart content.

# $defs.MessageContent.properties.type.description
'text': simple text content in the text field. 'multipart': array of content parts.

# $defs.MessageContent.properties.text.description
Simple text content. Used when type is 'text'.

# $defs.MessageContent.properties.parts.description
Multipart content. Used when type is 'multipart'.

# $defs.ContentPart.properties.ref.description
Reference to external file (path, URL, or storage ref).

# $defs.Citation.description
A citation or source referenced by a message.

# $defs.ToolCall.description
A tool or function call made by the assistant.

# $defs.ImportMetadata.description
Metadata about the import process. Enables debugging and re-import.

# $defs.ImportMetadata.properties.importer_version.description
Specific importer module version for this provider.

# $defs.ImportMetadata.properties.source_file.description
Original source file path or identifier.

# $defs.ImportMetadata.properties.source_checksum.description
SHA-256 of the original source file for integrity verification.