HMX-E: Event Specification

Protocol: Hippocortex Memory Protocol (HMX)
Component: HMX-E (Events)
Version: HMX-1.0
Status: Stable

1. Overview

An HMX Event is the atomic unit of observable information in the Hippocortex memory system. Every interaction, observation, decision, or state change captured by an agent is represented as an event. Events are the raw inputs from which all higher-order memory structures (artifacts, fingerprints, context packs) are derived.

HMX Events are designed for:

Streaming ingestion at high throughput (millions of events per tenant)
Deterministic ordering via monotonic timestamps + sequence numbers
Cross-system correlation via trace and correlation IDs
Language-agnostic serialization as JSON

Relationship to Hippocortex Architecture

HMX Events wrap and standardize the existing EpisodeTrace type from @hippocortex/types. An EpisodeTrace is the internal representation; an HMX Event is the wire-format protocol envelope. Any valid EpisodeTrace can be projected into an HMX Event, and any valid HMX Event can be ingested into the EpisodeTrace pipeline.

2. Event Structure

2.1 Required Fields

Field	Type	Description
`hmx_version`	`string`	Protocol version (e.g., `"HMX-1.0"`)
`event_id`	`string`	Globally unique event identifier (UUIDv7 recommended)
`event_type`	`string`	Event type discriminator (see §3)
`agent_id`	`string`	Identifier of the agent that produced this event
`tenant_id`	`string`	Tenant scope for multi-tenancy isolation
`session_id`	`string`	Session this event belongs to
`timestamp`	`string`	ISO 8601 datetime with timezone (e.g., `"2026-03-14T03:00:00.000Z"`)
`sequence`	`integer`	Monotonically increasing sequence number within a session (≥ 0)
`content`	`object`	Event payload (structure varies by `event_type`, see §4)
`metadata`	`object`	Extensible key-value metadata bag

2.2 Optional Fields

Field	Type	Description
`trace_id`	`string`	Distributed tracing ID for cross-service correlation
`correlation_id`	`string`	Correlation ID linking related events (e.g., request → response)
`parent_event_id`	`string`	ID of the causally preceding event
`embeddings`	`number[]`	Pre-computed embedding vector for semantic search
`salience`	`number`	Novelty/utility score in `[0.0, 1.0]`
`source`	`string`	Origin system or component (e.g., `"claude-agent"`, `"tool:gh"`)
`provenance_ref`	`string`	Reference to raw evidence (message ID, file path, etc.)
`tags`	`string[]`	Categorization tags for filtering
`ttl_seconds`	`integer`	Time-to-live hint for retention policies (≥ 0)

3. Event Types

HMX-1.0 defines the following event types. Implementations MUST accept all standard types and SHOULD pass through unknown types without error (forward compatibility).

Event Type	Description	Maps to EpisodeTrace
`message`	User or agent message	`message`
`tool_call`	Agent invokes a tool	`tool_call`
`tool_result`	Tool returns a result	`tool_result`
`file_edit`	File creation or modification	`file_edit`
`test_run`	Test execution and results	`test_run`
`command_exec`	Shell command execution	`command_exec`
`browser_action`	Browser automation action	`browser_action`
`api_result`	External API call result	`api_result`
`decision`	Agent makes a decision	`decision`
`error`	Error or exception	`error`
`observation`	Passive observation (no action)	(extension)
`state_change`	Internal state transition	(extension)
`feedback`	User feedback signal	(extension)

Custom event types MUST use a namespaced format: x-{vendor}-{type} (e.g., x-acme-custom_signal).

4. Content Structure

The content field is a JSON object whose schema depends on event_type. The following are normative content schemas for standard event types.

4.1 `message`

{
  "role": "user" | "assistant" | "system",
  "text": "string",
  "attachments": [{ "type": "string", "url": "string" }]
}

4.2 `tool_call`

{
  "tool_name": "string",
  "arguments": {},
  "call_id": "string"
}

4.3 `tool_result`

{
  "tool_name": "string",
  "call_id": "string",
  "result": {},
  "success": true | false,
  "duration_ms": 0
}

4.4 `decision`

{
  "question": "string",
  "chosen_option": "string",
  "alternatives": ["string"],
  "reasoning": "string",
  "confidence": 0.0
}

4.5 `error`

{
  "error_type": "string",
  "message": "string",
  "stack": "string",
  "recoverable": true | false
}

4.6 `feedback`

{
  "signal": "positive" | "negative" | "correction",
  "target_event_id": "string",
  "comment": "string"
}

Implementations SHOULD validate content structure but MUST NOT reject events with unknown content fields (extensibility).

5. JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hippocortex.dev/schemas/hmx-1.0/event.json",
  "title": "HMX Event",
  "type": "object",
  "required": [
    "hmx_version",
    "event_id",
    "event_type",
    "agent_id",
    "tenant_id",
    "session_id",
    "timestamp",
    "sequence",
    "content",
    "metadata"
  ],
  "properties": {
    "hmx_version": {
      "type": "string",
      "pattern": "^HMX-\\d+\\.\\d+$"
    },
    "event_id": {
      "type": "string",
      "minLength": 1
    },
    "event_type": {
      "type": "string",
      "minLength": 1
    },
    "agent_id": {
      "type": "string",
      "minLength": 1
    },
    "tenant_id": {
      "type": "string",
      "minLength": 1
    },
    "session_id": {
      "type": "string",
      "minLength": 1
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    },
    "sequence": {
      "type": "integer",
      "minimum": 0
    },
    "content": {
      "type": "object"
    },
    "metadata": {
      "type": "object"
    },
    "trace_id": {
      "type": "string"
    },
    "correlation_id": {
      "type": "string"
    },
    "parent_event_id": {
      "type": "string"
    },
    "embeddings": {
      "type": "array",
      "items": { "type": "number" }
    },
    "salience": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0
    },
    "source": {
      "type": "string"
    },
    "provenance_ref": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "ttl_seconds": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}

