Open · Alexein Docs

POST/v2/memory/openReads memoryTry it in the Playground

Auth: read key
Cost: free; never refused for your plan

Every fact and excerpt in a result carries a ref. Open returns what it names. No ranking.

An excerpt ref returns that excerpt whole, where search and latest cut it at 1,400 characters and grep at 320.
A fact ref returns the fact and the excerpts it was learned from: where it came from, in the words that were said.

To get an item as you added it, use item.

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

refstringrequired

A fact's or an excerpt's ref, such as mem_5pQ1zX8gHd2. Valid for this app user only.

Response

memoryobject

What the ref names: an excerpt, {type: "excerpt", ref, text, date, added_at, session, roles}, with its whole text; or a fact, {type: "fact", ref, text, source}.

sourcesobject[]

For a fact: the excerpts it was learned from, each whole. Absent for an excerpt.

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.

404not found

no memory for app user 'user_42' yet, or a ref memory does not hold for this app user.

422invalid

An empty ref: `ref` must not be empty.

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/open \
  -H "Authorization: Bearer $ALEXEIN_API_KEY" \
  -H "X-Alexein-User: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "mem_5pQ1zX8gHd2" }'

200 OK, a fact

{
  "memory": {
    "type": "fact",
    "ref": "mem_5pQ1zX8gHd2",
    "text": "(said 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"]
    }
  ]
}

200 OK, an excerpt

{
  "memory": {
    "type": "excerpt",
    "ref": "mem_7cJ4mE9tRw5",
    "text": "Alice is vegan and allergic to peanuts.",
    "date": "2026-10-02T12:00:00+00:00",
    "added_at": "2026-10-02T12:00:03+00:00",
    "session": null,
    "roles": []
  }
}