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:
GET /api/v1/{context_id}/profile{
"instructions": [
{
"label": "Bullet-point responses",
"description": "Always respond using bullet points, never flowing prose"
}
]
}See Profiles 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:
{
"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.