Struct Fact 

pub struct Fact {
    pub id: String,
    pub name: String,
    pub description: String,
    pub experimental_searchable_description: Option<String>,
    pub tags: Vec<String>,
    pub metadata: HashMap<String, Vec<String>>,
    pub body: String,
    pub pin: PinMode,
}

A fact registered for grounding — constant, declarative context an agent needs to have on hand (a barbershop’s address and hours, a brand’s voice). The push-path analog of a crate::Skill: where a skill is a playbook the agent pulls and runs on demand, a fact is content the grounding layer pushes into the context so the model is never missing it.

name, the effective searchable description, and tags drive ranking exactly as on a crate::Skill. The description component defaults to Self::description and can be replaced by Self::experimental_searchable_description, so the retrieval-gated tier is discoverable by query. body is the injected content — not indexed, so a long body never skews relevance. pin splits the tiers (see PinMode); metadata is free-form, non-indexed context for higher-layer biasing, never matched as query terms.

Fields

id: String

Stable identifier, returned in crate::FactHit::fact_id and stamped on the grounding trace events. Registering the same id again replaces the entry in place. Not indexed for ranking.

name: String

Short name. Indexed both verbatim and identifier-split, so snake_case/camelCase/kebab constituent words match.

description: String

What the fact is about — the primary ranking text (not the content itself; that is body).

experimental_searchable_description: Option<String>

Experimental replacement for the description component used by BM25 and dense retrieval. The fact name and tags remain indexed. None uses Self::description.

tags: Vec<String>

Author-declared labels and task phrases, indexed alongside the description.

metadata: HashMap<String, Vec<String>>

Free-form, non-indexed context for higher layers (push-path boosting/filtering); never matched as query terms.

body: String

The fact’s content — the payload injected into the context, not indexed (a long body would otherwise drown the description’s term weights).

pin: PinMode

Always-on vs retrieval-gated (see PinMode). Not indexed.