yvgude--lean-ctx/docs/specs/context-package-v2.md

.ctxpkg v2 Specification

Version: 2.0.0 Status: Draft Date: 2026-05-22

1. Overview

.ctxpkg v2 is an open, graph-native package format for portable AI-agent context. It extends .ctxpkg v1 with a knowledge graph core, typed relationships, activation energy (Phi scoring), Hebbian edge weights, temporal decay, and composability through graph-merge operations.

Key claims:

• .ctxpkg is to AI context what npm packages are to code: portable, versioned, composable, and installable.
• .ctxpkg is complementary to MCP (runtime), A2A (communication), and KCP (discovery).

2. File Format

A .ctxpkg file is a JSON bundle (with optional zstd compression in future versions):

{
  "manifest": { ... },
  "content": { ... }
}

In the future, .ctxpkg files MAY transition to ZIP-based archives:

my-package.ctxpkg (ZIP)
├── ctxpkg.json           # Manifest
├── graph.json             # Knowledge Graph
├── blobs/                 # Content-addressable large objects
│   ├── sha256-abc123...
│   └── sha256-def456...
└── rebuild.json           # Optional: Rebuild instructions

3. Manifest (ctxpkg.json)

3.1 Required Fields

Field	Type	Description
schema_version	u32	2 for v2 packages
name	string	Package name, allows @scope/name format
version	string	SemVer version string
description	string	Human-readable description
created_at	datetime	ISO 8601 creation timestamp
layers	string[]	Legacy v1 layer names for backward compat
integrity	object	SHA-256 hashes and byte size
provenance	object	Tool name, version, project hash

3.2 v2-Specific Fields

Field	Type	Description
conformance_level	u32	1, 2, or 3
kind	string?	What the package delivers: context (default), skills, addon, grammar — see §3.4
scope	string?	Namespace prefix (e.g., @company)
graph_summary	object?	Node/edge counts, types, activation mean
marketplace	object?	Categories, badges, license

3.3 Example

{
  "schema_version": 2,
  "conformance_level": 2,
  "name": "@company/auth-service-context",
  "version": "1.3.0",
  "description": "Complete context for the auth service",
  "scope": "@company",
  "graph_summary": {
    "node_count": 342,
    "edge_count": 891,
    "node_types": ["fact", "gotcha", "decision", "code_symbol"],
    "activation_mean": 0.67,
    "freshness": "2026-05-20T00:00:00Z"
  },
  "dependencies": {
    "@company/base-architecture": "^2.0",
    "@verified/jwt-patterns": "^1.0"
  },
  "optional_dependencies": {
    "@verified/security-review": "^1.0"
  },
  "conflicts": ["@outdated/legacy-auth"],
  "provenance": {
    "tool": "lean-ctx",
    "tool_version": "3.7.0",
    "project_hash": "abc123..."
  },
  "integrity": {
    "sha256": "...",
    "content_hash": "..."
  },
  "signature": {
    "algorithm": "ed25519",
    "public_key": "...",
    "value": "..."
  },
  "compatibility": {
    "min_lean_ctx_version": "3.7.0",
    "agents": ["lean-ctx>=3.7", "cursor", "claude-code"],
    "v1_fallback": true
  },
  "marketplace": {
    "categories": ["security", "authentication"],
    "badges": ["verified", "enterprise"],
    "license": "proprietary"
  }
}

3.4 Package kinds (unified distribution)

Since spec revision 2.1 (2026-07), a package declares what it delivers via the optional kind field. This unifies the distribution of agent knowledge and agent capabilities under one format, one registry and one trust chain (design: docs/specs/unified-distribution-v1.md):

kind	Payload	Notes
context	knowledge/graph/session/patterns/gotchas layers	The default. Behavior of all pre-existing packages, unchanged.
skills	markdown/script documents as verified content blobs	Content only — no execution semantics in lean-ctx.
addon	embedded addon manifest + per-platform binary artifact references	Installs through the addon trust chain (capabilities, sandbox, binhash, revocation).
grammar	embedded grammar manifest (signed tree-sitter dylib references)	In-process loading ⇒ mandatory hash + signature.

