Artemii
Sign in Open Artemii

Developers Memory API

Memory API.

One memory per person, shared by Artemii and the Mayfair apps.

Artemii keeps one memory per account. Mayfair apps can read and add to it, so a fact learned in one app helps in the others. The person is always in control: they can see and edit everything, and switch each app on or off.

Requirements

  • A person's delegated token, not a service key, with scopes ai memory.
  • An app registered with Artemii by a Mayfair administrator. The token's client_id must equal the app id, or be one of the clientIds in the app's manifest.
  • Memory switched on for that person, and not switched off for your app (see below).

Endpoints

EndpointWhat it does
GET /v1/memory?q&kind&limitSearch or list the person's memories.
POST /v1/memory {text, kind?}Add one. text is at most 500 characters. kind is fact, preference, project or person.
DELETE /v1/memory/{id}Delete a memory. An app can delete only what it wrote.
Shell
# MAYFAIR_TOKEN is the signed-in person's Mayfair ID access token (scopes "ai memory"), not a service key
curl "https://mayfair-ai.crelloo.workers.dev/v1/memory?q=coffee&limit=10" \
  -H "Authorization: Bearer $MAYFAIR_TOKEN"

curl -X POST https://mayfair-ai.crelloo.workers.dev/v1/memory \
  -H "Authorization: Bearer $MAYFAIR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Prefers meetings in the morning","kind":"preference"}'

curl -X DELETE https://mayfair-ai.crelloo.workers.dev/v1/memory/MEMORY_ID \
  -H "Authorization: Bearer $MAYFAIR_TOKEN"

Rules that apply to every write

  • At most 200 memories per person. Duplicates are not stored twice.
  • A sensitive-data filter refuses payment cards, bank details, government IDs, passwords and API keys, health, immigration, criminal record, abuse, self-harm, sexual content, caste and date of birth. The answer is 422 memory_sensitive and the text is not echoed back or logged.
  • In an incognito chat nothing is read or written.

The person's switches

Memory has a master switch, and each app has its own: off (not part of shared memory), read, or ask and allow (read and write). An app Mayfair has not registered is off. The person can always see and edit everything on the memory screen, even entries from an app they switched off.

Errors

StatusCodeMeaning
403user_token_requiredA service key was used. Use the person's token.
403insufficient_scopeThe token lacks ai memory.
403app_not_registeredThe token's client is not a registered app.
403memory_disabledThe person has memory switched off.
403blocked_by_permissionsThe person or their administrator switched this app off.
422memory_sensitiveThe text matched the sensitive-data filter.

Errors use the same JSON shape as the rest of the API.