diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index bdb44543b8..beb6d017ab 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -47,6 +47,7 @@
- [Workers](workers.md)
- [Using `synctl` with Workers](synctl_workers.md)
- [Systemd](systemd-with-workers/README.md)
+ - [State Compressor](state_compressor.md)
- [Administration](usage/administration/README.md)
- [Admin API](usage/administration/admin_api/README.md)
- [Account Validity](admin_api/account_validity.md)
diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 166cec38d3..646019db55 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -2648,3 +2648,38 @@ redis:
# Optional password if configured on the Redis instance
#
#password: <secret_password>
+
+
+## State compressor ##
+
+# The state compressor is an experimental tool which attempts to
+# reduce the number of rows in the state_groups_state table
+# of postgres databases.
+#
+# For more information please see
+# https://matrix-org.github.io/synapse/latest/state_compressor.html
+#
+state_compressor:
+ # Whether the state compressor should run (defaults to false)
+ # Uncomment to enable it - Note, this requires the 'auto-compressor'
+ # library to be installed
+ #
+ #enabled: true
+
+ # The (rough) number of state groups to load at one time. Defaults
+ # to 500.
+ #
+ #chunk_size: 1000
+
+ # The number of chunks to compress on each run. Defaults to 50.
+ #
+ #number_of_chunks: 1
+
+ # The default level sizes for the compressor to use. Defaults to
+ # 100,50,25.
+ #
+ #default_levels: 128,64,32.
+
+ # How frequently to run the state compressor. Defaults to 1d
+ #
+ #time_between_runs: 1w
diff --git a/docs/state_compressor.md b/docs/state_compressor.md
new file mode 100644
index 0000000000..56f21a03cd
--- /dev/null
+++ b/docs/state_compressor.md
@@ -0,0 +1,47 @@
+# State compressor
+
+The state compressor is an **experimental** tool that attempts to reduce the number of rows
+in the `state_groups_state` table inside of a postgres database. Documentation on how it works
+can be found on [its github repository](https://github.com/matrix-org/rust-synapse-compress-state).
+
+## Enabling the state compressor
+
+The state compressor requires the python library for the `auto_compressor` tool to be
+installed. Instructions for this can be found in [the `python.md` file in the source
+repo](https://github.com/matrix-org/rust-synapse-compress-state/blob/main/docs/python.md).
+
+The following configuration options are provided:
+
+- `chunk_size`
+The number of state groups to work on at once. All of the entries from
+`state_groups_state` are requested from the database for state groups that are
+worked on. Therefore small chunk sizes may be needed on machines with low memory.
+Note: if the compressor fails to find space savings on the chunk as a whole
+(which may well happen in rooms with lots of backfill in) then the entire chunk
+is skipped. This defaults to 500
+
+- `number_of_chunks`
+The compressor will stop once it has finished compressing this many chunks. Defaults to 100
+
+- `default_levels`
+Sizes of each new level in the compression algorithm, as a comma separated list.
+The first entry in the list is for the lowest, most granular level, with each
+subsequent entry being for the next highest level. The number of entries in the
+list determines the number of levels that will be used. The sum of the sizes of
+the levels effect the performance of fetching the state from the database, as the
+sum of the sizes is the upper bound on number of iterations needed to fetch a
+given set of state. This defaults to "100,50,25"
+
+- `time_between_runs`
+This controls how often the state compressor is run. This defaults to once every
+day.
+
+An example configuration:
+```yaml
+state_compressor:
+ enabled: true
+ chunk_size: 500
+ number_of_chunks: 5
+ default_levels: 100,50,25
+ time_between_runs: 1d
+```
\ No newline at end of file
|
