HMX-V: Protocol Versioning Specification

Protocol: Hippocortex Memory Protocol (HMX)
Component: HMX-V (Versioning)
Version: HMX-1.0
Status: Stable

---

1. Overview

This document defines the versioning strategy for the Hippocortex Memory Protocol (HMX). It covers version identifiers, negotiation between systems, backward compatibility guarantees, and schema evolution rules.

---

2. Version Identifier Format

HMX-{major}.{minor}

• Major: Incremented for breaking changes. Systems MUST NOT interoperate across different major versions without explicit migration.
• Minor: Incremented for backward-compatible additions. A system supporting HMX-1.2 MUST accept data from HMX-1.0 and HMX-1.1.

Current Version

HMX-1.0

Validation Pattern

^HMX-\d+\.\d+$

Version Comparison

Versions are compared numerically: HMX-1.10 > HMX-1.9 > HMX-1.0.

---

3. Version Negotiation

When two systems exchange HMX data, they MUST negotiate a compatible version.

3.1 Protocol

1. Producer includes hmx_version in every message/object
2. Consumer checks hmx_version against its supported range
3. Decision matrix:

Producer Version	Consumer Supports	Result
Same major + minor ≤ consumer	✅ Accept	Process normally
Same major + minor > consumer	⚠️ Accept with warning	Ignore unknown fields
Different major	❌ Reject	Return version mismatch error

3.2 API Negotiation

For HTTP APIs, version negotiation uses headers:

# Request
Accept: application/vnd.hmx+json; version=1.0

# Response
Content-Type: application/vnd.hmx+json; version=1.0
X-HMX-Version: HMX-1.0
X-HMX-Min-Version: HMX-1.0
X-HMX-Max-Version: HMX-1.0

3.3 Streaming Negotiation

For streaming protocols (WebSocket, SSE, message queues):

1. First message MUST be a version handshake:

{
  "type": "hmx_handshake",
  "supported_versions": ["HMX-1.0"],
  "preferred_version": "HMX-1.0"
}

2. Receiver responds with selected version:

{
  "type": "hmx_handshake_ack",
  "selected_version": "HMX-1.0"
}

3. All subsequent messages use the selected version.

---

4. Backward Compatibility Rules

4.1 Minor Version Guarantees

Within a major version, the following are guaranteed:

Action	Allowed?	Notes
Add new optional field	✅ Yes	Consumers MUST ignore unknown fields
Add new enum value	✅ Yes	Consumers SHOULD handle unknown enum values gracefully
Add new event type	✅ Yes	Custom types use x-{vendor}-{type} namespace
Add new artifact type	✅ Yes	Custom types use x-{vendor}-{type} namespace
Add new section type	✅ Yes	Unknown sections are treated as evidence
Remove a required field	❌ No	Breaking change → major version bump
Rename a field	❌ No	Breaking change → major version bump
Change a field type	❌ No	Breaking change → major version bump
Narrow an enum	❌ No	Breaking change → major version bump
Change validation rules to be stricter	❌ No	Breaking change → major version bump

4.2 Wire Format Rules

1. Unknown fields MUST be preserved when forwarding data (no field stripping)
2. Unknown enum values MUST NOT cause rejection (store as-is)
3. Missing optional fields have no default — they are simply absent
4. Null vs. absent: null and absent are treated identically for optional fields

4.3 Deprecation Process

1. Field is marked deprecated in schema docs (minor version)
2. Field is ignored but still accepted for 2 minor versions
3. Field is removed in the next major version

---

5. Schema Evolution

5.1 Adding Fields

New optional fields can be added in any minor version:

// HMX-1.0
{
  "hmx_version": "HMX-1.0",
  "event_id": "...",
  "event_type": "message"
}

// HMX-1.1 (added priority field)
{
  "hmx_version": "HMX-1.1",
  "event_id": "...",
  "event_type": "message",
  "priority": "high"
}

