Users & agents

Declare a name

Tell Korely that an end user is also called by a name: the id maria is Maria Rossi. The facts about Maria Rossi in that end user's memory then read as facts about maria.

POST /v1/users/{end_user}/names

SDK: korely.declare_name(name, user_id=end_user). CLI: korely init --name "Maria Rossi" --user-id maria.

Your agent may store memories under an id while the text names the person in full: "Maria Rossi moved to Rome", written for the end user maria. The store never merges two names of a person by itself, because two people can share a name, and a merge it guessed wrong would close one person's facts with another's. This call is the declaration that does it. From then on a fact written about the name in this end user's memory is a fact about the end user, and the facts already written about the name read that way at once. Their written words stay as they were.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key must carry the memories:write scope.

Path parameter

Parameter	Type	Description
`end_user`	string	The end user the name belongs to, the `user_id` exactly as written, which must follow the id rule (1 to 255 characters, no `/`, no control characters, not `.` or `..`, not starting with `erased:`). Percent-encode it as one path segment (`customer 42` is `customer%2042`).

Request body

Field	Type	Required	Description
`name`	string	Required	Another name of the end user, as the memories write it: a full name (`"Maria Rossi"`) for the id `maria`. 1 to 200 characters. The `user_id` itself is not a name.
`agent_id`	string	Optional	The agent namespace whose memory of this end user the name is declared in. Omit it for the end user's own memory.

Any other field is refused with 422 invalid_request: field names are snake_case.

Example request

curl -X POST https://api.korely.ai/v1/users/maria/names \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Rossi"}'

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

declared = korely.declare_name("Maria Rossi", user_id="maria")

print(declared.user_id, declared.name)   # maria Maria Rossi
print(declared.since)                    # 2026-10-18T21:04:11.412345Z

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const declared = await korely.declareName("Maria Rossi", { user_id: "maria" });

console.log(declared.user_id, declared.name);   // maria Maria Rossi
console.log(declared.since);                    // 2026-10-18T21:04:11.412345Z

korely init --name "Maria Rossi" --user-id maria
# name     "Maria Rossi" is maria: what the memories say about it is theirs, the facts already written included

Response

201 Created. The name and the end user it now belongs to. Declaring the same name again answers the same.

{
  "user_id": "maria",
  "name": "Maria Rossi",
  "agent_id": null,
  "since": "2026-10-18T21:04:11.412345Z"
}

Field	Type	Description
`user_id`	string	The end user the name belongs to (echoes the path parameter).
`name`	string	The name declared.
`agent_id`	string · null	The agent namespace whose memory holds the declaration, `null` for the end user's own memory.
`since`	string · null	ISO 8601 timestamp from which the facts about the name read as the end user's.

After the declaration

# A fact written about the full name, for the end user maria
curl -X POST https://api.korely.ai/v1/facts \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{"user_id": "maria", "subject": "Maria Rossi", "predicate": "lives_in", "object": "Rome"}'

# Once the name is declared, it comes back under maria
curl -G https://api.korely.ai/v1/facts \
  -H "Authorization: Bearer kor_live_..." \
  --data-urlencode "user_id=maria" \
  --data-urlencode "subject=maria"

Before the declaration, subject=maria finds nothing: the fact is about Maria Rossi. After it, the same read returns lives_in Rome. The fact was not written again: the declaration moved its stored subject to the end user.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Invalid or missing API key: ...`, then what is wrong.
`403`	`forbidden`	The key lacks the `memories:write` scope, or it is confined to some end users and the end user in the path is outside its list.
`409`	`conflict`	The name is already declared for somebody else in this memory: `this name is already declared for somebody else in this memory`. Nothing changes.
`413`	`payload_too_large`	The body is larger than 2,097,152 bytes. Refused before it is read; nothing was done. On the Cloud a body over 1 MB gets a bare `413` first, without this code.
`422`	`invalid_request`	`name` missing, empty or over 200 characters; the name is the `user_id` itself or is not a name (`name must be a name, and not the user_id itself`); the end user in the path or the `agent_id` breaking the id rule; an unknown field.
`429`	`rate_limit_exceeded`	Per-minute, per-hour or per-day request limit. Carries `Retry-After`.

Notes

One call per name. A person called by several names (a full name, a nickname) takes one declaration for each.
Scoped to the key's project and to one memory. The declaration holds in this end user's memory, in the key's project, and in the agent namespace you pass. Another end user who shares the name keeps their own facts.
The facts take the name at once. The memories and the facts keep the words they were written with; the facts already written about the name are stored under the end user from the declaration on. Two open facts that now say the same thing become one, and a plan that the same thing done now matches is closed. Removing the name later (deleting the alias in the dashboard) gives the facts back the names their words give, but merged facts stay one and closed plans stay closed.
Audited without the name. The call is recorded in the audit log as a fact_write event for the end user; the name itself is not in the event.
The dashboard does the same. An alias made in the dashboard for this end user is the same declaration. A name the dashboard already gave to somebody else answers 409 here.

Get facts, read the facts that now come back under the end user.
Get profile, the end user's facts, grouped by family.
CLI: declare a name, the same call from a shell.