x-for-you-feed

name

x-for-you-feed

description

Structured reference for xai-org/x-algorithm, the official X For You feed codebase. Maps retrieval (Thunder, Phoenix, SimClusters), Phoenix transformer ranking, weighted multi-action scoring, VMRanker DPP reranking, visibility filtering, labeling systems, and production params to file paths and workflows. Use when analyzing x-algorithm, explaining For You feed behavior, composing and optimizing high-performance posts, auditing tweet drafts for algorithmic reach, debugging visibility drops, comparing algorithm diffs, or implementing recommendation pipeline patterns from the open source release.

X For You Feed Algorithm

Structured reference for xai-org/x-algorithm. The upstream repository is the source of truth. This skill maps concepts to paths and defines agent workflows.

Core mental model

Three independent concerns compose every For You response:

Concern	Question	Primary code
Retrieval	Which posts enter the candidate pool?	thunder/, phoenix/ retrieval, simclusters/
Ranking	In what order?	home-mixer/scorers/, phoenix/ ranking, vm-ranker/
Visibility	Can this post be shown to this viewer?	visibility-filtering/, labeling path

Ranking and visibility are separate services. A high score does not override a DROP verdict. Visibility filtering runs after top-K selection.

Request path (Post Pipeline)

Execute stages in order. Stage toggles and defaults live in home-mixer/params/param.rs.

Query Hydration
  -> Candidate Sources (parallel)
  -> Candidate Hydration
  -> Pre-Scoring Filters
  -> Scoring
  -> Top-K Selection
  -> Post-Selection Hydration + Filters
  -> [Blending Pipeline: ads, Who to Follow, prompts]

Item	Path
Pipeline definition	home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs
Pipeline framework	candidate-pipeline/

Framework stage types: source, hydrator, filter, scorer, selector, side effect.

1. Query hydration

Loads viewer context before candidates are fetched:

• User action sequence (recent engagements; primary model input)
• Following list, blocks, mutes, muted keywords
• Previously seen or served posts, followed topics, demographics

Directory: home-mixer/query_hydrators/

2. Candidate sources (parallel)

Source	Network	Mechanism	Default max results
Thunder	In-network	In-memory recent posts from followed accounts	1200
Phoenix retrieval	Out-of-network	Two-tower embedding similarity	1000
SimClusters	Out-of-network	Community cluster similarity	See source implementation

Thunder excludes already-seen posts at the source. Other sources rely on pre-scoring filters for deduplication.

3. Candidate hydration

Enriches each candidate with text, media, author labels, language, engagement counts, subscription status, bidirectional-follow flag, and semantic IDs.

Directory: home-mixer/candidate_hydrators/

VFCandidateHydrator is not in this stage. It runs in post-selection hydration (see section 7).

4. Pre-scoring filters

Remove ineligible candidates before model inference. Full ordered list: reference/pipeline.md.

Filter	Behavior
AgeFilter	Removes posts older than 48 hours
OONRetweetReplyFilter	Drops OON reposts and replies; IN-network reposts and replies receive OON discount at scoring
PreviouslySeenPostsFilter (+ backup, served)	Impression deduplication
AuthorSocialgraphFilter	Blocked or muted authors
NewUserMinEngagementFilter	OON posts below engagement threshold for new accounts

5. Scoring chain

Three scorers run in sequence:

Order	Scorer	Path	Role
1	PhoenixScorer	home-mixer/scorers/phoenix_scorer.rs	Predicts P(action) per head
2	RankingScorer	home-mixer/scorers/ranking_scorer.rs	Weighted sum and post-processing
3	VMRanker	home-mixer/scorers/vm_ranker.rs	Calls vm-ranker/ DPP reranking service

6. Selection

TopKScoreSelector (home-mixer/selectors/top_k_score_selector.rs) sorts by final score and keeps top K.

7. Post-selection hydration and filters

Runs after top-K selection:

Hydrators (post_selection_hydrators in pipeline):

