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

# description
Universal interchange format for AI user memories. Enables portability of user context, preferences, knowledge, and conversation history across any LLM provider (OpenAI, Anthropic, Google, etc.) without vendor lock-in. This is an INTERCHANGE format, NOT a storage format. Implementations SHOULD use databases internally and MUST support export/import using this format. Embeddings are OPTIONAL and MAY be omitted entirely. When omitted, embedding_ref MUST be null. Consumers MUST NOT fail if embeddings are missing and SHOULD regenerate embeddings from content when needed.

# properties.schema.description
Schema identifier. MUST be 'portable-ai-memory'.

# properties.schema_version.description
Semantic version of the schema. Current: '1.0'.

# properties.spec_uri.description
URI or URN of the specification version this export conforms to. Implementations MUST NOT require spec_uri to resolve over network. It serves as a version identifier, not a fetchable resource.

# properties.export_id.description
Unique identifier for this specific export. SHOULD be UUID v4. Enables export tracking, duplicate import detection, and auditability.

# properties.exported_by.description
Identifier of the system that generated this export. Format: 'system-name/semver'.

# properties.export_date.description
ISO 8601 timestamp of when this export was generated.

# properties.memories.description
Array of memory objects. This is the primary payload of the interchange format.

# properties.relations.description
Semantic relationships between memory objects, forming a knowledge graph.

# properties.conversations_index.description
Lightweight index of conversations. Does NOT contain full message history. Full conversations are stored externally and referenced via storage.ref. Exporters MUST ensure consistency between memory.provenance.conversation_ref and conversation.derived_memories. Importers SHOULD treat derived_memories as advisory and MAY reconstruct from provenance.

# properties.integrity.description
Integrity verification block for the export.

# properties.export_type.description
Export type. 'full': complete memory store. 'incremental': delta since a previous export. When 'incremental', base_export_id and since SHOULD be provided.

# properties.base_export_id.description
For incremental exports: the export_id of the base export this delta applies to. SHOULD be provided when export_type is 'incremental'.

# properties.since.description
For incremental exports: only memories created or updated after this timestamp are included. SHOULD be provided when export_type is 'incremental'.

# properties.type_registry.description
URI of the official type registry for custom memory types. Enables discovery and standardization of community-defined types. Default registry: https://portable-ai-memory.org/types/

# properties.signature.description
Cryptographic signature for authenticity and tamper detection. OPTIONAL but RECOMMENDED for exports shared between systems.

# $defs.Owner.description
The individual who owns these memories. Memories are owned by a single person. For cross-platform identity resolution, the did field SHOULD be populated with a W3C Decentralized Identifier.

# $defs.Owner.properties.id.description
Unique identifier for the owner. MUST be a UUID v4 or a stable unique identifier that persists across exports. This ensures consistent identity resolution when merging exports from different sources.

# $defs.Owner.properties.did.description
W3C Decentralized Identifier (DID) for universal cross-platform identity. Supports any DID method including did:key, did:web, did:ion, did:pkh. See https://www.w3.org/TR/did-core/

# $defs.Owner.properties.created_at.description
Timestamp when the owner record was first created.

# $defs.MemoryObject.description
A single portable memory unit. Represents a fact, preference, skill, or other piece of knowledge about the user.

# $defs.MemoryObject.properties.id.description
Unique identifier for this memory. SHOULD be a UUID v4.

# $defs.MemoryObject.properties.type.description
Category of this memory. Determines how consumers should interpret the content.

# $defs.MemoryObject.properties.custom_type.description
Custom type identifier. REQUIRED when type is 'custom', MUST be null otherwise.

# $defs.MemoryObject.properties.content.description
The actual memory content in natural language. This is the primary semantic payload.

# $defs.MemoryObject.properties.content_hash.description
SHA-256 hash of normalized content for deduplication. Normalization: trim whitespace, lowercase, normalize unicode (NFC), collapse multiple spaces. Format: 'sha256:<hex>'.

