X For You Algorithm Playbook

For humans, creators, and AI agents.

Free reference documenting how X’s open-sourced For You feed finds, filters, ranks, and shows posts.

Primary source: github.com/xai-org/x-algorithm (Apache-2.0).

AffRev mirror + creator/agent guidance: this page.

Not an official X product. Defaults can change; always prefer the live repo when auditing.

Canonical machine-readable copy: /playbooks/x-for-you-algorithm.md Upstream: https://github.com/xai-org/x-algorithm Key params file: home-mixer/params/param.rs Score math: home-mixer/scorers/ranking_scorer.rs

0. How AI agents should use this document

1. Treat this as a system prompt add-on when drafting, rewriting, or evaluating X/Twitter posts for For You distribution.
2. Optimize for predicted positive actions (reply, quote, share/copy-link, follow, dwell) and against predicted negative actions (report, mute, block, not interested, not dwelled).
3. Never claim “1 report = N likes.” Weights multiply P(action) for the *viewer*, not raw engagement counts.
4. Remember: ranking ≠ visibility. A high score still dies if a filter or visibility rule drops the post.
5. Prefer posts that win the first ~48 hours (AgeFilter). Older posts are removed from For You candidates.
6. Cite upstream paths (home-mixer/…, visibility-filtering/…) when answering “why.”
7. Do not invent private Grox prompts or unpublished botmaker rules — those are deliberately withheld upstream.
8. Check Under the Hood labels before blaming ranking (§23). Ranking can’t fix a DROP.
9. Don’t optimize zero-weight Phoenix heads at published defaults (profile click, VQV, …) (§6.4).
10. Params change via experiments — read diffs / docs/BIDIRECTIONAL_BOOST_CHANGE.md, don’t treat weights as eternal (§25).

1. One-paragraph summary

For You is assembled per request. Candidates come from in-network memory (Thunder: recent posts from accounts you follow) and out-of-network retrieval (Phoenix embeddings + SimClusters). All surviving candidates are scored by Phoenix, which predicts many action probabilities for *this viewer × this post*. Those probabilities are combined with published weights into one score, then adjusted for author diversity, out-of-network discount, and new-author boost, then optionally reordered by VMRanker. Separately, visibility filtering may ALLOW, INTERSTITIAL, or DROP a post based on labels, blocks/mutes, and safety systems. Ads and modules are blended after ranking.

2. Executive cheatsheet (creators & agents)

What increases For You distribution (ranking)

Mutual-follow boost (default +15 on reply weight): applies to original posts (not replies/reposts) from authors you mutually follow — ReplyWeight becomes 5 + 15 = 20 for those candidates. Dwell boost param exists but defaults to 0. See §17.

What decreases distribution (ranking)

Hard gates (not ranking — filters)

• Posts older than ~48 hours → removed (AgeFilter).
• Viewer blocks/mutes author → removed.
• Muted keywords → removed.
• Already seen / served → removed.
• Own posts → removed from own For You.
• OON NSFW SimClusters authors → removed for non-followers.
• Brazil 2026 election filter → certain reported accounts removed for non-followers (compliance).
• Visibility filtering DROP → removed after selection (and can cascade to quotes/replies ancestors).

Post-score multipliers

• Author diversity: later posts from same author × decaying factor (decay 0.5, floor 0.25).
• Out-of-network factor: OON candidates × 0.75 (topic OON × 0.5). With EnableOonRescoreForInNetworkRepliesRetweets=true, in-network replies/reposts can also get OON-style rescore — thread strategy matters (§18).
• Cold-start / low-impression boost: authors under impression/follower thresholds can be lifted toward target slots (§19).
• VMRanker: DPP over embeddings (VMRankerDppTheta=0.65) — trades a bit of score for less near-duplicate neighbors (§20).
• Zero-weight heads: Phoenix still predicts some actions (profile click, VQV, …) but weight 0 → they don’t move score at defaults (§6.4).

3. Critical misconceptions (read this)

3.1 Weights are not “engagement exchange rates”

From upstream comments in param.rs:

