Add memory

Enable memory on the agent

Toggle memory in the console, or PATCH the agent:

memory_retention_days bounds how far back retrieval reaches; 0 means no cap. It controls relevance, not erasure - use a delete to remove a fact.

Reference the placeholder in the prompt

Add {{memory}} where you want the facts grounded. The retrieved block is already a numbered list, so keep the surrounding prompt short.

You are a support agent for Acme. Speak concisely.
{{memory}}
Greet the caller, confirm what they need, and escalate only if you can't resolve it in one turn.

With memory disabled, the placeholder is stripped - no literal braces reach the LLM.

Pass a stable caller identity

Memory pivots on caller_identity, which is separate from the short-lived realtime participant identity:

• Authenticated conversation creation - pass user_identity on POST /v1/agents/{id}/conversations. If omitted, user_<authenticated principal> remains the fallback caller key for backward compatibility.
• Public widget - pass user_identity yourself, such as your own opaque user ID or a hashed email.

$
curl -X POST "https://api.speechify.ai/v1/agents/$AGENT_ID/conversations" \
>
  -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"user_identity":"acme_user_42"}'

1
<speechify-agent
2
  agent-id="agent_01H..."
3
  user-identity="acme_user_42">
4
</speechify-agent>

Pick something stable and opaque: your own user ID or a hashed email, not an email address or a phone number you might reformat later. It may not begin with embed_, anon_ or user_ - those are reserved. Anonymous sessions - no identity supplied - are skipped by memory entirely.

See Embed for the widget attribute. The realtime token carries a separate, per-session participant identity, so your caller key never reaches the browser.

Verify it end to end

1. Give the agent a prompt containing {{memory}} and enable memory.
2. Place a test call and state something durable - “I can only do mornings; I’m vegetarian.” Hang up.
3. On the conversation detail page, Memories written this call lists the facts within about ten seconds.
4. Call again as the same caller and ask an open question - the agent should use the fact without re-asking.