API Reference

memory.updated

Sent when memory changes are detected and the project is configured with memoryWebhookMode set to FULL_STATE (default). Contains the complete current memory state for the User/Persona pair.

See the Memory Webhook guide for setup instructions.

Payload

{
  "event": "memory.updated",
  "data": {
    "userProfileId": "user_123",
    "personaProfileId": "persona_456",
    "memories": [
      {
        "uniqueIdentifier": "user_loves_italian_food",
        "target": "USER",
        "category": "FOOD_LIKE",
        "description": "Loves Italian food, especially pasta carbonara",
        "eventStartDate": null,
        "eventEndDate": null,
        "sourceText": "I absolutely love Italian food, carbonara is my favorite!",
        "timestamp": "2026-04-10T14:30:00Z",
        "tags": ["italian", "pasta", "carbonara", "food"]
      },
      {
        "uniqueIdentifier": "user_lives_in_paris",
        "target": "USER",
        "category": "LOCATION",
        "description": "Lives in Paris, France",
        "eventStartDate": null,
        "eventEndDate": null,
        "sourceText": "I've been living in Paris for 3 years now",
        "timestamp": "2026-04-10T14:30:00Z",
        "tags": ["paris", "france", "location"]
      }
    ]
  }
}

Fields

Field	Type	Description
`event`	`string`	Always `"memory.updated"`
`data.userProfileId`	`string`	The end-user's profile identifier
`data.personaProfileId`	`string`	The AI persona's profile identifier
`data.memories`	`array`	Complete list of all current memories for this pair

Memory Object

Field	Type	Description
`uniqueIdentifier`	`string`	Machine-friendly key (e.g. `user_loves_italian_food`)
`target`	`string`	Who the memory is about: `USER` or `PERSONA`
`category`	`string`	Content category (see categories)
`description`	`string`	Brief English summary of the fact
`eventStartDate`	`string \| null`	ISO 8601 date (`YYYY-MM-DD`). Only for `EVENT` category
`eventEndDate`	`string \| null`	ISO 8601 date (`YYYY-MM-DD`). Only for `EVENT` category
`sourceText`	`string`	The original message that produced this memory
`timestamp`	`string`	ISO 8601 UTC timestamp when the memory was recorded
`tags`	`string[]`	Up to 10 keywords summarizing the memory

Memory Targets

Target	Description
`USER`	A fact about the end-user (the person chatting)
`PERSONA`	A fact about the AI persona (as stated or implied during conversation)

Memory Categories

Category	Description
`NAME`	Name
`NICKNAME`	Nickname or alias
`AGE`	Age
`DATE_OF_BIRTH`	Date of birth
`GENDER`	Gender
`LOCATION`	Where they live or are located
`NATIONALITY`	Nationality or country of origin
`LANGUAGE`	Languages spoken
`RELIGION`	Religious beliefs
`CULTURE`	Cultural background
`OCCUPATION`	Job or professional role
`EDUCATION`	Education level or school
`SKILL`	Skills or abilities
`PERSONALITY`	Personality traits
`APPEARANCE`	Physical appearance
`HEALTH`	Health-related information, allergies and intolerances included
`RELATIONSHIP_STATUS`	Current relationship status
`ROMANTIC_RELATIONSHIP`	Romantic relationship details
`FRIEND`	Friends, roommates, named social connections
`PARENT`	Mother, father, or step-parent
`SIBLING`	Brothers and sisters
`CHILD`	Their own children
`FAMILY_MEMBER`	Relatives other than parents, siblings and children: grandparents, cousins, in-laws
`PET`	Pets
`SEXUAL_ORIENTATION`	Sexual orientation
`SEXUAL_INTEREST`	Fetishes, fantasies, and practices they like
`SEXUAL_TOY`	Sex toys owned, used, or wanted
`SEXUAL_DISLIKE`	Sexual practices, acts, or themes they refuse or dislike
`POLITICAL_VIEW`	Political views
`FOOD_LIKE`	Favourite foods and drinks, and the diet they follow
`FOOD_DISLIKE`	Foods and drinks they dislike or avoid by choice
`HOBBY`	Hobbies and pastimes that are not a physical activity
`SPORT`	Sports and physical activities practised or followed, gym and training habits included
`MUSIC_PREFERENCE`	Music taste
`MEDIA_PREFERENCE`	Movies, TV shows, books, etc.
`TECH_HABIT`	Technology usage habits
`PROJECT`	Personal projects or goals in progress
`AMBITION`	Ambitions or long-term goals
`EVENT`	Specific events with dates
`OTHER_IMPORTANT_INFORMATION`	Anything that doesn't fit another category
`CURRENT_EXCUSE_NOT_TO_MEET_USER`	The Persona's current reason for not meeting the User in person. Always `target: PERSONA`
`FOOD_PREFERENCE`	Legacy. Replaced by `FOOD_LIKE` and `FOOD_DISLIKE`. No new memory is filed under it, and memories already stored under it are re-filed as their conversation continues