HMX-F: Fingerprint Specification

Protocol: Hippocortex Memory Protocol (HMX)
Component: HMX-F (Fingerprints)
Version: HMX-1.0
Status: Stable

1. Overview

An HMX Fingerprint is a portable, compressed representation of an agent's learned memory state. It captures the distilled knowledge — compiled artifacts, behavioral patterns, graph structure, and semantic memory statistics — without exposing raw event history or sensitive data.

Fingerprints are designed for:

Portability — transfer learned knowledge between agent instances, environments, or organizations
Compact size — target < 100 KB for practical transfer and storage
Integrity verification — SHA-256 hashing for corruption detection
Reproducibility — same inputs produce identical fingerprints
Privacy — no raw events, no sensitive content, only distilled patterns

Relationship to Hippocortex Architecture

HMX Fingerprints wrap and standardize the existing MemoryFingerprint and FingerprintEnvelope types from @hippocortex/fingerprint. The protocol adds explicit versioning, hierarchical compression tiers, and behavioral pattern summaries.

2. Fingerprint Structure

2.1 Required Fields

Field	Type	Description
`hmx_version`	`string`	Protocol version (`"HMX-1.0"`)
`fingerprint_id`	`string`	Globally unique fingerprint identifier
`fingerprint_version`	`integer`	Schema version for forward compatibility (current: `1`)
`tenant_id`	`string`	Tenant identifier for routing
`created_at`	`string`	ISO 8601 datetime of generation
`artifact_summaries`	`object`	Compressed artifact knowledge (see §3)
`behavioral_patterns`	`object`	Agent behavioral statistics (see §4)
`graph_digest`	`object`	Knowledge graph structural digest (see §5)
`semantic_summary`	`object`	Semantic memory layer summary (see §6)
`context_priors`	`object`	Default context assembly hints (see §7)
`fingerprint_hash`	`string`	SHA-256 hash of all content fields
`metadata`	`object`	Extensible metadata

2.2 Optional Fields

Field	Type	Description
`agent_id`	`string`	Agent that generated this fingerprint
`compression_tier`	`string`	Compression level applied (see §8)
`source_event_count`	`integer`	Total events processed to produce this fingerprint
`source_artifact_count`	`integer`	Total artifacts summarized
`compiler_state`	`object`	Adaptive compiler parameters (see §9)
`tags`	`string[]`	Categorization tags
`expires_at`	`string`	ISO 8601 datetime after which this fingerprint is stale

3. Artifact Summaries

The artifact_summaries field contains compressed representations of compiled artifacts, organized by type:

{
  "policy_set": [
    {
      "artifact_id": "string",
      "condition": "string",
      "recommendation": "string",
      "scope": ["string"],
      "confidence": 0.0,
      "outcome_count": 0,
      "tags": ["string"]
    }
  ],
  "task_schema_set": [
    {
      "artifact_id": "string",
      "title": "string",
      "steps": ["string"],
      "tools_used": ["string"],
      "preconditions": ["string"],
      "postconditions": ["string"],
      "complexity": "low" | "medium" | "high",
      "success_rate": 0.0,
      "observed_count": 0,
      "confidence": 0.0,
      "tags": ["string"]
    }
  ],
  "playbook_set": [
    {
      "artifact_id": "string",
      "title": "string",
      "failure_pattern": "string",
      "trigger_conditions": ["string"],
      "recovery_steps": ["string"],
      "prevention_strategies": ["string"],
      "severity": "low" | "medium" | "high" | "critical",
      "occurrence_count": 0,
      "confidence": 0.0,
      "tags": ["string"]
    }
  ],
  "cluster_summaries": [
    {
      "cluster_id": "string",
      "label": "string",
      "dominant_type": "string",
      "member_count": 0,
      "representative_ids": ["string"],
      "shared_tags": ["string"],
      "avg_confidence": 0.0,
      "total_observations": 0
    }
  ]
}

These map directly to the existing PolicySummary, TaskSchemaSummary, PlaybookSummary, and ArtifactClusterSummary types from @hippocortex/fingerprint.

4. Behavioral Patterns

The behavioral_patterns field captures observable agent behaviors:

{
  "tool_usage": {
    "total_calls": 0,
    "tool_frequency": { "tool_name": 0 },
    "avg_success_rate": 0.0,
    "preferred_tools": ["string"]
  },
  "decision_patterns": {
    "total_decisions": 0,
    "avg_confidence": 0.0,
    "correction_rate": 0.0,
    "top_decision_domains": ["string"]
  },
  "error_patterns": {
    "total_errors": 0,
    "recovery_rate": 0.0,
    "common_error_types": { "error_type": 0 },
    "avg_recovery_time_ms": 0
  },
  "session_patterns": {
    "avg_session_length": 0,
    "avg_events_per_session": 0,
    "total_sessions": 0
  }
}

