Core Concepts

This page explains the fundamental concepts in Reflexio that power intelligent agent memory and personalization.

Interactions

Interactions are the primary inputs that users publish to Reflexio, representing any form of user activity or communication with your system. Think of interactions as the raw material from which Reflexio builds its understanding of users and their behavior.

What Are Interactions?

Interactions capture the complete context of user engagement, including:

• Conversational exchanges between users and agents
• User actions like clicks, scrolls, and form submissions
• Visual content such as images users share or view
• Contextual information about what users are doing when they interact

Types of Interactions

Text-Based Interactions

InteractionData(
    role="User",
    content="I'm looking for a laptop for software development",
    user_action=UserActionType.NONE
)

These capture conversational content, questions, comments, and any textual communication.

Action-Based Interactions

InteractionData(
    user_action=UserActionType.CLICK,
    user_action_description="clicked 'Add to Cart' for MacBook Pro",
    content=""
)

These track user behavior like button clicks, page navigation, form submissions, and other interface interactions.

Visual Interactions

InteractionData(
    content="I love this design!",
    image_encoding=base64_image_data,
    interacted_image_url="https://example.com/design.jpg"
)

These include images users share, screenshots they provide, or visual content they're viewing when they interact.

Interaction Metadata

Every interaction includes rich metadata:

• Role: Who is speaking (User, Agent, System, etc.)
• Source: Where the interaction came from (chat, email, support ticket, etc.)
• Request ID: For tracking related interactions and attribution
• Timestamps: When the interaction occurred
• Agent Version: Which version of your agent was involved

How Interactions Flow Through Reflexio

1. Input: Your application publishes interactions to Reflexio
2. Processing: Reflexio analyzes the interaction content and context
3. Profile Extraction: Relevant user information is extracted and stored as profiles
4. Playbook Analysis: Any agent playbook signals are identified and processed
5. Storage: The interaction is stored with vector embeddings for semantic search

User Profiles

Profiles are Reflexio's configurable memory system for each user, automatically extracted from interactions to enable personalization and long-term memory across sessions. Think of profiles as your agent's memory of each user — not just what they said, but what it means for their needs and preferences.

• AI-extracted — configurable prompts control what gets extracted from each interaction
• Semantically searchable — query profiles with natural language, not exact matches
• Evolving — new interactions automatically update and refine existing profiles
• Source-tracked — every profile records which interaction created it and when

# Search for relevant user context before responding
profiles = client.search_profiles(
    user_id="user_123",
    query="laptop preferences and budget",
    threshold=0.7
)

For extraction configuration, profile lifecycle, and advanced usage, see Understanding User Profiles.

Agent Playbook System

The playbook system captures how users respond to agent behavior and turns individual signals into actionable improvement recommendations. While profiles are per-user memory, playbooks are agent-level data — they help your agent get better for everyone.

The system operates as a two-stage pipeline:

User Playbooks

User playbooks are extracted automatically from individual user interactions. Each user playbook captures a single signal — a complaint, suggestion, or preference — tied to a specific user, interaction, and agent version. Think of user playbooks as individual data points: "User A said responses were too long," "User B asked for more detail," etc.

Agent Playbooks

When enough user playbooks accumulate around a common theme, Reflexio clusters and synthesizes them into agent playbooks — consolidated, cross-user recommendations for agent improvement. Agent playbooks strip away user-specific context and distill the pattern into actionable content (what to do or avoid) with a trigger (when to apply it).

# 1. User playbooks extracted from individual interactions:
#    User A: "Your recommendation was too expensive" → user playbook created
#    User B: "I said under budget, why show premium?"  → user playbook created
#
# 2. Aggregation clusters these and synthesizes:
#    Agent playbook: "Strictly respect stated budget constraints in recommendations"

For playbook configuration, aggregation thresholds, and the improvement cycle, see Understanding Agent Playbooks.

How Concepts Work Together

When a user interacts with your agent, Reflexio processes that interaction through two parallel pipelines:

1. User interacts with your agent → Interaction is published to Reflexio
2. Profile extraction analyzes the interaction → User profiles are created or updated
3. Playbook analysis checks for agent improvement signals → User playbooks are extracted if found
4. Personalization uses profiles → Agent provides tailored responses
5. Improvement uses agent playbooks → Agent evolves over time

This two-track system — profiles for personalization, playbooks for improvement — creates a continuously learning agent ecosystem that serves users better over time.