HMX Protocol

Why HMX?

Agent memory today is fragmented. Every framework defines its own format for storing what an agent has learned. HMX solves this with a single, open wire protocol that any runtime can implement. Capture events in one framework, compile knowledge in another, and synthesize context wherever you need it.

• •Portable. Export an agent's full knowledge and load it into a different runtime.
• •No vendor lock-in. HMX is open source. No proprietary formats or dependencies.
• •Deterministic. Zero LLM calls in the protocol layer. Pure data transformations.

Design Principles

HMX-EHMX Events

Events are the atomic unit of observable information in HMX. Every agent interaction is represented as a typed event with a consistent schema.

13 Event Types

Required Fields

Example Event

{
  "hmx_version": "HMX-1.0",
  "event_id": "evt_01HZ3N4K8W9XM2RVJCB5DF6GHP",
  "event_type": "tool_call",
  "agent_id": "agent-ops-1",
  "tenant_id": "ten_acme",
  "session_id": "sess_abc123",
  "timestamp": "2026-03-15T00:12:34.567Z",
  "sequence": 4,
  "content": {
    "tool_name": "deploy",
    "input": "{\"service\": \"payments\", \"env\": \"staging\"}"
  },
  "metadata": {
    "framework": "openai-agents",
    "model": "gpt-4o"
  }
}

HMX-AHMX Artifacts

Artifacts are compiled knowledge units produced by the Memory Compiler. They represent reusable, versioned knowledge extracted from raw event traces.

5 Artifact Types

Lifecycle Statuses

Every artifact includes a content_hash (SHA-256) for integrity verification and deduplication. The compiler produces deterministic output, so identical inputs always produce the same hash.

HMX-FHMX Fingerprints

A Fingerprint is a portable, compressed snapshot of an agent's entire learned state. Use it to clone knowledge between agents or bootstrap a new agent with pre-existing experience.

3 Compression Tiers

Fingerprint Contents

• •artifact_summaries Condensed versions of all compiled artifacts.
• •behavioral_patterns Statistical patterns across sessions (tool usage frequency, error rates, decision distributions).
• •graph_digest Compressed representation of the knowledge graph structure.
• •semantic_summary Natural-language summary of the agent's core competencies.
• •context_priors Pre-computed relevance weights for faster context synthesis.

HMX-CHMX Context Packs

Context Packs are token-budget-aware reasoning inputs assembled by the Context Synthesizer. They combine multiple knowledge signals into a structured payload that fits within a specified token budget.

10 Sections

7 Source Types

Each entry in a Context Pack includes provenance tracking. Source types include: artifact, event, graph_node, graph_edge, fingerprint, external, and computed.

Token Budget Management

The synthesizer ranks entries by relevance, recency, and confidence, then fills the budget greedily. When entries must be dropped, one of 6 drop reasons is recorded:

HMX-VHMX Versioning

HMX uses semantic versioning in the format HMX-{major}.{minor}. The current version is HMX-1.0.

Compatibility Levels

• •Minor version bump (e.g. 1.0 to 1.1): backward compatible. New optional fields, new event types. Existing consumers continue to work.
• •Major version bump (e.g. 1.x to 2.0): breaking changes. Requires migration. Removed fields, changed semantics.

Version Negotiation

Clients and servers negotiate version compatibility on connection. The hmx_version field in every event declares the protocol version used. Receivers must validate compatibility and reject events from unsupported major versions with a clear error.

JSON Schemas

Formal JSON Schema definitions for all HMX types are published at:

https://hippocortex.dev/schemas/hmx-1.0/event.json
https://hippocortex.dev/schemas/hmx-1.0/artifact.json
https://hippocortex.dev/schemas/hmx-1.0/fingerprint.json
https://hippocortex.dev/schemas/hmx-1.0/context-pack.json

Use these schemas for validation in CI pipelines, SDK code generation, or custom implementations.

SDK Integration

The Hippocortex SDK implements HMX natively. Here are examples for both languages.

TypeScript

import { Hippocortex } from '@hippocortex/sdk';

const hx = new Hippocortex({
  apiKey: process.env.HIPPOCORTEX_API_KEY!,
});

// Capture an HMX event
await hx.capture({
  type: 'message',
  sessionId: 'sess_001',
  payload: {
    role: 'user',
    content: 'Deploy payments to staging',
  },
});

// Compile events into artifacts
const result = await hx.learn({ scope: 'incremental' });
console.log(result.artifacts); // { created: 2, updated: 1 }

// Synthesize a context pack
const context = await hx.synthesize('deploy payments', {
  maxTokens: 4000,
  sections: ['procedures', 'failures'],
});

// Export an HMX fingerprint
const fingerprint = await hx.exportFingerprint({
  tier: 'compact',
  agentId: 'agent-ops-1',
});

Python

from hippocortex import Hippocortex

hx = Hippocortex(api_key="hx_live_...")

# Capture an HMX event
await hx.capture(
    type="message",
    session_id="sess_001",
    payload={"role": "user", "content": "Deploy payments to staging"},
)

# Compile events into artifacts
result = await hx.learn(scope="incremental")
print(result.artifacts)  # {"created": 2, "updated": 1}

# Synthesize a context pack
context = await hx.synthesize(
    query="deploy payments",
    max_tokens=4000,
    sections=["procedures", "failures"],
)

# Export an HMX fingerprint
fingerprint = await hx.export_fingerprint(
    tier="compact",
    agent_id="agent-ops-1",
)

Contributing

The HMX Protocol is open source and welcomes contributions. The specification, JSON Schemas, and reference implementations are maintained in the hippocortex-os repository. To propose changes, open an RFC issue or submit a pull request against the spec/ directory.

Next Steps