Profiles
Memories are individual facts. A profile is the summary of all of them for one entity: a single structured object, shaped by a JSON Schema you define, that Mem0 keeps current as new memories arrive. Search answers “what did this user say about X”. A profile answers “who is this user”, in one read, with no query to write.Use profiles when…
- You want to personalize a first response, before the user says anything in this session.
- You need a compact object to drop into a prompt instead of a list of memories.
- You want the same fields for every user, so your code can rely on their shape.
User Profiles are in beta and available on request. To enable them for your
organization, contact [email protected].
How it works
- You define a schema: the fields a profile should contain, each with a description.
- Mem0 builds each entity’s profile from their memories, and rebuilds it as new memories arrive.
- You read the profile whenever you need it.
status rather than failing.
Define the schema
The schema is JSON Schema. Every property needs adescription — that is what tells the model how to fill the field, so a vague description gives a vague profile.
Your schema’s property names reach the API exactly as you write them. The SDKs do not rewrite them, so a profile always comes back with the field names you chose.
enabled alone.
Read a profile
generation_count is how many times this profile has been (re)generated — 0 before the first generation completes.
Always branch on status
profile is empty unless status is succeeded. Check the status rather than the emptiness of the object, so a profile that is merely still building is not mistaken for a user you know nothing about.
A
404 means only that no such entity exists in your project.
Generate a profile on demand
Profiles are built once an entity has accumulated enough messages, so a brand-new user has none during their first few interactions. Trigger one directly to close that gap:status.
Test a schema before applying it
A schema that reads well can still produce disappointing profiles. Sample a few real entities and inspect the output before committing to it. Sampling is asynchronous: the call returns a job as soon as it is queued. Pollstatus_url until the job is terminal, then read each sampled entity’s profile:
Apply a new schema to existing entities
A new schema shapes the next generation. Profiles that already exist keep their values until their entity is generated again. Each entity picks the new schema up as it sends more memories, and you can generate one now withgenerate_profile.
Rebuilding every profile in a project at once is not available yet. Refresh profiles one entity at a time with
generate_profile, or let each one update on its own as its entity sends more memories.When profiles update
You never call an “update profile” endpoint — Mem0 keeps each profile current for you. Two things drive it:- Automatically, as memories accumulate. Mem0 refreshes an entity’s profile after roughly every 10 messages it receives, folding the new memories into the existing profile. There is no schedule to wait for and no extra call to make: the same
addyou already do keeps the profile moving. - On demand. Call
generate_profileto build or refresh a profile immediately — useful for a brand-new entity that has not yet crossed the automatic threshold.
add may still show the previous profile (or pending). Branch on status rather than assuming the latest memory is already reflected.
Updates are incremental, not a full rebuild each time — Mem0 merges what it newly learns into the stored profile and keeps the fields your schema still defines. After a schema change, existing profiles pick it up as their entities send more memories, or when you call
generate_profile — see Apply a new schema to existing entities.Use a profile in a prompt
The point of the structure is that it drops straight into a prompt:Writing a schema that works
- Describe every field. The description is the instruction; without it the model guesses.
- Prefer durable traits. “Prefers dark mode” ages well; “is annoyed today” does not.
- Keep it small. Ten focused fields beat forty speculative ones, and cost less to generate.
- Say what the field is not. A description that rules out the near-miss interpretation is worth more than one that only states the obvious.
- Sample before you commit. It is the only way to see what your descriptions actually produce.
A schema has a size budget of roughly 10,000 tokens of serialized JSON — the whole schema is sent to the model on every generation, so a handful of verbose fields can cost more than many terse ones. Oversized schemas are rejected on save.
Availability
The feature is in beta and enabled per organization on request — see the note at the top of this page. Once it is on, an entity gets a profile when two more things hold:- profiles are enabled with a schema for the project (see Define the schema), and
- the memory is scoped to an entity — a
user_id.
status: not_enabled rather than an error, so you can call it unconditionally and branch on the status.
Settings reference
enabled is project-wide. schema and custom_instructions apply to user
profiles, so the stored settings nest them under entities:
update_profile_settings comes back unchanged from get_profile_settings.
Profile settings are per project. An API key is scoped to one project, so profiles never cross a project boundary.
FAQ
Do I need to change myadd or search calls to use profiles?
No. Profiles are built from the memories you already add. You define a schema once and read the profile when you need it — your ingestion and retrieval code is unchanged.
Why is profile empty even though the entity has memories?
Generation is asynchronous and needs enough to work with. Branch on status: pending means it is still building, and insufficient_data means there are not yet enough memories to fill the schema. Read again shortly, or call generate_profile to build one now.
Is sampling free?
No. sample_profiles runs real generations against real memories and keeps the profiles it produces, so it counts toward your usage like any other generation. It exists to check a schema on a few entities before you commit to it — not as a zero-cost dry run.
Does changing the schema rewrite existing profiles?
No. A schema change applies to the next generation. An existing profile keeps its values until its entity is generated again, which happens as that entity sends more memories, or when you call generate_profile for it.
What happens to a field I remove from the schema?
It stops being maintained. On an entity’s next generation, fields your schema no longer defines are pruned from the stored profile — so keep a field in the schema for as long as you want its value kept.
How current is a profile?
It refreshes automatically as memories accumulate (about every 10 messages for an entity), plus any on-demand generate_profile calls. Because refreshes run in the background, expect a short delay after the triggering add rather than an instant update.
Related
Entity-Scoped Memory
How users, agents, apps and runs partition memories.
Custom Instructions
Steer what Mem0 extracts in the first place.