Skip to main content
This page is for existing integrations that pass legacy memory tags through the memory_stores field. These integrations remain supported, but new integrations should use Memory Stores and participant_tags. Only one participant tag is supported per conversation today.
Legacy memory tags and Memory Stores both let a PAL carry context across conversations, but they organize that context differently. A legacy memory tag is a developer-defined string that acts as a flexible memory bucket. A Memory Store is an explicit API resource representing one relationship, with pinned memories and inspectable learned memory. The two systems use separate storage models. Existing legacy memory tags are not automatically converted into Memory Stores.

​
How legacy memory tags work

Memories are pieces of information that a PAL learns during a conversation and can reference in later conversations. Passing one or more strings in memory_stores implicitly creates or reuses those memory buckets. Any later conversation using the same tag can reference and add memories associated with it. For example, suppose a participant named Anna talks with a PAL named Charlie, whose ID is p123456789ab. You can use anna-p123456789ab as the memory tag for their conversations. Charlie can then:
  • Form new memories from conversations with Anna.
  • Reference memories from their previous conversations when Anna returns.
Pass the tag when you create a conversation:
Use stable values that will not change when naming a memory tag. For one-to-one memory, combine a stable participant identifier with the PAL ID. Avoid identifiers such as a participant’s display name or a PAL’s name, which may change over time.

​
Organize memory across participants and PALs

Legacy memory tags are flexible namespaces and do not have to map one-to-one to participants. Every conversation that uses the same tag shares the memories in that bucket, regardless of which PAL or participant joins it. For isolated, one-to-one memory, use a different tag for each relationship. For example:
  • When Anna talks with Charlie (p123456789ab), use anna-p123456789ab.
  • When Anna talks with Gloria (p456789abcdef), use anna-p456789abcdef.
Some existing integrations intentionally share memory. For example, an online classroom might use classroom-1 so conversations using that tag contribute to and reference the same bucket. Reuse a tag only when this sharing is intentional; otherwise, participants or PALs may receive context from one another’s conversations.

​
Manage legacy memories

​
List memory tags

​
List memories for a tag

​
Add a memory

​
Delete a memory

Use the memory ID returned when you list or add memories:

​
Delete a memory tag

​
Migrate to Memory Stores

Migrate one relationship at a time:
  1. Create a memory store using the PAL ID and your stable participant identifier.
  2. Retrieve the relationship’s existing legacy memories. Add any facts that are still correct and should stay unchanged as pinned memories on the new store.
  3. Replace memory_stores with participant_tags containing the participant’s one stable tag in future conversation requests.
  4. Do not send both fields in the same conversation request. Other relationships can continue using legacy memory tags while you migrate incrementally.
Memory Stores do not support shared buckets across PALs or participants. If an existing tag is shared, decide which memories belong to each relationship before migrating. Move information that should apply to every participant into PAL-level context rather than copying it into relationship memory.