Skip to content

Grounding

Grounding means giving an agent evidence from the tenant’s own corpus, so that it reasons over retrieved records rather than only its prompt. FACE’s grounding layer is ai.Store, and its retrieval is Direct Corpus Interaction (DCI): no embeddings and no vector index. Passages are stored as plain text, and a search reads those passages directly.

How a search works

Retrieval is lexical: a search matches the words of the query against the passages in the tenant’s own indexed corpus, scoped per tenant. Every result cites the passage it came from, with a score that says how much of the query the passage covers, from 0 to 1.

Retrieval tiers

MemoryStore.Ground tries three tiers in order and returns the first that answers:

    flowchart TD
    Q[Grounding request<br/>name + fingerprint] --> M{Exact memo hit?}
    M -- yes --> R1[Cached response]
    M -- no --> K[Tenant corpus search<br/>tenant scope]
    K -- hits --> R2[Top results]
    K -- no hits --> D{Operator corpus<br/>configured?}
    D -- yes --> G[Grep inside the<br/>operator corpus root]
    D -- no --> N[Empty: nothing cited]
  
  1. Memo cache. An exact (name, fingerprint) hit returns the stored response. No model call is needed.
  2. Tenant corpus. The search above runs over what FACE has indexed:
    • ingested documents (a files connection’s Index documents, on Settings › Integrations);
    • memoized answers;
    • fetch samples;
    • hypothesis simulations;
    • retained web research.
  3. Operator corpus. inference/dci greps the directory named by FACE_DCI_CORPUS_DIR. FACE reads that directory and never writes to it. If the variable is unset, this tier doesn’t search an empty directory: it doesn’t search at all, and nothing from it is cited as local evidence.

Store.GroundEvidence is the direct evidence lookup. The domain graph uses it for relevant documents, and the catalogue item resolver uses it too. It keeps two answers apart:

  • (nil, nil): the corpus was searched and has nothing to say.
  • ErrRetrievalUnavailable: the corpus could not be searched, because it is not open or the search itself failed.

Callers treat those two differently. “Our data says nothing” and “retrieval is down” lead to opposite actions.

Per-tenant scoping

Isolation is structural: each tenant has its own directory, and the tenant is fixed by the deployment the request reaches.

  • The corpus keeps one scope per tenant.
  • IndexDocument writes to the calling tenant’s scope. The tenant comes from the authenticated context, never from document metadata. A tenant key in metadata is dropped, so a document can’t re-scope itself.
  • A search reads only the scopes the caller is entitled to, and each search is confined by a sandbox.
  • A tenant id that can’t be used as a directory name is hashed into its own scope name. It never falls back to another scope.

Durability

Every passage is written to the blob store before it becomes searchable. With an object store configured, the passages live there. Without one, they go in a local directory with owner-only permissions (directories 0700, files 0600).

At start-up, FACE rebuilds the searchable copy from the blob store. A file that exists only in the local copy is never found. The corpus holds document text, so it is treated as customer data at rest. Security describes how it is sealed at rest.

Reading the results

  • A grounded answer is not a correct answer. Retrieval supplies context; the model can still misread it.
  • A hit is a word match, not a meaning match. A passage that says the same thing in other words is not found. Ask with the words the documents use.
  • Grounding is only as good as what was indexed. An empty corpus grounds nothing, and that is reported as an absence, not as a finding.