rag-cpp turns into a conformant RCP/1 server with no glue code. RCP (Retrieval Context Protocol) is a JSON-RPC protocol for retrieval services; rag-cpp consumes the RCP C++ SDK directly — it does not reimplement the wire.
The server front-end (include/rag/rcp/) is a thin framework layer over the SDK:
- The handler is bound to the SDK's
Handlerconcept —static_assert(::rcp::Handler<EngineHandler>). If rag-cpp's handler ever drifts from the shape the SDK requires, it fails to compile. - Transports are the SDK's
rcp::serve_stdio/rcp::serve_http. - Capabilities are
::rcp::Capabilities; errors map torcp::errc. - Metadata filters are validated by
::rcp::filter::validateagainst the fields the server advertises — only filter evaluation is rag-cpp's own code, since the SDK can't know rag-cpp's metadata.
Where the SDK comes from at build time (CMake resolution order):
-DRAGCPP_RCP_SDK_DIR → a sibling ../rcp/sdk/cpp if present → FetchContent of
the pinned tag (RAGCPP_RCP_SDK_TAG). CI's pinned-sdk job builds against the
pinned FetchContent path with no sibling present — that's the build a stranger
gets.
Over stdio (one line):
#include <rag/rag.hpp>
#include <rag/rcp/rcp.hpp>
rag::Engine engine = /* built or opened */;
rag::rcp::serve_stdio(engine); // now an RCP/1 server on stdin/stdoutOver HTTP, with a fluent builder:
rag::rcp::ServerBuilder{engine}
.named("docs", "1.0")
.with_index(true) // expose index/add + index/delete
.with_graph() // expose graph/* (GraphRAG)
.with_feedback() // accept relevance feedback
.with_memory() // community-summary memory (HippoRAG-style)
.serve_http(8000);Or from the CLI (no code):
ragcpp serve corpus.ragdb --all --write # everything on, writable
ragcpp serve corpus.ragdb --http 8000 # HTTP instead of stdioSee The CLI for the full flag set.
Capabilities are derived from what you turned on, so a client discovers exactly what this server can do:
retrieve— always. Advertises the supportedmodes(hybrid / dense / sparse),max_k, and, when enabled, therewritemethods (hyde,multi-query) andreranksupport.rerank— listscross-encoder(if a reranker or rerank hook is set) andcolbert(if a token embedder is set).index—index/add(upsert, idempotent by id) andindex/delete(idempotent), whenwith_index.graph—graph/localandgraph/global, whenwith_graph.memory— community-level memory backed by the GraphRAG community structure, whenwith_memory.
A client can steer a single retrieve without touching shared server state
(which would be a data race, since the handler is used concurrently):
mode:"hybrid"(default),"dense", or"sparse".fusion_method:"rrf","weighted"(→ RSF), or default (→ convex). See Retrieval § Fusion.filter: a JSON filter tree (§8), validated against advertised fields.rewrite:"hyde"/"multi-query"when advertised.
Each such request runs on a locally-built pipeline rather than mutating the
shared Engine, so one client's ranking policy never leaks into another's
results.
The server is verified against the RCP spec's conformance suite:
python3 path/to/rcp/conformance/check.py -- ./build/cli/ragcpp serve corpus.ragdb --all --writerag-cpp is certified Level L2 (the suite reports the level and exits non-zero if any MUST check fails). CI runs conformance against the spec cloned at the same pinned tag on every push and weekly.
Every hit carries a citation — source (uri) plus startLine / endLine —
so a downstream generator can ground its answer and an auditor can trace every
claim back to an exact span. This is §7.7 / §14 of the spec; it's not optional
decoration, it's the point of a retrieval protocol.