# $defs.MemoryObject.properties.summary.description
Optional short summary of the memory content. Useful for display and quick scanning.

# $defs.MemoryObject.properties.tags.description
Lowercase tags for categorization and filtering. Pattern: alphanumeric with hyphens and underscores.

# $defs.MemoryObject.properties.confidence.description
Confidence scoring with temporal decay support.

# $defs.MemoryObject.properties.temporal.description
All time-related properties for this memory.

# $defs.MemoryObject.properties.provenance.description
Origin and extraction metadata. Enables auditability and conflict resolution across platforms.

# $defs.MemoryObject.properties.access.description
Access control for multi-agent and federation scenarios.

# $defs.MemoryObject.properties.embedding_ref.description
Reference to an embedding in the separate embeddings.json file. MUST be null if embeddings are not included in the export. Importers MUST NOT fail if this is null or if embeddings.json is missing. Importers MAY regenerate embeddings from the content field.

# $defs.MemoryType.description
Closed taxonomy of memory types. 'fact': objective verifiable information. 'preference': user preference or taste. 'skill': competency or expertise. 'context': situational or temporal context. 'relationship': relation to another entity. 'goal': active objective. 'instruction': how the user wants to be treated. 'identity': personal identity information. 'environment': technical or physical environment. 'project': active project or initiative. 'custom': extensible type requiring custom_type field. Custom types SHOULD be registered at the official type registry (see root type_registry field) for interoperability. Community-adopted custom types MAY be promoted to the standard taxonomy in future versions.

# $defs.MemoryStatus.description
'active': current and valid. 'superseded': replaced by a newer memory (see temporal.superseded_by). 'deprecated': still valid but no longer prioritized. 'retracted': explicitly invalidated by user. 'archived': retained for historical purposes only.

# $defs.ConfidenceBlock.properties.current.description
Current confidence score after decay and reinforcement.

# $defs.ConfidenceBlock.properties.decay_model.description
Model used for confidence decay over time.

# $defs.ConfidenceBlock.properties.last_reinforced.description
Last time this memory was confirmed or reinforced by user interaction.

# $defs.TemporalBlock.properties.created_at.description
When this memory was first created/extracted.

# $defs.TemporalBlock.properties.valid_from.description
Start of the period during which this memory is/was valid.

# $defs.TemporalBlock.properties.valid_until.description
End of validity period. null means still valid.

# $defs.TemporalBlock.properties.superseded_by.description
ID of the memory that replaces this one. Set when status becomes 'superseded'.

# $defs.ProvenanceBlock.description
Origin tracking for auditability and cross-platform conflict resolution.

# $defs.ProvenanceBlock.properties.platform.description
Source platform identifier. MUST be lowercase ASCII, 2-32 characters, matching ^[a-z0-9_-]{2,32}$. SHOULD be registered in a public registry to prevent collisions.

# $defs.ProvenanceBlock.properties.platform_user_id.description
User identifier on the source platform. Optional for privacy.

# $defs.ProvenanceBlock.properties.conversation_ref.description
Reference to a conversation in conversations_index.

# $defs.ProvenanceBlock.properties.message_ref.description
Reference to a specific message within the conversation.

# $defs.ProvenanceBlock.properties.extraction_method.description
How this memory was extracted from the source.

# $defs.ProvenanceBlock.properties.extractor.description
System that performed the extraction. Format: 'system-name/semver'.

# $defs.AccessBlock.description
Access control for multi-agent and federated scenarios.

# $defs.AccessBlock.properties.visibility.description
'private': owner only. 'shared': accessible to entities in shared_with. 'public': no access restriction.

# $defs.AccessBlock.properties.exportable.description
Whether this memory may be included in exports.

# $defs.AccessBlock.properties.shared_with.description
List of entities with access to this memory.

# $defs.AccessGrant.properties.entity.description
Identifier of the entity granted access (agent ID, system ID, user ID).

# $defs.MetadataBlock.description
Additional metadata. This block allows arbitrary additional properties for extensibility.

