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 for how writes are matched.
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 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, 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 describes how scopes are set on writes and reads.
Related pages
Reconciliation and supersession: how a write is matched to what the memory already holds.
Temporal validity: reading the memory as it was at a given time.
Spoiler-safe narrative memory: a reveal that arrives at a known point.
Robin Hood character graph: name variants in a real extraction, and one way to show them.