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

# Entities with several names

How SurrealDB Agent Memory handles nicknames, titles, pen names, renames, roles and secret identities, and when to keep names separate, link them or write them as one.

This page explains what SurrealDB Agent Memory does when one person, place or organisation is known by more than one name, and how to decide what should happen to each case in your own data. The same thing can be called Bill, Billy and William, or change its name partway through a story, and each of those needs different handling.

## One entity for each name

An entity is identified by its type and its normalised name. Normalising removes differences of case, spacing and Unicode composition, and nothing more, and a new mention matches an existing entity only when the type and the normalised name are identical. So `Bill` and `William` become two entities, and so do `Robin` and `Robin Hood`.

That is often the right result. A name carries the context it is used in, and the facts that come with it differ from one context to another. What a person's school friends know about Billy is not what their bank knows about William.

Where two entities do refer to one thing, a `same_as` relation records it. It is an ordinary relation fact: extraction writes one when the source says two names are one referent, and you can write one yourself as a structured fact. Like any relation, it carries a known time and scopes, so an `asOf` query only sees it once it has been learned, and a reader only sees it within their own scopes. Both entities keep their own facts and are returned separately. Showing them as one is a decision for your application. See [Reconciliation and supersession](/docs/agent-memory/reasoning/reconciliation-and-supersession.md) for how writes are matched.

> [!NOTE]
> Agent Memory does not link name variants automatically. `Robin` and `Robin Hood` stay unlinked unless the text states that they are the same person, or you write the relation.

## Choosing what to do

The cases below run from names that are plainly one person to names that must never be merged.

| Case | Example | What the names carry | Suggested handling |
| --- | --- | --- | --- |
| Informal variants | Bill, Billy, William | The same person in different registers: friends, family, official records | Keep the names separate if the context of use matters, and link them with `same_as`. If only one name matters to you, map the variants to it before you write. |
| Titles held for a period | Prince William, the Duke of Cambridge, the Prince of Wales | Titles that apply for a time and then give way to the next | Keep one entity for the person, and record the title as an attribute. A new title supersedes the old one, and the history keeps both with their dates. |
| Pen names and stage names | Samuel Clemens and Mark Twain | Different bodies of facts: the books under one name, the life under the other | Keep both, and link them with `same_as`. |
| Renamed places and organisations | Bombay and Mumbai | One referent with a name that changed on a known date | Record the name as an attribute, so the new name supersedes the old one, or keep both names linked by `same_as` from the date of the change. |
| Roles and the people who hold them | The Sheriff and the Sheriff of Nottingham; the Prime Minister and a named person | Different things: the office outlives each holder | Keep them separate, and relate the holder to the office with a relation that has a known time. Never merge them. |
| Secret identities | Batman and Bruce Wayne; Spider-Man and Peter Parker | Two personas that most people in the story know apart | Keep them separate. Write the `same_as` relation in a scope that only the readers who should know can see. |
| Disguises and reveals | Little John serving the Sheriff as Reynold Greenleaf | A link that becomes known at one point in the story | Keep them separate, and let the `same_as` relation arrive at the reveal, so `asOf` hides it before then. |
| The same name for different things | Paris the city and Paris of Troy; Will Scarlet and Will Stutely, both called Will | Unrelated referents | Never link them. A different type keeps Paris apart. Within one type, only the surrounding facts tell them apart. |

## Titles, renames and supersession

A title or a new name is usually a fact about one entity rather than a second entity. Prince William was known as the Duke of Cambridge from 2011 and as the Prince of Wales from 2022. Written as a `title` attribute on one entity, the later value supersedes the earlier one: a current read returns the Prince of Wales, a read `asOf` 2015 returns the Duke of Cambridge, and the entity's history returns both with their times. [Temporal validity](/docs/agent-memory/reasoning/temporal-validity.md) explains how those reads work.

Extraction does not always see it that way. A text that calls somebody "the Duke" for three chapters can produce an entity called `the Duke`. Where that matters, map the title to the person's entity before you write, or link the two with `same_as`.

## Roles are not people

A role and the person holding it are different things, even when a text uses them interchangeably. `the Sheriff` is an office that one person holds at a time, while `the Sheriff of Nottingham` names that person. Merging the two would give every later holder of the office the first holder's facts. Relate the person to the role instead, with a relation such as `holds`, which has its own known time.

The types extraction gives can help here. In the [Robin Hood character graph](/docs/agent-memory/cookbooks/showcase/robin-hood.md), `Sheriff` was extracted as an organisation and `Sheriff of Nottingham` as a person, so the two stayed apart.

## Secret identities and scope

A `same_as` relation is a fact like any other, so it can be scoped. For a secret identity, write the personas as two entities in the scope everybody can read, and write the relation between them in a narrower scope. A reader outside that scope sees Batman and Bruce Wayne as two people and nothing that links them, because a relation outside their scopes is never returned to them. [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md) describes how scopes are set on writes and reads.

## Related pages

- [Reconciliation and supersession](/docs/agent-memory/reasoning/reconciliation-and-supersession.md): how a write is matched to what the memory already holds.
- [Temporal validity](/docs/agent-memory/reasoning/temporal-validity.md): reading the memory as it was at a given time.
- [Spoiler-safe narrative memory](/docs/agent-memory/cookbooks/patterns/spoiler-safe-narrative-memory.md): a reveal that arrives at a known point.
- [Robin Hood character graph](/docs/agent-memory/cookbooks/showcase/robin-hood.md): name variants in a real extraction, and one way to show them.