HMX-C: Context Pack Specification

Protocol: Hippocortex Memory Protocol (HMX)
Component: HMX-C (Context Packs)
Version: HMX-1.0
Status: Stable

1. Overview

An HMX Context Pack is the final structured memory payload delivered to an LLM agent for reasoning. It contains prioritized, token-budgeted, section-organized knowledge assembled from artifacts, semantic memories, episodic traces, and graph relations.

Context Packs are designed for:

Bounded size — hard token budget prevents context window overflow
Deterministic ordering — same inputs produce the same output order
Fast assembly — optimized for real-time agent interactions (< 100ms target)
Transparency — every included item traces to its source, with relevance scores and drop reasons

Relationship to Hippocortex Architecture

HMX Context Packs wrap and standardize the existing ContextPack and ContextPackEntry types from @hippocortex/types, and the AssemblyResult from @hippocortex/retrieval. The protocol adds workflow hints, decision constraints, and a standardized assembly metadata structure.

2. Context Pack Structure

2.1 Required Fields

Field	Type	Description
`hmx_version`	`string`	Protocol version (`"HMX-1.0"`)
`pack_id`	`string`	Globally unique pack identifier
`query_context`	`string`	The query or situation that triggered assembly
`entries`	`array`	Ordered list of context entries (see §3)
`token_budget`	`object`	Token budget allocation and usage (see §4)
`assembly_metadata`	`object`	How this pack was assembled (see §5)
`created_at`	`string`	ISO 8601 datetime
`metadata`	`object`	Extensible metadata

2.2 Optional Fields

Field	Type	Description
`tenant_id`	`string`	Tenant scope
`agent_id`	`string`	Agent this pack was assembled for
`session_id`	`string`	Active session
`workflow_hints`	`object`	Suggested next actions or workflow steps (see §6)
`decision_constraints`	`array`	Active decision policies that constrain agent behavior (see §7)
`dropped_entries`	`array`	Entries that were dropped during assembly (see §8)
`fingerprint_priors`	`object`	Context priors from an imported fingerprint
`tags`	`string[]`	Categorization tags

3. Context Entries

Each entry in the entries array represents a single unit of knowledge:

{
  "section": "string",
  "content": "string",
  "source_id": "string",
  "source_type": "string",
  "relevance_score": 0.0,
  "token_estimate": 0,
  "rank": 0,
  "provenance": {
    "origin": "string",
    "confidence": 0.0,
    "evidence_count": 0
  }
}

3.1 Sections

Entries are organized into sections that map to different types of knowledge:

Section	Description	Source Types
`core`	Core identity, always included	policy, entity
`goals`	Active goals and objectives	memory, artifact
`facts`	Verified factual knowledge	memory, entity
`episodes`	Relevant past interactions	episode
`procedures`	Known procedures and task schemas	artifact, memory
`graph_relations`	Knowledge graph relationships	relation, entity
`conflicts`	Active conflicts or contradictions	conflict
`evidence`	Supporting evidence	memory, episode
`workflow`	Workflow suggestions and next steps	artifact
`constraints`	Active decision constraints	artifact, policy

3.2 Source Types

Source Type	Description
`episode`	From episodic memory (EpisodeTrace)
`memory`	From semantic memory (MemoryObject)
`relation`	From knowledge graph (RelationEdge)
`conflict`	From conflict records
`policy`	From memory policies
`entity`	From knowledge graph (EntityNode)
`artifact`	From compiled artifacts

3.3 Ordering

Entries within a section are ordered by:

relevance_score descending
token_estimate ascending (prefer concise entries)
source_id ascending (deterministic tiebreaker)

Sections are ordered by priority:

core > constraints > goals > procedures > facts > episodes > graph_relations > workflow > conflicts > evidence

4. Token Budget

{
  "total_budget": 4096,
  "used": 3200,
  "remaining": 896,
  "truncated": false,
  "section_budgets": {
    "core": { "budget": 512, "used": 450 },
    "facts": { "budget": 1024, "used": 980 },
    "procedures": { "budget": 1024, "used": 800 },
    "episodes": { "budget": 768, "used": 600 },
    "graph_relations": { "budget": 512, "used": 370 }
  },
  "dropped_count": 5
}

Budget Rules

Hard limit: The total token count MUST NOT exceed total_budget
Section allocation: Each section receives a proportional budget based on configured weights
Overflow redistribution: Unused budget from one section MAY be redistributed to sections that need more
Minimum guarantee: Each non-empty section gets at least 1 entry regardless of budget
Truncation: If a single entry exceeds its section's remaining budget, it MAY be truncated with a [truncated] marker

5. Assembly Metadata

Describes how the pack was assembled for auditability:

{
  "assembly_strategy": "ranked",
  "ranking_weights": {
    "relevance": 0.4,
    "recency": 0.2,
    "provenance": 0.2,
    "salience": 0.2
  },
  "retrieval_sources": ["episodic", "semantic", "graph", "compiler"],
  "candidate_count": 150,
  "included_count": 42,
  "assembly_duration_ms": 45,
  "query_classification": {
    "intent": "procedural",
    "keywords": ["deploy", "staging"],
    "entities": ["kubernetes"],
    "time_ref": null
  }
}

Assembly Strategies

Strategy	Description
`ranked`	Standard relevance-based ranking with composite scoring
`recency_biased`	Prioritize recent events and memories
`breadth_first`	Maximize diversity across sections
`depth_first`	Deep dive into the most relevant section
`fingerprint_guided`	Use imported fingerprint priors to guide assembly

6. Workflow Hints

Optional suggestions for the agent's next actions:

{
  "suggested_next_steps": [
    {
      "description": "Verify deployment succeeded",
      "artifact_id": "art-002",
      "confidence": 0.85,
      "tools": ["kubectl"]
    }
  ],
  "active_task_schema": "art-002",
  "current_step": 3,
  "total_steps": 5,
  "blockers": []
}

Workflow hints are advisory — the agent MAY ignore them.

7. Decision Constraints

Active decision policies that constrain agent behavior:

[
  {
    "artifact_id": "art-policy-001",
    "condition": "Database migration on tables > 1GB",
    "constraint": "Must use online migration tool",
    "confidence": 0.92,
    "override_allowed": true
  }
]

Constraints with override_allowed: false represent hard rules that the agent SHOULD NOT violate.

8. Dropped Entries

Entries that were considered but excluded from the final pack:

[
  {
    "source_id": "mem-099",
    "source_type": "memory",
    "section": "facts",
    "relevance_score": 0.45,
    "token_estimate": 120,
    "drop_reason": "budget_exceeded",
    "rank": 43
  }
]

Drop Reasons

Reason	Description
`budget_exceeded`	Token budget for the section or total was exhausted
`low_relevance`	Score below minimum threshold
`duplicate`	Semantically duplicate of a higher-ranked entry
`deprecated`	Source artifact/memory is deprecated
`conflict`	Conflicts with a higher-confidence entry
`provenance_failed`	Source evidence could not be verified

9. ContextPack Mapping

HMX Context Pack Field	ContextPack Field	Notes
`pack_id`	`id`	Direct mapping
`query_context`	`queryContext`	Direct mapping
`entries`	`entries`	Extended with `rank` and `provenance`
`token_budget`	`tokenBudget`	Extended with section-level budgets
`created_at`	`createdAt`	Direct mapping
`metadata`	`metadata`	Direct mapping
`assembly_metadata`	(from AssemblyResult)	Promoted from retrieval layer
`workflow_hints`	(new)	Protocol extension
`decision_constraints`	(new)	Protocol extension
`dropped_entries`	(from AssemblyResult.droppedItems)	Promoted to pack level

10. Example Context Pack

{
  "hmx_version": "HMX-1.0",
  "pack_id": "pack-019e5a3b-a000-7000-8000-000000000001",
  "query_context": "Deploy the staging environment",
  "entries": [
    {
      "section": "procedures",
      "content": "## Deploy to Staging\n1. Validate manifest\n2. Check namespace\n3. Apply manifests\n4. Verify rollout\n5. (optional) Run smoke tests\nTools: kubectl, curl",
      "source_id": "art-002",
      "source_type": "artifact",
      "relevance_score": 0.92,
      "token_estimate": 85,
      "rank": 1,
      "provenance": {
        "origin": "compiler",
        "confidence": 0.85,
        "evidence_count": 15
      }
    },
    {
      "section": "constraints",
      "content": "POLICY: Always verify rollout status before reporting success",
      "source_id": "art-policy-005",
      "source_type": "artifact",
      "relevance_score": 0.88,
      "token_estimate": 25,
      "rank": 2,
      "provenance": {
        "origin": "compiler",
        "confidence": 0.90,
        "evidence_count": 8
      }
    },
    {
      "section": "episodes",
      "content": "Previous deployment (2026-03-12): namespace issue caused failure, resolved by creating namespace first",
      "source_id": "ep-045",
      "source_type": "episode",
      "relevance_score": 0.78,
      "token_estimate": 40,
      "rank": 3,
      "provenance": {
        "origin": "episodic",
        "confidence": 1.0,
        "evidence_count": 1
      }
    }
  ],
  "token_budget": {
    "total_budget": 4096,
    "used": 150,
    "remaining": 3946,
    "truncated": false,
    "section_budgets": {
      "procedures": { "budget": 1024, "used": 85 },
      "constraints": { "budget": 256, "used": 25 },
      "episodes": { "budget": 768, "used": 40 }
    },
    "dropped_count": 2
  },
  "assembly_metadata": {
    "assembly_strategy": "ranked",
    "ranking_weights": {
      "relevance": 0.4,
      "recency": 0.2,
      "provenance": 0.2,
      "salience": 0.2
    },
    "retrieval_sources": ["episodic", "semantic", "compiler"],
    "candidate_count": 35,
    "included_count": 3,
    "assembly_duration_ms": 12,
    "query_classification": {
      "intent": "procedural",
      "keywords": ["deploy", "staging"],
      "entities": ["kubernetes"],
      "time_ref": null
    }
  },
  "created_at": "2026-03-14T03:00:00.000Z",
  "metadata": {},
  "workflow_hints": {
    "suggested_next_steps": [
      {
        "description": "Check if staging namespace exists",
        "artifact_id": "art-002",
        "confidence": 0.85,
        "tools": ["kubectl"]
      }
    ],
    "active_task_schema": "art-002",
    "current_step": 1,
    "total_steps": 5,
    "blockers": []
  },
  "dropped_entries": [
    {
      "source_id": "mem-old-deploy",
      "source_type": "memory",
      "section": "facts",
      "relevance_score": 0.35,
      "token_estimate": 60,
      "drop_reason": "low_relevance",
      "rank": 36
    }
  ]
}

11. Performance Requirements

Metric	Target
Assembly latency (p50)	< 50 ms
Assembly latency (p99)	< 200 ms
Max entries per pack	500
Max pack size (serialized)	256 KB
Deterministic output	Same query + same state = identical pack

12. Size Constraints

Maximum pack size: 256 KB (JSON serialized)
Maximum entries: 500
Maximum dropped_entries: 100 (truncate oldest drops)
Maximum workflow_hints.suggested_next_steps: 10
Maximum decision_constraints: 20
Maximum tags: 64