Skip to main content
The Social Memory API gives an agent a running memory of a group conversation and lets it reason person-centrically about the people in it: every fact is attributed to the person it is about, not to whoever happened to say it. It exposes three actions over the same conversation scope:
  • ingest — append messages to a scope. A plain write: it just stores them, cheap to call on every turn.
  • recall — given an arriving turn, return injectable context about the people involved. Billable.
  • ask — answer a natural-language question over a scope. Billable.
You ingest as the conversation happens, and on each new turn either pull context with recall (typical agent loop) or query the scope directly with ask.

​
Scopes

A scope is one conversation — “which group” the memory is about. The caller chooses the identifier:
​
scope_id
string
required
A non-empty string of up to 255 characters. The caller picks it (for example, team-chat-1 or room:42). All three actions are addressed by this id.
Scopes are partitioned by the verified caller: one account’s scopes are invisible to another’s, even if they choose the same scope_id. There is no clear or delete endpoint — to reset a scope, generate a new scope_id and ingest into that. The old scope simply stops being read from.

​
Messages

Every transcript message — both the rows you ingest and the arriving turn passed to recall — uses the same shape:
​
speaker
string
required
Who sent the message: a display name or stable id, 1–255 characters. The speaker is part of the signal — the same text from different speakers pulls different context on recall.
​
text
string
required
The message text.

​
What a read sees

recall and ask answer from the conversation you have ingested into the scope. A scope can grow without bound — there is no cap on how much you ingest, and you can keep ingesting for the life of the conversation. The only request rejected up front is an incoming recall.message.text or ask.question that is itself too large for a single call: shorten it and retry (400). An empty scope is a no-op for recall and ask — both return an empty result immediately.

​
Authentication

Every request authenticates with a bearer token. See Authentication for the full model. 
Authorization: Bearer <token>

​
Errors

All three actions return the standard error envelope. Shared status codes:
StatusCodeWhen
400VALIDATION_ERRORThe request could not be processed, or recall.message.text / ask.question is too large for a single call.
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
402PAYMENT_REQUIREDYour account does not have enough credits to cover a billable read (recall, ask). You are not charged.
403forbiddenThe token is valid but not allowed here.
422VALIDATION_ERRORThe body is malformed (missing scope_id, empty transcript, etc.).
502UPSTREAM_ERRORA dependency the request relies on was unavailable. Retry with backoff.

​
Next

  • Ingest — append messages to a scope.
  • Recall — get context for an arriving turn.
  • Ask — answer a question over a scope.