Open File Format

A file format for
AI‑agent context

.ctxpkg packages project knowledge, domain expertise, policies, and patterns into portable files that agents can load, verify, and reuse.

terminal
$ lean-ctx pack create --name my-project --level 2

✓ Package created
  Name:   my-project
  Graph:  59 nodes, 12 edges
  Size:   28.9 KB
JWT RS256PostgreSQL 16Token race conditionRedis cacheStateless authPool limit = 20Event sourcingfactgotchadecision

What a .ctxpkg contains

A single JSON document: a manifest (metadata) and a knowledge graph. The graph captures facts, decisions, gotchas, code symbols, and their relationships.

Knowledge Graph

Typed nodes (facts, gotchas, decisions, symbols) connected by typed edges (supports, contradicts, depends on).

Activation Energy

Every node scored 0–1. Under token budgets, agents prioritize relevant nodes. Activation decays over time.

Composability

Multiple packages merge via graph union. Shared nodes update activation; conflicts surface via contradicts edges.

Integrity

SHA-256 composite hash + Ed25519 signatures verified on every load. Failures reject the file.

Three conformance levels

Not every tool needs the full graph. Three levels let any tool participate — from basic fact loading to complete context transfer.

1

Basic

Any JSON parser

Flat nodes, no edges required. A list of typed facts — knowledge, gotchas, decisions. Any tool that can read JSON can load a Level 1 package.

nodes only
2

Graph

lean-ctx, MCP tools

Typed nodes and typed edges. Relationships between context items preserved — supports, contradicts, depends on. Graph-merge composition with conflict detection.

nodes + edges
3

Cognitive

lean-ctx (reference)

Activation energy on every node. Weighted edges. Temporal decay based on creation date. Full cognitive state transfer between agents or sessions.

full state

Context needs trust

A context package can influence how an AI agent reasons, writes code, or follows policies. Verification is essential — every package is checked before it can be loaded.

Verification Pipeline
Package#SHA-256SignatureProvenanceVerified

Integrity

SHA-256 composite hash on every load

Signatures

Ed25519 authorship verification

Provenance

Tool, project, timestamp tracked

Freshness

Timestamps show context currency

How to package context

Use the lean-ctx CLI (recommended) or write the JSON by hand.

Recommended

With lean-ctx

terminal
# Install lean-ctx
$ curl -fsSL https://leanctx.com/install.sh | sh

# Create a package from your project
$ lean-ctx pack create \
    --name my-project \
    --level 2

Package created successfully:
  Name:     my-project
  Graph:    59 nodes, 12 edges
  Size:     28.9 KB

# Export to a portable file
$ lean-ctx pack export my-project \
    --output my-project.ctxpkg

# Share it — anyone can install it
$ lean-ctx pack import my-project.ctxpkg
$ lean-ctx pack install my-project
Manual

Write JSON directly

minimal.ctxpkg
{
  "manifest": {
    "name": "my-project",
    "version": "1.0.0",
    "description": "Project context",
    "conformance_level": 1,
    "created_at": "2026-05-22T00:00:00Z",
    "integrity": {
      "sha256": "...",
      "content_hash": "...",
      "byte_size": 0
    }
  },
  "content": {
    "context_graph": {
      "nodes": [
        {
          "id": "F1",
          "type": "fact",
          "content": "Uses PostgreSQL 16"
        },
        {
          "id": "G1",
          "type": "gotcha",
          "content": "Connection pool max is 20"
        }
      ],
      "edges": []
    }
  }
}

Where the project stands

Specification — Published as draft. Graph-native architecture, three levels.
lean-ctx — Reference implementation. Shipped in 3.6+.
Registry — In development at ctxpkg.com.
Third-party tools — Format is open. Contributions welcome.

Context is infrastructure

Context should be explicit, portable, inspectable, verifiable, reusable, and owned by the people who create it.