xai-org/x-algorithm

X For You Feed Algorithm

This repository contains the core code that determines which posts a viewer sees in the For You feed on X. It combines in-network content (from accounts the viewer follows) with out-of-network content (discovered through ML-based retrieval and other mechanisms), filters content based on a variety of inputs, and ranks posts using a transformer model.

Table of Contents

• Notable Updates
• September 18th, 2026
• August 14th, 2026
• August 13th, 2026
• Overview
• System Architecture
• Request Path
• Labeling Path
• Components
• How It Works
• Scoring and Ranking
• Filtering
• Experiments and Configuration
• What's not in this repo?
• Under the Hood Label Transparency Tool
• Key Design Decisions
• License

Notable Updates

September 18th, 2026

• Under the Hood. Reports now include information about whether one's account or posts have had their visibility limited because of required compliance with law(s). For example, you'll be able to see if any of your posts were withheld from showing in a country following a legal demand — and which country.

August 14th, 2026

Notable updates:

• How weights work. There's a common misconception about how weights related to actions (e.g. Like, Share, Block, Report, etc) work in ranking. The weights scale the predicted probabilities of such actions (or predicted continuous values, e.g. dwell time) — they do not scale the raw engagement counts, so e.g. it'd be incorrect to see that a report has 468 times higher weight than a like and conclude that e.g. "1 report cancels out 468 likes". The weights are a multiple on your own predicted probability of Liking, Reporting, etc, which is substantially driven by your own behavior. We've added comments to the code so that LLMs or people reading it are more likely to understand it correctly.
• Brazil 2026 Elections. As announced by X, in accordance with Brazilian electoral law, For You now runs Brazil2026ElectionFilter, which removes posts from accounts reported to Brazil's Electoral Court for the 2026 election, unless the viewer explicitly follows the account. (Account list updated August 27, 2026.) A benefit of open-source is that you can see that changes like this exist, and exactly how they work — take a look at the code.

August 13th, 2026

This release:

• Adds key configuration parameters (including weights used to blend predicted action values into a score for a post)
• Adds code for systems that impact whether a post is filtered from the For You feed
• Replaces the Phoenix demonstration model with the code used to train the models the feed uses, as well as synthetic data generation code so one can run a proof-of-concept training run of Phoenix.

1. Visibility filtering: visibility-filtering/ determines whether to show a post, drop it, or show it behind an interstitial. 2. The systems that produce labels that drive visibility filtering's responses: rules that apply labels (botmaker/, botmaker-rules/, scarecrow/), models that score accounts on various dimensions (agatha/, bdsm/, user-cred-v2/), models that examine images and video (media-model-proxy/, clip/), and enforcement (abuse-enforcement-service/). 3. Phoenix model code: phoenix/ now contains code that trains and runs the model, plus synthetic data generation. 4. SimClusters: simclusters/, an additional source of posts from accounts the viewer does not follow that is called in retrieval alongside Thunder and Phoenix retrieval.

This update is also paired with a new Under the Hood transparency tool that allows people to see aggregate statistics about the labels on their account and posts that can limit visibility.

---

Overview

The For You feed is assembled per request. Posts come from two places:

1. In-Network — thunder/ keeps recent posts from the accounts a viewer follows in memory 2. Out-of-Network — phoenix/ retrieval and simclusters/ find posts from accounts the viewer does not follow

Both are ranked together by the same model. Phoenix reads the viewer's recent engagement history and predicts, for each post, how likely the viewer is to take each action on it. Those predictions are combined into one score using weights held in the code — see Scoring and Ranking.

Two pipelines do the work. The Post Pipeline finds, ranks and filters posts. The Blending Pipeline wraps it and adds what the model does not rank: ads, Who to Follow recommendations, prompts.

Ranking sets the order. Whether a post can be shown at all is decided separately, by visibility-filtering/, from the viewer's own actions such as blocks and mutes and from labels that other systems here attach to posts and accounts.

---

System Architecture

Request Path

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                   FOR YOU FEED REQUEST                                   │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌──────────────────────────────── HOME MIXER   home-mixer/ ────────────────────────────────┐
│                                                                                          │
├───────────────────────  POST PIPELINE   PhoenixCandidatePipeline  ───────────────────────┤
│                                                                                          │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 1. QUERY HYDRATION                                                                 │  │
│  │    user action sequence — the viewer's recent engagements, and the                 │  │
│  │    main input to the model · following list · blocks and mutes · muted             │  │
│  │    keywords · posts already seen and served · followed topics, etc.                │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 2. CANDIDATE SOURCES — queried in parallel                                         │  │
│  │    ┌───────────────────────────────┐ ┌────────────────────────────────────────┐    │  │
│  │    │ IN-NETWORK                    │ │ OUT-OF-NETWORK                         │    │  │
│  │    │ Thunder                       │ │ Phoenix retrieval   retrieval model    │    │  │
│  │    │   recent posts from the       │ │ SimClusters         cluster similarity │    │  │
│  │    │   accounts the viewer follows │ │                                        │    │  │
│  │    └───────────────────────────────┘ └────────────────────────────────────────┘    │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 3. CANDIDATE HYDRATION                                                             │  │
│  │    post text and media · author details and account labels · quoted post ·         │  │
│  │    language · engagement counts · subscription status, etc.                        │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 4. PRE-SCORING FILTERS                                                             │  │
│  │    duplicates across sources · older than 48 hours · the viewer's own              │  │
│  │    posts · blocked and muted accounts · muted keywords · already seen              │  │
│  │    or served · subscriber-only posts the viewer cannot access, etc.                │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 5. SCORING                                                                         │  │
│  │    PhoenixScorer   a probability for each action the viewer might take             │  │
│  │    RankingScorer   weighted sum, then repeated-author decay, an                    │  │
│  │                    out-of-network discount, a new-author boost                     │  │
│  │    VMRanker        calls the reranking service in vm-ranker/                       │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 6. SELECTION — TopKScoreSelector                                                   │  │
│  │    sort by final score, keep the top K                                             │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ 7. POST-SELECTION FILTERS — after the order is fixed                               │  │
│  │    VFCandidateHydrator  asks visibility-filtering/ per post and viewer             │  │
│  │    VFFilter             removes the posts it said to drop                          │  │
│  │    DedupConversationFilter  collapses branches of one conversation                 │  │
│  │                         ◄── these labels come from the Labeling Path               │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                          │
├─────────────────────  BLENDING PIPELINE   ForYouCandidatePipeline  ──────────────────────┤
│                                                                                          │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ the ranked posts are one source here; the others add non-post items:               │  │
│  │    ads · Who to Follow · prompts · push-to-home, etc.                              │  │
│  │                                                                                    │  │
│  │ BlenderSelector interleaves them. The default ads blender reorders                 │  │
│  │ posts for ad adjacency. Who to Follow and prompts go at fixed positions.           │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                            ▼                                             │
│  ┌────────────────────────────────────────────────────────────────────────────────────┐  │
│  │ SIDE EFFECTS — after the response is sent                                          │  │
│  │    record which posts were served · refresh the post cache · log ad                │  │
│  │    and client events, etc.                                                         │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                 RANKED FOR YOU TIMELINE                                  │
└──────────────────────────────────────────────────────────────────────────────────────────┘

