Working with User Profiles

Reflexio 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)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_profiles" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"user_id":"user_123","query":"communication preferences","top_k":5}'

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.