A HMX-1.0 consumer receiving HMX-1.1 data MUST ignore the unknown priority field.

5.2 Extending Enums

New enum values can be added in minor versions:

// HMX-1.0 event types
message, tool_call, tool_result, file_edit, ...

// HMX-1.1 adds
planning, reflection

A HMX-1.0 consumer receiving event_type: "planning" SHOULD:

1. Accept the event without error
2. Store it with the unknown type preserved
3. Log a warning if desired

5.3 Content Schema Evolution

The content field in events and artifacts uses duck typing. New content schemas are added without changing the protocol version — the event_type / artifact_type discriminator determines interpretation.

5.4 Migration Transforms

When upgrading across minor versions, migrations are typically no-ops (additive only). Cross-major migrations require explicit transforms:

interface MigrationTransform {
  from_version: string;  // e.g., "HMX-1.0"
  to_version: string;    // e.g., "HMX-2.0"
  transform(data: unknown): unknown;
}

---

6. Component Version Matrix

Each HMX component has its own internal schema version in addition to the protocol version:

Component	Protocol Version	Schema Version	Field
Events (HMX-E)	hmx_version	—	Part of protocol version
Artifacts (HMX-A)	hmx_version	—	Part of protocol version
Fingerprints (HMX-F)	hmx_version	fingerprint_version	Independent, currently 1
Context Packs (HMX-C)	hmx_version	—	Part of protocol version
Fingerprint Envelope	hmx_version	envelope_version	Independent, currently 1

Version Independence

• fingerprint_version and envelope_version can increment independently of hmx_version
• A HMX-1.0 system may encounter fingerprint_version: 2 — it should attempt best-effort import
• The protocol version is the primary compatibility gate

---

7. Version Support Policy

Version	Status	Support
HMX-1.0	Current	Full support

Planned Lifecycle

• Active: Full support, receives minor updates
• Maintenance: Security fixes only, no new features
• End of Life: No longer supported, migration required

Support timeline (planned):

• Active support: 2 years from release
• Maintenance: 1 additional year
• EOL: 3 years after initial release

---

8. Implementation Requirements

Producers

1. MUST include hmx_version on every emitted object
2. MUST produce valid data according to the declared version's schema
3. SHOULD support emitting data in older minor versions if requested

Consumers

1. MUST check hmx_version before processing
2. MUST reject data with an unsupported major version
3. MUST accept data from any supported minor version (≤ their own)
4. MUST NOT reject data with unknown optional fields
5. SHOULD log warnings for unknown fields or enum values
6. SHOULD store data with version metadata for future migration

Libraries/SDKs

1. MUST export version constants: HMX_VERSION, HMX_MAJOR, HMX_MINOR
2. MUST provide version comparison utilities
3. MUST provide version negotiation helpers
4. SHOULD provide migration transform registry

---

9. Version Negotiation API

TypeScript Reference

interface VersionInfo {
  readonly full: string;      // "HMX-1.0"
  readonly major: number;     // 1
  readonly minor: number;     // 0
}

function parseVersion(version: string): VersionInfo | null;
function isCompatible(producer: string, consumer: string): boolean;
function negotiateVersion(
  supported: string[],
  requested: string
): string | null;

Compatibility Rules

isCompatible("HMX-1.0", "HMX-1.0") → true   // exact match
isCompatible("HMX-1.0", "HMX-1.2") → true   // consumer is newer
isCompatible("HMX-1.2", "HMX-1.0") → true   // minor mismatch OK (forward compat)
isCompatible("HMX-1.0", "HMX-2.0") → false  // major mismatch
isCompatible("HMX-2.0", "HMX-1.0") → false  // major mismatch

---

10. Changelog

HMX-1.0 (2026-03-14)

• Initial release
• Event specification (HMX-E)
• Artifact specification (HMX-A)
• Fingerprint specification (HMX-F)
• Context Pack specification (HMX-C)
• Versioning specification (HMX-V)