Context

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.

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

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

Per-triple provenance:

• source_chunk_ids — chunk ids that grounded the fact
• source_session_ids — session ids tied to that triple

History-aware retrieve

There is no request flag for history mode. Query phrasing decides whether superseded / invalidated edges are included.

• Phrases that sound like timeline, contradiction, or prior state (e.g. "previously", "originally", "contradict", "walk me through the order") turn history mode on.
• Phrases that ask for current truth (e.g. "now", "currently", "latest", "after the update") keep history mode off, even if a history-looking word also appears.

Examples:

Event GraphRAG surfaces

Context retrieval expands beyond a single hop:

• Topics — soft groupings over related events (topics in the response).
• Paths — multi-hop walks across event hubs (paths).
• Cross-event bridges — controlled by cross_event_bridges (default 3). Higher values can surface more multi-hop links at some latency cost.
• Provenance — chunk and session ids on triples plus graph_session_ids / source_passages so 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:

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

• Structured ingestion
• Ranked Search
• Entity synergies