Secure retrieval and GraphRAG

Secure retrieval makes authorization part of candidate generation. Evidence outside the caller's current Knowledge Asset scope cannot affect ranking, graph traversal, or the model prompt.

Retrieval flow

The application executes these stages in order:

1. Resolve scope. The signed-in actor and organization determine which stable Knowledge Asset IDs OpenFGA may return.
2. Pin current state. Canonical SQL verifies lifecycle, current source revision, ACL generation, publication state, projection generation, embedding model, and retrieval profile.
3. Retrieve authorized candidates. The selected engine searches only evidence contributed by the authorized Assets.
4. Rank and budget context. The server expands, merges, and ranks the candidates, then applies one token budget across entities, relations, and chunks.
5. Close and recheck evidence. The budget-selected grounding becomes a complete evidence closure. OpenFGA BatchCheck and the canonical ledger must still agree for every item in it.
6. Build the prompt. Citation references are assigned and only the rechecked evidence reaches the model gateway.

This ordering prevents a denied chunk, hidden neighbor, node degree, edge weight, or entity description from influencing a visible result.

Choose the retrieval engine

The deployment selects one retrieval engine with orgmemory.assistant.retrieval-engine. This is an operator setting, not a request parameter.

Within GraphRAG, the server owns the mixed chunk-and-graph plan. A client cannot select an internal query mode or weaken the authorization stages.

How GraphRAG works

OrgMemory implements a LightRAG-inspired pipeline with LightRAG v1.5.4 as its pinned semantic comparison baseline, not as a wire-compatible dependency. The GraphRAG engine always uses a server-owned MIX plan: one query combines entity, relation, and chunk retrieval instead of choosing only one view of the knowledge.

Build the graph from evidence

1. Chunk the current source revision. Each chunk keeps its source span and Knowledge Asset identity.
2. Extract entities and relations. The extraction model returns typed entities and relations with descriptions, keywords, orientation, weight, and confidence. Token and response guards bound every extraction round.
3. Resolve canonical identities. Equivalent names and endpoints map to stable organization-scoped graph identities. Their descriptions are not collapsed into one authorization-free summary; each source remains an immutable contribution.
4. Publish a complete generation. Chunk, entity, and relation vectors are associated with the same source revision, ACL coordinate, extraction profile, and publication generation. A partial graph never becomes the current read generation.

Run one mixed query

The server prepares keyword planning and embeddings once for the logical request, then executes three internal branches:

For example, a question about which suppliers depend on Project Atlas may produce low-level terms such as Project Atlas and supplier, while a high-level term such as dependency targets relationship descriptions. These are planning signals, not filters supplied by the client. If planning returns no usable graph keywords, direct chunk retrieval can still provide evidence; the engine does not invent graph seeds.

The local branch performs a bounded walk from entity seeds and loads their incident relations. The global branch keeps the relation seeds and their endpoint entities. After merging those graph results, the engine selects supporting chunks: source chunks whose contributions support the selected entities and relations. It interleaves and deduplicates those chunks with the direct vector results. A configured reranker may reorder only the already-authorized chunks; entity and relation ordering remains part of the graph result.

Without a reranker, chunks are interleaved round-robin in direct, entity, relation order and deduplicated by chunk ID. Across Knowledge Spaces, entities, relations, and chunks are merged by their stable IDs, then ordered by score, original branch order, and stable ID for deterministic tie-breaking.

The grounding assembler applies separate token caps to the already-ordered entity and relation lists, then gives the remaining total allowance to chunks. Allocation keeps whole items and stops a list at the first item that would cross its cap. The resulting budget-selected grounding defines the evidence closure that the application rechecks before rendering the prompt.

These branches are internal mechanics, not public query modes. OrgMemory does not expose LightRAG's local, global, hybrid, naive, or mix choices to a client. The application fixes GraphRAG to MIX so every branch receives the same authorization snapshot, limits, model profile, and failure policy.

Adapt LightRAG to governed memory

The pinned LightRAG baseline exposes query modes and aggregates graph descriptions for retrieval. The repository records the exact upstream revision in its parity oracle test. OrgMemory keeps the retrieval technique but changes its trust boundary:

• entity and relation descriptions remain evidence contributions tied to source chunks and Knowledge Assets;
• keyword seeds, vector candidates, graph neighbors, degrees, and relation weights are computed only from the authorized projection;
• graph expansion is depth- and result-bounded;
• the complete selected closure is checked again before prompt construction;
• source updates publish a complete immutable generation before it can replace the current read generation.

Evidence remains Asset-scoped

Graph entities and relations do not have independent ACLs. Their descriptions, keywords, confidence values, and links remain attached to immutable evidence contributions that identify the source chunk, Knowledge Asset, source revision, ACL coordinate, model, prompt, and extraction time.

GraphRAG filters those contributions to the authorized Asset scope before it uses them for traversal or ranking. Structured contributions remain intact until the renderer applies one model-context budget across the selected Knowledge Spaces.

Default graph-store boundary

The reference deployment selects the PostgreSQL GraphStore. In that configuration, PostgreSQL owns graph identities, contributions, publication heads, entity and relation vectors, and the live traversal path. Bounded graph walks run as recursive SQL over contribution-filtered relations.

Neo4j can replace that GraphStore when its adapter is explicitly enabled; it does not replace PostgreSQL's canonical application and authorization ledger. OpenSearch implements the publication projection contract, but it is not the live GraphRAG read path in the reference deployment.

Every adapter returns candidates, not authorization decisions. The application rechecks the complete evidence closure against the canonical ledger before any candidate can enter a model prompt.

Authorization is stable for one turn

The snapshot boundary separates two cases: an authorization change detected before the snapshot is finalized triggers a retry, while a change after finalization applies to later turns and citation opens.

After ranking the already authorization-scoped candidates, the application BatchChecks and re-reads the complete chunk, entity, and relation closure. Organization, OpenFGA model, ACL snapshot, source revision, and projection generation must still match. If authorization changes during retrieval, the request retries exactly once without sending evidence to the model. A second change fails the request closed.

The verified closure becomes an immutable snapshot for that Assistant turn. Revocation applies to the next turn. An already-started turn may finish under its snapshot and remains bounded by the configured turn timeout.

The snapshot governs model generation only. Opening a citation is a new access decision, so a citation may stop opening after access is revoked even when its originating turn was allowed to finish.

Citations are checked again

Only evidence that fits the final prompt budget receives a citation number. The browser makes interactive only the markers declared by the server. Opening a citation runs a fresh canonical access check, validates its source revision and blob integrity, and streams the original bytes through an authenticated no-store route. Missing, changed, corrupt, and denied citations return the same opaque response.

Limits and failure behavior

• a missing model route, mismatched immutable profile, malformed extraction, or failed snapshot closes the request;
• GraphRAG never silently falls back to canonical hybrid retrieval;
• reranking defaults off and cannot start without a named adapter;
• a transient reranker failure may retain the already-authorized order while emitting sanitized telemetry;
• one request may span at most 20 Knowledge Spaces and its complete evidence closure may contain at most 2,000 items;
• multi-space retrieval with reranking enabled is refused rather than running with ambiguous global ordering;
• an authorization mismatch, timeout, adapter failure, or malformed result in one Knowledge Space fails the complete multi-space request closed.