Skip to content

Subject

One person or thing memory holds, by name - how it went, its values now, its facts in the order they were said, the conversations about it and how it relates to others.

POST/v2/memory/subjectTry it in the Playground
Auth
read key
Cost
free; never refused for your plan

Search ranks what bears on one question. Subject opens one person or thing, such as a colleague or a project, by name, and returns its whole story: a few lines on how it went, each property's newest value, its facts in the order they were said, what each conversation about it was about, and how it relates to other people and things. Call it when a question wants everything about someone or something, which no single search holds.

Every fact and excerpt in the answer carries a ref, for open, around and related. summary lists the subjects memory holds most about, in subjects.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Alexein-Userstringrequired

The app user whose memory to read. See App users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

namestringrequired

Who or what, by name, such as Alice Chen or Acme billing migration. Case does not matter. 1 to 512 characters.

limitinteger

How many facts timeline holds at most. 1 to 60, default 60. When memory holds more, they are taken evenly over the whole span, so the story is not only its latest week.

Response

namestring

The name as memory holds it, or as sent when memory holds nothing by it.

factsinteger

How many facts memory holds about it. 0 when it holds none by that name.

aboutobject[]

A few lines on how it went, each {text, refs}: refs are the facts the line rests on. These lines are written over time, so a subject memory has only just met has none yet.

valuesobject[]

Each property's newest value, sorted by attribute, each {attribute, value, since}: since is the day it was said. Whether it still holds is left to the model reading it, with the date in front of it. history returns every value, old and new.

timelineobject[]

Its facts in the order they were said, oldest first, each {date, text, ref, source}: date is the day it was said, ref the fact's, and source the ref of the excerpt it was learned from, or null.

conversationsobject[]

What each conversation about it was about, oldest first, up to 30, each {date, text, ref}: text is one line, and ref is an excerpt of that conversation, for open or around.

linksobject[]

How it relates to other people and things, newest said first, up to 30, each {link, date, ref}: link in words, such as Acme billing migration led by Alice Chen, date the day it was said, and ref the fact that says it.

suggestionsstring[]

Only when facts is 0: up to 5 names memory holds that are nearest the one sent, in lower case. Send one of them back as name. The other lists are absent.

Each text and link is a line for your model; don't parse it. Refs are valid for this app user only. Facts and lines resting on anything the person asked memory to forget are not shown.

For an app user with no memory yet it answers 200 with facts: 0 and suggestions empty.

Errors

400bad request

X-Alexein-User is missing or not a usable id.

401unauthorized

The bearer is not a key this service issued.

403forbidden

The organisation has been closed in the console.

422invalid

A field is out of bounds, such as an empty name or a limit over 60. detail names the field.

429too many requests

Too many requests in flight, or reads too fast. Retry after Retry-After seconds. See Limits.

503unavailable

The service is busy or briefly unavailable. Retry after Retry-After seconds, or with backoff when there is none.

Request
curl https://api.alexein.ai/v2/memory/subject \
  -H "Authorization: Bearer $ALEXEIN_API_KEY" \
  -H "X-Alexein-User: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme billing migration" }'
200 OK (shortened)
{
  "name": "Acme billing migration",
  "facts": 23,
  "about": [
    {
      "text": "Alice has led the move to the new invoicing system since August; the cutover slipped once, to November",
      "refs": ["mem_6sG2bN8yRc4", "mem_3wE8rT1yUi6"]
    }
  ],
  "values": [
    { "attribute": "cutover", "value": "2026-11-23", "since": "2026-10-14" },
    { "attribute": "status", "value": "testing", "since": "2026-10-20" }
  ],
  "timeline": [
    {
      "date": "2026-08-04",
      "text": "(said 2026-08-04) Alice will lead the Acme billing migration",
      "ref": "mem_6sG2bN8yRc4",
      "source": "mem_1aZ5cX7vBn2"
    },
    {
      "date": "2026-10-14",
      "text": "(said 2026-10-14) The cutover moved from November 2 to November 23",
      "ref": "mem_3wE8rT1yUi6",
      "source": "mem_8qW3eR5tYu1"
    }
  ],
  "conversations": [
    {
      "date": "2026-08-04",
      "text": "Planning the Acme billing migration with the finance team",
      "ref": "mem_1aZ5cX7vBn2"
    },
    {
      "date": "2026-10-14",
      "text": "Moving the billing cutover after a failed test run",
      "ref": "mem_8qW3eR5tYu1"
    }
  ],
  "links": [
    { "link": "Acme billing migration led by Alice Chen", "date": "2026-08-04", "ref": "mem_6sG2bN8yRc4" }
  ]
}
200 OK, a name memory does not hold
{
  "name": "billing",
  "facts": 0,
  "suggestions": ["acme billing migration"]
}