💎 Memory Scanner

A Ruby-powered command-line utility for testing RAM integrity

Inspired by the algorithms behind classic diagnostic tools like memtest86.

---

📖 Table of Contents

• How It Works
• Requirements
• Installation
• Usage
• Available Tests
• Running the Test Suite
• Project Structure
• Example Output
• License

---

⚙️ How It Works

This program runs entirely inside a Ruby process (user-space). It works by:

1. 🧱 Allocating a block of memory of the size you specify.
2. ✍️ Writing well-known data patterns into it — zeros, ones, alternating bits, random data, and more.
3. 🔍 Reading it back and comparing it byte-by-byte to detect any unexpected change (a bit flip), which may indicate memory instability or corruption.

Important

No application running on top of an operating system — without kernel-level privileges or booting from external media — can exclusively test the entire physical RAM. The OS itself occupies a significant portion of memory and prevents applications from directly accessing arbitrary physical memory regions belonging to other processes.

For a complete hardware-level memory diagnostic, tools such as memtest86+ must be booted from a USB drive before the operating system starts.

This project is great for:

🏋️	Stress-testing the memory available to your applications
📚	Learning classic memory-testing algorithms (Walking Bit, Checkerboard, etc.)
🚨	Catching potential memory issues while running memory-intensive apps or servers

---

📦 Requirements

• Ruby ≥ 3.0
• Bundler (optional — only needed to run the RSpec suite)

🚀 Installation

cd memory_scanner
bundle install   # optional, only required for RSpec tests
chmod +x bin/memscan

▶️ Usage

Run the default scan (256 MB, all tests) ruby bin/memscan

Specify a custom size (e.g. 1024 MB = 1 GB) ruby bin/memscan --size 1024

Run only selected tests ruby bin/memscan --tests solid_zeros,solid_ones,random

Tune the internal chunk size (useful on low-memory systems) ruby bin/memscan --size 512 --chunk 32

List all available tests ruby bin/memscan --list

Disable colored output (useful when redirecting to a file) ruby bin/memscan --no-color > report.txt

🧪 Available Tests

Test	Description
solid_zeros	Fills memory with 0x00 and verifies its integrity
solid_ones	Fills memory with 0xFF and verifies its integrity
alternating	Uses the alternating bit pattern 0xAA (10101010)
inverted	Uses the inverted alternating pattern 0x55 (01010101)
checkerboard	Alternates between 0xAA and 0x55 for each memory chunk
walking_bit	Moves a single set bit through all 8 positions to detect address-line and cell interaction issues
random	Uses reproducible pseudo-random data generated from a seed

✅ Running the Test Suite (RSpec)

bundle exec rspec

🗂️ Project Structure

memory_scanner/
├── assets/
│   └── banner.svg               # README banner
├── bin/
│   └── memscan                  # CLI executable
├── lib/
│   ├── memory_scanner.rb        # Library entry point
│   └── memory_scanner/
│       ├── patterns.rb          # Memory test data patterns
│       ├── tester.rb            # Core testing engine
│       ├── reporter.rb          # Terminal output and reporting
│       └── system_info.rb       # Reads real system memory information
├── spec/
│   └── tester_spec.rb           # RSpec test suite
├── Gemfile
└── README.md

🖥️ Example Output

============================================================
                Memory Scanner v1.0.0
============================================================
Total system memory   : 16384 MB (16.0 GB)
Currently available   : 9421 MB (9.2 GB)
Requested test size   : 256 MB (0.25 GB)

  Solid Zeros (0x00)       ✔ PASS      0.12 sec   2133.3 MB/s   errors: 0
  Solid Ones (0xFF)        ✔ PASS      0.11 sec   2327.3 MB/s   errors: 0
  ...
------------------------------------------------------------
Total scan time  : 0.85 sec
Total errors     : 0
Final result: no memory errors detected ✔

---

📄 License

This project is open source — free to use, modify, and distribute.

Made with 💎 and Ruby