Concepts

Core concepts

Six ideas underpin everything else: Units, Locators, planes, modalities, scopes, and namespaces.

Unit#

A Unit is the atom of retrieval — one addressable piece of content such as a document chunk, an image region, a video shot, an audio utterance, or a log template. A Unit is stored in two places: a rich, filterable, BM25-able row in the SQL catalog, and a vector plus a small pushdown-metadata blob in the vector index.

a Unit (abridged)

{
  "unit_id": "u-call-02",
  "namespace": "acme-corp",
  "scope": "acme/alpha/backend",
  "root_source_id": "doc-earnings-call",
  "modality": "asr",
  "plane": "text",
  "text": "CFO: Total Q3 revenue came in at 412 million dollars...",
  "source_uri": "acme/alpha/backend/earnings/2026-q3-earnings-call.mp3#t=95",
  "locator": { "kind": "time_range", "t_start_ms": 95000, "t_end_ms": 121000, "speaker": "CFO" },
  "acl_owner": "alice@acme",
  "acl_groups": ["eng-backend", "finance"]
}

Locator#

The Locator is the differentiator: results point at the exact sub-unit span, not just a document id. A Locator is a discriminated union keyed on kind, with four variants:

kind	Addresses	Fields	Glyph
`time_range`	Audio / video moment	`t_start_ms, t_end_ms, speaker?, shot_idx?`	⏱
`bbox`	Image / page region	`box [x0,y0,x1,y1], page?`	□
`char_span`	Text passage	`byte_start, byte_end, page?`	¶
`line_range`	Code / log lines	`first_line, last_line`	≡

Planes & modalities#

A plane is a retrieval index family — one per modality family. Text is the universal join key: every encoder aligns to text, so a natural-language query fans out across the relevant planes and fuses at rank level.

text — chunks, captions, OCR, ASR transcripts.
visual — images and image regions.
audio — audio utterances.
doc_visual — document pages rendered as images.

A modality is the finer-grained type of an individual Unit — one of text, chunk, caption, ocr, asr, image, image_region, doc_page, video_shot, audio_utterance, log_template, detection.

Multimodal retrieval is live

All four planes are queryable — a single natural-language query fans out across text, visual, audio, and doc-visual and fuses the results. See Multimodal hybrid search for plane selection and modality filtering, and Cited answers for grounded synthesis over multimodal evidence.

Scopes & namespaces#

A namespace is the tenant / organization isolation boundary (for example acme-corp). A scope is a project partition below the namespace, written path-like (for example acme/alpha/backend). Scopes nest: a grant on a parent scope also grants its children.

Scope resolution

Requested scope — from X-Aegis-Scope / ?scope=, defaulting to your active scope.
Effective scope — the requested scope intersected with your allowed scopes. It can only ever narrow.
Requesting * expands to all of your allowed scopes.

See the full algorithm in the Security model.