• Weights scale predicted probabilities (or continuous values like watch time).
• They do not scale raw like/report counts.
• It is incorrect to say “1 report cancels 468 likes” by dividing |−234| / 0.5.

Why report weight is huge: baseline P(report) is often >1000× lower than P(like). The large weight exists so a small predicted report probability can still move the final score.

3.2 Mass report / block brigades

Upstream notes multiple inhibitors:

1. Personalization: predictions are about *this viewer*. Bad-actor reports mainly hurt recommendations for users similar to those actors, not a global “everyone sees less of this” count dump.
2. Only engagements on posts served in Home Timeline count for the recommendation system. Coordinated drive-bys from people who navigated directly (e.g. via group chat links) do not have the ranking impact people assume.
3. You cannot reliably force a post into timelines just to farm coordinated engagement.

3.3 Ranking vs visibility

• Ranking orders candidates that survived filters.
• Visibility filtering decides ALLOW / INTERSTITIAL / DROP using labels + graph + settings.
• Spam rules for out-of-network recommendations can be stricter than for followers: the same post may show to followers but DROP for OON.

4. Request path (For You pipeline)

High-level stages inside Home Mixer (home-mixer/), built on candidate-pipeline/:

4.1 Query hydration

Viewer context loaded first, including roughly:

• Recent engagement action sequence (main Phoenix input)
• Following list
• Blocks and mutes
• Muted keywords
• Posts already seen / served
• Followed topics
• Other request features

4.2 Candidate sources (parallel)

4.3 Candidate hydration

Attach post text/media, author details/labels, quoted post, language, engagement counts, subscription status, etc.

4.4 Pre-scoring filters

Remove ineligible candidates before expensive scoring (see §7).

4.5 Scoring

1. PhoenixScorer — P(action) for many actions
2. RankingScorer — weighted sum + diversity / OON / new-author adjustments
3. VMRanker — diversity rerank via DPP service (vm-ranker/)

4.6 Selection

TopKScoreSelector — sort by final score, keep top K.

4.7 Post-selection filters

Visibility filtering drops, ancillary drops (if parent/quote/repost dropped), conversation dedupe.

4.8 Blending pipeline (not Phoenix rank)

After the post pipeline, `ForYouCandidatePipeline` blends:

Creator implication: a “weird slot” or gap next to an ad is often blending, not a Phoenix score mystery. Organic score still matters for which posts enter the organic slate before blending.

4.9 Side effects

Record served posts, refresh caches, log events — after response. Seen/served stores feed PreviouslySeen / PreviouslyServed filters on later requests (§26).

5. Labeling path (offline / continuous)

Runs continuously, not only on the request path:

5.1 Content understanding

5.2 Labeling rules

5.3 Visibility filtering answers

For each (post, viewer):

Rules consider labels, blocks/mutes/follows, protected/suspended/deactivated, subscriber-only, viewer settings/country. Some DROP rules apply only to OON recommendations.

6. Scoring formula (exact conceptual model)

FinalScore ≈ Σ_i ( weight_i × P_viewer(action_i | post) )
           then × author_diversity_multiplier
           then × oon_multiplier (when applicable)
           then new-author position boost (when applicable)
           then VMRanker reorder

6.1 Action families Phoenix predicts

Engagement    favorite · reply · repost · quote · share · share via DM · share via copy link
Clicks        post · profile · link · photo expand · video open · quoted post
Attention     video quality view · dwell · dwell time · click dwell time · active seconds
Author        follow author
Negative      not interested · mute author · block author · report · not dwelled

6.2 Published default weights (home-mixer/params/param.rs)

Snapshot of production defaults mirrored in the public repo (verify upstream if auditing):

Positive / neutral

Negative

Multipliers / diversity

Value model mode default: "weighted".

6.3 Media’s real role

Media is not scored by a separate “pretty image” bonus in RankingScorer. It matters because:

1. Hydration attaches media features.
2. Phoenix predicts P(photo expand) and P(video open) (and dwell / VQV heads).
3. Those probabilities × 0.05 / 0.07 enter the sum (VQV weight is 0 at defaults — §6.4).
4. Separately, media classifiers can cause DROP / INTERSTITIAL in visibility filtering (§24).