5. Graph Digest

The graph_digest field provides structural statistics about the knowledge graph without exposing raw entities:

{
  "entity_count": 0,
  "relation_count": 0,
  "entity_type_distribution": { "type": 0 },
  "relation_type_distribution": { "type": 0 },
  "avg_entity_confidence": 0.0,
  "avg_relation_weight": 0.0,
  "top_connected_entities": [
    { "name": "string", "type": "string", "connection_count": 0 }
  ],
  "max_depth": 0
}

This maps directly to the existing MemoryGraphDigest type.

6. Semantic Summary

{
  "promoted_count": 0,
  "tentative_count": 0,
  "deprecated_count": 0,
  "contradicted_count": 0,
  "type_distribution": { "type": 0 },
  "extraction_method_distribution": { "method": 0 },
  "avg_promoted_confidence": 0.0,
  "avg_observation_count": 0.0
}

Maps directly to the existing SemanticMemorySummary type.

7. Context Priors

The context_priors field provides default hints for context assembly when restoring from a fingerprint:

{
  "preferred_sections": ["string"],
  "section_weights": { "section": 0.0 },
  "default_token_budget": 0,
  "priority_artifact_ids": ["string"],
  "priority_tags": ["string"],
  "suppressed_tags": ["string"]
}

These priors are advisory — the context assembly system MAY override them based on the current query.

8. Hierarchical Compression

Fingerprints support three compression tiers to trade off fidelity vs. size:

Tier	Target Size	What's Included
`full`	< 100 KB	All artifact summaries, all behavioral data, full graph digest
`compact`	< 50 KB	Top-N artifacts per type, aggregated behaviors, graph statistics only
`minimal`	< 10 KB	Cluster summaries only, key metrics, no individual artifacts

Compression Rules

Artifact deduplication: Artifacts with identical content_hash are collapsed
Cluster collapsing: Related artifacts (shared tags, similar titles) are merged into clusters
Truncation: At compact tier, keep top 20 artifacts per type by confidence × observed_count
Aggregation: At minimal tier, replace individual artifacts with statistical summaries

9. Compiler State

Optional snapshot of the adaptive compiler's parameters:

{
  "total_parameters": 0,
  "adapted_parameter_count": 0,
  "global_freeze": false,
  "adapted_parameters": [
    {
      "parameter": "string",
      "current_value": 0.0,
      "baseline_value": 0.0,
      "delta": 0.0,
      "adaptation_count": 0,
      "frozen": false
    }
  ],
  "adaptive_schema_version": 0
}

Maps directly to the existing CompilerStateSummary type.

10. Export Envelope

Fingerprints are wrapped in an export envelope for transfer:

{
  "format": "hmx-fingerprint",
  "envelope_version": 1,
  "hmx_version": "HMX-1.0",
  "fingerprint": { "..." },
  "exported_at": "ISO-8601",
  "integrity_hash": "sha256-hex",
  "exported_by": "string"
}

Integrity Verification

Extract fingerprint from envelope
Verify fingerprint.fingerprint_hash against recomputed hash
Verify envelope.integrity_hash against SHA-256 of serialized fingerprint
Both hashes MUST match for a valid import

11. Generation

Input Requirements

To generate a fingerprint, the system needs:

All active compiled artifacts (from compiler repository)
Knowledge graph snapshot (entities + relations)
Semantic memory statistics (counts, distributions)
Telemetry data (tool usage, error patterns)
Compiler adaptive state (if adaptive compilation is enabled)

Algorithm

function generateFingerprint(sources):
  1. Summarize each artifact type → artifact_summaries
  2. Cluster related artifacts → cluster_summaries
  3. Aggregate telemetry → behavioral_patterns
  4. Digest graph structure → graph_digest
  5. Summarize semantic layer → semantic_summary
  6. Extract context priors from retrieval history → context_priors
  7. Snapshot compiler state → compiler_state
  8. Apply compression tier
  9. Compute fingerprint_hash
  10. Return MemoryFingerprint

Determinism

Fingerprint generation MUST be deterministic:

Same set of artifacts → same artifact_summaries
Same graph state → same graph_digest
Deterministic JSON serialization for hashing
Sorting: artifact summaries sorted by artifact_id, entities by name