6. Validation Rules

hmx_version MUST match pattern HMX-\d+\.\d+
event_id MUST be a non-empty string; UUIDv7 is RECOMMENDED for sortability
timestamp MUST be valid ISO 8601 with timezone designator
sequence MUST be a non-negative integer; MUST be monotonically increasing within a session
salience (if present) MUST be in [0.0, 1.0]
embeddings (if present) MUST be a non-empty array of finite numbers
content MUST be a JSON object (not null, not array)
metadata MUST be a JSON object (not null, not array)
tags (if present) MUST be an array of strings
ttl_seconds (if present) MUST be a non-negative integer

7. Ordering Guarantees

HMX Events support deterministic ordering via the following composite key:

ORDER BY (tenant_id, session_id, sequence ASC, timestamp ASC)

Within a session: sequence provides total order. Ties are broken by timestamp.
Across sessions: No global ordering is guaranteed. Consumers MUST handle out-of-order cross-session events.
Streaming: Events MAY arrive out of order. Consumers SHOULD buffer and reorder within a configurable window (default: 5 seconds).

8. Streaming Compatibility

HMX Events are designed for streaming ingestion:

NDJSON (newline-delimited JSON): One event per line
Server-Sent Events (SSE): Each event as an SSE data field
Message queues: Each event as a single message (Kafka, NATS, Redis Streams)
WebSocket: Each event as a single frame

Events MUST be self-contained (no references to previous events required for validation).

9. Example Events

User Message

{
  "hmx_version": "HMX-1.0",
  "event_id": "019e5a3b-7c4d-7000-8000-000000000001",
  "event_type": "message",
  "agent_id": "agent-claude-001",
  "tenant_id": "tenant-acme",
  "session_id": "session-2026-03-14-001",
  "timestamp": "2026-03-14T03:00:00.000Z",
  "sequence": 0,
  "content": {
    "role": "user",
    "text": "Deploy the staging environment",
    "attachments": []
  },
  "metadata": {
    "channel": "slack",
    "user_id": "U12345"
  },
  "source": "user",
  "salience": 0.7,
  "tags": ["deployment", "staging"]
}

Tool Call

{
  "hmx_version": "HMX-1.0",
  "event_id": "019e5a3b-7c4d-7000-8000-000000000002",
  "event_type": "tool_call",
  "agent_id": "agent-claude-001",
  "tenant_id": "tenant-acme",
  "session_id": "session-2026-03-14-001",
  "timestamp": "2026-03-14T03:00:01.500Z",
  "sequence": 1,
  "content": {
    "tool_name": "exec",
    "arguments": { "command": "kubectl apply -f staging.yaml" },
    "call_id": "call-001"
  },
  "metadata": {},
  "trace_id": "trace-deploy-staging",
  "correlation_id": "019e5a3b-7c4d-7000-8000-000000000001",
  "parent_event_id": "019e5a3b-7c4d-7000-8000-000000000001",
  "source": "claude-agent",
  "salience": 0.8
}

Error Event

{
  "hmx_version": "HMX-1.0",
  "event_id": "019e5a3b-7c4d-7000-8000-000000000003",
  "event_type": "error",
  "agent_id": "agent-claude-001",
  "tenant_id": "tenant-acme",
  "session_id": "session-2026-03-14-001",
  "timestamp": "2026-03-14T03:00:05.000Z",
  "sequence": 2,
  "content": {
    "error_type": "KubectlError",
    "message": "namespace staging not found",
    "stack": "",
    "recoverable": true
  },
  "metadata": { "exit_code": 1 },
  "trace_id": "trace-deploy-staging",
  "correlation_id": "019e5a3b-7c4d-7000-8000-000000000002",
  "source": "tool:kubectl",
  "salience": 0.9,
  "tags": ["error", "kubernetes"]
}

10. EpisodeTrace Mapping

HMX Event Field	EpisodeTrace Field	Notes
`event_id`	`id`	Direct mapping
`event_type`	`eventType`	Same enum values
`session_id`	`sessionId`	Direct mapping
`timestamp`	`timestamp`	Same format
`content`	`payload`	Renamed for clarity
`salience`	`salienceScore`	Direct mapping
`source`	`source`	Direct mapping
`provenance_ref`	`provenanceRef`	Direct mapping
`metadata`	`metadata`	Direct mapping
`agent_id`	(via metadata)	Promoted to top-level
`tenant_id`	(via metadata)	Promoted to top-level
`sequence`	(new)	Added for deterministic ordering
`hmx_version`	(new)	Protocol envelope field

11. Size Constraints

Maximum event size: 1 MB (JSON serialized)
Maximum content size: 512 KB
Maximum embeddings length: 4096 dimensions
Maximum tags count: 64
Maximum metadata size: 64 KB

Implementations SHOULD reject events exceeding these limits with a clear error.