docs: clarify OUT_OF_MEMORY threshold behavior

Update documentation for `--memory-used-max-percentage` to accurately
describe how the OOM threshold is calculated. The threshold uses the
minimum of 500MB or the percentage-based value, and is only enforced
when the parameter is set to less than 100.

- Clarify that at default (100%), no memory-based rejection occurs
- Explain threshold calculation: min(500MB, (100-percentage)% × total_memory)
- Add concrete example with 8GB system at 90% threshold
- Update both v29.0 and v30.0 documentation

Author: alangmartini

docs-site/content/29.0/api/cluster-operations.md

@@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
 When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
 set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.
 
+The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
+and free memory falls below the calculated threshold. The threshold is determined as:
+`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.
+
+For example, with `--memory-used-max-percentage=90` on an 8GB system:
+- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
+- Final threshold: min(500MB, 800MB) = 500MB
+- Writes are rejected when free memory drops below 500MB
+
+When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.
+
+When this condition is met, Typesense will reject write operations to prevent system instability.
+
 #### Definition
 `GET ${TYPESENSE_HOST}/health`
 

docs-site/content/29.0/api/server-configuration.md

@@ -88,7 +88,7 @@ Command line arguments can be passed to the server as `--parameter=value`.
 | `--cache-num-entries`             | false    | Number of entries to be stored in the LRU cache used for storing search query responses. Default: `1000`.                                                                                                                                                                            |
 | `--embedding-cache-num-entries`   | false    | Number of entries to be stored in the LRU cache used for storing text embeddings returned by remote embedders. Default: `100`.                                                                                                                                                      |
 | `--disk-used-max-percentage`      | false    | Reject writes when used disk space exceeds this percentage. Default: `100` (never reject).                                                                                                                                                                                           |
-| `--memory-used-max-percentage`    | false    | Reject writes when used memory usage exceeds this percentage. Default: `100` (never reject).                                                                                                                                                                                         |
+| `--memory-used-max-percentage`    | false    | Reject writes when free memory falls below a threshold. The threshold is calculated as the minimum of 500MB or `(100 - this_percentage)% × total_memory`. This will trigger an `OUT_OF_MEMORY` error. Default: `100` (resource check is skipped entirely, no rejection occurs). |
 | `--healthy-read-lag`              | false    | Reads are rejected if the updates lag behind this threshold. Default: `1000`.                                                                                                                                                                                                        |
 | `--healthy-write-lag`             | false    | Writes are rejected if the updates lag behind this threshold. Default: `500`.                                                                                                                                                                                                        |
 | `--snapshot-interval-seconds`     | false    | Frequency of replication log snapshots. Default: `3600` follower recovery.<br><br>**NOTE**: Frequent snapshotting helps in faster recovery from a cold start. However, if this value is too low for a large dataset, repeated snapshotting can actually slow down follower recovery. |

docs-site/content/30.0/api/cluster-operations.md

@@ -477,6 +477,19 @@ curl "http://localhost:8108/health"
 When a node is running out of memory / disk, the API response will have an additional `resource_error` field that's
 set to either `OUT_OF_DISK` or `OUT_OF_MEMORY`.
 
+The `OUT_OF_MEMORY` error is triggered when the `--memory-used-max-percentage` server parameter is set to less than `100`
+and free memory falls below the calculated threshold. The threshold is determined as:
+`min(500MB, (100 - memory_used_max_percentage)% × total_memory)`.
+
+For example, with `--memory-used-max-percentage=90` on an 8GB system:
+- Percentage-based threshold: (100-90)% × 8GB = 800MB free memory required
+- Final threshold: min(500MB, 800MB) = 500MB
+- Writes are rejected when free memory drops below 500MB
+
+When `--memory-used-max-percentage=100` (default), the resource check is skipped entirely and no memory-based rejection occurs.
+
+When this condition is met, Typesense will reject write operations to prevent system instability.
+
 #### Definition
 `GET ${TYPESENSE_HOST}/health`
 

docs-site/content/30.0/api/server-configuration.md

@@ -88,7 +88,7 @@ Command line arguments can be passed to the server as `--parameter=value`.
 | `--cache-num-entries`             | false    | Number of entries to be stored in the LRU cache used for storing search query responses. Default: `1000`.                                                                                                                                                                            |
 | `--embedding-cache-num-entries`   | false    | Number of entries to be stored in the LRU cache used for storing text embeddings returned by remote embedders. Default: `100`.                                                                                                                                                      |
 | `--disk-used-max-percentage`      | false    | Reject writes when used disk space exceeds this percentage. Default: `100` (never reject).                                                                                                                                                                                           |
-| `--memory-used-max-percentage`    | false    | Reject writes when used memory usage exceeds this percentage. Default: `100` (never reject).                                                                                                                                                                                         |
+| `--memory-used-max-percentage`    | false    | Reject writes when free memory falls below a threshold. The threshold is calculated as the minimum of 500MB or `(100 - this_percentage)% × total_memory`. This will trigger an `OUT_OF_MEMORY` error. Default: `100` (resource check is skipped entirely, no rejection occurs). |
 | `--healthy-read-lag`              | false    | Reads are rejected if the updates lag behind this threshold. Default: `1000`.                                                                                                                                                                                                        |
 | `--healthy-write-lag`             | false    | Writes are rejected if the updates lag behind this threshold. Default: `500`.                                                                                                                                                                                                        |
 | `--snapshot-interval-seconds`     | false    | Frequency of replication log snapshots. Default: `3600` follower recovery.<br><br>**NOTE**: Frequent snapshotting helps in faster recovery from a cold start. However, if this value is too low for a large dataset, repeated snapshotting can actually slow down follower recovery. |