01 Introduction

The Context Graph Protocol

An open wire protocol for context retrieval. A host asks providers for frames relevant to a goal, under a token budget; each provider returns frames that carry their own origin, their honest cost, and a human-readable citation label.

CGP specifies context retrieval: typed, budgeted, provenance-carrying, consent-gated, conformance-verified frames that a host composes into a prompt. The unit of exchange is a frame, never a blob. A frame states what it is, where it came from, what it costs, when it was true, and how to cite it.

The current revision is contextgraph/1.0. It froze on 2026-08-11. The specification, reference implementation, conformance suite, and SDKs are dual-licensed MIT OR Apache-2.0 and developed in the open at oxageninc/context-graph-protocol.

The seven guarantees

Every design decision in the protocol serves one of seven properties. They compose, and the combination is the point — remove any one and the trust model collapses back to the blob-pipe.

Provenance. Frames carry a chain of origin records — file, URI, range, digest, derivation method — so every passage in a prompt can be traced to its source.
Budget honesty. token_cost is computed by a canonical rule and the sum across frames must never exceed the query’s max_tokens. Hosts drop the frames of any provider that lies, with a loud report.
Consent enforcement. A provider declares its data flow — reads, writes, egress, egress scopes. A host must never auto-enable an egress provider or transmit a query before consent is recorded.
Conformance. “CGP conformant” is a machine-checked claim, not a self-attestation.
Citation. Every frame carries a human-readable citation_label, so the host can attribute what it used.
Version stability. Versions interoperate if and only if they share a major family; additive changes are minor.
Temporal validity. Frames may declare valid_from / valid_to, and queries may pin retrieval to an instant with as_of.

Scope: CGP and MCP compose

CGP does not specify tool invocation — that is the Model Context Protocol’s scope, and CGP will not absorb it. MCP connects tools: an action protocol. CGP connects context: a retrieval-evidence protocol. An agent needing both composes them — CGP frames feed the prompt, MCP tools do the work.

Frame content is untrusted data. A conforming host delimits frame content as quoted material, never as instructions — the same security principle that separates an email body from its headers. CGP makes that contract part of the protocol rather than leaving it to host discretion.

The shape of a session

A host opens with a handshake, the provider answers with its identity and capabilities, and only then do queries flow. Everything is a single JSON envelope per message.

Lifecycle

handshake  →  handshake_ack
query      →  frames        (repeated; correlated by id)
verify     →  verified      (optional, capability-gated)
shutdown

Versions

CGP has two version numbers, and each moves on its own schedule.

Protocol version. contextgraph/1.0 is what a host and a provider negotiate in the handshake. Rust code reads it from contextgraph_types::PROTOCOL_VERSION.
Crate version. The Rust crates are at 2.0.0 and follow semantic versioning for their Rust API.

Crate 2.0.0 speaks contextgraph/1.0. It changed the Rust API, when FrameKind became an open vocabulary, and left the bytes on the wire as they were. A change that breaks the wire needs contextgraph/2.0 and a new crate major together. No 1.x crate reached crates.io. The pre-freeze 0.1.x crates are still there and speak the same contextgraph/1 family.

The pre-freeze name of this revision, contextgraph/1.0-draft, is in the same family and still interoperates after the freeze. New implementations send contextgraph/1.0. docs/stability.md in the protocol repository has the full rules, and SDKs & host has the install commands.

Continue with Core concepts for the frame model, or jump straight to the SDK quickstarts to build a provider in TypeScript, Python, or Go.