📐 Spec

Recall Pipeline

2 min readRecall engineerSpec-X11

What this page covers

The recall pipeline retrieves semantically relevant facts for agent queries. It runs three independent retrieval stages, fuses their results with salience signals, and packs the output within a caller-specified token budget using Maximal Marginal Relevance (MMR).

Audience: engineers building recall-capable agents or contributing to the recall subsystem (Spec-X11-Recall-Graph).

Pipeline overview

Salience signals

Applied during the fusion step to adjust raw retrieval scores:

Signal

Range

Formula

Recency

(0, 1]

exp(-0.01 × age_days)

Confidence

[0, 1]

fact.confidence

Access frequency

[0, 1]

log(1 + access_count) / log(1 + max_access_count)

Contradiction penalty

{0.7, 1.0}

1.0 if no unresolved contradiction; 0.7 otherwise.

Garden tier

[0, 1]

Configurable per garden; quarantine default 0.2.

Source-trust multiplier

[0.5, 1]

0.5 + 0.5 × t (maps [0,1] → [0.5,1.0]).

Security: ANN scope filter

Stage 2 ANN results MUST be joined back against facts and filtered by the caller's scope and garden ACL before fusion.

vec_facts holds embeddings for all scopes with no scope column. Without this filter, facts from unauthorized gardens could leak into the response.

Example

curl -X POST http://localhost:8765/v1/recall \
  -H "Authorization: Bearer $KEY" \
  -d '{
    "query": "What is Alice'\''s current role?",
    "scope": "company",
    "token_budget": 2000,
    "weights": {"lexical": 0.3, "vector": 0.5, "graph": 0.2}
  }'