RapidWebs-SysStable 🛡️
System stability monitor with Hermes integration — daemon, CLI, and plugin.
A background daemon that collects real-time system metrics (RAM, CPU, disk, swap, temperature, network, battery), thresholds them against configurable watermarks, and feeds results into Hermes Agent via plugin hooks. When resources get tight, Hermes adapts — blocking delegation on critical states, injecting context warnings on pressure.
✨ Features
| Capability | What It Does |
|---|---|
| 🔍 Metric Collection | RAM, ZRAM, SWAP, CPU (per-core + load avg), disk, net I/O, battery, temperature, uptime — every 15s |
| 🎚️ Threshold Engine | Green/Yellow/Orange/CRITICAL watermarks per metric. Supports CRITICAL severity level and threshold watermark for immediate action. Reverse-aware (lower=worse for RAM/disk, higher=worse for CPU/temp) |
| 🤖 Hermes Plugin | pre_tool_call blocks delegation on RED/CRITICAL, warns on YELLOW/ORANGE. With v0.2.0, it now supports CRITICAL severity blocking. pre_llm_call injects [SYSTEM STATUS] context. |
| 🖥️ CLI | sysstable status, history, trend, start, stop, init, uninstall, kill-list, processes, never-kill, resolution-history. Supports starting with --never-kill flag. |
| 🔌 Memory Pressure Resolution System | System for automatically resolving memory pressure situations by intelligently killing non-critical processes when system RAM falls below a defined critical threshold. Includes MemoryPressureResolver, PressureStateMachine, ProcessSnapshot, NoKillManager, and KillListGenerator. |
| 🗄️ SQLite Storage | WAL mode, configurable retention (24h–14d), auto-pruning, unix socket IPC. New tables in DB schema for enhanced data management. |
| ⚙️ Configurable | YAML config — thresholds, intervals, retention, webhook URLs, hook directories. New config blocks: memory_pressure, resolution, process_scoring, never_kill. |
| 🐦 Security Enhancements | Triple (pid,name,cmdline) matching for process identification and security. |
| 🐚 systemd Support | --user service template with Restart=on-failure |
🏗️ Architecture
┌──────────────────────────────────────────────────┐
│ Daemon (sysstabled) │
│ - Python, systemd --user service │
│ - Collects every 15s (configurable) │
│ - Reads /proc + psutil │
│ - Writes metrics → SQLite (WAL, retention) │
│ - Writes current state → state.json │
│ - Evaluates thresholds → dispatches events │
└────┬──────────────┬─────────────┬────────────────┘
│ │ │
│ state.json │ unix socket │ Memory Pressure Resolution Layer
▼ ▼ ▼ (monitors state.json, acts on critical thresholds)
┌─────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────┐
│ Hermes │ │ CLI (sysstable) │ │ Resolver (memory_pressure) │
│ Plugin │ │ - status │ │ - Manages resolution lifecycle │
│ (pre_tool, │ │ - history, trend │ │ - Integrates with Process Watch modules │
│ pre_llm) │ │ - daemon lifecycle │ └──────────────────────────┘
└─────────────┘ │ - init, uninstall │
│ - kill-list, processes, etc. │
└──────────────────────────────┘
📦 Installation
Requirements
- Python ≥ 3.10
- Linux (reads
/proc; psutil sensors) - Hermes Agent (for plugin integration)
From PyPI
pip install rw-sysstable
From Source
git clone https://github.com/steven-page-8926/rapidwebs-sysstable.git
cd rapidwebs-sysstable
uv venv
source .venv/bin/activate
uv pip install -e ."[dev]"
Hermes Plugin
# Install the plugin from github repo via hermes plugins install
hermes plugins install https://github.com/steven-page-8926/rapidwebs-sysstable/hermes-plugin/rapidwebs-sysstable
# Enable it
hermes config set plugins.rapidwebs-sysstable.enabled true
🚀 Quick Start
# 1. Initialize directories + default config
sysstable init
# 2. Start the daemon (background)
sysstable start
# 3. Check system status
sysstable status
# 4. View metric history
sysstable history -n 10
# 5. See trends
sysstable trend -n 10
# 6. Stop the daemon
sysstable stop
# 7. View process list (for debugging memory pressure)
sysstable processes
# 8. Generate a kill list for non-critical processes
sysstable kill-list
# 9. Check resolution history
sysstable resolution-history
# Start the daemon, preventing it from killing processes initially
sysstable start --never-kill
Systemd (persistent)
cp docs/sysstable.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now sysstable
⚙️ Configuration
~/.config/sysstable/config.yaml — auto-created on sysstable init.
interval_seconds: 15 # Collection interval
retention_hours: 72 # Data retention (24 | 72 | 120 | 168 | 336)
db_path: ~/.cache/sysstable/metrics.db
socket_path: ~/.cache/sysstable/sysstable.sock
state_path: ~/.hermes/plugins/rapidwebs-sysstable/state.json
# Memory Pressure Resolution Configuration
memory_pressure:
enabled: true # Enable automatic memory pressure resolution
check_interval_seconds: 30 # How often to check for memory pressure
severity_threshold: 128 # Memory available in MB to trigger resolution (e.g., CRITICAL threshold < 128 MB)
grace_period_seconds: 120 # Time to wait before killing processes after pressure detected
resolution:
# Settings for the MemoryPressureResolver
max_kill_attempts: 5 # Max processes to attempt killing in one cycle
min_process_ram_mb: 100 # Minimum RAM usage to consider a process for termination
max_cpu_usage_percent: 50 # Don't kill processes consuming high CPU (e.g., active services)
process_scoring:
# Scoring parameters for prioritizing processes to kill
ram_usage_weight: 0.6
cpu_usage_weight: 0.1
runtime_weight: 0.1
importance_score_weight: 0.2 # Higher score = less important
never_kill:
# List of processes (by pid, name, or cmdline) to never kill
user_list: ["hermes-agent", "sysstabled"] # Process names to protect (from config file)
events:
shell_hooks_dir: ~/.config/sysstable/hooks.d
webhooks: []
python_extensions_dir: ~/.config/sysstable/extensions.d
thresholds:
ram_available_mb: { yellow: 1024, orange: 512, red: 256, critical: 128 } # CRITICAL added
cpu_load_15m: { yellow: 2.0, red: 4.0 }
disk_root_free_mb: { yellow: 5120, red: 1024 }
swap_percent: { yellow: 50, red: 80 }
temperature_celsius: { yellow: 80, red: 95 }
🧠 Memory Pressure Resolution System
This system proactively identifies and resolves memory pressure situations by intelligently terminating non-critical processes when system RAM falls below a defined critical threshold. It integrates seamlessly with the existing daemon and Hermes Agent, and is controlled via new CLI commands and configuration blocks.
Lifecycle Overview:
- Detection: The
sysstableddaemon continuously monitors system metrics. Whenram_available_mbdrops below thecriticalwatermark (defined inthresholds.critical), the Memory Pressure Resolution system is triggered. - Initiation: The
MemoryPressureResolver(fromresolver.py) is engaged. It checks the newmemory_pressure.enabledconfiguration. If enabled, and after agrace_period_seconds, it begins the resolution process. - Process Assessment: The
ProcessSnapshotclass (fromprocess_watch.py) gathers detailed information about all running processes, including their PID, name, command line, RAM usage, CPU usage, and runtime. - Scoring & Prioritization: The
resolutionconfiguration block defines parameters for scoring processes. Each process is assigned an importance score based on RAM usage, CPU usage, runtime, and animportance_score_weight. Thenever_killconfiguration (pids, names, cmdlines) is consulted to exclude critical processes (e.g.,hermes-agent,sysstableditself). - Termination: The
KillListGenerator(fromprocess_watch.py) uses scorers and thenever_killlist to create a prioritized list of non-critical processes to terminate. TheMemoryPressureResolverthen signals the termination of processes from this list, respectingmax_kill_attemptsandmin_process_ram_mb. - Monitoring & Feedback: The
PressureStateMachine(fromstate_machine.py) tracks the state of the memory pressure resolution. The CLI commandresolution-historyprovides a log of these events. The Hermes plugin receivesCRITICALseverity alerts, enabling immediate, system-wide actions.
New Modules:
src/sysstable/process_watch.py: ContainsProcessSnapshot,NoKillManager,KillListGenerator.src/sysstable/state_machine.py: ContainsPressureStateMachine.src/sysstable/resolver.py: ContainsMemoryPressureResolver.
New CLI Commands:
sysstable processes: List all running processes with key metrics.sysstable kill-list: Generate and display a prioritized list of processes that could be killed.sysstable resolution-history: View logs of memory pressure resolution events.sysstable start --never-kill: Temporarily disable the auto-kill feature on startup.
🧪 Development
# Install with dev deps
uv pip install -e ."[dev]"
# Run tests (98 tests total)
pytest tests/ -v
# Lint
ruff check src/ tests/
# Format
ruff format src/ tests/
# Full check
make check
📊 Threshold Behavior
| Severity | Plugin Action |
|---|---|
| 🟢 Green | Silence |
| 🟡 Yellow | Injects [SYSTEM STATUS] context warning via pre_llm_call |
| 🟠 Orange | Injects warning, blocks first delegation attempt, allows retry |
| 🔴 Red | Blocks delegate_task via pre_tool_call. Release manually. |
| 🚨 CRITICAL | Blocks delegate_task via pre_tool_call. Triggers Memory Pressure Resolution system. |
🗺️ Project Structure
rapidwebs-sysstable/
├── src/sysstable/ # Main package
│ ├── __init__.py # Version info
│ ├── __main__.py # python -m entry
│ ├── daemon.py # Collection loop + state
│ ├── collector.py # psutil wrappers
│ ├── thresholds.py # Watermark engine
│ ├── events.py # Hook/extension dispatch
│ ├── database.py # SQLite store
│ ├── socketd.py # Unix IPC
│ ├── cli.py # Click CLI
│ ├── config.py # YAML loader
│ ├── process_watch.py # Process (snapshot, no-kill, kill-list) modules
│ ├── state_machine.py # State machine for pressure resolution
│ └── resolver.py # Memory pressure resolver logic
├── hermes-plugin/ # Hermes integration
│ └── rapidwebs-sysstable/
├── tests/ # Pytest suite (98 tests)
├── docs/ # systemd service
├── pyproject.toml # Build config
├── Makefile # Dev commands
└── Dockerfile # Container build
🔗 Related
- Hermes Agent — AI agent platform
- rapidwebs-sysstable Hermes Plugin — v0.2.0 with CRITICAL severity blocking
- psutil — System metrics library
- RapidWebs Enterprise — Digital architecture studio
📄 License
MIT © 2026 RapidWebs Enterprise. See LICENSE for details.
Metadata
Release files for rw-sysstable 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rw_sysstable-0.2.2.tar.gz | 153.0 kB | With provenance | Details for rw_sysstable-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rw_sysstable-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for rw_sysstable-0.2.2-py3-none-any.whl |
Total release size: 200.3 kB
Release files / rw_sysstable-0.2.2.tar.gz
| Download URL | rw_sysstable-0.2.2.tar.gz |
|---|---|
| Size | 153.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31466440bde667c6c354c27b889ba9c9e44389a4876b2adbdff42d8acdce101f
|
|
BLAKE2b-256 checksum How to use checksums |
b11072b88fa15675a2f31a36d1af779b380839581befaddf6c52f218d63f00e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2026.
Transparency logRelease files / rw_sysstable-0.2.2-py3-none-any.whl
| Download URL | rw_sysstable-0.2.2-py3-none-any.whl |
|---|---|
| Size | 47.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acaf24d108f771175f7cbc2b540e68d5ca33585aab511743cb04badd094c1a15
|
|
BLAKE2b-256 checksum How to use checksums |
d8baf1bc86ba36226ba3851bb747ab3844009c43c46a04801ea10fff6d20b2fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2026.
Transparency logSecurity for rw-sysstable 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for rw_sysstable-0.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.