Implication for agents: media helps when it gets opened and doesn’t trigger safety drops. Conversation/share heads still dominate published weights.

6.4 Zero-weight heads (do not chase at defaults)

Phoenix can still predict these, but published weights are 0 → no score contribution until params change:

Agent rule: optimizing “get profile clicks” or “VQV” for For You score is wasted effort *at these defaults*. Prefer copy-link, reply, quote, DM share, follow.

Small but non-zero: PostUnexploredWeight = 0.02 (exploration; often in-network-only via PostUnexploredWeightInNetworkOnly=true).

7. Pre-scoring filters (ordered)

From home-mixer/filters/ (README order):

Note: Thunder also excludes already-seen when queried; other sources rely on filters. Geo/law filters prove rank can be overridden by policy without changing Phoenix weights.

8. Post-selection filters

Visibility rule evaluation (visibility-filtering/rules/registry.rs):

• Safety levels: TimelineHome (followers / home shared rules) vs TimelineHomeRecommendations (shared rules + OON-only drops).
• First DROP short-circuits later rules.
• INTERSTITIAL does not short-circuit the same way; a later DROP can still win.
• DROPs are ordered before interstitials in the wired home policy.
• Extra recommendation-only rules are DROPs only (high-recall spam/NSFW amplify blocks for non-followers).

See §22 for the public rule name walkthrough creators/agents should use.

9. Component map (encyclopedia)

Home mixer & framework

Candidate sources & index

Ranking

Safety / labels / visibility

See §5 tables (grox, media-model-proxy, clip, agatha, bdsm, user-cred-v2, scarecrow, botmaker, visibility-filtering, under-the-hood, …).

10. Design decisions (upstream)

1. Multi-action prediction — not a single opaque “relevance” logit; combining weights is explicit.
2. Candidate isolation — during transformer inference, candidates don’t attend to each other (only viewer context) → scores cacheable/consistent.
3. Hash-based embeddings — no frozen vocab; new posts representable immediately.
4. Ranking ⊥ visibility — different services, inputs, rules.
5. Composable pipeline — stages toggled via params; experiment defaults mirrored into repo.

11. What’s NOT in the public repo

Intentionally limited publication (anti-gaming), including:

• Grox LLM prompts (e.g. .j2 files)
• Some botmaker rules

Compensation: Under the Hood transparency tool shows aggregate visibility-impacting labels on an account/posts (under-the-hood/).

Also: not all deployment infra is included; focus is post-visibility transparency for For You.

12. Creator playbook (actionable)

12.1 Optimize the score heads that matter

Do more of

1. Copy-link / sendable posts (weight 20) — utility, tea, frameworks, punchy artifacts people paste.
2. Replies & quotes (5) — questions, debates, “wrong answers only,” quotable one-liners.
3. DM-worthy content (5) — “send this to X friend” energy without being spammy.
4. Follow hooks (4) — series, niche promise, reason to stay.
5. Mutual community — originals from mutual follows get reply-weight boost (+15); build people who follow you back (§17).
6. Dwell — strong first line, scannable structure, payoff.
7. Openable media — expands/opens; not decorative noise.
8. Freshness — ship when audience is awake; fight for first 48h.

Do less of

1. Like-only soft content with no conversation or send pull.
2. Ragebait that predicts report / mute / block / not interested.
3. Spam farm patterns (F4F, engagement pods, link dumps) → OON DROP risk.
4. Flooding many posts from one author in one session (diversity decay to floor 0.25).
5. Relying on off-platform brigade engagement to “poison” or “boost” ranking.

12.2 Out-of-network breakout

OON candidates start with a 0.75 score factor (harder than in-network). Breakout still happens via Phoenix/SimClusters retrieval when predicted positive actions are high for *similar viewers*. Early in-network conversation teaches the model who else might engage.

12.3 Agent drafting checklist

When writing a post for For You, an agent should ask:

• [ ] Is there a reply prompt or debate hook?
• [ ] Is there a quotable line?
• [ ] Would someone copy-link / DM this?
• [ ] Is there a reason to follow?
• [ ] Does line one stop the scroll?
• [ ] If media: will people expand/open it?
• [ ] Any language that raises report/mute/block/not-interested risk?
• [ ] Any spam/NSFW visibility risk for OON?
• [ ] Will this ship inside the 48h relevance window for the audience’s timezone?
• [ ] Avoid stacking many near-identical posts (author diversity)?

12.4 Rewrite patterns (agents)

13. Agent system-prompt snippet (copy/paste)

You are optimizing content for X's open-sourced For You ranking (xai-org/x-algorithm).

Score ≈ Σ weight_i × P_viewer(action_i). Notable weights: copy-link share 20, reply 5, quote 5,
DM share 5, follow 4, share 2, repost 1, like 0.5, photo expand 0.05, video open 0.07,
report -234, mute -58.8, not interested -43.2, block -31.2.

Rules:
- Maximize predicted replies/quotes/shares/follows/dwell; minimize predicted reports/mutes/blocks/not-interested.
- Do not treat weights as raw engagement exchange rates.
- Posts > ~48h are filtered out of For You candidates.
- OON candidates are discounted (~0.75). Visibility DROP can remove posts regardless of score.
- Mutual-follow ORIGINAL posts get reply-weight boost (+15 → effective reply weight 20); not replies/reposts.
- Prefer one strong post over author-diversity-decaying spam.
- Zero-weight heads (profile click, VQV, …) don’t move score at defaults.
- OON factor 0.75; in-network replies/reposts can also be rescored OON-style.
- Cold-start can lift low-impression authors into ~slots 15–16 when eligible.
- Cite home-mixer/params/param.rs when discussing weights; check Under the Hood before blaming rank.

14. Glossary

15. Source hygiene

• Upstream license: Apache-2.0
• AffRev playbook: educational compilation + creator/agent guidance
• When defaults disagree with this doc, trust the live `param.rs` in xai-org/x-algorithm
• Notable upstream updates: weight misconceptions clarification; Brazil 2026 election filter; Under the Hood tool; bidirectional boost experiment history in docs/BIDIRECTIONAL_BOOST_CHANGE.md

16. Quick reference: score intuition

Very high travel potential: copy-link worthy + reply/quote magnets + early mutual conversation + clean safety + fresh.

Follower-range only: status/flex updates, like-bait, no send/reply pull, weak OON predictions.

Buried: safety DROP, muted/blocked, aged out, or strong predicted negative feedback.

17. Mutual-follow boost (bidirectional) — exact eligibility

Source: docs/BIDIRECTIONAL_BOOST_CHANGE.md, ranking_scorer.rs, bidirectional_follow_hydrator.rs.

What it does: for eligible candidates, reply_weight = ReplyWeight + BidirectionalFollowReplyWeightBoost (defaults 5 + 15 = 20). Optional dwell boost exists (BidirectionalFollowDwellWeightBoost, default 0).

Eligible only if all are true:

1. Author is a mutual follow (is_mutual_follow_author == true)
2. Post is an original (not a reply: in_reply_to_tweet_id empty)
3. Post is not a retweet (retweeted_tweet_id empty)

Not eligible: your replies, your retweets, one-way follows, OON strangers.

History (why defaults move):

Creator / agent takeaway: invest in mutual community and original posts that invite replies. Don’t expect the +15 on reply-threads or quote-RT spam.

18. OON discount nuance (replies & reposts)

Defaults:

• OonWeightFactor = 0.75 — typical OON score multiplier
• TopicOonWeightFactor = 0.5 — topic OON harder
• EnableOonRescoreForInNetworkRepliesRetweets = true — in-network replies and retweets can be rescored with OON-style factors

Why it matters: a reply under a viral OON post, or a retweet you push to followers, is not automatically treated like a clean original Thunder post. Originals in-network have an easier path than reply/RT inventory.

Practical:

• Prefer original posts for breakout, then use replies to retain conversation (mutual boost only on originals anyway).
• Don’t assume “I follow them, so their RT of spam is full in-network scored.”
• OON breakout still happens when Phoenix/SimClusters retrieve you and predicted positives overcome the 0.75 factor.

