Skip to content
AlexeinDocs
Get started

Two products, one account

Facts & timing

How an added item becomes searchable at once and gives dated facts soon after, how to see where each item is, and how to find where a fact came from.

An item is searchable seconds after you add it. Its dated facts follow, usually within minutes.

What happens after an add

Queued. The add request takes your items and answers 202. Nothing is lost from here on, but the items are not searchable yet.

Stored. A moment later the items are stored, and from then on search, grep and latest find them as excerpts. Send "wait": true with an add to hold the request until this step, up to 10 seconds.

Processed. Memory learns short, dated facts from what was said, each with the excerpt it came from, and brings its known lines and history up to date. This is usually done within minutes.

Until an item is processed, search finds its words as excerpts. Once it is processed, the same search can also return facts and known lines learned from it.

Facts also wait when your organisation's daily budget is spent; see Facts and your budget.

What a fact is

A fact is one short, dated statement learned from what was said, such as:

{
  "type": "fact",
  "ref": "mem_5pQ1zX8gHd2",
  "text": "(happened 2026-10-01) Alice lives in Lisbon",
  "source": "mem_9fK2xQ7aLp3"
}
  • ref is the fact's handle. Pass it to open, correct or forget. It is valid only for this app user and only to send back to this API: don't parse it.
  • text is a line for your model. Its wording can change, so don't parse it.
  • source is the ref of the excerpt it was learned from, or null.

Facts about a person's or a thing's details, such as Alice's home city, also shape the known lines and history. facts lists every fact memory holds for an app user, newest first, each with its date.

See where an item is

/v2/memory/status takes up to 500 item ids and returns the status of each.

curl https://api.alexein.ai/v2/memory/status \
  -H "Authorization: Bearer $ALEXEIN_API_KEY" \
  -H "X-Alexein-User: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "items": ["msg-001", "pref-diet", "nope-404"] }'
{
  "items": [
    { "id": "msg-001", "status": "processed", "reason": null },
    { "id": "pref-diet", "status": "stored", "reason": null },
    { "id": "nope-404", "status": "unknown", "reason": null }
  ]
}
StatusMeaning
queuedAccepted, not searchable yet.
storedStored and searchable.
processedFacts have been learned from it.
unknownMemory holds no item by this id, or it was forgotten or has expired.

reason is null, or a plain sentence saying what is holding the item back. Poll at a modest rate if your app needs to know when facts are ready.

Where a fact came from

Pass a fact's ref to /v2/memory/open, and it returns the fact with the excerpts it was learned from, whole:

Response (shortened)
{
  "memory": {
    "type": "fact",
    "ref": "mem_5pQ1zX8gHd2",
    "text": "(happened 2026-10-01) Alice lives in Lisbon",
    "source": "mem_9fK2xQ7aLp3"
  },
  "sources": [
    {
      "type": "excerpt",
      "ref": "mem_9fK2xQ7aLp3",
      "text": "I just moved to Lisbon from Berlin for the new job at Acme.",
      "date": "2026-10-01T09:30:00+00:00",
      "added_at": "2026-10-01T09:30:02+00:00",
      "session": "onboarding",
      "roles": ["user"]
    }
  ]
}

Pass an excerpt's ref to open to read that excerpt whole, and to around for what was said either side of it. Use these to show a user why memory believes something before you correct or forget it.

Facts and your budget

Learning facts counts against your organisation's daily budget, set in the console under Settings › Limits (personal memory has a daily cap of its own, under My memory › Settings › Limits). When the day's budget is spent, new facts wait until the next UTC day. Adding, searching and every other memory route keep working. See Limits.