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. The Glossary defines a declared name and the other words used across the docs.

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 permission (the API calls it a 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.
`409`	`too_many_names`	The account has declared 1,000 names, the most it may have, here and with an admin key together: `this account has declared 1000 names, the most it may have is 1000: delete one first`. 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`	`quota_exceeded`	Cloud only: the month's writes are used up. A declaration counts as one write.
`429`	`rate_limit_exceeded`	Per-minute, per-hour or per-day request limit. Carries `Retry-After`.
`503`	`unavailable`	The database did not answer, or the request waited past one of the store's deadlines. Retry after the seconds in `Retry-After`.

Notes

One call per name. A person called by several names (a full name, a nickname) takes one declaration for each.
Up to 1,000 names per account. The names declared here and with an admin key count together; the names Korely reads from the memories by itself do not. Declaring a name again for the same end user answers 201 and takes no new place. On the Cloud each declaration, and each removal, counts as one write of the month.
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 (with an admin key) 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.
An admin key does the same. Names can also be declared and removed with an admin key, which never belongs in a tool your agent runs. A name already declared that way for 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.