Understanding Context Packs

Overview of Context Packs

A Context Pack is the fundamental unit of storage in ContextSubstrate. It is an immutable, content-addressed manifest that captures the entire state of an AI agent's execution. By treating agent runs as versioned, hashable artifacts, ctx allows you to treat AI workflows with the same rigor as source code.

Every pack is stored in the .ctx/ directory as a collection of content-addressed blobs and a central JSON manifest.

Anatomy of a Pack

A Context Pack captures five primary dimensions of an agent's run:

1. Inputs & Prompts

This includes the raw materials provided to the agent:

• System Prompt: The core instructions defining the agent's persona and constraints.
• User Prompts: The sequence of messages or queries sent to the model.
• Input Files: Any files or data snapshots the agent "read" during execution. These are stored as blobs to ensure that even if the original file on disk changes, the pack preserves the exact version the agent saw.

2. Execution Steps

The Steps array is a chronological trace of the agent's internal logic and tool usage. Each step records:

• Tool Calls: Which tool was invoked (e.g., read_file, web_search) and with what parameters.
• Output: The raw response from the tool.
• Determinism: A flag indicating if the step is expected to produce the same result every time (critical for the replay engine).

3. Outputs

The final artifacts produced by the agent. Outputs are registered with a name and a content hash, allowing for Provenance Verification. You can use ctx verify <artifact> to prove that a specific file was generated by a specific Context Pack.

4. Model Configuration

To ensure reproducibility, packs store the exact model identifier (e.g., gpt-4o) and hyperparameters like temperature, top_p, and seed.

5. Environment Metadata

Packs capture the execution context:

• Runtime: OS and language versions (e.g., darwin, go1.22).
• Tool Versions: A map of specific versions for every tool the agent had access to, preventing "environment drift" where the same code behaves differently due to updated dependencies.

Content Addressing & Immutability

ContextSubstrate uses SHA-based content addressing. When you run ctx pack, the following happens:

1. Each unique string (prompts, tool outputs, files) is hashed and stored as a blob in .ctx/objects/.
2. A manifest is generated containing the hashes (references) to these blobs.
3. The manifest itself is hashed. This Pack Hash serves as the unique ID for the entire execution.

If a single character in a prompt changes, the resulting Pack Hash will be entirely different. This makes packs inherently immutable; you cannot "edit" a pack, you can only fork it to create a new one.

The ctx:// URI

Packs are referenced using a standard URI format: ctx://<hash>

You can use short hashes (e.g., the first 12 characters) in most CLI commands:

ctx show 58a6ff02

The Pack Lifecycle

Creation

Packs are typically created from execution logs generated by your agent framework.

ctx pack execution_log.json

Inspection & Debugging

You can view the structured contents of a pack to understand exactly why an agent made a specific decision.

ctx show <hash>

Comparison (Drift Detection)

One of the most powerful features of Context Packs is the ability to diff two executions. The diff engine identifies specific types of "Drift":

• Prompt Drift: Changes in system or user instructions.
• Tool Drift: Changes in which tools were called or the order of calls.
• Param Drift: Changes in the arguments passed to tools.
• Reasoning Drift: The model produced different logic/output despite identical inputs.

ctx diff <hash-a> <hash-b> --human

Replay

Because a pack contains the inputs and environment metadata, the ctx replay command can attempt to re-execute the agent run step-by-step to verify that the results are consistent with the original recording.

Technical Manifest Structure

For developers integrating directly with the substrate, the underlying manifest follows this structure:

{
  "version": "0.1",
  "hash": "sha256:...",
  "created": "2023-10-27T10:00:00Z",
  "model": {
    "identifier": "gpt-4",
    "parameters": { "temperature": 0 }
  },
  "system_prompt": "blob_hash_1",
  "prompts": [
    { "role": "user", "content_ref": "blob_hash_2" }
  ],
  "steps": [
    {
      "index": 0,
      "type": "tool_call",
      "tool": "read_file",
      "parameters": { "path": "config.yaml" },
      "output_ref": "blob_hash_3",
      "deterministic": true
    }
  ],
  "environment": {
    "os": "linux",
    "runtime": "go1.22",
    "tool_versions": { "read_file": "1.0.2" }
  }
}