Skip to main content
This is an advanced feature requiring explicit config. It is not enabled by default.
Agent Memory is an experimental feature that allows your assistant to persist data about users across conversations. This enables experiences like repeat-caller logic, customer preferences, and cross-channel continuity. It uses a key-value store attached to a user identifier (like phone number). Memory is read at the start of each turn and written after the conversation ends. You can:
  • Read memory using conv.memory.get("key")
  • Write memory by setting conv.state["key"] = value (if configured with state_keys)

​
Configuration

​
JSON config (Agent Studio)

To enable Agent Memory: 
{
  "memory": {
    "repeat_caller": {
      "analytics_enabled": true,
      "state_keys": ["booking_day", "cheese_type"],
      "identifier_blacklist": ["+447777"]
    }
  }
}
  • analytics_enabled: Adds repeat caller metrics to Studio analytics
  • state_keys: Keys to save from conv.state to memory
  • identifier_blacklist: Optional list of excluded IDs (e.g. test numbers)

​
Using memory in functions

​
Read memory

def start_function(conv: Conversation):
    cheese = conv.memory.get("cheese_type")
    if cheese:
        conv.say(f"You previously picked {cheese}.")

​
Write memory (using conv.state)

def book(conv: Conversation):
  conv.state["cheese_type"] = "brie"
These fields will only be persisted if they are listed under state_keys in your config.

​
Example: conditional reuse

def start_function(conv: Conversation):
  booking_day = conv.memory.get("booking_day")
  cheese_type = conv.memory.get("cheese_type")
  if booking_day and cheese_type:
    conv.say(f"You booked {cheese_type} for {booking_day}. Rebook?")

​
Memory behavior

  • Memory is read once per turn and cached.
  • Memory is persisted at the end of a conversation.
  • The default identifier is the caller’s phone number.

​
Custom memory identifiers

You can configure a custom memory lookup key based on SIP headers, integration attributes, or conversation state. This allows you to identify users by something other than phone number — for example, a customer ID from a CRM or a session token from a webchat integration. Configure this in the JSON config: 
{
  "memory": {
    "repeat_caller": {
      "analytics_enabled": true,
      "state_keys": ["booking_day", "cheese_type"],
      "identifier_source": "sip_header:X-Customer-Id"
    }
  }
}
Supported identifier sources:
  • SIP headers — e.g., sip_header:X-Customer-Id
  • Integration attributes — e.g., integration_attribute:customer_id
  • Conversation state — e.g., state:customer_id
If no custom identifier is configured, the system defaults to the caller’s phone number.

​
FAQ

​
Can I store nested JSON?

No. Each value must be a string, number, or flat serializable object. Always avoid packing PII into a single field.

​
Can I check if memory exists?

Yes: 
if "booking_day" in conv.memory:

​
Can I prevent overwrites?

Not directly, but you can check before writing: 
if "cheese_type" not in conv.memory:
  conv.state["cheese_type"] = value

​
How do I get all memory fields?

Use the fields() method: 
all_memory = conv.memory.fields()  # Returns a dict copy of all fields

​
How do I check how many fields are stored?

Use Python’s len(): 
field_count = len(conv.memory)