Hydrator	Role
VFCandidateHydrator	Fetches visibility-filtering verdicts
AdsBrandSafetyVfHydrator	Brand safety labels for ads
TweetTypeMetricsHydrator	Tweet type metrics
FollowingRepliedUsersHydrator	Reply graph context
MutualFollowJaccardHydrator	Mutual follow signals
TopicFeedbackContextHydrator	Topic feedback context

Filters (post_selection_filters):

Filter	Role
VFFilter	Removes posts with DROP verdict
AncillaryVFFilter	Drops posts whose parent, quote, or repost ancestor was dropped
DedupConversationFilter	Collapses conversation branches

For You OON recommendations use safety level TimelineHomeRecommendations, which includes additional OON-only rules beyond the base home policy.

Scoring formula

Step 1: Weighted sum

score = sum(weight_i * P(action_i))

Production weights (synced 2026-08-12): reference/scoring-weights.md

Largest positive weights in param.rs defaults:

• Share via copy link: 20.0 (40x a like)
• Reply (mutual follow boost): 20.0 total (15.0 boost + 5.0 base)
• Reply: 5.0 (10x a like)
• Quote: 5.0 (10x a like)
• Share via DM: 5.0 (10x a like)
• Follow author: 4.0 (8x a like)
• Repost: 1.0 (2x a like)
• Favorite: 0.5 (baseline)

Largest magnitude negative penalties:

• Report: -234.0 (wipes out 468 likes)
• Mute author: -58.8 (wipes out 117 likes)
• Not interested: -43.2 (wipes out 86 likes)
• Block author: -31.2 (wipes out 62 likes)

Step 2: Post-sum adjustments

Applied in RankingScorer (ranking_scorer.rs):

Adjustment	Params	Default behavior
Author diversity	AuthorDiversityDecay, AuthorDiversityFloor	Multiplier (1 - floor) * decay^k + floor per author occurrence k in slate
OON discount	OonWeightFactor	OON posts multiplied by 0.75
IN repost/reply discount	EnableOonRescoreForInNetworkRepliesRetweets	IN reposts and replies also multiplied by OON factor when enabled
Cold start	ColdStartImpressionThreshold, ColdStartSlotMin, ColdStartSlotMax	Authors under 1000 impressions boosted toward slot positions 15-16
Bidirectional follow	BidirectionalFollowReplyWeightBoost, BidirectionalFollowDwellWeightBoost	Additive weight on reply and dwell predictions for mutual follows

Implementation: AuthorColdStart in home-mixer/scorers/author_cold_start.rs.

Step 3: VMRanker DPP

Determinantal point process over post embeddings reorders candidates for diversity. Defaults: VMRankerDppTheta = 0.65, VMRankerDppMaxSelectedRank = 150. Code: vm-ranker/dpp.rs.

Labeling path (offline to request)

Runs continuously, not per request:

Content understanding -> Labeling rules -> Storage -> Visibility filtering -> VFFilter

Stage	Systems
Post and media classifiers	grox/, media-model-proxy/, clip/
Account scoring	agatha/, bdsm/, user-cred-v2/
Event rules	scarecrow/, botmaker/, botmaker-rules/
Enforcement	abuse-enforcement-service/
User-level aggregation	safety-label-user-agg/

VF verdicts: ALLOW, INTERSTITIAL (viewer can tap through), DROP.

Rule evaluation: first matching DROP ends evaluation. OON recommendation rules apply only when the viewer does not follow the author. The same post may ALLOW for followers and DROP for non-followers.

Rule registry: visibility-filtering/rules/registry.rs. Details: reference/visibility-filtering.md.

Phoenix model

Production JAX ranking and retrieval in phoenix/. Documented design constraints:

Constraint	Description
Candidate isolation	Candidates attend to user context only, not each other; scores are batch-independent
Hash-based embeddings	No fixed vocabulary; new posts represented immediately
Multi-action heads	Separate logits per engagement type
Retrieval	Two-tower with semantic IDs (6 x 256 residual quantization) and hashed author IDs

Local run via synthetic data: phoenix/QUICKSTART.md. Architecture detail: reference/phoenix-model.md.

