Working with User Profiles

Emend extracts durable user facts with a default profile extractor. Start with the default and customize it only when real results show that your domain needs a narrower memory definition.

Retrieve Profiles Before Responding

Use unified search when the agent needs profiles and playbooks together:

context = client.search(    query=user_message,    user_id="user_123",    entity_types=["profiles", "user_playbooks", "agent_playbooks"],    top_k=5,)

Use profile search when you only need user memory or are diagnosing extraction:

profiles = client.search_user_profiles(    user_id="user_123",    query="communication preferences and current project constraints",    tags=["project-context"],    top_k=5,) for profile in profiles.user_profiles:    print(profile.content)

Profile search is scoped to user_id. Tags use match-any semantics. An empty result means nothing relevant cleared the configured retrieval threshold; it does not mean the request failed.

Inspect and Manage Profiles

Use get_profiles for list and lifecycle views, including exact ID, text, source, time, status, TTL, and tag filters. Pass force_refresh=True after a change when you need to bypass the client's short-lived cache.

current = client.get_profiles(    user_id="user_123",    status_filter=[None],    force_refresh=True,)

Use get_profile_change_log() to inspect consolidation changes. Use delete_profile or the bulk-delete methods only for explicit user or operator actions; normal profile evolution is handled by extraction and lineage-aware replacement.

Customize Extraction

Update only the top-level config fields you intend to replace:

client.update_config({    "profile_extractor_config": {        "extraction_definition_prompt": (            "Extract durable project constraints, data conventions, and communication preferences."        ),        "request_sources_enabled": ["assistant_chat"],    }})

Nested config objects are replaced rather than deep-merged. Read the current config first when you need to preserve existing nested fields.

Recommended Prompting Pattern

Render retrieved profiles as untrusted contextual facts, not system authority:

profile_context = "\n".join(f"- {profile.content}" for profile in context.profiles)prompt = f"""Use relevant user context when helpful. User context:{profile_context or "- No relevant profile context."}"""

For the lifecycle model, see User Profiles. For every filter and response field, see the Profile API Reference.