HMX-A: Artifact Specification

Protocol: Hippocortex Memory Protocol (HMX)
Component: HMX-A (Artifacts)
Version: HMX-1.0
Status: Stable

1. Overview

An HMX Artifact is a compiled unit of reusable knowledge derived from one or more HMX Events. Artifacts represent the agent's distilled understanding: task procedures, failure recovery plans, decision policies, causal relationships, and strategic approaches.

Artifacts are:

Immutable — once created, an artifact is never modified. Updates produce new artifacts that supersede the old.
Evidence-backed — every artifact traces to the source events and memories from which it was compiled.
Deterministically hashable — the same inputs produce the same content hash, enabling deduplication and integrity verification.
Portable — JSON-serializable, language-agnostic, transferable between systems.

Relationship to Hippocortex Architecture

HMX Artifacts wrap and standardize the existing CompiledArtifact type hierarchy from @hippocortex/compiler. The internal types (TaskSchema, FailurePlaybook, DecisionPolicy, CausalPattern, StrategyTemplate) map directly to HMX Artifact types. The protocol adds standardized versioning, supersession chains, validity scoping, and deterministic hashing.

2. Artifact Structure

2.1 Required Fields

Field	Type	Description
`hmx_version`	`string`	Protocol version (`"HMX-1.0"`)
`artifact_id`	`string`	Globally unique artifact identifier (UUIDv7 recommended)
`artifact_type`	`string`	Type discriminator (see §3)
`title`	`string`	Human-readable title
`summary`	`string`	Concise description of what this artifact captures
`content`	`object`	Type-specific compiled knowledge (see §4)
`confidence`	`number`	Confidence score in `[0.0, 1.0]` based on evidence quality
`status`	`string`	Lifecycle status (see §5)
`source_events`	`string[]`	IDs of HMX Events this artifact was compiled from
`source_memory_ids`	`string[]`	IDs of intermediate memory objects used in compilation
`version`	`integer`	Artifact version (starts at 1, increments on supersession)
`created_at`	`string`	ISO 8601 datetime
`content_hash`	`string`	SHA-256 hash of deterministically serialized `content`
`metadata`	`object`	Extensible key-value metadata

2.2 Optional Fields

Field	Type	Description
`tenant_id`	`string`	Tenant scope
`agent_id`	`string`	Agent that compiled this artifact
`superseded_by`	`string`	ID of the artifact that supersedes this one
`supersedes`	`string`	ID of the artifact this one supersedes
`validity_scope`	`object`	Conditions under which this artifact is applicable (see §6)
`tags`	`string[]`	Categorization tags
`observed_count`	`integer`	Number of times the pattern was observed
`success_rate`	`number`	Historical success rate `[0.0, 1.0]`
`updated_at`	`string`	ISO 8601 datetime of last metadata update

3. Artifact Types

Artifact Type	Description	Maps to CompiledArtifact
`task_schema`	Reusable procedure for completing a category of tasks	`TaskSchema`
`failure_playbook`	Failure pattern with recovery and prevention strategies	`FailurePlaybook`
`decision_policy`	Rule for making decisions based on historical outcomes	`DecisionPolicy`
`causal_pattern`	Observed cause → effect relationship	`CausalPattern`
`strategy_template`	Reusable approach for achieving goals	`StrategyTemplate`

Custom artifact types MUST use a namespaced format: x-{vendor}-{type}.

4. Content Schemas

4.1 `task_schema`

{
  "steps": [
    {
      "order": 1,
      "description": "string",
      "tools_used": ["string"],
      "optional": false
    }
  ],
  "preconditions": ["string"],
  "postconditions": ["string"],
  "tools_used": ["string"],
  "estimated_complexity": "low" | "medium" | "high"
}

4.2 `failure_playbook`

{
  "failure_pattern": "string",
  "trigger_conditions": ["string"],
  "symptoms": ["string"],
  "recovery_steps": ["string"],
  "prevention_strategies": ["string"],
  "severity": "low" | "medium" | "high" | "critical"
}

4.3 `decision_policy`

{
  "condition": "string",
  "recommendation": "string",
  "alternatives": [
    {
      "description": "string",
      "outcome": "string",
      "chosen_count": 0,
      "success_rate": 0.0
    }
  ],
  "outcomes": [
    {
      "decision": "string",
      "outcome": "string",
      "positive": true,
      "source_memory_id": "string"
    }
  ],
  "scope": ["string"]
}