Rules:

• kind defaults to context and writers MUST omit the field for that default — every pre-kind package stays byte-identical.
• Non-context kinds REQUIRE schema_version: 2; validators reject a v1 manifest carrying a non-default kind.
• Readers MUST tolerate unknown kind values by refusing installation with a clear "newer lean-ctx required" error (never by misinterpreting the payload).

4. Knowledge Graph (context_graph)

The knowledge graph is the core of a v2 package. It is stored in the content.context_graph field.

4.1 Format

{
  "format": "ctxpkg-graph-v2",
  "nodes": [...],
  "edges": [...]
}

4.2 Node Schema

Field	Type	Required	Description
id	string	yes	Unique node identifier within this package
type	string	yes	Node type (see taxonomy below)
content	string	yes	Node content / value
activation	f64	no	Activation energy (Phi), default 1.0
category	string?	no	Classification category
source	string?	no	Source session or origin
created_at	datetime?	no	Creation timestamp
decay_half_life_days	u32?	no	Temporal decay half-life in days
blob_ref	string?	no	Reference to content-addressable blob
file_path	string?	no	Associated source file
line_start	usize?	no	Start line in source file
line_end	usize?	no	End line in source file
confidence	f32?	no	Confidence score (0.0-1.0)
supersedes	string?	no	ID of node this supersedes

4.3 Node Type Taxonomy (extensible)

Category	Types
Semantic	fact, pattern, insight, convention
Memory	gotcha, decision, finding, episode
Structure	code_symbol, code_file, code_module, code_function, code_class
Session	session, task, evidence, procedure
Governance	policy, overlay, profile, slo
Event	bus_event, handoff, tool_call
Custom	Any string (vendor-extensible)

4.4 Edge Schema

Field	Type	Required	Description
from	string	yes	Source node ID
to	string	yes	Target node ID
type	string	yes	Edge type (see taxonomy below)
weight	f64	no	Edge weight, default 1.0
coactivations	u32	no	Hebbian co-activation counter
metadata	string?	no	Additional metadata

4.5 Edge Type Taxonomy (extensible)

Category	Types
Semantic	supports, contradicts, supersedes, elaborates
Causal	decided_by, caused_by, followed_by, tested_by
Structural	imports, calls, exports, contains, related_to, depends_on
Hebbian	co_activated (with weight + coactivations)
Dependency	depends_on, extends, conflicts_with

5. Conformance Levels

Three levels enable progressive adoption:

Level 1: Basic

Any tool can implement this in a single day.

• JSON manifest + flat nodes array (only id, type, content)
• No edges required
• Install = merge nodes as facts into agent context
• Target tools: Cursor, Claude Code, Copilot, Windsurf

Level 2: Graph

Requires graph-merge logic.

• Typed nodes + typed edges
• Dependency resolution (SemVer)
• Graph-merge composition with conflict detection
• Target tools: lean-ctx, advanced MCP servers

Level 3: Cognitive

Full lean-ctx cognitive state transfer.

• Activation energy (Phi scoring) on every node
• Hebbian edge weights + co-activation counters
• Temporal decay (nodes/edges age)
• Rebuild protocol for index reconstruction
• Overlay portability
• Target tools: lean-ctx (reference implementation)

6. Composition (Graph-Merge)

When installing multiple packages, contexts are composed using the Sheaf Gluing algorithm:

1. Union: All non-conflicting nodes (ID-based)
2. Edge Merge: Shared edges → weight averaging via f64::midpoint
3. Conflict Detection: Nodes with contradicts edges → warning
4. Activation Propagation: New edges from dependencies increase activation of connected nodes
5. Supersedes Resolution: If Package A node X supersedes Y, node Y is deactivated (activation = 0.0)

This is the Sheaf Gluing Operation: local sections (packages) glue to a global section (merged context) when compatibility conditions are met.

7. Scopes and Namespaces

