Guides
Conversation Memory: The 30-Message Window
Every time you enqueue a conversation, the Persona is given the 30 most recent messages of that conversation. That window is its short-term memory: it is everything the Persona can see about what has already been said.
Integrators usually think of this as "the last 30 exchanges". It is not. It is 30 messages, and both sides spend from the same budget. This page explains exactly what occupies a slot, so you can predict what the Persona remembers.
What the window contains
When a conversation is enqueued, we call your Chat History Endpoint and keep the 30 most recent messages of what you return, together with the message being processed. Older messages are not sent to the model.
Two consequences follow:
- You decide what we count. The window is built from the history you return. A message you leave out of your response never reaches the Persona; a message you include occupies a slot, whatever it is.
- The message being replied to is part of the count. It occupies the newest slot in the window, not an extra one.
One message, one slot
A slot is a message, not an event. It does not matter what the message carries: a photo, a gift and a plain "hey" each take exactly one slot.
| What the user or Persona sends | Field in the history | Slots used |
|---|---|---|
| Text | text | 1 |
| Photo | pictureUrls | 1 |
| Video | videoUrls | 1 |
| Voice message | audioUrls | 1 |
| Poke | poke | 1 |
| Gift | gifts | 1 |
| Sticker | sticker | 1 |
| Text and a photo, in the same message | text + pictureUrls | 1 |
A shared photo is a message, not an extra event added on top of one. A message that carries text, a sticker and a gift at once is still a single message, and still a single slot.
Only USER and PERSONA messages count
Each message in the history declares a sender, and the public API accepts two values:
USER: a message from your end user.PERSONA: a message from the profile we generate content for.
Nothing else is counted, because nothing else can be sent. Platform notifications such as "you have a new Like" or "it's a match" are not part of the window unless you choose to put them into the history as an ordinary message, with one of those two senders. If you do, they occupy a slot like any other message.
Every Persona message counts individually
This is the point most integrations miss.
When multi-message replies are enabled, one reply can be delivered as two or three separate messages. For billing, only the first one counts, and the follow-ups are free. For the memory window, they are not free. A reply split into 3 messages returns 3 messages to your Chat History Endpoint, and occupies 3 slots.
So the reach of the window depends directly on how talkative your Personas are:
| Persona reply style | Slots per exchange | Exchanges held in the window |
|---|---|---|
| 1 message per reply | 2 | ~15 |
| 2 messages per reply | 3 | ~10 |
| 3 messages per reply | 4 | ~7 |
An exchange here is one user message plus the Persona's reply.
What this means for your integration
- Count messages, not turns. When you reason about what a Persona still knows, count the rows you return from your Chat History Endpoint, including the Persona's own.
- Facts said early can fall out of the window. A user's name, city or preference mentioned in the first exchanges is no longer visible to the Persona once 30 newer messages exist. If a fact must survive, it belongs in the Persona or User profile you send us, not only in the chat.
- Your history endpoint is the control point. It is the one place where you decide what the Persona sees. Returning a clean, complete, oldest-first history is what keeps replies coherent.
A window, slot by slot
Here is the tail of a real-shaped conversation. Note how the Persona's three-message reply spends three slots, and how the photo, the gift and the poke each spend exactly one.
| Slot | Sender | Message |
|---|---|---|
| 22 | USER | "what are you up to tonight?" |
| 23 | PERSONA | "nothing planned yet" |
| 24 | PERSONA | "was thinking of cooking something" |
| 25 | PERSONA | "you?" |
| 26 | USER | Photo of a restaurant table |
| 27 | USER | "already out 😄" |
| 28 | PERSONA | Sticker |
| 29 | USER | Gift: Teddy Bear (LOW) |
| 30 | USER | Poke |
Nine messages, nine slots, but only four user turns. Slot 1 is now the 30th-newest message in the conversation; anything older has left the window.
When Smart becomes Pro
On projects where the automatic model upgrade is enabled, the 30-message window is also the tier boundary:
- At 30 messages, the reply is still generated by the Smart model.
- At 31 messages, the reply is generated by the Pro model, and long-term memory starts being kept for that conversation.
The message being processed is included in that count, so the switch happens on the reply to the 31st message, not the one after. From that reply on, the conversation is billed at the Pro rate. See Choose Your Model for both rates.
The upgrade is opt-in per project. You turn it on in your project settings in the Customer Dashboard, or by explicitly requesting the automatic model in your request. A project that pins a chatModel stays on that model whatever the conversation length.