Configuring Storage and Cache in the Synapse Media Repository
Running a Matrix homeserver alongside your community discussion platforms gives members real-time chat, but media files can accumulate rapidly on disk. Whether managing local avatars, files uploaded directly to rooms, or assets brought in through federation, administrators need a clear technical understanding of how content is cataloged, referenced, and retained. Synapse separates local media, remote cached files, and temporary link previews across distinct database tables and directory trees on the filesystem.
Understanding MXC URIs and Repository Architecture
Every piece of media across the Matrix ecosystem is identified by an MXC URI using the format mxc://<server-name>/<media-id>. As detailed in the Synapse Media Repository documentation, the media repository serves three distinct operational roles within the server stack:
- It stores avatars, attachments, and corresponding thumbnails uploaded by local users.
- It caches avatars, attachments, and thumbnails uploaded by remote users on federated servers.
- It caches web resources and thumbnails generated for URL previews.
When planning storage for a homeserver—such as one configured alongside your wider network as covered in our Synapse Matrix Homeserver Profile—knowing which folder holds permanent local content versus ephemeral cached data helps prevent running out of drive space.
Tracking Local Uploads and Database Metadata
When a local user uploads an attachment or avatar, Synapse generates an identifier consisting of case-sensitive upper and lowercase letters. Every local media ID generated by Synapse is exactly 24 characters in length. Other homeserver implementations may generate their media IDs differently, but Synapse always enforces this 24 character scheme for local assets.
Local media metadata is written to the local_media_repository database table. This record preserves crucial tracking details, including:
- MIME types associated with uploaded files.
- Upload timestamps.
- Observed file sizes.
Maintaining clean metadata ensures administrators can review attachment volume and locate potentially problematic files when enforcing server rules, similar to standard practices outlined in our guide on Safe Forum File Uploads.
Navigating the Local Storage Directory Structure
Synapse splits files across sharded directories using the beginning characters of the media ID. For example, if a locally uploaded file receives the media ID aabbcccccccccccccccccccc, the raw content file is placed on disk at:
local_content/aa/bb/cccccccccccccccccccc
Generated thumbnails follow an equivalent directory convention under the thumbnail tree. If a client requests a 128x96 thumbnail created by scaling an image with media ID aabbcccccccccccccccccccc and a MIME type of image/jpeg, Synapse writes the generated asset to:
local_thumbnails/aa/bb/cccccccccccccccccccc/128-96-image-jpeg-scale
Managing Remote Media Caching and Directory Paths
Federated interactions require caching remote media so local users can view incoming room content without querying the originating server on every request. When Synapse requests media from a remote homeserver, it assigns the asset a local filesystem_id. This identifier uses the exact same format as local media, consisting of a 24 character case-sensitive string of letters.
Mappings between remote MXC URIs (containing the remote server name and original media ID) and local filesystem identifiers are stored in the remote_media_cache table. When inspecting cached remote content, the directories are segmented by originating server name. For example, a file from matrix.org with filesystem identifier aabbcccccccccccccccccccc resides at:
remote_content/matrix.org/aa/bb/cccccccccccccccccccc
Thumbnails for that remote file follow a specific path structure. A 128x96 image/jpeg thumbnail created by scaling is stored at:
remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg-scale
Administrators auditing disk directories should note that the directory remote_thumbnail/ does not end with an s. Furthermore, older thumbnails on the filesystem may omit the thumbnailing method from the filename, appearing simply as remote_thumbnail/matrix.org/aa/bb/cccccccccccccccccccc/128-96-image-jpeg.
Auditing URL Previews and Cache Lifecycles
When URL preview generation is enabled, Synapse downloads and caches external web resources, including preview images. These temporary items receive media IDs formatted with the current calendar date and a random sequence of 16 case-sensitive letters:
yyyy-mm-dd_aaaaaaaaaaaaaaaa
Metadata for URL previews is tracked across two database tables: local_media_repository and local_media_repository_url_cache. Because these previews exist solely to enhance message readability, Synapse automatically purges resources for URL previews after a few days. The files and thumbnails are stored within dedicated cache directories:
url_cache/yyyy-mm-dd/aaaaaaaaaaaaaaaa
url_cache_thumbnails/yyyy-mm-dd/aaaaaaaaaaaaaaaa/128-96-image-jpeg-scale
Understanding these distinct directory pathways allows administrators to separate temporary preview caches from permanent user uploads when reviewing filesystem consumption, as documented in the Synapse Media Repository specifications.
Sources
Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.