19. Cold-start / low-impression author boost

After weighted scoring (+ diversity/OON), eligible low-impression authors can be lifted toward a target position band.

Published defaults (param.rs):

Creator takeaway: early impressions matter; first-day freshness compounds with AgeFilter (48h) and cold-start (often 24h window). New accounts aren’t helpless, but spam/NSFW DROPs still win.

Agent takeaway: for small accounts, write for early reply/share in the first hours — boost helps position, Phoenix still needs positive P(action).

20. VMRanker (DPP diversity)

VMRanker calls vm-ranker/: a determinantal point process over embeddings reorders the scored list, giving up a little score for less similar neighbors.

Defaults:

• VMRankerDppTheta = 0.65
• VMRankerDppMaxSelectedRank = 150

Why your post “lost” to a lower-score neighbor: diversity rerank, not only RankingScorer. Near-duplicate posts from you or a cluster get spread/suppressed as neighbors.

Creator takeaway: don’t flood near-identical angles in one window (also hits author diversity decay). Vary topic/embedding space.

21. Blending vs ranking (ads & modules)

Organic Phoenix order is an input to blending, not always the final UI order.

• Ads blender may reorder for ad adjacency
• Who to Follow / prompts often sit at fixed positions
• Side effects record what was served (feeds later seen filters)

Diagnostic: if analytics show impressions but odd placement, check blending/ads before rewriting the hook for “rank.”

22. Visibility registry walkthrough (public rule names)

From visibility-filtering/rules/registry.rs tests (wired order). Use these names when matching Under the Hood labels or debugging DROP.

Shared home rules (TimelineHome) — drops then interstitials

Author state / graph drops: SuspendedAuthor, DeactivatedAuthor, ErasedAuthor, OffboardedAuthor, ProtectedAuthorDrop, ViewerBlocksAuthor, ViewerMutesAuthor, MutedRetweets.

Tweet label / legal / TES drops: PdnaTweetLabel, BounceTweetLabel, SpamTweetLabel, ForEmergencyUseOnlyDrop, FosnrHatefulConduct / ViolentSpeech / Abuse / CivicIntegrity, NullcastedTweet, DropStaleTweets, DropLegalTakendownPost, DropLocalLawsTakendownPost.

Sensitive viewer drops: SensitiveViewerLoggedOut / Underage / NoStatedAge (country-gated NSFW policies exist).

Exclusive: DropExclusiveTweetContent.

Interstitials (tap-through): NsfwHighPrecisionInterstitial, GoreAndViolenceInterstitial, NsfwCardImageInterstitial, NsfwAuthorInterstitial.

Extra OON-only drops (TimelineHomeRecommendations)

Examples: DropTweetsWithDmcaMedia, DropTweetsWithGeoRestrictedMedia, DropNsfwUser/AdminAuthor, TweetNsfwUser/AdminDrop, NsfwHighRecallDrop, NsfwHighPrecisionOonDrop, GoreAndViolenceOonDrop, NsfwCardImageOonDrop, DoNotAmplifyOonDrop, MaliciousUrlOonDrop, SpamHighRecallDrop, NsfwTextTweetLabelDrop, FosnrAbuseInsultsOonDrop, user-label drops (NsfwHighRecall/Precision, SpamHighRecall, Compromised, ReadOnly, Impersonation…), NsfwAvatar/Banner, AbusiveHighRecall, NsfwNearPerfectAuthor, DoNotAmplifyNonFollower.

Follower vs OON: many of these only fire for recommendations. Followers may still see content that OON DROPs — “my followers saw it but it didn’t travel” is often VF OON policy, not weak copy-link weight.

Brazil note: Brazil2026ElectionFilter is a home-mixer pre-score filter, separate from this VF registry, but same idea: compliance can hard-remove OON distribution.

23. Under the Hood diagnostic loop

Tool: https://x.com/i/under_the_hood Code: under-the-hood/

Use when: reach collapsed, OON died, interstitials appear, or an agent should not “just rewrite the hook.”

Loop:

1. Open Under the Hood for the account / period.
2. List visibility-impacting labels (automated vs manual).
3. Map label → likely rule family in §22 / visibility-filtering/ / media / account models (§24).
4. If DROP/interstitial labels dominate → fix safety/account state, not Phoenix weights.
5. If clean labels + weak travel → optimize ranking heads (copy-link, reply, quote, …) and freshness.
6. Re-check after changes; labels can lag (batch jobs).

Agent rule: never prescribe “post more controversial takes” when Under the Hood shows spam/NSFW/DoNotAmplify-class labels.

24. Media models & account models (what labels you)

Media / content understanding

Creative checklist: avoid gore/hateful-symbol bait; don’t repost known banned media hashes; NSFW may interstitial for followers and DROP for OON.

Account-level models

Takeaway: one toxic post can stain the account, which then poisons future OON via user-label DROP rules — even if later posts are clean.

25. Experiments, params, and reading diffs

• Many tunables live in a config system; cron mirrors primary production defaults into home-mixer/params/param.rs.
• Notable experiments (≥ ~10% traffic) are intended to appear in the public repo.
• Example narrative + diffs: `docs/BIDIRECTIONAL_BOOST_CHANGE.md`.

Agent rule: when citing weights, say “as of mirrored defaults in param.rs” and prefer live file over this playbook if they diverge.

26. Seen / served stores & inventory holdout

Why a viewer never saw you (non-ranking):

Holdout params (defaults often disabled / 0%):

• EnableInventoryHoldout (default false)
• InventoryHoldoutOriginalsPercent / RepliesPercent / RetweetsPercent (default 0)

Takeaway: absence of impressions ≠ always “bad score.” Could be seen-before, session dedupe, holdout experiment, VF DROP, or never retrieved.

27. SimClusters, retrieval index, and VF-before-index

Critical: a post can be blocked from retrieval index membership, not only dropped after TopK. If VF says the post shouldn’t be amplified, Phoenix retrieval may never surface it to strangers.

SimClusters creator note: you get into clusters by who engages, not by hashtags alone. Early quality engagement from real communities teaches OON who else might care — engagement pods / brigades are the wrong lesson (§3.2).

28. Phoenix training surface (for technical agents)

Public phoenix/ includes training + serving code (JAX + Rust), synthetic data, and `phoenix/QUICKSTART.md`.

What the quickstart proves end-to-end (nano, not production quality):

1. Generate synthetic world snapshots + dumps
2. Train ranking checkpoint
3. Resume training
4. Serve ranking
5. Train two-tower retrieval
6. retrieve_then_rank loop over synthetic sessions

Implications for understanding (not for “train your own For You”):

• Ranking consumes a viewer action sequence + candidates (candidate isolation: candidates don’t attend to each other).
• Retrieval is a separate two-tower path; index + SID services matter.
• Hash-based embeddings → new posts representable without a frozen vocab.
• Production data, checkpoints, and scale are not in the repo.

Creator myth to kill: you cannot download Phoenix weights and “predict your virality score” for a draft with production fidelity from this alone. Use published weights + filters + VF as the actionable layer.

29. Expanded agent drafting checklist

Use with §12.3:

• [ ] Original post (not relying on RT/reply inventory for score)?
• [ ] Mutual graph: will mutuals want to reply (boost path)?
• [ ] Copy-link / DM / quote hooks present?
• [ ] Not near-duplicate of your last posts (diversity + DPP)?
• [ ] Fresh inside cold-start (~24h) and AgeFilter (~48h)?
• [ ] Zero-weight heads ignored?
• [ ] Media clear of gore / hateful symbols / known banned media?
• [ ] Account Under the Hood clean of spam/NSFW/DoNotAmplify-class labels?
• [ ] Avoid OON-only poison (malicious URLs, high-recall spam patterns)?
• [ ] Geo/compliance: any election/law filters relevant to audience?
• [ ] If diagnosing failure: retrieval/VF/seen/holdout considered before “write harder”?

30. Failure-mode map (what to fix)

*Maintained for AffRev free tools so creators and AI agents can reason about For You distribution without paying for closed “algorithm myth” products. Always pair with the upstream repository for audits. Raw markdown: /playbooks/x-for-you-algorithm.md.*