Agent workflows

Workflow A: Explain ranking score

1. Identify network type (IN via Thunder vs OON via Phoenix or SimClusters)
2. Read weights in home-mixer/params/param.rs
3. Map predicted actions to weight contributions using reference/scoring-weights.md
4. Check adjustments: OON factor, author diversity multipliers, cold start, bidirectional follow boost
5. Note VMRanker may reorder via DPP
6. Visibility is separate; high score does not prevent post-selection DROP

Workflow B: Explain visibility drop

1. Determine whether the post is an OON recommendation (additional rule set)
2. Walk visibility-filtering/rules/registry.rs in evaluation order
3. Cross-reference labels via Under the Hood (under-the-hood/, https://x.com/i/under_the_hood)
4. Check AncillaryVFFilter for ancestor drops
5. Note OON-only rules (e.g. spam high recall) do not apply to followers

Workflow C: Track algorithm change

1. Read annotated diffs in docs/ (e.g. BIDIRECTIONAL_BOOST_CHANGE.md)
2. Diff home-mixer/params/param.rs for weight and default changes
3. Check pipeline registration in phoenix_candidate_pipeline.rs
4. Describe behavioral change in plain language, then cite code and params

Workflow D: Navigate unfamiliar component

Use reference/component-index.md.

Workflow E: Post composition and quality engineering

When composing or rewriting a post or thread for maximum distribution:

1. Target the 20x Copy Link Factor: Formulate the core payload as a dense, reference-grade asset (framework, cheat sheet, benchmark, breakdown) that motivates readers to copy the link or bookmark (ShareViaCopyLinkWeight = 20.0).
2. Engineer High-Signal Reply Prompts: End with a specific, opinionated question to trigger peer replies (5.0 weight) and mutual follower interactions (+15.0 boost).
3. Format for Dwell Time: Structure with clean whitespace, scannable lists, and visual assets to capture continuous dwell time (ContDwellTimeWeight = 0.004) while preventing quick bounces (NotDwelledWeight = -0.02).
4. Shield Against Negative Penalties: Remove polarizing ragebait, misleading claims, and hashtag spam to prevent "Not Interested" (-43.2) or "Report" (-234.0) clicks.
5. Ensure OON Standalone Integrity: Make the root post completely self-contained. Keep external links out of the primary post body.
6. Reference deep composition patterns in reference/post-optimization.md.

Workflow F: Draft audit and pre-flight check

When auditing a user's draft tweet or thread:

1. Calculate Multi-Action Score Potential: Assess predicted probability across copy-link, reply, quote, repost, favorite, and dwell heads.
2. Run Negative Penalty Vulnerability Scan: Flag phrases or hooks likely to generate report, mute, or not-interested signals.
3. Verify OON Eligibility: Ensure original format, zero duplicate text, and clean media.
4. Inspect Thread Cascade Safety: Check root post against AncillaryVFFilter to ensure thread descendants will not be collapsed.
5. Provide a clear Before vs After optimization breakdown.

Unpublished in the repository

Do not infer behavior for systems not in the repo:

• Some Grox LLM prompts (.j2 files)
• Some botmaker rules
• Production data feeds, cluster orchestration, internal infrastructure imports

Under the Hood label reports plus published code provide transparency for unpublished rule outcomes.

Output conventions

When responding:

• Ground composition advice in actual mathematical weights (param.rs)
• Separate ranking (order) from visibility (eligibility)
• Separate IN-network from OON; different filters and VF rules apply
• Cite file paths and param names for production defaults
• Check param.rs sync timestamp comment for weight freshness
• State when behavior is inferred vs documented in source

Additional resources

Topic	File
Post composition & quality engineering	reference/post-optimization.md
Pipeline stages and filter order	reference/pipeline.md
Production weight table	reference/scoring-weights.md
Retrieval sources	reference/retrieval-sources.md
Visibility rules	reference/visibility-filtering.md
Phoenix architecture	reference/phoenix-model.md
Component directory index	reference/component-index.md
Agent task examples	examples.md