Crate memo128

Memo128

A library for encoding 128-bit values 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): Who is performing the action
• Setting (10 bits): Where the action takes place
• Action (8 bits): What is being done
• Object (9 bits): What is being acted upon
• Outcome (8 bits): The result of the action

Basic Usage

use memo128::Memo128;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new Memo128 instance
    let memo128 = Memo128::new()?;

    // Encode a 128-bit value (32-character hex string)
    let hex_input = "0123456789abcdef0123456789abcdef";
    let sentences = memo128.encode(hex_input)?;

    // Print the encoded sentences
    for (i, sentence) in sentences.iter().enumerate() {
        println!("Sentence {}: {}", i + 1, sentence);
    }

    // Decode the sentences back to the original value
    let hex_output = memo128.decode(&sentences)?;
    assert_eq!(hex_input, hex_output);

    Ok(())
}

Fuzzy Decoding

Memo128 also supports fuzzy decoding for imperfect sentence recall:

use memo128::fuzzy::FuzzyMemo128;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a fuzzy decoder with maximum Levenshtein distance of 2
    let fuzzy_decoder = FuzzyMemo128::new(2)?;

    // Decode sentences with typos or rephrasing
    let imperfect_sentences = vec![
        "a brave mouze inside a cosmic cathedral disconnected a question of time but it was too late".to_string(),
        "a worried parent within a cosmic algorithm accepted a math impossibility as code predicted".to_string(),
        "the fjord elder inside the particle accelerator stole a reality glitch rebooting systems".to_string(),
    ];

    // Get all possible valid matches
    let possible_matches = fuzzy_decoder.fuzzy_decode(&imperfect_sentences)?;

    // Display matches
    for (i, hex) in possible_matches.iter().enumerate() {
        println!("Match {}: {}", i + 1, hex);
    }

    Ok(())
}

Requirements

Memo128 requires five dictionary files in the working 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

1. Input: A 32-character hexadecimal string (128 bits)
2. Calculate a 7-bit checksum using SHA-256
3. Combine into a 135-bit sequence
4. Split into three 45-bit chunks
5. Map each chunk to sentence components using dictionaries
6. Assemble three memorable sentences

When decoding, the process is reversed and the checksum is verified to detect errors.

Modules

fuzzy

Fuzzy decoding module for Memo128

Structs

Dictionary

Dictionary of phrases used for each component of the sentences

Memo128

Main struct for encoding and decoding 128-bit values as memorable sentences

Enums

Memo128Error

Errors that can occur when using Memo128

Constants

ACTION_BITS

Number of bits used for the Action component in each sentence (8 bits = 256 possibilities)

CHARACTER_BITS

Number of bits used for the Character component in each sentence (10 bits = 1024 possibilities)

CHECKSUM_BITS

Number of bits used for checksum (7 bits, allowing for values 0-127)

CHUNK_BITS

Total number of bits per chunk/sentence (45 bits)

NUM_CHUNKS

Number of chunks/sentences used to encode the complete 128-bit payload

OBJECT_BITS

Number of bits used for the Object component in each sentence (9 bits = 512 possibilities)

OUTCOME_BITS

Number of bits used for the Outcome component in each sentence (8 bits = 256 possibilities)

SETTING_BITS

Number of bits used for the Setting component in each sentence (10 bits = 1024 possibilities)