Searching Learned Context

Use unified search, profile search, and playbook search to retrieve the right Reflexio context for your agent.

Searching Learned Context

Search is how your agent turns Reflexio's learned context back into runtime behavior. Use unified search for most agent turns, then use profile or playbook search directly when you need a narrower workflow.

API reference

For complete parameters, response schemas, and cURL payloads, use the Unified Search API Reference, Profiles API Reference, and Playbook API Reference.

Which Search Should I Use?

Default for agent turns

Unified search

client.search

Retrieves profiles, agent playbooks, and user playbooks together so your agent can build complete prompt context in one call.

Returns all learned context types

User memory

Profile search

client.search_user_profiles

Finds durable user facts, preferences, goals, constraints, and other profile memory for a specific user.

Returns user profiles

Per-interaction lessons

User playbook search

client.search_user_playbooks

Finds raw user-level playbook signals when you need to inspect evidence, debug behavior, or review recent lessons.

Returns user playbooks

Reusable behavior rules

Agent playbook search

client.search_agent_playbooks

Finds consolidated agent guidance, usually filtered to approved playbooks for production prompt context.

Returns agent playbooks

Unified search is usually the best default because it searches the three learned context types in parallel. Entity-specific search is better for review screens, debugging, audits, or workflows that only need one type of result.

Unified Search

Unified search calls /api/search and fans out across profiles, user playbooks, and agent playbooks. top_k applies per entity type, so top_k=3 can return up to three profiles, three user playbooks, and three agent playbooks.

API reference: client.search.

When an agent playbook represents one or more source user playbooks, Reflexio omits those represented user playbooks from the user_playbooks result to avoid injecting duplicate guidance.

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var

results = client.search(
    query="customer wants a concise answer about billing dispute next steps",
    user_id="customer_123",
    agent_version="support-agent@2026-06-21",
    top_k=4,
    threshold=0.35,
    agent_playbook_status_filter=["approved"],
)

profile_context = "\n".join(f"- {profile.content}" for profile in results.profiles)
agent_playbook_context = "\n".join(
    f"- {playbook.content}" for playbook in results.agent_playbooks
)
user_playbook_context = "\n".join(
    f"- {playbook.content}" for playbook in results.user_playbooks
)

system_context = f"""
User profiles:
{profile_context or "- No matching profiles."}

Approved agent playbooks:
{agent_playbook_context or "- No matching agent playbooks."}

Recent user-specific playbook signals:
{user_playbook_context or "- No matching user playbooks."}
""".strip()

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "customer wants a concise answer about billing dispute next steps",
  "user_id": "customer_123",
  "agent_version": "support-agent@2026-06-21",
  "top_k": 4,
  "threshold": 0.35,
  "agent_playbook_status_filter": ["approved"]
}
JSON

Narrow Unified Search

Use entity_types when you want the unified search behavior, query reformulation, and shared filters, but only need some result types.

profile_and_agent_guidance = client.search(
    query="how should we answer this premium user about renewal?",
    user_id="customer_123",
    agent_version="support-agent@2026-06-21",
    entity_types=["profiles", "agent_playbooks"],
    agent_playbook_status_filter=["approved"],
    top_k=5,
)

Use enable_reformulation=True when the user's latest message depends on recent conversation context. Pass conversation_history so Reflexio can rewrite the query before retrieval.

results = client.search(
    query="what should I say next?",
    user_id="customer_123",
    conversation_history=[
        {"role": "user", "content": "I was charged twice for my plan."},
        {"role": "assistant", "content": "I can help check the invoice."},
    ],
    enable_reformulation=True,
    top_k=3,
)

Profile Search

Profile search is scoped to one user_id. Use it when you only need durable facts, preferences, goals, constraints, or user-specific memory.

API reference: client.search_user_profiles.

profiles = client.search_user_profiles(
    user_id="customer_123",
    query="billing preferences communication style",
    tags=["billing"],
    top_k=5,
    threshold=0.6,
)

for profile in profiles.user_profiles:
    print(profile.content)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_profiles" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "user_id": "customer_123",
  "query": "billing preferences communication style",
  "tags": ["billing"],
  "top_k": 5,
  "threshold": 0.6
}
JSON

Profile search also supports filters such as source, custom_feature, generated_from_request_id, start_time, end_time, tags, and search_mode.

User Playbook Search

User playbooks are interaction-level lessons extracted from a user's actual experience. Search them when you want to inspect the evidence behind behavior changes, find recent user-specific signals, or debug why an aggregated agent playbook exists.

API reference: client.search_user_playbooks.

user_playbooks = client.search_user_playbooks(
    query="billing disputes require concise next steps",
    user_id="customer_123",
    agent_version="support-agent@2026-06-21",
    tags=["billing"],
    top_k=10,
)

for playbook in user_playbooks.user_playbooks:
    print(playbook.request_id, playbook.content)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_user_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "billing disputes require concise next steps",
  "user_id": "customer_123",
  "agent_version": "support-agent@2026-06-21",
  "tags": ["billing"],
  "top_k": 10
}
JSON

Use user playbook search for investigation and review. For production prompt injection, prefer unified search or approved agent playbook search so your agent does not overfit to a single interaction.

Agent Playbook Search

Agent playbooks are consolidated rules intended to guide the agent across users. Search them when you want reusable behavior guidance, especially approved playbooks for production traffic.

API reference: client.search_agent_playbooks.

agent_playbooks = client.search_agent_playbooks(
    query="billing disputes require concise next steps",
    agent_version="support-agent@2026-06-21",
    playbook_status_filter="approved",
    tags=["billing"],
    top_k=5,
)

for playbook in agent_playbooks.agent_playbooks:
    print(playbook.playbook_name, playbook.content)

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/search_agent_playbooks" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "billing disputes require concise next steps",
  "agent_version": "support-agent@2026-06-21",
  "playbook_status_filter": "approved",
  "tags": ["billing"],
  "top_k": 5
}
JSON

For agent-facing context, filter to approved playbooks unless you intentionally want to preview pending or rejected guidance in an internal review workflow.

Search Modes and Tags

Use search_mode when you need explicit retrieval behavior, and use tags to keep retrieval aligned to a product area, workflow, or domain.

Setting	Use when	Example
`search_mode="hybrid"`Default when hybrid search is configured	You want both semantic similarity and keyword matching.	`search_mode="hybrid"`
`search_mode="vector"`Conceptual retrieval	The query is conceptual and does not depend on exact keywords.	`search_mode="vector"`
`search_mode="fts"`Keyword retrieval	Exact terms, identifiers, or product names matter more than semantic similarity.	`search_mode="fts"`
`tags`Domain filtering	Match profiles, user playbooks, or agent playbooks that have any requested tag.	`tags=["billing", "support"]`

Practical Defaults

Start with client.search for agent turns.
Pass user_id whenever the result should include user profiles or user-level playbooks.
Pass agent_version when searching playbooks for a specific deployed agent version.
Use agent_playbook_status_filter=["approved"] or playbook_status_filter="approved" for production prompt context.
Keep top_k small enough that the retrieved context fits your model prompt.
Lower threshold if useful context is missing; raise it if results are noisy.