@verified/       -- Verified by ctxpkg.com
@official/       -- Framework maintainers (React, Next.js, etc.)
@community/      -- Community-contributed
@<org>/           -- Private organization namespaces
@local/           -- Local/development packages

Package names follow the pattern @scope/name (e.g., @company/auth-service). Names without @ are treated as unscoped.

8. Multi-Scale Support

Scale	Example	Typical Size
Micro	@verified/react-hooks-gotchas	~10 nodes, ~5 KB
Topic	@verified/security-review-playbook	~100 nodes, ~50 KB
Project	@company/my-saas-project	~1000 nodes, ~500 KB
System	@company/platform-architecture	~5000 nodes, ~2 MB
Organization	@company/full-engineering-context	~50000 nodes, ~20 MB

9. Backward Compatibility with v1

v1 packages are interpreted as a graph without edges and with uniform activation:

v1 Source	v2 Graph Mapping
knowledge.facts[]	Nodes of type fact (activation: 1.0)
knowledge.patterns[]	Nodes of type pattern (activation: 1.0)
graph.nodes/edges	Nodes/edges with type mapping
session	Node of type session with blob_ref
gotchas[]	Nodes of type gotcha (activation: 1.0)

The manifest field compatibility.v1_fallback: true signals that this v2 package can be read as v1 (edges and activation are ignored).

10. Integrity

content_hash = SHA256(content_json_bytes)
sha256 = SHA256("{name}:{version}:{content_hash}")

The integrity algorithm is identical to v1. The content_json includes the context_graph field for v2 packages.

11. Signing

Ed25519 signatures. The signing message is:

SHA256("ctxpkg-sign-v1:{name}:{version}:{integrity.sha256}")

12. CLI Interface

# Level 1: Basics (Knowledge + Gotchas + Session)
lean-ctx pack create --name my-pkg --level 1

# Level 2: + Graph + Relations + Dependencies
lean-ctx pack create --name my-pkg --level 2

# Level 3: Complete Cognitive State
lean-ctx pack create --name my-pkg --level 3

# Scoped packages
lean-ctx pack create --name auth-service --level 2 --scope @company

# Install
lean-ctx pack install @verified/react-patterns
lean-ctx pack install ./colleague-project.ctxpkg

# Info (shows v2 graph summary)
lean-ctx pack info my-pkg

# Publish (coming soon)
lean-ctx pack publish --registry https://registry.ctxpkg.com

13. Scientific Foundations

The .ctxpkg v2 format is informed by research across multiple disciplines:

Discipline	Key Insight	Design Impact
Neuroscience (HeLa-Mem, Kairos, Synapse)	Episodic-semantic dual graph with Hebbian learning	Typed nodes (fact/decision/episode), co-activation edge weights
Physics (Thermodynamic Transformers)	Softmax as free energy minimum	Activation energy (Phi) = node importance
Information Theory (COMI, γ-Covering)	Marginal information gain	Edge weights encode relevance minus redundancy
Swarm Behavior (SwarmSys, SBP)	Pheromone traces with temporal decay	decay_half_life_days on nodes
Psychology (Extended Mind, Situated Cognition)	Knowledge inseparable from relational context	Graph preserves relational structure
Category Theory (Sheaf Theory)	Local-to-global semantic gluing	Package composition via sheaf-gluing algorithm

14. Ecosystem Positioning

.ctxpkg complements existing AI agent standards:

• MCP = how agents connect to tools (runtime, synchronous)
• A2A = how agents communicate with each other (tasks, events)
• KCP = how knowledge is structured for discovery (metadata)
• .ctxpkg = how context is packaged, shared, and composed (packaging, offline, composable)

Appendix A: Differences from v1

Aspect	v1	v2
Data model	5 static layers	Graph-native with typed nodes/edges
Composition	No merge semantics	Graph-merge with conflict detection
Dynamic state	None	Activation energy, Hebbian weights, temporal decay
Naming	Flat names	Scoped @org/name
Adoption path	All-or-nothing	3 conformance levels
Marketplace	None	Categories, badges, license