12. Restore

Restoring from a fingerprint primes an agent's memory system:

Validate the envelope integrity (§10)
Import artifact summaries as seed knowledge
Configure context assembly with context_priors
Initialize compiler parameters from compiler_state
Log the import as a telemetry event

Restore is additive — it MUST NOT delete existing memories. Conflicts between imported and existing artifacts are resolved by the standard conflict resolution system.

13. Versioning

Field	Purpose
`hmx_version`	Protocol version (`HMX-1.0`)
`fingerprint_version`	Schema version of the fingerprint structure
`envelope_version`	Schema version of the export envelope

When importing:

If hmx_version is unsupported → reject
If fingerprint_version is newer → attempt best-effort import, warn on unknown fields
If fingerprint_version is older → apply migration transforms

14. Example Fingerprint

{
  "hmx_version": "HMX-1.0",
  "fingerprint_id": "fp-019e5a3b-9000-7000-8000-000000000001",
  "fingerprint_version": 1,
  "tenant_id": "tenant-acme",
  "created_at": "2026-03-14T03:00:00.000Z",
  "artifact_summaries": {
    "policy_set": [
      {
        "artifact_id": "art-001",
        "condition": "Database migration with large tables",
        "recommendation": "Use online migration tool",
        "scope": ["database"],
        "confidence": 0.92,
        "outcome_count": 8,
        "tags": ["database", "migration"]
      }
    ],
    "task_schema_set": [
      {
        "artifact_id": "art-002",
        "title": "Deploy to Staging",
        "steps": ["Validate manifest", "Check namespace", "Apply", "Verify"],
        "tools_used": ["kubectl"],
        "preconditions": ["kubeconfig set"],
        "postconditions": ["pods running"],
        "complexity": "medium",
        "success_rate": 0.87,
        "observed_count": 15,
        "confidence": 0.85,
        "tags": ["kubernetes"]
      }
    ],
    "playbook_set": [],
    "cluster_summaries": []
  },
  "behavioral_patterns": {
    "tool_usage": {
      "total_calls": 1250,
      "tool_frequency": { "exec": 450, "read": 380, "write": 220, "browser": 200 },
      "avg_success_rate": 0.94,
      "preferred_tools": ["exec", "read"]
    },
    "decision_patterns": {
      "total_decisions": 89,
      "avg_confidence": 0.78,
      "correction_rate": 0.12,
      "top_decision_domains": ["deployment", "debugging"]
    },
    "error_patterns": {
      "total_errors": 67,
      "recovery_rate": 0.91,
      "common_error_types": { "CommandFailed": 25, "TimeoutError": 18 },
      "avg_recovery_time_ms": 3500
    },
    "session_patterns": {
      "avg_session_length": 1800,
      "avg_events_per_session": 42,
      "total_sessions": 156
    }
  },
  "graph_digest": {
    "entity_count": 234,
    "relation_count": 567,
    "entity_type_distribution": { "tool": 45, "concept": 89, "project": 12 },
    "relation_type_distribution": { "uses": 120, "related_to": 200 },
    "avg_entity_confidence": 0.82,
    "avg_relation_weight": 0.71,
    "top_connected_entities": [
      { "name": "kubernetes", "type": "concept", "connection_count": 34 }
    ],
    "max_depth": 5
  },
  "semantic_summary": {
    "promoted_count": 145,
    "tentative_count": 23,
    "deprecated_count": 12,
    "contradicted_count": 3,
    "type_distribution": { "fact": 80, "procedure": 35, "preference": 20, "schema": 10 },
    "extraction_method_distribution": { "consolidation": 100, "inferred": 45 },
    "avg_promoted_confidence": 0.84,
    "avg_observation_count": 3.2
  },
  "context_priors": {
    "preferred_sections": ["procedures", "facts"],
    "section_weights": { "procedures": 1.2, "facts": 1.0, "episodes": 0.8 },
    "default_token_budget": 4096,
    "priority_artifact_ids": ["art-001", "art-002"],
    "priority_tags": ["kubernetes", "deployment"],
    "suppressed_tags": []
  },
  "fingerprint_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "metadata": { "generator": "hippocortex-v0.1" },
  "compression_tier": "full",
  "source_event_count": 6580,
  "source_artifact_count": 42
}

15. Size Constraints

Maximum fingerprint size: 100 KB (full tier), 50 KB (compact), 10 KB (minimal)
Maximum artifact summaries per type: 100 (full), 20 (compact), 0 (minimal)
Maximum top_connected_entities: 10
Maximum tags: 64