4.4 `causal_pattern`

{
  "cause": "string",
  "effect": "string",
  "direction": "forward" | "bidirectional",
  "strength": 0.0,
  "conditions": ["string"],
  "counterexamples": ["string"]
}

4.5 `strategy_template`

{
  "goal": "string",
  "phases": [
    {
      "order": 1,
      "name": "string",
      "description": "string",
      "tools_used": ["string"],
      "success_criteria": ["string"]
    }
  ],
  "applicability_conditions": ["string"],
  "estimated_complexity": "low" | "medium" | "high"
}

5. Lifecycle States

            ┌──────────┐
            │  draft    │ ← freshly extracted
            └────┬─────┘
                 │ validate
            ┌────▼─────┐
     ┌──────│  active   │──────┐
     │      └────┬─────┘      │
     │ archive   │ supersede  │ deprecate
     │      ┌────▼──────┐     │
     │      │ superseded │     │
     │      └───────────┘     │
┌────▼────┐              ┌────▼──────┐
│ archived │              │ deprecated │
└─────────┘              └───────────┘

Status	Description	Retrievable?
`draft`	Freshly extracted, pending validation	No
`active`	Validated, available for retrieval and context assembly	Yes
`superseded`	Replaced by a newer version	No (unless explicitly requested)
`deprecated`	Source evidence contradicted or decayed	No
`archived`	Manually archived by operator	No (unless explicitly requested)

State transitions:

draft → active (validation passes)
active → superseded (new version compiled)
active → deprecated (source evidence invalidated)
active → archived (operator decision)
draft → deprecated (validation fails due to contradicted sources)

6. Validity Scope

The validity_scope field constrains when an artifact is applicable:

{
  "tenant_ids": ["string"],
  "agent_ids": ["string"],
  "tags": ["string"],
  "time_range": {
    "start": "ISO-8601",
    "end": "ISO-8601"
  },
  "conditions": ["string"]
}

All fields are optional. An empty validity_scope means the artifact is universally applicable within its tenant.

7. Supersession Chain

Artifacts form a linked list of versions via supersedes / superseded_by:

artifact-v1 (superseded_by: artifact-v2)
  └── artifact-v2 (supersedes: artifact-v1, superseded_by: artifact-v3)
        └── artifact-v3 (supersedes: artifact-v2) ← active

Rules:

An artifact MUST NOT supersede itself
An artifact MUST NOT create a cycle in the supersession chain
When an artifact is superseded, its status MUST transition to superseded
Only one artifact in a chain SHOULD have active status
The chain is traversable in both directions via supersedes / superseded_by

8. Deterministic Hashing

The content_hash field enables deduplication and integrity verification.

Algorithm

Extract the content field
Serialize deterministically:
- Sort object keys lexicographically (recursive)
- Use consistent number formatting (no trailing zeros)
- No whitespace
- Null values preserved (not omitted)
Compute SHA-256 of the UTF-8 encoded serialized string
Encode as lowercase hexadecimal

Pseudocode

content_hash = hex(sha256(utf8(deterministicJson(artifact.content))))

Two artifacts with the same content_hash represent the same compiled knowledge, regardless of when or where they were compiled.

9. JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hippocortex.dev/schemas/hmx-1.0/artifact.json",
  "title": "HMX Artifact",
  "type": "object",
  "required": [
    "hmx_version",
    "artifact_id",
    "artifact_type",
    "title",
    "summary",
    "content",
    "confidence",
    "status",
    "source_events",
    "source_memory_ids",
    "version",
    "created_at",
    "content_hash",
    "metadata"
  ],
  "properties": {
    "hmx_version": { "type": "string", "pattern": "^HMX-\\d+\\.\\d+$" },
    "artifact_id": { "type": "string", "minLength": 1 },
    "artifact_type": {
      "type": "string",
      "enum": ["task_schema", "failure_playbook", "decision_policy", "causal_pattern", "strategy_template"]
    },
    "title": { "type": "string", "minLength": 1 },
    "summary": { "type": "string" },
    "content": { "type": "object" },
    "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "superseded", "deprecated", "archived"]
    },
    "source_events": { "type": "array", "items": { "type": "string" } },
    "source_memory_ids": { "type": "array", "items": { "type": "string" } },
    "version": { "type": "integer", "minimum": 1 },
    "created_at": { "type": "string", "format": "date-time" },
    "content_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
    "metadata": { "type": "object" },
    "tenant_id": { "type": "string" },
    "agent_id": { "type": "string" },
    "superseded_by": { "type": "string" },
    "supersedes": { "type": "string" },
    "validity_scope": { "type": "object" },
    "tags": { "type": "array", "items": { "type": "string" } },
    "observed_count": { "type": "integer", "minimum": 0 },
    "success_rate": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
    "updated_at": { "type": "string", "format": "date-time" }
  },
  "additionalProperties": false
}