# $defs.MetadataBlock.properties.language.description
BCP 47 language tag for the content. Supports language (en), language-region (pt-BR), language-script (zh-Hans), and language-script-region (zh-Hant-TW).

# $defs.RelationObject.description
A semantic relationship between two memory objects, forming edges in a knowledge graph.

# $defs.RelationObject.properties.type.description
'supports': source provides evidence for target. 'contradicts': source conflicts with target. 'extends': source adds detail to target. 'supersedes': source replaces target. 'related_to': general semantic relation. 'derived_from': source was inferred from target.

# $defs.ConversationIndexEntry.description
Lightweight index entry for a conversation. Full message history is stored externally. Importers SHOULD treat derived_memories as advisory and MAY reconstruct from memory provenance.

# $defs.ConversationIndexEntry.properties.id.description
Unique identifier for this conversation.

# $defs.ConversationIndexEntry.properties.platform.description
Platform where this conversation occurred. Same namespace as provenance.platform.

# $defs.ConversationIndexEntry.properties.title.description
Human-readable title or summary of the conversation.

# $defs.ConversationIndexEntry.properties.message_count.description
Total number of messages in the conversation.

# $defs.ConversationIndexEntry.properties.tags.description
Tags or topics associated with this conversation. Uses the same field name and pattern as memory tags for consistency.

# $defs.ConversationIndexEntry.properties.derived_memories.description
IDs of memories extracted from this conversation. ADVISORY: Exporters MUST ensure consistency with memory.provenance.conversation_ref. Importers MAY reconstruct by scanning provenance.

# $defs.ConversationIndexEntry.properties.storage.description
Reference to the full conversation data.

# $defs.StorageReference.description
Reference to external storage for large data objects.

# $defs.StorageReference.properties.ref.description
Reference path, URI, or identifier to the stored data.

# $defs.SignatureBlock.description
Cryptographic signature over the export for authenticity verification. The signature MUST be computed over a canonicalized payload containing integrity.checksum, export_id, export_date, and owner.id (see spec Section 18.3). Supports Ed25519 (recommended), ECDSA, and RSA algorithms via JWS (RFC 7515) or detached signatures.

# $defs.SignatureBlock.properties.algorithm.description
Signature algorithm. Ed25519 is RECOMMENDED for its speed, small key size, and resistance to side-channel attacks.

# $defs.SignatureBlock.properties.public_key.description
Public key of the signer. Format depends on algorithm: Base58 for Ed25519, JWK or PEM for others. If owner.did is present, this key SHOULD correspond to a verification method in the DID document.

# $defs.SignatureBlock.properties.value.description
The signature value, Base64url-encoded (RFC 4648 §5). Computed over the RFC 8785 (JCS) canonicalization of the payload object {checksum, export_id, export_date, owner_id} as defined in spec Section 18.3.

# $defs.SignatureBlock.properties.signed_at.description
ISO 8601 timestamp of when the signature was created.

# $defs.SignatureBlock.properties.key_id.description
Optional key identifier. If owner.did is present, this SHOULD be the DID URL of the verification method (e.g., 'did:key:z6Mk...#z6Mk...').

# $defs.IntegrityBlock.description
Integrity verification block. checksum is the SHA-256 hash of the canonicalized memories array. Default canonicalization is RFC 8785 (JSON Canonicalization Scheme): deterministic JSON serialization with sorted keys, no whitespace, and UTF-8 encoding. Memory objects are sorted by id ascending before canonicalization.

# $defs.IntegrityBlock.properties.canonicalization.description
Canonicalization algorithm used before hashing. RFC 8785 (JCS - JSON Canonicalization Scheme) is the default and currently only supported method. Ensures deterministic serialization across all implementations regardless of language or platform.

# $defs.IntegrityBlock.properties.checksum.description
SHA-256 of the canonicalized memories array: objects sorted by id ascending, then canonicalized per the specified canonicalization method. Format: 'sha256:<hex>'.

# $defs.IntegrityBlock.properties.total_memories.description
Total count of memory objects. MUST match memories array length.