Playbooks

Playbooks capture how an agent should behave. They are behavioral guidance at two scopes: user-specific evidence and agent-wide rules.

User Playbooks

User playbooks are extracted from one user's interactions. They capture a correction, constraint, or successful procedure tied to its source evidence—for example, “When this user asks for a recommendation, respect the stated budget before optimizing other attributes.”

They are useful for personalization and as evidence for broader improvement, but they should not be mistaken for universal policy.

Agent Playbooks

Agent playbooks consolidate recurring user-playbook patterns into guidance for an agent version. They remove user-specific detail and express an actionable trigger and response.

Agent playbooks use a human approval gate:

User interactions
    ↓ extraction
User playbooks
    ↓ clustering and synthesis
Pending agent playbook
    ↓ human review
Approved or rejected

Only approved agent playbooks should be treated as validated agent-wide guidance.

Retrieval Behavior

Unified search can return profiles, user playbooks, and agent playbooks together. When a returned agent playbook already represents a source user playbook, Reflexio suppresses that duplicate user playbook from the result.

Use:

• User playbooks for user-specific steering and source-level debugging.
• Approved agent playbooks for reusable behavior across users.
• Pending agent playbooks for review, not production prompting.

Configuration and Optimization

Reflexio includes a default playbook extractor and aggregator. Tune extraction prompts or aggregation thresholds only after observing real traffic. Optional playbook optimization can refine content against replayable source windows while preserving the normal approval rules.

Aggregation is incremental and durable. Publishing a qualifying user playbook schedules bounded background work, and unfinished items remain pending across restarts. Successful bounded batches continue on subsequent scheduler polls until the version is drained. Identical residual work backs off progressively instead of repeating every poll; a source lifecycle change makes it immediately eligible again. Similar new items are batched by an existing cluster. On the hourly run, Reflexio makes one update call with the current agent playbook plus up to the 100 newest items in that cluster's delta, while attaching the complete delta as cluster membership. It embeds the replacement, supersedes the prior agent playbook, and uses the replacement embedding as the next centroid. Clustering and centroid matching are isolated by agent version, so playbooks from different versions are never clustered together. When a source lifecycle change requires a cluster rebuild, Reflexio generates from the 100 most recent remaining sources without using the invalidated agent playbook as model context. It restores the complete retained membership while the replacement, new embedding centroid, and superseding of the prior agent commit atomically. Existing cluster fingerprints are adopted in bounded pages on upgrade so rollout does not regenerate already-represented rules. The manual run_playbook_aggregation operation remains a full rebuild: it is serialized with automatic work, snapshots its bounded inputs before model calls, atomically rebuilds the incremental state, and leaves changes committed after that snapshot pending for the next run. It returns a failure when the corpus exceeds the configured safety cap.

Scheduled clustering considers only the newest 20,000 unclustered user playbooks by default (configured by REFLEXIO_MAX_CLUSTERING_PLAYBOOKS). Older unclustered rows are intentionally left out permanently rather than added in later runs. Large clusters use at most 100 representative source items for generation while retaining their complete durable membership. Generation compares each cluster with a small relevance-ranked set of current agent playbooks from that same version. This keeps prompt construction and repeated model context bounded without allowing rules from different agent versions to mix.

New user playbooks schedule discovery directly instead of producing lifecycle invalidation records. If a clustered agent playbook is later edited, rejected, archived, or deleted, Reflexio retires that centroid and returns its source members to residual discovery so rejected or stale guidance is not refreshed.

For integration patterns, see Collecting and Using Playbooks. For optimization details, see Playbook Optimization. For exact methods and schemas, see the Playbook API Reference.