Skip to main content
POST https://api.humalike.com/v1/social-memory/actions/recall
Given the arriving turn in a conversation, return a short, ready-to-inject block of context about the people in the scope — drop it straight into an agent’s prompt before it replies. recall is meant to run every turn, before the agent’s reply. The arriving message is part of the signal: the same text from different speakers pulls different context (what does Alice asking about lunch surface, versus Bob?). Run one recall per turn alongside whatever else feeds your prompt. This is a billable read over the scope’s conversation; see What a read sees.

​
Authorization

​
Authorization
string
required
Your bearer token: Bearer <token>. See Authentication.

​
Request body

​
scope_id
string
required
Which scope to recall from. 1–255 characters. See Scopes.
​
message
Message
required
The arriving turn — the message the agent is about to respond to.
Request
{
  "scope_id": "team-chat-1",
  "message": {"speaker": "carol", "text": "want to grab thai for lunch?"}
}

​
Response

​
context
string
Prose context about the people involved, tuned to the arriving turn. Drop it into the agent’s prompt before it replies. Empty ("") when the scope has no stored messages yet.
200 OK
{
  "context": "Alice has said she cannot touch peanuts. Bob acknowledged this and avoids thai food on her behalf. Carol is the one asking; she has not previously expressed a preference."
}

​
Errors

StatusCodeWhen
400VALIDATION_ERRORThe request could not be processed, or message.text is too large for a single call — shorten and retry.
401UNAUTHORIZEDThe bearer token is missing, invalid, or expired.
402PAYMENT_REQUIREDYour account does not have enough credits to cover this request. You are not charged.
403forbiddenThe token is valid but not allowed here.
422VALIDATION_ERRORThe body is malformed (missing scope_id, missing message, etc.).
502UPSTREAM_ERRORA dependency the request relies on was unavailable. Retry with backoff.
See Errors for the full envelope shape.

​
Example

curl https://api.humalike.com/v1/social-memory/actions/recall \
  -H "Authorization: Bearer $HUMALIKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_id": "team-chat-1",
    "message": {"speaker": "carol", "text": "want to grab thai for lunch?"}
  }'