.ctxpkg

The open package format for portable, versioned, verifiable AI-agent context.

---

AI agents pull knowledge from READMEs, wikis, Slack threads, tickets, and previous sessions. This context is ephemeral, unversioned, and impossible to verify. Every agent starts from scratch.

.ctxpkg gives context the same rigor as code: packaged, versioned, verified, portable.

A .ctxpkg file is a single JSON file containing a manifest (identity + trust metadata) and content organized into typed layers. Any agent, editor, or runtime can load and verify it.

Quick look

{
  "manifest": {
    "schema_version": 1,
    "name": "security-review",
    "version": "1.2.0",
    "layers": ["knowledge", "gotchas"],
    "integrity": {
      "sha256": "a1b2c3...",
      "content_hash": "d4e5f6...",
      "byte_size": 48210
    }
  },
  "content": {
    "knowledge": { "facts": [...], "patterns": [...] },
    "gotchas": { "gotchas": [...] }
  }
}

Core properties

Property	Description
Portable	One file, any agent. No vendor lock-in.
Versioned	SemVer for knowledge. Track changes, diff, roll back.
Verifiable	SHA-256 integrity on every load. Tamper detection built in.
Layered	Five typed content layers. Agents load only what they need.
Open	Vendor-neutral. RFC-based governance. Open-source reference implementation.

Content layers

Layer	Purpose
knowledge	Domain facts, architecture decisions, patterns, best practices
gotchas	Known pitfalls, edge cases, severity, trigger conditions, resolution
graph	Property graph of code relationships (nodes, edges, kinds)
session	Task context, findings, decisions, next steps
policies	Security constraints, compliance rules, quality gates

Integrity

Every package carries a three-part integrity block that is verified on every load:

1. Content hash — SHA-256 of canonical JSON content
2. Composite hash — SHA-256 of name:version:content_hash
3. Byte size — exact byte length of canonical content

Optional HMAC-SHA256 signing is available for cross-machine transport via the A2A protocol.

Specification

The full manifest specification is in spec/manifest-v1.md.

Summary of manifest fields:

Field	Type	Description
schema_version	u32	Must be 1
name	string	[a-zA-Z0-9._-], max 128 chars
version	string	SemVer-compatible, max 64 chars
description	string	Human-readable summary
author	string?	Optional author
created_at	datetime	Creation timestamp (UTC)
layers	string[]	Non-empty, no duplicates
dependencies	object[]	Other packages this depends on
tags	string[]	Free-form tags
integrity	object	SHA-256 hashes and byte size
provenance	object	Tool, version, project hash, session
compatibility	object	Target languages, frameworks, min runtime
stats	object	Entry count and compression ratio

Reference implementation

LeanCTX provides the reference implementation with a full CLI:

lean-ctx pack create --name my-package    # Build from project
lean-ctx pack export my-package           # Export as .ctxpkg file
lean-ctx pack install my-package          # Apply to current project
lean-ctx pack send --target agent.local   # Share via A2A transport

Other implementations are welcome. The format is designed to be simple enough that any tool can read and write .ctxpkg files.

Registry

ctxpkg.com is the upcoming registry for discovering, publishing, and verifying context packages. Public registries for the community, private namespaces for teams.

Governance

CTXPKG is not owned by any single company. The specification evolves through open RFCs.

• No single vendor controls the spec
• Changes go through public RFCs in this repository
• Reference implementations are open-source
• Backward compatibility is a first-class concern

See GOVERNANCE.md for details.

Contributing

We welcome contributions to the specification, documentation, and example packages.

1. Open an issue or discussion for feedback
2. Submit RFCs as pull requests to spec/rfcs/
3. Share example packages in examples/

See CONTRIBUTING.md for guidelines.

Links

• Website — ctxpkg.org
• Registry — ctxpkg.com
• Reference implementation — LeanCTX
• Discussions — GitHub Discussions

License

This specification is released under CC BY 4.0. Reference implementations may use their own licenses.

---

Developed in Switzerland.