For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.
Context
Retrieve hybrid graph + passage context for a query
The context API (POST /retrieve/context) returns a hybrid pack of curated graph facts and source passages for a natural-language query. It is the primary retrieval surface for assistants, RAG, and benchmark harnesses.
For agents
POST /retrieve/contextwithBrainPAT; JSON body includestext,brain_id, optionalmax_facts,max_passages,use_ppr- Synchronous retrieve (not a 202 task) — use for RAG / assistant context packs
- Prefer this over plain
/retrievewhen you need both graph facts and passages
Usage
const result = await brain.retrieveContext({text: "Who's the CEO of Apple inc.?",brain_id: "example1",max_facts: 40,max_passages: 8,use_ppr: true,});Request body
Prop
Type
Response
text_context is a single string that mixes topic labels, [passage] lines, and fact lines. Structured fields carry the same evidence for clients that want typed access.
export interface GetContextTriple {identified_entity: string;triple: [EntityNode, Predicate, EventNode, Predicate, EntityNode];source_chunk_ids?: string[];source_session_ids?: string[];}export interface GetContextResponse {text_context: string;triples: GetContextTriple[];historical_context: string[];source_passages: string[];graph_session_ids?: string[];temporal_conflicts?: Record<string, unknown>[];paths?: Record<string, unknown>[];topics?: Record<string, unknown>[];stage_timings?: Record<string, unknown>;}Response field reference
Prop
Type
Per-triple provenance:
source_chunk_ids— chunk ids that grounded the factsource_session_ids— session ids tied to that triple
History-aware retrieve
POST /retrieve/context accepts an optional include_history boolean.
truereturns prior copies. Superseded source text is labeled[superseded], including older copies that search did not rank, up tohistorical_limit.falsereturns only the current copy.- Omit the field to decide automatically. The query embedding is compared with example questions in several languages. History is included only when the query is closer to the prior-version examples than to the current-value examples. If the embedding is unavailable, retrieve stays on the current copy.
There is no word list for this decision. The same question can be asked in another language.
Event GraphRAG surfaces
Context retrieval expands beyond a single hop:
- Topics — soft groupings over related events (
topicsin the response). - Paths — multi-hop walks across event hubs (
paths). - Cross-event bridges — controlled by
cross_event_bridges(default3). Higher values can surface more multi-hop links at some latency cost. - Provenance — chunk and session ids on triples plus
graph_session_ids/source_passagesso you can cite sources.
Tune max_facts, max_passages, and use_ppr for product latency; leave sufficiency_retry false unless you accept a second pass.
Passage retrieval mode
Context remains a prompt-ready evidence API even when Search is enabled. Search plugins, catalog mode, filters, facets, and personalized ranking do not run on this endpoint.
When SEARCH_ENABLED=false, Context preserves its historical passage behavior:
dense retrieval fused with the existing ILIKE lexical leg. The value of
CONTEXT_PASSAGE_MODE is ignored in that state.
When Search is enabled, CONTEXT_PASSAGE_MODE selects the passage legs:
| Mode | Passage retrieval |
|---|---|
hybrid | Dense + BM25, fused with RRF (default) |
bm25 | BM25 only; no query embedding for passages |
dense | Dense only |
ilike | Dense + legacy ILIKE lexical search |
This setting changes only the passage evidence inside Context. It does not
change graph fact retrieval or make the response equivalent to the ranked
/retrieve/search hit list.
Stage profiler
Set profile_stages: true on the request to receive stage_timings. Operators can also enable the server-side profiler with TRACE_STAGE_PROFILER_ENABLED (not in .env.example by default). See Installation.
Related
Last updated on
