diff --git a/docs/api-reference/profiles/generate-profiles.mdx b/docs/api-reference/profiles/generate-profiles.mdx index 4b215ad41..e5de5a12d 100644 --- a/docs/api-reference/profiles/generate-profiles.mdx +++ b/docs/api-reference/profiles/generate-profiles.mdx @@ -1,5 +1,5 @@ --- title: 'Generate Profiles' -description: "Start one generation: sample a few entities, build one, or rebuild the project." +description: "Start one generation: sample a few entities, or build one for a single entity." openapi: post /v2/profiles/jobs/ --- diff --git a/docs/api-reference/profiles/get-profile.mdx b/docs/api-reference/profiles/get-profile.mdx index fc10ef8f4..604535a3c 100644 --- a/docs/api-reference/profiles/get-profile.mdx +++ b/docs/api-reference/profiles/get-profile.mdx @@ -1,5 +1,5 @@ --- title: 'Get Profile' -description: "Retrieve the structured profile for a user or agent, with a status describing whether generation has completed." +description: "Retrieve the structured profile for a user, with a status describing whether generation has completed." openapi: get /v2/entities/{entity_type}/{entity_id}/profile/ --- diff --git a/docs/llms.txt b/docs/llms.txt index 807af9202..fe3ffc1d4 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -197,7 +197,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or a Platform call st ### Features - Essential - [V2 Memory Filters](https://docs.mem0.ai/platform/features/v2-memory-filters) [Platform]: Use when compound filters (AND/OR on metadata, entity, time) are needed at search. - [Entity-Scoped Memory](https://docs.mem0.ai/platform/features/entity-scoped-memory) [Platform]: Use when partitioning memories by user, agent, app, or run. -- [Profiles](https://docs.mem0.ai/platform/features/user-profiles) [Platform]: Use when a structured always-current summary of a user or agent is needed in one read, instead of searching their memories. +- [Profiles](https://docs.mem0.ai/platform/features/user-profiles) [Platform]: Use when a structured always-current summary of a user is needed in one read, instead of searching their memories. - [Graph Memory](https://docs.mem0.ai/platform/features/graph-memory) [Platform]: Use when connecting facts across memories through shared entities for entity-centric or multi-hop questions. - [Async Client](https://docs.mem0.ai/platform/features/async-client) [Platform]: Use when the app issues many concurrent Mem0 calls and needs non-blocking I/O. - [Multimodal Support](https://docs.mem0.ai/platform/features/multimodal-support) [Platform]: Use when storing images or PDFs as memory input. @@ -363,10 +363,10 @@ All API Reference docs describe Mem0 Platform REST endpoints (requires API key). ### Entities - [Get Users](https://docs.mem0.ai/api-reference/entities/get-users) [Platform]: Use when listing users, agents, or apps known to a project. - [Delete User](https://docs.mem0.ai/api-reference/entities/delete-user) [Platform]: Use when removing an entity and all its memories. -- [Get Profile](https://docs.mem0.ai/api-reference/profiles/get-profile) [Platform]: Use when reading a user's or agent's structured profile and branching on its generation status. +- [Get Profile](https://docs.mem0.ai/api-reference/profiles/get-profile) [Platform]: Use when reading a user's structured profile and branching on its generation status. - [Get Profile Settings](https://docs.mem0.ai/api-reference/profiles/get-profile-settings) [Platform]: Use when checking the project's profile schema, instructions, or enabled flag. - [Update Profile Settings](https://docs.mem0.ai/api-reference/profiles/update-profile-settings) [Platform]: Use when defining or changing the JSON Schema that shapes profiles for a project. -- [Generate Profiles](https://docs.mem0.ai/api-reference/profiles/generate-profiles) [Platform]: Use when building profiles now: a sample of ten, one entity, or the whole project. +- [Generate Profiles](https://docs.mem0.ai/api-reference/profiles/generate-profiles) [Platform]: Use when building profiles now: a sample of ten, or one entity. - [Get Generation Job](https://docs.mem0.ai/api-reference/profiles/get-profile-job) [Platform]: Use when checking how far a generation has got, and whether it finished. ### Organizations diff --git a/docs/openapi.json b/docs/openapi.json index 3ac7284a6..e5d6b55ce 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -8078,7 +8078,7 @@ ], "operationId": "profiles_read", "summary": "Get an entity's profile", - "description": "Return the memory profile for one user or agent.\n\nGeneration is asynchronous, so a known entity that has no profile yet is a normal 200 carrying a `status`. A 404 means only that no such entity exists.", + "description": "Return the memory profile for one user.\n\nGeneration is asynchronous, so a known entity that has no profile yet is a normal 200 carrying a `status`. A 404 means only that no such entity exists.", "parameters": [ { "name": "entity_type", @@ -8087,8 +8087,7 @@ "schema": { "type": "string", "enum": [ - "user", - "agent" + "user" ] }, "description": "The kind of entity that carries the profile." @@ -8130,8 +8129,7 @@ "entity_type": { "type": "string", "enum": [ - "user", - "agent" + "user" ] }, "entity_id": { @@ -8272,12 +8270,12 @@ ], "operationId": "profiles_create_job", "summary": "Generate profiles", - "description": "Start one generation. `operation` says what to build:\n\n- `sample` — up to 10 real entities, so a schema can be judged before it is used widely. These are real profiles: they are saved to those entities and count toward usage.\n- `trigger` — one entity, named by `entity_id`.\n- `regenerate` — every entity in the project. Not available yet; returns 501 `not_yet_available` and creates nothing. Check `capabilities.full_rebuild` on the settings route first.\n\nSend an `Idempotency-Key` header. Replaying the same key returns the same job instead of charging twice. Poll `status_url` from the response until the status is terminal.", + "description": "Start one generation. `operation` says what to build:\n\n- `sample` — up to 10 real entities, so a schema can be judged before it is used widely. These are real profiles: they are saved to those entities and count toward usage.\n- `trigger` — one entity, named by `entity_id`.\n\nSend an `Idempotency-Key` header. Replaying the same key returns the same job instead of charging twice. Poll `status_url` from the response until the status is terminal.", "parameters": [ { "in": "header", "name": "Idempotency-Key", - "required": false, + "required": true, "schema": { "type": "string", "minLength": 8, @@ -8300,16 +8298,14 @@ "type": "string", "enum": [ "sample", - "trigger", - "regenerate" + "trigger" ], "description": "What to generate. Optional only when `entity_id` is set, which means `trigger`." }, "entity_type": { "type": "string", "enum": [ - "user", - "agent" + "user" ], "default": "user" }, @@ -8388,9 +8384,6 @@ "429": { "description": "Cooldown. `retry_after_seconds` sits inside `error`." }, - "501": { - "description": "`not_yet_available` — this operation does not exist yet. Nothing is created or charged." - }, "503": { "description": "`jobs_unavailable` — generation is switched off for this project." } diff --git a/docs/platform/features/user-profiles.mdx b/docs/platform/features/user-profiles.mdx index eca4bd233..4575784b5 100644 --- a/docs/platform/features/user-profiles.mdx +++ b/docs/platform/features/user-profiles.mdx @@ -1,6 +1,6 @@ --- title: Profiles -description: "Build a structured, always-current summary of each user or agent from their memories, shaped by a JSON Schema you define." +description: "Build a structured, always-current summary of each user from their memories, shaped by a JSON Schema you define." icon: "id-card" --- @@ -17,8 +17,6 @@ Search answers "what did this user say about X". A profile answers "who is this - You want the same fields for every user, so your code can rely on their shape. -Profiles cover **users and agents**. An agent profile summarizes how an agent behaves, in the same way a user profile summarizes a person. - Profiles are a **Pro-plan feature** — see [Plan availability](#plan-availability) for the details. ## How it works @@ -137,10 +135,13 @@ A response looks like this: "status": "succeeded", "entity_type": "user", "entity_id": "alice", - "updated_at": "2026-02-08T10:30:00Z" + "updated_at": "2026-02-08T10:30:00Z", + "generation_count": 3 } ``` +`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. @@ -155,18 +156,6 @@ A response looks like this: A `404` means only that no such entity exists in your project. -For an agent, pass the entity type: - - -```python Python -client.get_profile("support-bot", entity_type="agent") -``` - -```typescript TypeScript -await client.getProfile({ entityId: "support-bot", entityType: "agent" }); -``` - - ## 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: @@ -185,20 +174,32 @@ The call returns as soon as the work is queued. Poll the read endpoint and branc ## 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: +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. Poll `status_url` until the job is terminal, then read each sampled entity's profile: ```python Python -result = client.sample_profiles(limit=5) +job = client.sample_profiles(limit=5) -for row in result["results"]: +# Poll until the sample job finishes. +status = client.get_profile_job(job["status_url"])["job"] +print(status["status"], status["succeeded"], "of", status["total"]) + +# Each result names one sampled entity; read its saved profile. +for row in status["results"]: print(client.get_profile(row["entity_id"])) ``` ```typescript TypeScript -const result = await client.sampleProfiles({ limit: 5 }); +const job = await client.sampleProfiles({ limit: 5 }); -for (const row of result.results) { +// Poll until the sample job finishes. +const { job: status } = await client.getProfileJob(job.statusUrl); +console.log(status.status, status.succeeded, "of", status.total); + +// Each result names one sampled entity; read its saved profile. +for (const row of status.results ?? []) { console.log(await client.getProfile({ entityId: row.entityId })); } ``` @@ -206,22 +207,6 @@ for (const row of result.results) { These are real generations. The profiles are saved to those entities and count toward your usage, so sampling is not wasted work and not a free dry run. A sample covers up to 10 entities and cannot be repeated immediately. -Both calls return as soon as the job is queued. Poll `status_url` to see how it went: - - -```python Python -job = client.sample_profiles(limit=5) -status = client.get_profile_job(job["status_url"])["job"] -print(status["status"], status["succeeded"], "of", status["total"]) -``` - -```typescript TypeScript -const job = await client.sampleProfiles({ limit: 5 }); -const { job: status } = await client.getProfileJob(job.statusUrl); -console.log(status.status, status.succeeded, "of", status.total); -``` - - ## 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. @@ -229,7 +214,7 @@ A new schema shapes the next generation. Profiles that already exist keep their Each entity picks the new schema up as it sends more memories, and you can generate one now with `generate_profile`. -Rebuilding a whole project in one call is not available yet. `regenerate_profiles()` returns `501 not_yet_available` and creates nothing. Check `capabilities.full_rebuild` in the settings response before you offer it. +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 @@ -242,7 +227,7 @@ You never call an "update profile" endpoint — Mem0 keeps each profile current Generation is **asynchronous and incremental**. A refresh runs in the background a short while after its trigger, so a read taken immediately after an `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. To rebuild every profile from scratch after a schema change, use [regenerate](#apply-a-new-schema-to-existing-entities). + 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](#apply-a-new-schema-to-existing-entities). ## Use a profile in a prompt @@ -281,13 +266,13 @@ else: | Capability | Free | Starter | Pro | Enterprise | |---|:---:|:---:|:---:|:---:| | **Profiles** (define a schema, generate, read) | — | — | ✓ | ✓ | -| **Profiles dashboard** (schema editor, samples, regenerate) | — | — | ✓ | ✓ | +| **Profiles dashboard** (schema editor, samples) | — | — | ✓ | ✓ | Profiles require a **Pro plan or higher**. For an individual entity to get a profile, three things must hold: - the project is on **Pro or above**, - profiles are **enabled** with a schema for the project (see [Define the schema](#define-the-schema)), and -- the memory is scoped to an entity — a `user_id`, or an `agent_id` for agent profiles. +- the memory is scoped to an entity — a `user_id`. On a project where profiles are turned off, a read returns `status: not_enabled` rather than an error, so you can call it unconditionally and branch on the status. @@ -320,9 +305,6 @@ No. A schema change applies to the next generation. An existing profile keeps 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. -**Can I have profiles for agents, not just users?** -Yes. Pass `entity_type="agent"` to `get_profile` / `generate_profile`. An agent profile summarizes an agent the same way a user profile summarizes a person. - **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.