5 releases (breaking)
new 0.5.0 | May 2, 2025 |
---|---|
0.4.0 | May 2, 2025 |
0.3.0 | May 2, 2025 |
0.2.0 | May 2, 2025 |
0.1.0 | May 2, 2025 |
#411 in Cryptography
47 downloads per month
73KB
930 lines
Memo128
A Rust library and CLI tool for encoding 128-bit numbers as memorable natural language sentences.
Overview
Memo128 converts cryptographic keys, blockchain addresses, and other 128-bit values into easy-to-remember sentences. It adds a 7-bit checksum for error detection and uses five dictionaries to create structured sentences that form mini-stories.
Each 128-bit value (plus 7-bit checksum) is encoded as three sentences, with each sentence containing:
- Character (10 bits)
- Setting (10 bits)
- Action (8 bits)
- Object (9 bits)
- Outcome (8 bits)
Installation
cargo install --path .
Usage
Encoding a 128-bit hex value
cargo run -- encode 0123456789abcdef0123456789abcdef
This will output three sentences representing the encoded value.
Sentence 1: a brave mouse inside a cosmic cathedral disconnected a question of time but it was already too late
Sentence 2: a worried parent within the cosmic algorithm accepted a mathematical impossibility as code predicted
Sentence 3: the fjord elder inside a particle accelerator stole a reality glitch rebooting the system
Decoding sentences back to the original value
cargo run -- decode \
"a brave mouse inside a cosmic cathedral disconnected a question of time but it was already too late" \
"a worried parent within the cosmic algorithm accepted a mathematical impossibility as code predicted" \
"the fjord elder inside a particle accelerator stole a reality glitch rebooting the system"
Make sure to quote each sentence and provide all three sentences in the correct order.
Fuzzy decoding for imperfect sentences
Memo128 provides fuzzy decoding capabilities to handle sentences with typos, minor rephrasing, or other imperfections:
cargo run -- fuzzy-decode --max-distance 1 \
"a brave mouze inside a cosmic cathedral disconnected a question of time but it was already too late" \
"a worried parent within the cosmic algorithm accepted a mathematical impossibility as code predicted" \
"the fjord elder inside a particle accelerator stole a reality glitch rebooting the system"
cargo run -- fuzzy-decode --max-distance 3 \
"a brave mouse inside the cosmic cathedral disconnected a question of time but it was already too late" \
"a worried parent within the cosmic algorithm accepted a mathematical impossibility as code predicted" \
"the fjord elder inside a particle accelerator stole a reality glitch rebooting the system"
The --max-distance
parameter specifies the maximum Levenshtein distance allowed when matching sentence components
against
dictionary entries. Higher values allow more flexibility but may increase computation time and false matches:
--max-distance 1
: Handles minor typos (e.g., "mouze" instead of "mouse")--max-distance 2
: Handles word form changes (e.g., "rebooting the systems" vs "rebooting the system")--max-distance 3+
: Handles more extensive rephrasing but may be slow and less accurate
Fuzzy decoding may return multiple possible matches if the imperfect sentences can be interpreted in different ways.
Requirements
- Rust 1.81+
- Five dictionary files in the current directory:
character_10bit.txt
(1024 entries)setting_10bit.txt
(1024 entries)action_8bit.txt
(256 entries)object_9bit.txt
(512 entries)outcome_8bit.txt
(256 entries)
How It Works
- Input a 32-character hexadecimal string (128 bits)
- Calculate a 7-bit checksum using SHA-256
- Combine into a 135-bit sequence
- Split into three 45-bit chunks
- Map each chunk to story components using dictionaries
- Assemble three sentences from the components
For full details, see SPEC.md.
Development
# Build the project
cargo build
# Run tests
cargo test
# Format code
cargo fmt
# Run linter
cargo clippy
Dependencies
~2–2.9MB
~59K SLoC