Matrix User Directory Privacy: Visibility and Search FAQ

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

Connecting community discussions to decentralized chat networks requires careful attention to member discovery and data exposure. Homeservers operating Matrix Synapse manage local and federated participant listings through specialized database tracking. If you run community infrastructure—whether paired with traditional message boards explored in our Synapse Matrix homeserver profile or operated independently—understanding directory mechanics helps maintain member privacy. Below are answers to key administrative questions regarding user directory visibility, search ranking, and index synchronization.

Which Matrix Users Appear in the Homeserver Directory?

A Synapse homeserver maintains its user directory based on people who are visible to that specific server. This includes users who are local to the server as well as remote federated users who share at least one room with a local user. However, Synapse automatically excludes three specific local user categories from all directory tables:

• Support users
• Appservice users
• Deactivated users

For everyone else, profile data is kept in the main directory storage. As detailed in the User Directory - Synapse documentation, there is strictly one directory record per user. Because a single record exists, it stores only publicly visible details—such as user ID, display name, and avatar—to ensure that custom nicknames or specialized avatars adopted inside private rooms are never leaked to broader searches.

How Does Synapse Decide Who Can Find Whom in Search?

Directory exposure depends on homeserver configuration settings and the relationship between participants. Synapse evaluates whether a search query should return a matching profile using the search_all_users setting. When search_all_users is set to false, directory lookups are restricted. A requesting user will only see results for individuals who:

• Exist in the public room associations table, or
• Share a private room with the requesting user.

If an administrator sets search_all_users to true, Synapse removes these relationship boundaries and permits queries to match any user known to the server. Account lock status also affects visibility: Synapse excludes locked accounts from search results by default, though enabling show_locked_users stops this filtering and returns locked accounts regardless.

Before executing a lookup, Synapse normalizes incoming search terms to lowercase using NFKC. This normalization canonicalizes variations of text, treats characters case-insensitively, and aligns roughly equivalent characters. The server then segments phrases into distinct terms using the icu_segmenter Rust crate, which relies on embedded language dictionaries and Long Short-Term Memory machine learning models.

What Database Tables Store Visibility and Search Records?

Synapse structures its user directory architecture across five database tables. Three of these tables record known user identities, while two search tables determine visibility between individuals:

• user_directory: Stores the user ID, display name, and avatar. This table is indexed on rooms and indexed on users.
• user_directory_search: Joined directly to user_directory, this table provides an additional column for full-text searches against display names and user IDs, with dedicated schemas for SQLite and Postgres. It is indexed on users and full-text search data.
• user_directory_stream_pos: Records the stream position once the background process completes its initial directory population. Synapse uses this pointer to monitor room events and perform incremental directory updates.
• users_in_public_rooms: Tracks associations between users and public rooms to decide who is publicly discoverable. This table logs both local and remote users.
• users_who_share_private_rooms: Stores visibility relationships as triples containing a local user, a second local or remote user, and the room identifier. When two local accounts join the same room, Synapse writes two separate rows to track reciprocal visibility.

Maintaining clear boundaries in these tables aligns with general community confidentiality standards, similar to the data management principles discussed in our guide on privacy basics for forum owners.

How Are Search Queries Scored Across Databases?

Synapse prioritizes real accounts over bots and deactivated accounts, assuming genuine users provide a display name and avatar. Scoring mechanisms differ based on the underlying database engine.

Under PostgreSQL, the normalized text segments generate exact and prefix queries using to_tsquery. Rows matching either query in user_directory_search receive a calculated weighted score starting from an initial baseline of 1:

• 4x multiplier if a user ID exists.
• 1.2x multiplier if the account has a display name.
• 1.2x multiplier if the account has an avatar.
• 0x to 3x added from full-text ranking (ts_rank_cd) on the exact query, weighted at 0.9 for display names, 0.1 for user ID domain, and 0.1 for user ID localpart (with 0.1 allocated to an unused variable).
• 0x to 1x added from ts_rank_cd on the prefix query using the same weights.
• 2x multiplier for local accounts if the server has enabled prefer_local_users.

Under SQLite, ordering uses the matchinfo function rank, with ties resolved sequentially: local users appear first if prefer_local_users is active, followed by users with display names, and finally users with avatars.

What Steps Fix a User Directory That Is Out of Sync?

On active Matrix installations, directory tables can occasionally desynchronize, which is treated as a software bug. When out-of-sync records distort visibility or omit legitimate room members, administrators can follow the Synapse user directory maintenance workflow via the admin API.

Submitting the regenerate_directory command triggers a background maintenance task. This process flushes existing directory tables and regenerates records from current room and user data. Depending on total user volume and the quantity of rooms hosted, rebuilding the directory can take a noticeable amount of time to complete.

Sources

• User Directory - Synapse

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.