docs(profiles): make profiles docs user-only and match the shipped API
Hide agent profiles for this release (backend exists but is gated off) and sync the guide, api-reference, openapi, and llms.txt to the User Profiles feature head. Agent removal: - Drop "users and agents" framing, the entity_type="agent" get_profile example, and the "profiles for agents" FAQ from the guide. - Reduce entity_type to user-only in the read path/param/response and the jobs request body in openapi.json; drop "or agent" from the api-ref and llms.txt descriptions. Code sync (verified against the feature head): - Read example + prose now include generation_count alongside profile, status, entity_type, entity_id, updated_at. - Sample flow corrected: sample_profiles returns a job; poll get_profile_job and read each result's entity, instead of iterating a non-existent results field on the create response. - Bulk regenerate is gated off for v1 (FULL_REBUILD_ENABLED=False): remove it from the guide, openapi operation enum, and the 501 note; keep only sample and trigger. Idempotency-Key marked required to match the backend. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
karthik
@@ -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/
|
||||
---
|
||||
|
||||
@@ -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/
|
||||
---
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
+7
-14
@@ -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."
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
</Info>
|
||||
|
||||
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:
|
||||
|
||||
<CodeGroup>
|
||||
```python Python
|
||||
client.get_profile("support-bot", entity_type="agent")
|
||||
```
|
||||
|
||||
```typescript TypeScript
|
||||
await client.getProfile({ entityId: "support-bot", entityType: "agent" });
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 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:
|
||||
|
||||
<CodeGroup>
|
||||
```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:
|
||||
|
||||
<CodeGroup>
|
||||
```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);
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
## 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`.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user