Memories

Help a PAL remember each participant and build continuity across conversations.

A memory store represents an ongoing relationship between a PAL and a participant, such as one of your end users. Pass the same participant tag in participant_tags with every conversation, and Tavus finds or creates the store for that relationship so the PAL can use and build memory over time.

Learned memory works automatically and requires no ongoing maintenance. Everything in the memory store is viewable, and you can selectively delete information whenever needed. You can also add optional pinned memories when there are specific facts you want the PAL to know, including before the first conversation.

You can create and manage Memory Stores in PAL Maker or programmatically through the API.

How Memories work

A relationship is the pairing of one PAL and one participant tag. Each relationship has exactly one memory store, created automatically — you never create it yourself unless you want to pre-seed pinned memories (see below).

The first time a PAL and a participant tag appear together in a conversation, Tavus creates a store for that relationship. Every later conversation using that same PAL and tag reuses it, building the profile and timeline over time. If the same tag talks to a different PAL, that’s a different relationship with its own store that starts empty. Memories are not shared between PALs.

For example, suppose participant tag alex_taylor talks with a math tutor PAL (p_math_tutor) and, separately, an English tutor PAL (p_english_tutor):

Conversation	PAL	participant_tag	Store used
1st with the math tutor	p_math_tutor	alex_taylor	Creates a new store for (math tutor, alex_taylor)
2nd with the math tutor	p_math_tutor	alex_taylor	Reuses that store — the PAL remembers Alex
1st with the English tutor	p_english_tutor	alex_taylor	Creates a separate, empty store — no memory of the math sessions

Each PAL relationship develops independently. If you want both tutors to start from the same baseline (for example, Alex’s learning goals), add the same pinned memories to both stores rather than expecting them to share one.

Memory type	How it works	When to use it
Learned memory	Tavus automatically maintains it after completed conversations	Giving the PAL continuity as the relationship develops.
Pinned memories (optional)	Individual facts you add. Tavus keeps them unchanged until you update or delete them.	Pre-seeding facts before the first conversation, or adding facts that should stay unchanged until you change them.

Both types of memory are viewable. You can selectively delete learned information and update or delete pinned memories. When pinned and learned memory conflict, Tavus prioritizes the pinned memory.

Start using Memories

For an API integration, pass the participant’s stable tag in participant_tags whenever you create a conversation.

1. Pass a participant tag with every conversation

   Use any stable, non-empty string from your application as the one value in participant_tags, such as an internal user ID. Avoid values that may change, such as a display name.

   curl --request POST \
     --url https://tavusapi.com/v2/conversations \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <api-key>' \
     --data '{
       "pal_id": "p123456789ab",
       "face_id": "r123456789ab",
       "participant_tags": ["user_12345"]
     }'
   

   Tavus finds the store for that PAL and participant, or creates one if this is their first conversation. Reuse the same tag with the same PAL to continue the relationship’s memory.

participant_tags accepts zero or one tag today. Omit it, or send an empty array, for a stateless conversation. Sending more than one tag returns a 400 error; multi-participant memory is not supported yet.

That’s all that’s required. Learned memory updates automatically after completed conversations; pinned memories and memory management are optional.

Optionally provide specific context

Pinned memories are static facts you provide directly. Tavus makes them available to the PAL whenever you create a conversation with that relationship’s tag in participant_tags, including before the first conversation.

For example, you might add “Prefers concise answers,” “Has completed onboarding,” or “Their account includes priority support.” Keep each pinned memory focused on one fact so it can be updated or deleted independently.

Pinned memories remain unchanged until you update or delete them. If a pinned fact can become outdated, keep it synchronized with your application.

To seed facts before the first conversation, explicitly create a memory store and include pinned memories. You can also manage pinned memories later in PAL Maker or through the API:

• Create Pinned Memory
• List Pinned Memories
• Update Pinned Memory
• Delete Pinned Memory

Review and control what the PAL remembers

You do not need to review memory after every conversation. When you want visibility or control, Get Memory Store returns both pinned and learned memory for the relationship.

Learned memory contains:

• Profile: Structured information the PAL has learned about the participant.
• Timeline: A time-aware history of their prior interactions with the PAL.

You can view learned memory, delete a specific profile field, or delete a specific timeline entry. Learned memory cannot be edited directly. If information is incorrect, delete it. Add a pinned replacement only when you know the correct fact and want the PAL to use it consistently.

Find a memory store to manage it

Use List Memory Stores to list all of your memory stores, or filter by pal_id, participant_tag, or both. Use both filters to find the memory_store_id for a specific relationship when you need to view or manage it. You never need this ID when creating a conversation.

Delete a relationship’s memory

Delete Memory Store removes the store so it can no longer be viewed or used by the PAL. A later conversation with the same tag in participant_tags creates a new store for that relationship.

Troubleshooting

Result	Likely cause	What to do
Store creation returns 409	A store already exists for the PAL and participant	Use List Memory Stores to find its ID, then use it to add pinned facts or manage the existing store
A conversation starts without remembered context	participant_tags is missing or changed, or the conversation uses a different PAL	Reuse the same stable tag with the same PAL
Learned memory is unchanged immediately after a call	Post-conversation learning is still processing	Wait for processing before starting a conversation that needs the latest context

For more answers, see the Memory FAQs.

Already using legacy memory tags through the memory_stores field? See Legacy memory tags. New integrations should use participant_tags. Do not send both fields in the same conversation request.