Memory (server to server)

Read, replace and delete what Kletso remembers about one of your users from your own backend, with the secret key.

Use this when your own backend needs to show, edit or delete a user’s remembered facts outside the chat — a “what this app remembers about you” screen, say. Every call is scoped to your project’s own end users: an externalId that belongs to a different project (or doesn’t exist) answers 404.

externalId is the sub your host JWT (userAuth) carries, the same id POST /v1/sessions resolves to an end user.

List facts

GET /v1/users/:externalId/memory
Authorization: Bearer kl_sec_live_…
{
  "facts": [
    { "id": "fct_01J8…", "kind": "preference", "text": "Prefers window seats", "confidence": 0.9, "createdAt": "2026-11-01T12:00:00Z", "source": { "conversationId": "conv_…", "messageId": "msg_…" } }
  ],
  "summaryCount": 3
}
  • kind is preference, fact or outcome — see how memory works for what each means.
  • summaryCount is how many of the user’s conversations carry a running summary. The summaries themselves aren’t returned here — only the dashboard’s Conversations view shows conversation text.

Replace facts

PUT /v1/users/:externalId/memory
Authorization: Bearer kl_sec_live_…
Content-Type: application/json

{ "facts": [ { "text": "Prefers aisle seats", "kind": "preference" } ] }

Replaces the whole list — this is the same validation the dashboard’s own fact editor uses: at most 50 facts, each trimmed to 300 characters, unknown kind becomes fact. Keep an existing id to edit a fact in place; omit it (or omit the field entirely) to add a new one. Facts left out of the array are dropped. An empty { "facts": [] } also removes the user’s indexed recall entries for past conversations, since nothing is left to recall.

Returns 200 with the stored list, shaped like GET’s facts array.

Delete one fact

DELETE /v1/users/:externalId/memory/:factId
Authorization: Bearer kl_sec_live_…

Returns the remaining facts array. 404 if that id isn’t one of the user’s stored facts (or the user doesn’t exist).

Delete everything

DELETE /v1/users/:externalId/memory
Authorization: Bearer kl_sec_live_…
{ "deleted": true, "facts": 4, "summaries": 2, "vectors": 11 }

Clears the user’s facts, every one of their conversations’ running summary, and their indexed recall entries (Vectorize) — the same “forget everything” the dashboard’s memory editor does when you clear the list there, plus the running summaries a dashboard edit alone doesn’t touch. The user’s conversations and messages themselves are not deleted.

See how memory works for how facts are extracted and judged during chat.

Last updated 2026-09-28 · Report an issue with this page