> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Instructions and uncertainties

How behavioural directives are captured and tracked. Including ambiguous or contradictory information.

Not everything in a turn is a fact about the world. Some statements tell the agent **how to behave**; others cannot be interpreted confidently. SurrealDB Agent Memory stores these as **instructions** and **uncertainties** - separate from ordinary attributes.

## Instructions

An **instruction** is a persistent behavioural directive extracted from conversation:

- “Always respond in bullet points.”
- “Never use technical jargon.”
- “From now on, label sarcasm when you detect it.”
- “Keep responses under three sentences.”

Instructions are **active constraints** the agent should honour on subsequent turns within the relevant **scope**, not one-off preferences buried in an attribute.

### When a user reverses an instruction

Instructions are not revoked or superseded. When a user reverses a directive (“stop using bullet points”), the reversal is extracted as a **new active instruction**, and the earlier one stays active beside it. Your agent sees both in the profile and has to decide between them, for example by preferring the more recent one.

The only time an instruction is deactivated is when it is a duplicate: a restatement with the same label and description (compared without case) in an overlapping scope merges into the existing instruction instead of creating a second one.

### Using instructions in your agent

Active instructions appear in **`GET /profile`** ( **`instructions`** section) and **`GET /state`**. Fetch a profile before assembling a system prompt:

```http
GET /api/v1/{context_id}/profile
```

```json
{
  "instructions": [
    {
      "label": "Bullet-point responses",
      "description": "Always respond using bullet points, never flowing prose"
    }
  ]
}
```

See [Profiles](/docs/agent-memory/memory-and-knowledge/operations/profiles.md) for the full profile shape.

---

## Uncertainties

An **uncertainty** is recorded when extraction cannot commit to a single interpretation. The pipeline stores **what** was ambiguous and **why**, instead of guessing.

Common triggers:

- A statement followed by a contradictory correction (“I'm CEO - well, co-CEO, it's complicated”)
- Ambiguous references when several entities are in scope
- A claim that contradicts existing memory with no clear winner
- Temporal references that cannot be resolved to a date
- Sarcasm or humour that may or may not contain genuine information

### How uncertainties resolve

A later turn that clarifies the topic can resolve an open uncertainty automatically during extraction. Until then, the uncertainty stays visible so the agent can ask a follow-up question when appropriate.

Open uncertainties appear in **`GET /state`** under **`unknowns`**, as `about` and `reason` only. To read the full record, including whether it is resolved, use `GET /uncertainty`:

```json
{
  "unknowns": [
    {
      "about": "job title",
      "reason": "User joked about being CEO, then appeared to correct themselves"
    }
  ]
}
```

### Uncertainties and partial extractions

SurrealDB Agent Memory may still write a **tentative** attribute when extraction is partial, linked to the same turn as the uncertainty. Default current-state queries include it; applications that need higher confidence can treat attributes with open uncertainties on their source turn as lower trust until resolved.

## Related reading

- [Extraction pipeline](/docs/agent-memory/memory-and-knowledge/reasoning/extraction-pipeline.md)
- [Authority when pillars meet](/docs/agent-memory/memory-and-knowledge/reasoning/authority-hierarchy.md)
- [Profiles](/docs/agent-memory/memory-and-knowledge/operations/profiles.md)
- [REST API - state and profile](/docs/agent-memory/reference/rest-api.md)
