📐 Spec

Spec-07-Recall-Pipeline

3 min readSpec contributor · SDK authorDraft · v0.9.0aN

What this spec defines

The supported recall path: query filtering, scope and garden authorization, scoring inputs, result packing, and the boundary between basic recall and deferred advanced graph/embedding features.

Extraction status

This file contains the ADR-010 prose extraction for the basic recall pipeline. Advanced graph traversal, subscriptions, memory cards, and provenance walks remain experimental or separately assigned.

Recall inputs

Recall begins with caller-supplied filters such as entity, relation, source, scope, confidence threshold, and optional garden id. Implementations MUST apply normalization and authorization before ranking or returning results.

The recall pipeline MUST NOT rank or pack facts the caller is not authorized to read.

Scope and garden ACL are filters, not score penalties.

Authorization order

Implementations MUST enforce:

1. Caller identity and read permission.
2. Scope visibility.
3. Garden ACL for garden-tagged facts.
4. Tombstone, quarantine, or sanitizer suppression when those components are active.

Only surviving facts may enter scoring.

Scoring inputs

Basic recall MAY combine:

Lexical match

Semantic match

When embeddings are enabled.

Graph adjacency

When the graph index is enabled.

Source trust

Confidence

Recency or decay

Contradiction state

Garden tier

The result score is local and derived.

Peers MUST NOT be allowed to supply an authoritative score in federated fact payloads.

Low-trust and quarantine interaction

Low-trust source handling belongs to federation trust and quarantine specs, but recall must honor their outputs. Facts admitted to quarantine gardens SHOULD be excluded or down-ranked unless the caller explicitly has quarantine visibility and the route semantics allow inspection.

Packing

When recall is used to feed an agent context window, implementations SHOULD pack results to preserve diversity and avoid spending the entire budget on near duplicates. Entity-centric recall MAY disable diversity packing and return the top facts for that entity.

Packing MUST preserve authorization decisions.

A packed summary MUST NOT reveal the existence of unauthorized facts.

Response shape

RecallResponse {
  results:      RecallResult[]
  generated_at: ISO 8601 UTC
  query:        object
}

RecallResult {
  fact:  FactRecord
  score: number
  why:   string[]?
}

Exact route shape is owned by Spec-03-HTTP-API.

Out of scope

This spec does not define:

Advanced recall graph

Spec-X11-Recall-Graph.

Subscriptions

Spec-X7-Subscriptions.

Lazy instruction recall

Spec-X1-Lazy-Instruction-Discovery.

Synthesis

Spec-X10-Synthesis.

Adapter context injection

Adapter ABI, component ID TBD.