# Instructions and uncertainties

How SurrealDB Agent Memory captures behavioural directives and tracks 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.

### Revoking instructions

When a user reverses a directive (“stop using bullet points”), SurrealDB Agent Memory **deactivates** the matching instruction rather than deleting it. History of what was asked - and when it was revoked - remains available for audit.

### Using instructions in your agent

Active instructions appear in **`GET /profile`** ( **`instructions`** section) and **`POST /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/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 **`POST /state`** under **`unknowns`**:

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

### 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/reasoning/extraction-pipeline.md)
- [Authority when pillars meet](/docs/agent-memory/reasoning/authority-hierarchy.md)
- [Profiles](/docs/agent-memory/operations/profiles.md)
- [REST API - state and profile](/docs/agent-memory/reference/rest-api.md)