From 637dd035cc0062f2ef6140109d916164ada6c9e9 Mon Sep 17 00:00:00 2001
From: ergosteur <1992147+ergosteur@users.noreply.github.com>
Date: Sun, 27 Sep 2026 13:06:45 -0400
Subject: [PATCH] Document zram swap setup on neon

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md |  7 +++++
 ZRAM.md   | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+)
 create mode 100644 ZRAM.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 0000f76..82268b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -148,3 +148,10 @@ headroom), avs topology blobs hand-downloaded from upstream
 linux-firmware into `/lib/firmware/intel/avs/`, and a `Syntax 7` →
 `Syntax 6` sed over the UCM files for neon's alsa-lib 1.2.11. FydeOS on
 the eMMC has no audio yet (not investigated).
+
+## zram swap (neon)
+
+Disk swapfile replaced by an 8GiB zstd zram device via `zram-tools`
+(`/etc/default/zramswap`), set up 2026-03-05. Documented in **`ZRAM.md`**.
+Loose ends as of 2026-09-27: `vm.swappiness=100` was only set at runtime
+(back to 60), and the unused 512MiB `/swapfile` is still on disk.
diff --git a/ZRAM.md b/ZRAM.md
new file mode 100644
index 0000000..6eb0cc2
--- /dev/null
+++ b/ZRAM.md
@@ -0,0 +1,93 @@
+# zram swap on hp-chell (KDE neon)
+
+Set up **2026-03-05**, reconstructed on 2026-09-27 from `~/.bash_history`
+and the live config. It replaces the disk swapfile with compressed swap
+in RAM. That suits this machine: 15GiB RAM, and neon's root lives on a
+slow external USB/SD card (`sda`) that you don't want to swap to or wear
+out.
+
+## Current state (2026-09-27)
+
+```
+$ zramctl
+NAME       ALGORITHM DISKSIZE DATA COMPR TOTAL STREAMS MOUNTPOINT
+/dev/zram0 zstd            8G   4K   59B   20K         [SWAP]
+$ swapon --show
+NAME       TYPE      SIZE USED PRIO
+/dev/zram0 partition   8G   0B  100
+```
+
+The zram device is the only swap. zswap is off
+(`/sys/module/zswap/parameters/enabled` = `N`), and there's nothing
+zram-related on the kernel command line.
+
+## What was done
+
+1. **Installed `zram-tools`** (Debian's simple `zramswap` service; not
+   `systemd-zram-generator`, which isn't installed):
+   `sudo apt install zram-tools`, `sudo systemctl enable --now zramswap`.
+2. **Configured `/etc/default/zramswap`**. The file is still the
+   package's own conffile (`dpkg -V zram-tools` flags it as modified),
+   with these lines added at the end:
+   ```
+   ENABLED=true
+   ALGO=zstd
+   SIZE=8192
+   PRIORITY=100
+   ```
+   - `ALGO=zstd`: better compression than the default `lz4`, at some
+     CPU cost. Fine on this 4-core Core m7 for swap-sized traffic.
+   - `SIZE=8192`: an 8GiB zram device, a fixed size in MiB. `PERCENT`
+     isn't set; if set, it would override `SIZE`. That's the uncompressed
+     capacity; actual RAM used is the compressed size (`COMPR`/`TOTAL`
+     in `zramctl`).
+   - `PRIORITY=100`: above any disk swap, so zram is used first.
+
+   Tuned over several stop/edit/start rounds (the history shows
+   `systemctl stop zramswap` / `nano` / `start` three or four times).
+   Only the final values are known. Apply changes with
+   `sudo systemctl restart zramswap`.
+3. **Disabled the disk swapfile**: in `/etc/fstab`,
+   ```
+   # removed swapfile, using zram instead
+   #/swapfile                                 swap           swap    defaults   0 0
+   ```
+   then `sudo swapoff /swapfile`.
+4. **Raised `vm.swappiness` to 100**, at runtime only
+   (`sudo sysctl vm.swappiness=100`). See the loose ends below.
+
+## Loose ends (as of 2026-09-27)
+
+- **`vm.swappiness=100` was never made persistent.** It's back to the
+  default **60** now: no `swappiness` line in `/etc/sysctl.conf`,
+  `/etc/sysctl.d/` or `/usr/lib/sysctl.d/`. To keep it (a common choice
+  with zram-only swap, since swapping to zram is cheap):
+  ```
+  echo 'vm.swappiness=100' | sudo tee /etc/sysctl.d/99-zram.conf
+  sudo sysctl --system
+  ```
+  Some zram guides also set `vm.page-cluster=0` (currently `3`), because
+  zram has no seek cost and readahead just wastes work.
+- **`/swapfile` still exists**: 512MiB, `root:root 0600`, dated
+  2026-03-04. It's unused since its fstab line is commented out. Remove
+  it with `sudo rm /swapfile` to get the space back, or keep it as a
+  low-priority fallback.
+
+## Reapplying on a fresh neon install
+
+```
+sudo apt install zram-tools
+sudo tee -a /etc/default/zramswap >/dev/null <<'EOF'
+ENABLED=true
+ALGO=zstd
+SIZE=8192
+PRIORITY=100
+EOF
+sudo systemctl enable --now zramswap
+# comment out any /swapfile line in /etc/fstab, then:
+sudo swapoff /swapfile
+# optional: persist swappiness
+echo 'vm.swappiness=100' | sudo tee /etc/sysctl.d/99-zram.conf && sudo sysctl --system
+```
+
+Check with `zramctl` and `swapon --show`.