> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vocabulary: Facts & Records

> The nouns of your agent's world — every value it can know and every thing it can hold.

`vocabulary.yaml` declares the agent's typed vocabulary: **facts** (values the agent can know) and **records** (things it can hold instances of). Everything the agent decides is downstream of these — capabilities name the facts they need, policies gate on them, derivations compute them, and replies read them back.

## Facts

A fact is one typed value with a meaning:

```yaml theme={"dark"}
facts:
  - id: order.id
    type: text
    known_from: conversation
    ask_as: "Which order is this about — for example W-1042?"
    means: The order the caller wants help with.

  - id: order.total
    type: money
    known_from: source
    means: What the caller paid, including shipping.
```

| Key          | Purpose                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| `id`         | The fact's name — `order.total` scopes it to the `order` record              |
| `type`       | `text`, `enum`, `money`, `number`, `date`, `datetime`, `duration`, `boolean` |
| `means`      | What the value *is*, in words the caller could hear read back                |
| `known_from` | Where the value comes from — the most important line in the file             |
| `ask_as`     | The exact question to ask when the fact must come from the caller            |

**`known_from` is the seam between language and state.** It declares whether a value arrives from the host at session open (`given`), is said by the caller (`conversation`), is fetched from a system (`source`), or is computed from other facts (`derived`). Once a value is established, everything downstream of it — gates, arithmetic, branching — is deterministic.

Facts can also carry a shape check (`looks_like`), sensitivity flags (`sensitive`, `public: false`), and asking behavior (`never_ask`, `once`).

## Records

A record is a thing the agent holds instances of — an order, a claim, a booking — with a key, fields, and optionally a lifecycle:

```yaml theme={"dark"}
records:
  - id: order
    means: A purchase the caller made.
    key: order.id
    known_as: "the order, my purchase"
    states: [placed, shipped, delivered, returned]
    transitions:
      - { do: return-order, from: delivered, to: returned }
```

The record's fields are simply the facts scoped to it (`order.id`, `order.total`, …). The state machine — `states` and `transitions` — makes lifecycle rules enforceable: a transition that isn't declared can't happen. A record holding several rows at once (search results, a cart) is a **collection**.

## How the vocabulary is used

* **Capabilities** list the facts they `need` — the runtime establishes each one from its `known_from`, asking the caller only with that fact's `ask_as`.
* **Policies** gate on facts and record state: `requires: order.status is "delivered"`.
* **[Derivations](/overview/derivations)** compute new facts from existing ones — thresholds, eligibility, totals.
* **Replies** read facts back to the caller using their `means`, so the agent describes values the way the business does.

Declare a noun once, and every capability, gate, and reply speaks the same language.