Stages can be switched on and off individually, with defaults in home-mixer/params/param.rs — see Experiments and Configuration for how those defaults relate to what runs in production.

Labeling Path

┌───────  1. CONTENT UNDERSTANDING — happens continuously, not on the request path  ───────┐
│                                                                                          │
│    POSTS AND MEDIA                    ACCOUNTS                                           │
│    grox/          classifiers for     agatha/        blocks and reports                  │
│                   text and media                     relative to favorites               │
│    media-model-   image and video     bdsm/          inauthentic behavior                │
│      proxy/       models              user-cred-v2/  PageRank over follow                │
│    clip/          image and text                     and engagement edges                │
│                   embeddings the                                                         │
│                   media models use                                                       │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌──────────────────────────────────  2. LABELING RULES  ───────────────────────────────────┐
│                                                                                          │
│    scarecrow/  reacts to events as they happen. Embeds botmaker/ as its                  │
│       rule engine and loads rules from botmaker-rules/scarecrow/. A rule                 │
│       reads: on this event, if these conditions hold, apply this label.                  │
│                                                                                          │
│    abuse-enforcement-service/  reads model scores about an account. Its                  │
│       rules label the account or its posts, challenge it, or suspend it.                 │
│                                                                                          │
│    safety-label-user-agg/  labels an account for what its posts collected.               │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌──────────────────────────────────────  3. STORAGE  ──────────────────────────────────────┐
│             labels are written to storage, and read back on the request path             │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌───────────────────  4. VISIBILITY FILTERING   visibility-filtering/  ────────────────────┐
│                                                                                          │
│    for each post and viewer, one of three answers:                                       │
│                                                                                          │
│       ALLOW          show the post normally                                              │
│       INTERSTITIAL   show it behind an interstitial the viewer can tap                   │
│                      through, e.g. for adult or graphic media                            │
│       DROP           do not show it                                                      │
│                                                                                          │
│    the rules read the labels above, plus whether the viewer blocks, mutes                │
│    or follows the author, whether that account is protected, suspended or                │
│    deactivated, subscriber-only status, and the viewer's settings and                    │
│    country. Some rules drop a post only when it is a recommendation from                 │
│    an account the viewer does not follow — spam caught at high recall, for               │
│    instance. The same post is allowed to a follower.                                     │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                             ▼
┌───────────────  5. POST-SELECTION FILTERS   VFFilter, AncillaryVFFilter  ────────────────┐
│                                                                                          │
│    drop  ──►  the post is removed after ranking, and so is any post whose                │
│               ancestor in the thread, quoted post or reposted post was                   │
│               itself dropped                                                             │
│    interstitial  ──►  the post stays in the feed; nothing in this                        │
│               repository draws the interstitial                                          │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘

---

Components

Home Mixer and Candidate Pipeline

| Component | What it does | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | home-mixer/ | Builds the For You feed: the pipeline stages, the scoring weights, and calls other systems on the request path. | | candidate-pipeline/ | The framework home-mixer is built on. Defines the stage types — source, hydrator, filter, scorer, selector, side effect — and runs them, in parallel where it can. |

Candidate Sources

| Component | What it does | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | | thunder/ | Holds recent posts in memory as they are published, and returns those from the accounts a viewer follows. | | phoenix/ retrieval | Embeds the viewer and each post as vectors, and returns the posts nearest the viewer. | | simclusters/ | Clusters accounts and posts by who engages with what, then uses the clusters to find candidates. |

Retrieval Index

| Component | What it does | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | phoenix-rankall/ | Maintains the index of posts Phoenix retrieval queries, updating it as events arrive. | | phoenix-rankall-strato/ | The event layer that determines which index a post belongs in, consulting visibility filtering first. |

Ranking

| Component | What it does | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | phoenix/ ranking | Predicts how likely the viewer is to take each action on each post. Training and serving code, in JAX with a Rust serving layer. | | vm-ranker/ | The service VMRanker calls once posts are scored. It reorders them with a determinantal point process over their embeddings, giving up a little score for less similarity between neighbours. |

Content Understanding

These produce the scores and labels that Visibility Filtering reads.

| Component | What it does | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | grox/ | Runs as pos