Context Graph

01 Executive summary

What Context Graph is, and the one idea everything else hangs on.

Standard RAG retrieves text chunks; standard knowledge graphs store (subject, predicate, object) triples. Neither records why a relationship exists. Context Graph (CG) attaches a RelationContext (rc) to every edge — who approved it, why, via which channel, under which policy, for how long, with what evidence and confidence. The graph becomes a system of decision, not just a system of record, and you can query the lineage, not only the fact.

02 Components at a glance

Nine moving parts, nine jobs.

03 End-to-end architecture

From document (or live decision) to a grounded, decision-aware answer.

04 The quadruple & RelationContext

The data model that makes everything else possible.

A 5-field relation (no rc) gets relation_context = null — full backward compatibility with standard LightRAG extraction.

05 Ingestion: extract & emit

Two paths in; one graph.

Extraction format (6-field relation)

# standard LightRAG (5 fields)
relation<|#|>source<|#|>target<|#|>keywords<|#|>description
# Context Graph adds a 6th — a compact RelationContext JSON
relation<|#|>source<|#|>target<|#|>keywords<|#|>description<|#|>{"decision_trace":"…","approved_by":"…","confidence_score":0.95}

Emission (runtime, no document)

from lightrag.context_graph_types import RelationContext
rc = RelationContext(
    decision_trace="VP approved 20% discount; 5-yr relationship + competitive pressure",
    approved_by="Sarah Chen", approved_via="in_person",
    valid_until="2024-12-31", policy_ref="DiscountPolicy_Standard",
    quantitative_data="20% discount", confidence_score=0.97)
await cg.emit_decision_trace("Sarah Chen", "MegaCorp", "discount_approval", rc)

06 Querying & CGR3

Six retrieval modes for single-shot, CGR3 for multi-hop.

from lightrag import QueryParam
# standard query — rc enriches retrieved edges; annotated context by default
res    = await cg.aquery("Who approved discounts above 15% in Q3?", param=QueryParam(mode="hybrid"))
# CGR3 multi-hop
answer = await cg.cgr3_query("Are there precedents for waiving payment terms for a renewal?")

07 Decisions & precedents

The capabilities a flat graph can't offer.

These map to dedicated REST endpoints (§8): /graph/decision/emit, /graph/decisions/search, and /graph/decisions (filter by approver, channel, policy, confidence, date).

08 REST API reference

All endpoints are workspace-aware. CG-specific endpoints return 503 when USE_CONTEXT_GRAPH=false.

Standard (inherited from LightRAG)

Context Graph-specific CG

Governance & ingestion CG

Auth & workspace

Authenticate with X-API-Key; select the tenant with the LIGHTRAG-WORKSPACE header.

# query a specific workspace
curl -X POST http://localhost:9621/query \
  -H "X-API-Key: $LIGHTRAG_API_KEY" \
  -H "LIGHTRAG-WORKSPACE: company_acme" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who approved the MegaCorp discount?", "mode": "hybrid"}'

# CGR3 multi-hop reasoning
curl -X POST http://localhost:9621/cgr3/query \
  -H "X-API-Key: $LIGHTRAG_API_KEY" -H "LIGHTRAG-WORKSPACE: company_acme" \
  -d '{"query": "Precedents for waiving payment terms on a renewal?"}'

# filter decisions (illustrative params)
curl "http://localhost:9621/graph/decisions?approved_via=slack&min_confidence=0.8" \
  -H "X-API-Key: $LIGHTRAG_API_KEY" -H "LIGHTRAG-WORKSPACE: company_acme"

Exact request/response schemas live in lightrag/api/routers/context_graph_routes.py; payloads above are illustrative.

09 MCP server

The same capabilities as tools for MCP-speaking agents.

When enabled (ENABLE_MCP=true, default), the server mounts a Model Context Protocol sub-app exposing 8 tools, each wrapping one rag method. It uses FastMCP(stateless_http=True), validates the X-API-Key header on the MCP sub-app, and tools that require CG mode raise an MCP error (not HTTP 503) when USE_CONTEXT_GRAPH=false. Workspace isolation is automatic via the parent app's middleware.

10 Storage & LLM providers

Four pluggable storage layers; multiple LLM/embedding backends.

11 Multi-tenancy (workspaces)

Per-request isolation — one deployment, many tenants.

Each company gets an isolated workspace selected by the LIGHTRAG-WORKSPACE request header. Isolation spans Neo4j nodes/edges (label-based), per-workspace indexes, vector collections, KV stores, doc status, LLM cache, and the decision-trace index.

# Neo4j: nodes carry a workspace label; queries + drops are workspace-scoped
MERGE (n:`company_acme` {entity_id: $id})
MATCH (n) WHERE n:`company_acme` …
MATCH (n:`company_acme`) DETACH DELETE n

Workspace names allow a-z A-Z 0-9 _ only.

12 Configuration

Key environment variables (full list in env.example / config.ini.example).

Run it

# server (port 9621)
lightrag-server
# dev with auto-reload
uvicorn lightrag.api.lightrag_server:app --reload
# tests
python -m pytest tests

13 Repository map

The Context-Graph surface on top of the LightRAG tree.

14 Glossary