The Context Graph Protocol: A Technical Overview

A marketing overview written for engineers. If you want the deep research analysis, read Advantages and Uniqueness. If you want to build a provider today, read Implementing a provider. This page is the one-read explanation of what Context Graph Protocol is, why it exists, and why you would build against it.

The problem: your agent's context is an unaccountable blob-pipe

Every AI coding agent retrieves context. It runs a vector search, a grep, or a symbol lookup, and it pastes the result into the prompt. Then five questions have no answer:

• How many tokens did that cost? The agent guesses, or ignores it.
• Where did it come from? A file path, if you are lucky. A digest you can verify against disk, almost never.
• Did it leave the machine? If retrieval called a cloud embedding API, your workspace content was transmitted. There is no record that you agreed.
• Can the agent cite it? Only if it reconstructs a label from raw metadata.
• Is it still true? A snippet from a stale index may not match the file on disk anymore.

This is the blob-pipe: retrieval as an opaque firehose of text that nobody can account for. It works until the budget silently overflows, a provider lies about cost, workspace content leaks to a third party, or an auditor asks "where did this answer come from?" and there is no trail.

The Context Graph Protocol makes every one of those questions answerable. Not by convention, but by contract.

What Context Graph Protocol is, in one paragraph

Context Graph Protocol is an open wire protocol for context retrieval. It treats a piece of context as a typed, budgeted, provenance-carrying, consent-gated, and conformance-verified unit of exchange called a frame. 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. The host composes them into a prompt it can trust as evidence, not accept on faith. The protocol is three Rust crates you can build against today: contextgraph-types (the wire types, zero dependencies beyond serde), contextgraph-host (the host runtime), and contextgraph-conformance (the machine-checked conformance suite). All three are dual-licensed MIT OR Apache-2.0.

The seven guarantees

Context Graph Protocol makes seven promises about every frame that enters a prompt. Each one is a type in contextgraph-types and an enforcement path in contextgraph-host or contextgraph-conformance, not a line in a style guide.

The properties compose, and the combination is the point. Provenance without budget honesty means you can trace a frame but not control its cost. Budget honesty without consent means costs are honest but data can still leak. Remove any one and the trust model collapses back to the blob-pipe. That is why Context Graph Protocol is specified as one integrated protocol, not a menu of options.

The wire surface

Three shapes carry the whole protocol. Every one lives in contextgraph-types, round-trips through serde_json, and is the protocol. There is no separate IDL.

Capability (the handshake). A provider says who it is and what it does with data before a host sends it anything.

pub struct DataFlow {
    pub reads: bool,   // sees workspace content in query payloads
    pub writes: bool,  // persists writes
    pub egress: bool,  // sends anything off the local machine
}

egress is the security-critical field. A conforming host must not auto-enable a provider that declares egress: true. It gates that provider behind explicit, named, one-time consent. The HTTP transport goes further and treats every remote provider as egress, so a provider cannot lie its way past the gate.

Query (the request). A retrieval request that always carries a budget.

pub struct ContextQuery {
    pub goal: String,
    pub query_text: Option<String>,
    pub kinds: Vec<FrameKind>,   // empty means "your best frames of any kind"
    pub anchors: Vec<String>,    // open files, mentioned symbols
    pub max_frames: u32,
    pub max_tokens: u32,         // a hard contract, not a hint
    pub as_of: Option<String>,   // pin retrieval to a point in time
    // ...
}

Frame (the answer). The unit of exchange. A frame is not a string. It is a structured record of relevance, cost, provenance, and validity.

pub enum FrameKind { Snippet, Symbol, Fact, Doc, Memory, Episode, Graph }

pub struct ContextFrame {
    pub id: String,                  // stable, for dedup, never the on-screen label
    pub kind: FrameKind,
    pub title: String,               // human label, required
    pub content: String,             // untrusted data, host quotes it, never executes it
    pub score: f32,                  // relevance in [0, 1]
    pub token_cost: u32,             // honest, conformance-audited
    pub provenance: Vec<Provenance>,
    pub citation_label: Option<String>,
    pub valid_from: Option<String>,
    pub valid_to: Option<String>,
    // ...
}

Frame content is transported as untrusted data. A conforming host delimits it as quoted material and never treats it as instructions, the same way a mail client separates a message body from its headers.

How Context Graph Protocol relates to MCP

They are complementary, not competing. The Model Context Protocol (MCP) connects tools: functions an agent calls to take an action. Context Graph Protocol connects context: typed, budgeted, cited evidence a host composes into the prompt before the agent acts. MCP has no budget-honesty contract, no egress consent gate, no provenance chain, and no conformance suite, because those are outside its scope, not deficiencies in it. An agent that needs both composes them. Context Graph Protocol frames feed the prompt. MCP tools do the work.

Why you would build against it

• Any language, no lock-in. contextgraph-types depends only on serde. The barrier to writing a provider is a JSON codec and the wire table. In-process, over stdio, or over HTTP.
• Conformance is a test you run in CI. Point contextgraph-inspect at your provider. Green means it works with any Context Graph Protocol host. A broken provider is caught at CI time, not at integration time. The suite ships a --misbehave mode that trips every check on purpose, so you know the checks are real.
• Stability you can pin. The protocol version is contextgraph/1.0-draft. Two versions interoperate when they share a major family, the part before the first dot. So contextgraph/1.0-draft and contextgraph/1.0 both belong to family contextgraph/1 and interoperate. When the draft freezes, every deployed provider keeps working. No flag day.

Status

Context Graph Protocol is contextgraph/1.0-draft today. The wire types are stable enough to build against, the host runtime enforces the guarantees, and the conformance suite verifies them. The path from "open context as an idea" to "open context as a standard" is the conformance suite: anyone can build a provider, anyone can verify it, and the protocol evolves inside a stable family without breaking what is already deployed.

Start with Protocol surface to read the types, Implementing a provider to build one, and Running conformance to prove it.