# Memory categories

Episodic raw turns plus five extracted experiential categories - identity, knowledge, context, instructions, uncertainty.

SurrealDB Agent Memory splits the **experiential** side of memory into **six** typed areas. Each has its own lifecycle, decay posture, and retrieval weighting. A parallel **[trace layer](/docs/agent-memory/architecture/traces-and-evolution.md)** records how memory was *used*.

The eight **pillars** are summarised in [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md).

## An example: four sentences about cats

The six categories are easier to remember if you map them to how you already classify speech:

| Sentence | Category in play |
| --- | --- |
| “I have a cat.” | **Identity** / **knowledge** about the speaker (present) |
| “I saw a cat last night.” | **Episodic** (the story) plus extracted **knowledge** with a past **valid time** |
| “House cats weigh about 4 kg.” | **Knowledge** at general scope - like a textbook fact, not “about Alice” |
| “I used to have a cat.” | **Knowledge** superseded in time - still stored, no longer current |

**Instructions** and **uncertainty** sit beside these: “always use cute nicknames for pets” is not a zoology fact; “Alice says 5 kg but the manual says 4 kg” becomes **uncertainty**, not a silent average. Together with [Tri-temporal model](/docs/agent-memory/architecture/tri-temporal-model.md), this is how SurrealDB Agent Memory keeps personal, general, and time-bound memories from blurring together.

## 1. Episodic - the raw conversational record

The ordered **session / turn** stream: what was said, in order, including **anaphora** (pronouns and references like “he” or “that project” that point back to something said earlier).

- Written **once**; not reconciled like extracted facts.
- May **age out** faster than derived beliefs.
- Browsed with [Sessions and turns](/docs/agent-memory/mental-model/sessions-and-turns.md) tooling.

## 2. Identity - who the principal is

Stable facts about the person or agent: “Alice is Head of Platform at Acme”, “King Charles III is head of state of the United Kingdom”. **Long retention**, high weight in profile summaries.

## 3. Knowledge - what the principal knows

Facts shared in conversation, distinct from uploaded manuals: “Alice is learning Rust”, “The Atlas launch is in Q3”. **Medium retention** - fades without reinforcement unless consolidated.

## 4. Context - what is happening now

The working set for **this** conversation: “Alice is debugging checkout today”, “We are reviewing the EU pricing page”. **Short retention**, replaced quickly.

## 5. Instructions - how to behave

Behavioural directives, not world facts: “always British English”, “never use my first name”, “keep answers under three bullet points”. Applied at **prompt assembly**, not generic retrieval.

## 6. Uncertainty - explicit gaps

Records when SurrealDB Agent Memory is not confident enough to commit: conflicting sources, weak extraction, or open questions. Surfaces “I’m not sure” instead of invented fill-ins.

## Reading them back

Every extracted attribute carries its `memory_category`, so anything that
assembles a profile should filter on it rather than treating all attributes
alike:

- **`identity`** and **`knowledge`** for anything that should stay true - a user profile, a character sheet, a summary someone will read next week.
- **`context`** for what is happening now - valuable for the current turn, misleading in a durable summary.

The split can be stark. Ingesting a novel chapter by chapter will tend to produce far more `context` attributes for protagonists against compared with `identity` and `knowledge`: things like `state_of_mind`, `physical_state` and `feeling`
against `occupation`, `eye_color` and `personality_trait`. When read as one undifferentiated set, that describes a mood; filtered to identity and knowledge, it describes a person.

Note that a `context` key can hold several live values at once. Transient states are written as they are observed, and a later value does not necessarily supersede an earlier one. As such, the "the current state" is not a single row. You can take the most recent by `created_at` (which is *known* time - the chapter, not the upload), or read the whole chain from `GET /entities/{type}/{name}/history/{key}` and pick from it.

## At a glance

| Category | Holds | Typical lifetime |
| --- | --- | --- |
| Episodic | Raw turns / transcripts | Short-to-medium |
| Identity | Stable facts about the principal | Long |
| Knowledge | Learned / shared factual context | Medium |
| Context | Current working state | Short |
| Instructions | Behaviour preferences | Until revoked |
| Uncertainty | Deliberate “we do not know” | Until resolved or superseded |

## Related reading

- [Eight pillars and six categories](/docs/agent-memory/architecture/eight-pillars-and-categories.md)
- [Sessions and turns](/docs/agent-memory/mental-model/sessions-and-turns.md)