10. Example Artifacts

Task Schema

{
  "hmx_version": "HMX-1.0",
  "artifact_id": "019e5a3b-8000-7000-8000-000000000001",
  "artifact_type": "task_schema",
  "title": "Deploy to Kubernetes Staging",
  "summary": "Standard procedure for deploying applications to the Kubernetes staging environment",
  "content": {
    "steps": [
      { "order": 1, "description": "Validate deployment manifest", "tools_used": ["kubectl"], "optional": false },
      { "order": 2, "description": "Check namespace exists", "tools_used": ["kubectl"], "optional": false },
      { "order": 3, "description": "Apply manifests", "tools_used": ["kubectl"], "optional": false },
      { "order": 4, "description": "Verify rollout status", "tools_used": ["kubectl"], "optional": false },
      { "order": 5, "description": "Run smoke tests", "tools_used": ["curl", "jest"], "optional": true }
    ],
    "preconditions": ["kubeconfig configured", "namespace exists"],
    "postconditions": ["pods running", "health check passes"],
    "tools_used": ["kubectl", "curl", "jest"],
    "estimated_complexity": "medium"
  },
  "confidence": 0.85,
  "status": "active",
  "source_events": ["evt-001", "evt-002", "evt-003"],
  "source_memory_ids": ["mem-001", "mem-002"],
  "version": 2,
  "created_at": "2026-03-14T03:00:00.000Z",
  "content_hash": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "metadata": { "compiled_by": "compiler-v2.1" },
  "tenant_id": "tenant-acme",
  "supersedes": "019e5a3b-7fff-7000-8000-000000000001",
  "tags": ["kubernetes", "deployment", "staging"],
  "observed_count": 15,
  "success_rate": 0.87
}

Decision Policy

{
  "hmx_version": "HMX-1.0",
  "artifact_id": "019e5a3b-8000-7000-8000-000000000002",
  "artifact_type": "decision_policy",
  "title": "Database Migration Strategy Selection",
  "summary": "Policy for choosing between online and offline database migrations",
  "content": {
    "condition": "Database migration needed with table size > 1GB",
    "recommendation": "Use online migration with pt-online-schema-change",
    "alternatives": [
      {
        "description": "Direct ALTER TABLE",
        "outcome": "Causes downtime on large tables",
        "chosen_count": 3,
        "success_rate": 0.33
      }
    ],
    "outcomes": [
      {
        "decision": "online migration",
        "outcome": "zero-downtime schema change",
        "positive": true,
        "source_memory_id": "mem-010"
      }
    ],
    "scope": ["database", "migration"]
  },
  "confidence": 0.92,
  "status": "active",
  "source_events": ["evt-010", "evt-011", "evt-012"],
  "source_memory_ids": ["mem-010", "mem-011"],
  "version": 1,
  "created_at": "2026-03-13T10:00:00.000Z",
  "content_hash": "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
  "metadata": {},
  "tags": ["database", "migration", "decision"]
}

11. CompiledArtifact Mapping

HMX Artifact Field	CompiledArtifact Field	Notes
`artifact_id`	`id`	Direct mapping
`artifact_type`	`type`	Same enum values
`title`	`title`	Direct mapping
`summary`	`summary`	Direct mapping
`content`	(type-specific fields)	Flattened into nested `content` object
`confidence`	`confidence`	Direct mapping
`status`	`status`	Same enum values
`source_events`	`evidenceRefs`	Renamed
`source_memory_ids`	`sourceMemoryIds`	Direct mapping
`version`	(new)	Explicit version counter
`content_hash`	(new)	Deterministic integrity hash
`superseded_by`	`supersededBy`	Direct mapping
`tags`	`tags`	Direct mapping
`metadata`	`metadata`	Direct mapping

12. Size Constraints

Maximum artifact size: 512 KB (JSON serialized)
Maximum content size: 256 KB
Maximum source_events count: 10,000
Maximum tags count: 64